arcane-os 0.48.0 → 0.50.0

package/browser-runtime/ai/twin-cloud-speech.mjs

@@ -3,7 +3,7 @@ import Queue from '../dependencies/js-queue/queue.js';
 
 const is = new Is(false);
 const INVOKE_URL = 'https://inference.do-ai.run/v1/async-invoke';
-const SUBMISSION_RETRY_DELAY_MS = 1000;
+const RATE_LIMIT_RETRY_DELAY_MS = 1000;
 
 function speechError(message, code, cause) {
     const error = cause === undefined
@@ -36,30 +36,6 @@ function assertIdentifier(value, label) {
     }
 }
 
-function waitForStatus(delay, signal) {
-    assertNotAborted(signal);
-    return new Promise(
-        function waitForCloudSpeechStatus(resolve, reject) {
-            const timer = setTimeout(finishStatusWait, delay);
-            function finishStatusWait() {
-                signal.removeEventListener('abort', cancelStatusWait);
-                resolve();
-            }
-            function cancelStatusWait() {
-                clearTimeout(timer);
-                signal.removeEventListener('abort', cancelStatusWait);
-                reject(abortedSpeech(signal));
-            }
-            signal.addEventListener(
-                'abort',
-                cancelStatusWait,
-                {once: true}
-            );
-            if (signal.aborted) cancelStatusWait();
-        }
-    );
-}
-
 function retryAfterDelay(response) {
     const value = response.headers?.get?.('Retry-After');
     if (!value?.trim()) return null;
@@ -69,11 +45,11 @@ function retryAfterDelay(response) {
     return is.finite(date) ? Math.max(0, date - Date.now()) : null;
 }
 
-async function requireSuccessfulResponse(response, signal, operation) {
-    if (response.ok) return response;
+async function readResponseError(response, signal, operation) {
+    if (response.ok) return null;
     const detail = await response.text();
     assertNotAborted(signal);
-    throw speechError(
+    return speechError(
         `TWiN Cloud speech ${operation} failed with HTTP ${response.status}${detail ? `: ${detail}` : '.'}`,
         'ARCANE_AI_CLOUD_SPEECH_HTTP_ERROR'
     );
@@ -83,8 +59,8 @@ async function requireSuccessfulResponse(response, signal, operation) {
  * A remote provider/2 TTS adapter. The application selects the model and voice,
  * and getApiKey returns its current credential or the application's existing
  * refresh promise. Credentials never enter status or configuration. The runtime
- * owns whole-job admission and playback order. This provider owns immediate
- * submissions and one configurable queue for follow-up HTTP/body operations.
+ * owns playback order. This provider queues whole synthesis jobs, submission
+ * attempts, and follow-up HTTP/body operations under one shared 429 cooldown.
  */
 export function createTwinCloudTTSProvider({
     id,
@@ -115,18 +91,132 @@ export function createTwinCloudTTSProvider({
 
     const modelId = model.id;
     const defaultVoice = model.defaultVoice;
+    const requests = new Set();
     const activeRequests = new Set();
     const credentialWaits = new Set();
     let state = 'unloaded';
     let generation = 0;
     let unloadOperation = null;
     let disposeOperation = null;
+    const jobs = new Queue();
+    jobs.autoRun = false;
+    const submissions = new Queue();
+    submissions.autoRun = false;
     const followUps = new Queue();
     followUps.autoRun = false;
+    let cooldownUntil = 0;
+    let submissionTimer = null;
     let activeFollowUps = 0;
     let nextFollowUpStart = 0;
     let followUpTimer = null;
 
+    function dispatchJobs() {
+        while (state === 'ready' && activeRequests.size < maxConcurrentRequests && jobs.size) {
+            jobs.next();
+        }
+    }
+
+    function queueSynthesis(request, payload, requestGeneration) {
+        const signal = request.controller.signal;
+        assertNotAborted(signal);
+        return new Promise(
+            function enqueueCloudSpeechJob(resolve, reject) {
+                function cancelQueuedJob() {
+                    jobs.contents = jobs.contents.filter(
+                        function keepOtherJob(task) {return task !== startJob;}
+                    );
+                    signal.removeEventListener('abort', cancelQueuedJob);
+                    reject(abortedSpeech(signal));
+                    dispatchJobs();
+                }
+                function finishJob() {
+                    activeRequests.delete(request);
+                    dispatchJobs();
+                }
+                function startJob() {
+                    signal.removeEventListener('abort', cancelQueuedJob);
+                    activeRequests.add(request);
+                    // A slot belongs to the entire synthesis, including its
+                    // accepted remote job, every read, and the complete audio.
+                    synthesize(payload, request.controller, requestGeneration).then(
+                        function acceptCloudSpeechJob(audio) {
+                            finishJob();
+                            resolve(audio);
+                        },
+                        function rejectCloudSpeechJob(error) {
+                            finishJob();
+                            reject(error);
+                        }
+                    );
+                }
+                jobs.add(startJob);
+                signal.addEventListener(
+                    'abort',
+                    cancelQueuedJob,
+                    {once: true}
+                );
+                if (signal.aborted) cancelQueuedJob();
+                else dispatchJobs();
+            }
+        );
+    }
+
+    function dispatchSubmissions() {
+        clearTimeout(submissionTimer);
+        submissionTimer = null;
+        if (state !== 'ready' || !submissions.size) return;
+        const delay = cooldownUntil - Date.now();
+        if (delay > 0) {
+            submissionTimer = setTimeout(dispatchSubmissions, Math.min(2147483647, delay));
+            return;
+        }
+        // Each admitted job awaits its current attempt before requeueing, so
+        // whole-job capacity also bounds concurrent submission attempts.
+        while (state === 'ready' && submissions.size) submissions.next();
+    }
+
+    function queueSubmission(readResponse, signal) {
+        assertNotAborted(signal);
+        return new Promise(
+            function enqueueCloudSpeechSubmission(resolve, reject) {
+                function cancelQueuedSubmission() {
+                    submissions.contents = submissions.contents.filter(
+                        function keepOtherSubmission(task) {return task !== startSubmission;}
+                    );
+                    signal.removeEventListener('abort', cancelQueuedSubmission);
+                    reject(abortedSpeech(signal));
+                    dispatchSubmissions();
+                }
+                async function consumeSubmission() {
+                    assertNotAborted(signal);
+                    return await readResponse();
+                }
+                function startSubmission() {
+                    signal.removeEventListener('abort', cancelQueuedSubmission);
+                    consumeSubmission().then(resolve, reject);
+                }
+                submissions.add(startSubmission);
+                signal.addEventListener(
+                    'abort',
+                    cancelQueuedSubmission,
+                    {once: true}
+                );
+                if (signal.aborted) cancelQueuedSubmission();
+                else dispatchSubmissions();
+            }
+        );
+    }
+
+    function observeRateLimit(response) {
+        if (response.status !== 429) return;
+        cooldownUntil = Math.max(
+            cooldownUntil,
+            Date.now() + Math.max(RATE_LIMIT_RETRY_DELAY_MS, retryAfterDelay(response) ?? 0)
+        );
+        dispatchSubmissions();
+        dispatchFollowUps();
+    }
+
     function dispatchFollowUps() {
         clearTimeout(followUpTimer);
         followUpTimer = null;
@@ -136,18 +226,20 @@ export function createTwinCloudTTSProvider({
         const eligibleIndex = followUps.contents.findIndex(
             function eligibleFollowUp(task) {return task.eligibleAt <= now;}
         );
-        if (now < nextFollowUpStart || eligibleIndex === -1) {
+        const nextStart = Math.max(nextFollowUpStart, cooldownUntil);
+        if (now < nextStart || eligibleIndex === -1) {
             const firstEligibility = followUps.contents.reduce(
                 function earliestFollowUp(time, task) {return Math.min(time, task.eligibleAt);},
                 Infinity
             );
             // Long Retry-After dates may exceed the platform timer's range.
             // Revisit at that boundary without shortening the job's eligibility.
-            followUpTimer = setTimeout(dispatchFollowUps, Math.min(2147483647, Math.max(nextFollowUpStart, firstEligibility) - now));
+            followUpTimer = setTimeout(dispatchFollowUps, Math.min(2147483647, Math.max(nextStart, firstEligibility) - now));
             return;
         }
-        // A job's Retry-After does not hold up eligible siblings. Queue remains
-        // the sole pending-task owner, with FIFO order among eligible entries.
+        // Successful pending responses retain job-local Retry-After timing.
+        // HTTP 429 also applies the shared cooldown before any queued start.
+        // Queue owns pending tasks in FIFO order among eligible entries.
         if (eligibleIndex > 0) {
             const [eligibleTask] = followUps.contents.splice(eligibleIndex, 1);
             followUps.contents.unshift(eligibleTask);
@@ -287,7 +379,7 @@ export function createTwinCloudTTSProvider({
             localOnly: false,
             state,
             loaded,
-            busy: activeRequests.size > 0,
+            busy: requests.size > 0,
             execution: {
                 requestedDevice: 'remote',
                 selectedDevice: loaded ? 'remote' : null,
@@ -310,11 +402,12 @@ export function createTwinCloudTTSProvider({
                 // an identified job's status read can retry a network failure.
                 return {error, retryable: options.method === 'GET' && error instanceof TypeError};
             }
+            assertNotAborted(signal);
+            observeRateLimit(response);
             const nextEligibility = Date.now() + (retryAfterDelay(response) ?? 0);
-            try {
-                await requireSuccessfulResponse(response, signal, operation);
-            } catch (error) {
-                assertNotAborted(signal);
+            const error = await readResponseError(response, signal, operation);
+            assertNotAborted(signal);
+            if (error) {
                 return {error, retryable: response.status === 429, eligibleAt: nextEligibility};
             }
             // Parsing errors are not Fetch failures and must not replay a job.
@@ -325,7 +418,7 @@ export function createTwinCloudTTSProvider({
         while (true) {
             assertNotAborted(signal);
             const outcome = options.method === 'POST'
-                ? await readInferenceResponse()
+                ? await queueSubmission(readInferenceResponse, signal)
                 : await queueFollowUp(readInferenceResponse, signal, eligibleAt);
             assertNotAborted(signal);
             if (!outcome.error) return outcome;
@@ -333,11 +426,6 @@ export function createTwinCloudTTSProvider({
             retryError = outcome.error;
             console.warn(`Retrying the cloud speech ${operation} once.`, retryError);
             eligibleAt = outcome.eligibleAt ?? 0;
-            if (options.method === 'POST') {
-                // A readable submission rejection retains its own bounded retry
-                // delay. It never delays another job or enters the GET queue.
-                await waitForStatus(Math.max(SUBMISSION_RETRY_DELAY_MS, eligibleAt - Date.now()), signal);
-            }
         }
     }
 
@@ -402,7 +490,11 @@ export function createTwinCloudTTSProvider({
         const audio = await queueFollowUp(
             async function downloadCloudSpeechAudio() {
                 const audioResponse = await fetchImpl(result.output.audio.url, {signal});
-                await requireSuccessfulResponse(audioResponse, signal, 'audio download');
+                assertNotAborted(signal);
+                observeRateLimit(audioResponse);
+                const error = await readResponseError(audioResponse, signal, 'audio download');
+                assertNotAborted(signal);
+                if (error) throw error;
                 return await audioResponse.blob();
             },
             signal,
@@ -491,9 +583,6 @@ export function createTwinCloudTTSProvider({
             if (state !== 'ready' || unloadOperation || disposeOperation) {
                 throw speechError('The cloud speech provider is not ready.', 'ARCANE_AI_NOT_READY');
             }
-            if (activeRequests.size >= maxConcurrentRequests) {
-                throw speechError('The cloud speech provider is at capacity.', 'ARCANE_AI_PROVIDER_BUSY');
-            }
             const payload = context.payload;
             if (!is.string(payload?.input) || !payload.input.trim()) {
                 throw new TypeError('Cloud speech input must be a nonempty string.');
@@ -523,16 +612,16 @@ export function createTwinCloudTTSProvider({
             );
             if (context.signal?.aborted) cancelCloudSpeechRequest();
             const request = {controller, promise: null};
-            activeRequests.add(request);
-            request.promise = synthesize(payload, controller, generation);
+            requests.add(request);
             try {
+                request.promise = queueSynthesis(request, payload, generation);
                 return await request.promise;
             } catch (error) {
                 if (controller.signal.aborted) throw abortedSpeech(controller.signal);
                 throw error;
             } finally {
                 context.signal?.removeEventListener('abort', cancelCloudSpeechRequest);
-                activeRequests.delete(request);
+                requests.delete(request);
             }
         },
 
@@ -546,11 +635,15 @@ export function createTwinCloudTTSProvider({
             if (unloadOperation) return unloadOperation;
             state = 'unloading';
             generation += 1;
+            clearTimeout(submissionTimer);
+            submissionTimer = null;
+            clearTimeout(followUpTimer);
+            followUpTimer = null;
             for (const cancelCredentialWait of [...credentialWaits]) cancelCredentialWait();
-            const requests = [...activeRequests];
-            for (const request of requests) request.controller.abort('Cloud speech provider unloaded.');
+            const pendingRequests = [...requests];
+            for (const request of pendingRequests) request.controller.abort('Cloud speech provider unloaded.');
             unloadOperation = Promise.allSettled(
-                requests.map(
+                pendingRequests.map(
                     function pendingCloudSpeechRequest(request) {
                         return request.promise;
                     }

package/docs/reference/ai/browser-speech.md

@@ -1,7 +1,7 @@
 # Browser speech providers
 
 `arcane-os/ai/browser-speech` supplies caller-selected Whisper or native Web
-Speech recognition, Kokoro text-to-speech, and TWiN Cloud text-to-speech providers. Its local path
+Speech recognition and synthesis, Kokoro text-to-speech, and TWiN Cloud text-to-speech providers. Its local path
 provides artifact storage, live module routing, role Workers, provider/2
 adapters, bounded parallel TTS synthesis, audio normalization, cancellation,
 and cleanup.
@@ -82,6 +82,78 @@ honestly rather than recording again or silently switching providers. See the
 [Web Speech specification](https://webaudio.github.io/web-speech-api/#speechreco-methods)
 for native stop/abort behavior.
 
+## Native browser text-to-speech and voice previews
+
+`createBrowserSpeechSynthesisProvider({id,model:{id,name?,defaultVoice?},language?})`
+uses the host browser's `speechSynthesis` and `SpeechSynthesisUtterance`.
+The application selects this provider as its default when desired; constructing
+it does not change global preferences, activate Chat speech, or play audio.
+The provider declares `localOnly:false` because a browser voice may use a remote
+service. Individual catalog records expose the browser's `localService` value.
+
+```javascript
+import {createBrowserSpeechSynthesisProvider} from 'arcane-os/ai/browser-speech';
+
+const voicePreview = createBrowserSpeechSynthesisProvider({
+  id: 'browser-preview',
+  model: {id: 'browser-voices', name: 'Browser voices'}
+});
+const unsubscribe = voicePreview.subscribeCatalog(function showVoices(models) {
+  // Pass these real records to the application's language/voice selector.
+  console.log(models[0].voices);
+});
+
+// Call only from the application's explicit Play action.
+function playIntroduction(input, voice) {
+  return voicePreview.play({input, voice});
+}
+// The owning view unsubscribes and disposes voicePreview when it closes.
+```
+
+`catalog()` synchronously returns an array of model records. Each model has
+`speech:{playback:'native'}` and `voices:[{id,name,lang,default,localService}]`;
+`id` is the exact native `voiceURI`. `subscribeCatalog(callback)` immediately
+replays that same shape and updates it on `voiceschanged`, returning an
+unsubscribe function. An initially empty inventory is ordinary pending browser
+state. There is no polling, discovery utterance, model download, or page-load
+barrier. Language selectors derive their choices from this actual inventory.
+
+`prepare({input,voice?,language?,speed?},{signal?})` returns an inert
+`{kind:'native-speech',input,voice,language,speed,play(options)}` descriptor.
+`play(payload,{signal,onState})` is the explicit-preview convenience. Both
+preserve complete input. Omitted voice uses the configured `model.defaultVoice`
+or the actual browser default; a supplied voice is never replaced with a named
+SDK alias. Language comes from that voice unless explicitly provided. Neither
+API reads the conversation's language preference. A saved voice waits for
+`voiceschanged` if the inventory is empty; a nonempty inventory missing it
+reports `ARCANE_AI_SPEECH_VOICE_UNAVAILABLE`.
+
+Playback returns `{finished,released,state,error,pause(),resume(),stop()}`.
+`finished` resolves `true` on actual native end, `false` on stop/abort, and
+rejects genuine native failures. `released` resolves when native resource
+ownership actually ends: a failed pause/resume/cancel can report an error before
+the utterance terminates. `onState({state,error})` observes queued,
+waiting-for-voices, playing, paused, complete, stopped, or error. Keep complete
+errors in diagnostics and ordinary status in the interface.
+
+Preview does not depend on AI mute or model activation. Use a separate provider
+instance when the preview should have a lifetime independent of Chat's selected
+provider. Provider unload/dispose stop their own playback, invalidate prepared
+descriptors, and disposal removes catalog listeners. Web Speech pause/resume/cancel
+operate on the native synthesis object globally; the SDK serializes its own
+utterances and does not claim control isolation from unrelated direct native
+callers. See the [native synthesis contract](https://webaudio.github.io/web-speech-api/#tts-section).
+
+For Chat, configure this provider with `ai.configureSpeechProvider('tts',provider)`
+and retain the existing explicit mute/unmute lifecycle. `AI.streamTTS()` and
+`SpeechPlayback` use actual utterance completion and cancellation in original
+order. `AI.prepareTTSPlayback(payload,signal)` returns either real Blob audio or
+the native descriptor without speaking; its signal remains attached by default
+when the returned descriptor is played. `AI.fetchTTS()` and durable
+`AI.prepareTTS()` remain audio-file APIs and report
+`ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE` for native synthesis, which exposes no
+downloadable audio file.
+
 <a id="digitalocean-fal-text-to-speech"></a>
 
 ## TWiN Cloud text-to-speech
@@ -138,11 +210,13 @@ playback remain the only owners. Use
 punctuation boundary should submit promptly. This is incremental playback of
 completed synthesis jobs, not a live audio stream from TWiN Cloud.
 
-The SDK submits `POST https://inference.do-ai.run/v1/async-invoke` immediately
-after credential readiness, outside the follow-up queue. It then reads that job
-until its completed `output.audio.url` is available. The provider's
-`maxConcurrentRequests` retains its whole-synthesis-job meaning; it is separate
-from `followUpQueue.maxConcurrentRequests`.
+The provider queues each complete synthesis job, including initial
+`POST https://inference.do-ai.run/v1/async-invoke` and any eligible submission
+retry. `maxConcurrentRequests` defaults to four whole jobs. Each slot remains
+occupied through credential readiness, submission, queued/running status, and
+the complete final audio response. Additional requests wait in order; cancelling
+a waiting job removes it before credential reading or submission. This capacity
+is separate from `followUpQueue.maxConcurrentRequests`.
 
 One provider-local `js-queue` owns only follow-up status/result GETs and the final
 audio GET. `followUpQueue` defaults to `{maxConcurrentRequests:4,intervalMs:250}`;
@@ -153,20 +227,31 @@ job awaits its current response and body before immediately enqueueing another
 request only when incomplete or eligible for a retry. There is no additional
 per-job polling delay.
 
-A readable `Retry-After` changes only the affected job's next eligibility, not
-sibling requests or initial submissions. A readable `429` permits one retry of
-that submission or status read; submission retries retain a one-second minimum, while
-follow-up retries use the queue cadence and any longer readable `Retry-After`.
+A successful pending response's `Retry-After` changes that job's next eligibility.
+A `429` applies a shared cooldown to all queued submission and follow-up starts,
+using a one-second minimum and any longer readable `Retry-After`. A completely
+readable `429` permits one retry of that submission or status read, within the
+same whole-job slot. Already dispatched operations retain their response ownership.
 An accepted job's status Fetch network failure may retry once for the same job;
-JSON parsing failures are not network retries. Repeated failures surface their
+Ambiguous POST network, JSON parsing, and error-body read failures never replay
+the submission. Repeated failures surface their
 complete diagnostics without an endless retry loop; a failed job does not cancel
 siblings. Retry diagnostics remain in the developer console, outside conversation
 history.
 
-The queue is created when this cloud factory is called, not when the browser
+The provider-local queues are created when this cloud factory is called, not when the browser
 speech entrypoint is imported. Local Kokoro and Whisper do not use this queue;
 their setup, Workers, synthesis/transcription, and lifecycle remain independent.
 
+Ordinary Kokoro descriptors may supply `model.voices` as complete display records,
+for example `{id:'af_heart',name:'Heart',lang:'en-US'}`. The synchronous
+`provider.catalog()[0].voices` preserves that array and its metadata without
+loading the model or fetching a catalog. The application supplies the inventory
+for its selected runtime; these records neither create a synthesis allow-list
+nor establish that a voice has loaded or played. Ordinary Worker configuration
+does not receive this display inventory. Existing artifact-graph voice paths
+retain their separate meaning.
+
 The SDK pins published `js-queue` through npm. Its browser Queue entry, original
 package metadata, and license are projected unchanged by
 `node tools/sync-js-queue.mjs` after an SDK dependency update. The existing runtime

package/docs/reference/runtime-modules.md

@@ -160,7 +160,7 @@ read-only `ttsSegmentation`, `configureTTSSegmentation()`,
 `streamTTS(text='',end=false,options={})`,
 `prepareTTS({parts,storage,identity,signal,onState})`,
 `playPreparedTTS(prepared,{signal,onState})`,
-`finishTTS()`, `fetchTTS()`, `fetchSTT()`, `stopAudio()`, `resumeAudio()`,
+`finishTTS()`, `prepareTTSPlayback()`, `fetchTTS()`, `fetchSTT()`, `stopAudio()`, `resumeAudio()`,
 `playAudio()`; consumes `user-entity-loaded` and `arcane-ollama-ready`,
 installs `window.ai`, and emits `ai-ready` and `ai-tts-failure`.
 
@@ -374,7 +374,7 @@ marks from a cloned outbound input before delegation; the caller's payload stays
 unchanged. The third `preparation` argument is reserved for SDK-internal
 delegation, where `{speechInputPrepared:true}` prevents a second cleanup pass;
 applications omit it. `streamTTS(text='',end=false,options={})` and
-`finishTTS()` use this same request boundary. The third-argument options below
+`finishTTS()` use the selected playback boundary. The third-argument options below
 are available in SDK `0.5.12`. The `textFormat` compatibility extra added in
 SDK `0.5.16` is ignored beginning in `0.5.17`:
 
@@ -386,7 +386,7 @@ SDK `0.5.16` is ignored beginning in `0.5.17`:
 | `waitForPlayback` | `false` | Omission retains the preparation promise. With `true`, the promise resolves after every extracted segment reaches a terminal playback state: `true` when all naturally end, or `false` after terminal cancellation or failure. |
 | `textFormat` | Ignored compatibility extra | Repeated same formatting marks are removed automatically from every TTS call. This value no longer selects or disables cleanup. |
 
-The voice and speed use the existing `fetchTTS()` validation and error path.
+Audio-file voice and speed use the existing `fetchTTS()` validation and error path.
 The automatic cleanup changes only the outbound speech-input copy; displayed,
 stored, model, and caller-owned content remains exact. It is a narrow
 formatting-mark filter, not a full Markdown parser: links, code contents, list
@@ -405,6 +405,24 @@ for a complete passage. A call extracting no segments resolves
 `true` without waiting for earlier jobs; `finishTTS()` remains a preparation
 flush, not a queue-wide playback barrier. A muted call resolves `false`.
 
+`prepareTTSPlayback(payload,signal,preparation={})` is the silent playback-oriented
+request. Audio-file providers retain the `fetchTTS()` Blob contract; a selected
+model with `speech.playback:'native'` returns an inert `native-speech` descriptor.
+Its `play({signal,onState})` returns native completion and lifecycle controls.
+The preparation signal remains its default playback signal. Native input stays
+complete; per-request voice/language/speed and the configured model default own
+selection, without reading global user voice or conversation-language fields.
+Native streaming jobs wait for actual end in order and allocate no AudioContext.
+When native speech follows recorded audio, the preceding audio clock still owns
+its requested inter-part pause. Native trailing silence delays the next part,
+not the completed playback promise; cancellation retires either pending gap.
+Failed native control remains owned through its `released` promise, so Stop can
+still reach it and subsequent buffered audio cannot overlap it. Explicit saved
+Blob playback continues to use its own AudioContext even when native speech is
+the currently selected provider. `fetchTTS()` and durable `prepareTTS()` report
+`ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE` for native selection; no audio file is
+fabricated. See [native voice catalogs and previews](ai/browser-speech.md#native-browser-text-to-speech-and-voice-previews).
+
 Playback completion stays pending while the browser waits for an audio-unlock
 gesture or a recoverable resume attempt. If resuming a closed `AudioContext`
 fails, the affected jobs terminate and their playback results settle `false`.
@@ -3731,8 +3749,10 @@ new SpeechPlayback({
 })
 ```
 
-`speech` must expose either `fetchTTS(payload, signal)` or
-`synthesize(payload, {signal})`. `SpeechPlayback` also supplies a third
+`speech` may expose `prepareTTSPlayback(payload,signal)` returning a Blob or
+native descriptor, a native provider's silent `prepare(payload,{signal})`,
+`fetchTTS(payload, signal)`, or `synthesize(payload, {signal})`.
+The playback-oriented method is preferred. `SpeechPlayback` also supplies a third
 SDK-internal preparation object; existing two-argument clients may ignore it.
 `prepare({key,parts,model,voice,responseFormat,
 speed,autoplay=true})` uses only caller-supplied model, voice, and response-format
@@ -3775,6 +3795,15 @@ releases prepared URLs. Replay keeps completed URLs and still-pending provider
 work, then re-submits only failed missing provider segments before starting
 again from index zero.
 
+Native descriptors are retained separately from Blob URLs and never assigned to
+an audio element. `autoplay:false` remains silent. Play, Pause, Resume, Stop and
+Replay use the native control; only a successful current native `finished`
+advances the next part. Native errors remain observable, and a failed native
+control stays owned until its optional `released` promise confirms cleanup.
+Stale completion after stop/restart/disposal cannot advance replacement content.
+Selecting a native part hides and clears the HTML audio source while preserving
+the same shared playback state events and complete original parts.
+
 Every preparation owns an operation ID and one AbortController for each active
 synthesis segment or playback delay. Replacement,
 `stop()`, `cancel()`, and `destroy()` abort their owned signals, suppress stale

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.48.0",
+  "version": "0.50.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/runtime/arcane/components/speech.html

@@ -1912,9 +1912,11 @@
             ].includes(error?.code);
     }
 
-    function reportTranscriptionCancellation(reason, message) {
-        const operationId = transcriptionOperationId
-            || nextSpeechOperationId('transcription');
+    function reportTranscriptionCancellation(
+        reason,
+        message,
+        operationId = transcriptionOperationId || nextSpeechOperationId('transcription')
+    ) {
         localStatus = {
             message,
             tone: ''
@@ -1940,6 +1942,10 @@
     }
 
     function cancelSTTOperation(reason) {
+        // A native error can clear the ambient ID before its capture actually ends.
+        const operationId = nativeCaptureSession?.operationId
+            || captureSession?.operationId
+            || transcriptionOperationId;
         const hadActiveOperation = recordingRequested
             || Boolean(captureSession)
             || Boolean(nativeCaptureSession)
@@ -1976,7 +1982,8 @@
                 String(reason || 'stt-transcription-cancelled'),
                 reason === 'component-destroyed'
                     ? 'Transcription stopped because the speech component was destroyed.'
-                    : 'Transcription stopped because the selected service became unavailable.'
+                    : 'Transcription stopped because the selected service became unavailable.',
+                operationId || undefined
             );
         }
         transcriptionOperationId = null;