arcane-os 0.75.0 → 0.77.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 0.77.0
+
+- Add `AI.prepareAudioOutput()` for synchronous, silent preparation of a reusable
+  WebAudio output. Observe its actual context state through immediate subscription
+  replay and `AI_AUDIO_OUTPUT_STATE_EVENT`; resume and dispose explicitly.
+- Add optional `audioOutput` to `playPreparedTTS()` so prepared narration borrows
+  that same output across plays. Completion and stop leave the borrowed context
+  open; omission preserves the existing per-playback context lifecycle.
+- Keep replacement, pending suspension, decoding, cancellation and disposal tied
+  to their actual output and playback owners. Cleanup failures remain observable
+  and failed context closure can be retried. Independent native speech, saved
+  audio and detached preparation retain their existing ownership.
+- Preparation plays no sound, creates no audio source, resumes no context,
+  changes no mute setting and loads no model. A running WebAudio context is not
+  a guarantee of future autoplay, native speech or HTML audio readiness. No
+  physical-GPU placement or native-engine change is included.
+
+## 0.76.0
+
+- Add public `textFormat:'plain'` to the `SpeechPlayback` constructor and
+  `prepare()` options. Preserve every prepared part's exact input through
+  audio-file, native and custom speech clients, including queued narration;
+  omitted selection retains the existing formatting cleanup.
+- Distinguish a current native utterance's non-error stopped completion from
+  initial preparation with `reason:'native-playback-stopped'` on the existing
+  `ready` event. Natural final completion remains `ended`; an error does not
+  establish native resource release.
+- Preserve per-part voices, ordered playback, cancellation, replay and silent
+  preparation. No model, dependency, native host or activation changes are
+  included. Focused source fixtures are authored separately from the selected
+  package verification; no live speech result is claimed.
+
 ## 0.75.0
 
 - Advertise whole-image `img2img` alongside `txt2img` for the built-in

package/README.md

@@ -20,7 +20,7 @@ selected SDK projection or an explicit live SDK source mount. Both profiles
 share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.75.0` SDK contract. Development applications declare
+This checkout defines the `0.77.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;
@@ -476,9 +476,10 @@ ordinary repeated punctuation remain literal. Complete synthesis calls may
 select `textFormat:'plain'` to preserve exact input: supply it in `prepareTTS`
 options or the payload of `fetchTTS`, provider-runtime TTS requests, or direct
 Kokoro requests. The SDK consumes this control before engine/host dispatch;
-omission keeps the default cleanup. Streaming narration and `SpeechPlayback`
-retain their existing formatting behavior. This option does not change the
-selected engine's input capacity or establish complete upstream synthesis. Original
+omission keeps the default cleanup. `SpeechPlayback` accepts the same option in
+its constructor or `prepare()` call and forwards each part's exact input.
+Streaming narration retains its existing formatting behavior. This option does
+not change the selected engine's input capacity or establish complete upstream synthesis. Original
 messages and caller payloads remain unchanged for display, storage, and model
 input. The `arcane-os/speech-text` entrypoint exports the same
 `MarkdownSpeech` streaming class and `stripSpeechFormatting()` one-pass helper

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

@@ -889,7 +889,7 @@ provider cleanup remains observable through that operation's settlement.
 
 ### Playback controls and independent lifetimes
 
-`ai.playPreparedTTS(prepared,{signal,onState})` returns
+`ai.playPreparedTTS(prepared,{signal,onState,audioOutput})` returns
 `{state,error,finished,pause(),resume(),stop()}` immediately. It uses the
 existing AI audio-clock scheduler and waits for each earlier segment before scheduling
 later audio. Ready adjacent buffers retain contiguous scheduling. Requested
@@ -902,8 +902,9 @@ states are `waiting`, `waiting-for-gesture`, `scheduled`, `paused`, `complete`,
 `stopped`, and `error`. Use `waiting-for-gesture` to present an audio-unlock
 control. A `false` result from `resume()` is not a first-segment-ready signal;
 inspect `state` and `error` to distinguish a stopped or unavailable context
-from browser gesture waiting. The ordinary playback path creates its audio
-context immediately, before the first audio segment is ready.
+from browser gesture waiting. With `audioOutput` omitted or `null`, playback
+creates its own audio context immediately, before the first segment is ready,
+and closes that context after completion, stop, cancellation, or failure.
 
 `finished` resolves `true` after natural playback completion and `false` after
 stop, playback cancellation, or failure. Real failures also reach the existing
@@ -931,6 +932,87 @@ preparations. A page that starts several preparations owns and observes every
 `ready` promise, even when it plays only one handle. Browser autoplay permission
 still applies; neither promise proves that a person heard the audio.
 
+### Prepare a silent reusable WebAudio output
+
+`ai.prepareAudioOutput()` synchronously returns an AI-owned output handle.
+It creates or reuses that AI's persistent WebAudio context and observes its
+actual state. Preparation stays silent: it does not resume the context, unmute
+speech, load a model, create an audio source, play a test sound, or install
+gesture listeners. It does not wait for speech preparation or provider readiness.
+
+The handle exposes `kind:'web-audio'`, live `state`, `contextState`, and `error`
+getters, `subscribe(listener)`, `resume()`, and `dispose()`. Repeated preparation
+returns the same handle until its output is disposed or its context closes.
+`contextState` is the platform context's current state, or `null` when unavailable;
+`error` retains the complete actual error, or `null`.
+
+| Output state | Meaning |
+| --- | --- |
+| `ready` | This WebAudio context is currently `running`. |
+| `suspended`, `interrupted`, or another platform state | The context reports that state; suspension alone does not establish a gesture requirement. |
+| `gesture-required` | A resume operation actually reported `NotAllowedError` while the context was not running. |
+| `unavailable` | Context creation failed; `error` contains the actual failure. |
+| `error` | An output operation failed; inspect the complete `error`. |
+| `disposing`, `disposed` | Owner disposal is in progress or has completed. |
+| `closed` | The underlying context has closed outside completed owner disposal. |
+
+`subscribe(listener)` immediately replays `{kind,state,contextState,error}` and
+then delivers state changes through the canonical AI event owner. It returns
+an idempotent unsubscribe function. The named export
+`AI_AUDIO_OUTPUT_STATE_EVENT` from `AI.js` is `'ai-audio-output-state'`; its
+canonical occurrences carry the same snapshot in `detail` and an output-specific
+`operationId`. Handle subscriptions select only their own output. Disposal or
+context closure releases those subscriptions after the terminal notification;
+a later handle subscription still receives the current snapshot immediately.
+
+`resume()` is an explicit asynchronous action for the application's user-gesture
+flow. It resolves `true` only when the context is actually running, and `false`
+when unavailable, disposed, superseded, or held by a paused prepared playback.
+A platform rejection rejects with its actual error and retains that failure in
+the output state. It does not unmute speech or load a model. Output readiness
+does not establish HTML audio readiness, native-speech readiness, future autoplay
+permission, available speech audio, or audible delivery.
+
+Pass the handle explicitly to borrow that exact output for prepared playback:
+
+```javascript
+// ai and prepared are the same AI owner and preparation used above.
+const audioOutput = ai.prepareAudioOutput();
+
+function observeNarrationOutput(listener) {
+  return audioOutput.subscribe(listener);
+}
+
+function resumeNarrationOutput() {
+  // Call from the application's user action and observe the returned promise.
+  return audioOutput.resume();
+}
+
+function playNarration() {
+  return ai.playPreparedTTS(prepared, {audioOutput});
+}
+
+function disposeNarrationOutput() {
+  // Call when this owner no longer needs the output; observe its promise.
+  return audioOutput.dispose();
+}
+```
+
+The selected handle must be live and belong to the same AI instance; another
+owner's, closed, or disposing output throws `TypeError`. Borrowed playback
+retains the same ordered scheduling, pause/resume, cancellation, and single-lane
+replacement behavior. Completion or stopping playback leaves the output open
+for reuse. Merely preparing an output does not change the omitted-option path.
+
+The application owns the output lifetime and calls `dispose()` when finished
+with it. Disposal stops playback bound to that context and any following work
+waiting on its clock, observes cleanup, and awaits the actual context close.
+It preserves detached preparation, saved audio, unrelated contexts, and model
+selection. Concurrent calls share the disposal promise. Actual cleanup or close
+errors reject and remain observable; a failed context close permits a later
+disposal retry. Stop/mute controls retain their existing playback/provider scope
+and do not replace this explicit output disposal.
+
 ## Stream chunks as they arrive
 
 Use the configured `ai` created above. Run this snippet from an owned user
@@ -1008,8 +1090,11 @@ waits for its next character or the final flush.
 state. `fetchTTS()`, provider-runtime TTS requests, direct Kokoro provider
 requests, and `SpeechPlayback` apply the same default cleanup to complete input.
 Complete-input APIs can explicitly select `textFormat:'plain'` as described
-below. The streaming `streamTTS()` options still ignore `textFormat`;
-streaming narration and `SpeechPlayback` keep their existing cleanup.
+below. `SpeechPlayback` accepts `textFormat:'plain'` in its constructor or
+`prepare()` options and forwards each prepared part's exact input through every
+supported speech client. Omitted options reuse its current selection; explicit
+`null` restores default cleanup. The streaming `streamTTS()` options still ignore
+`textFormat` and streaming narration keeps its existing cleanup.
 SDK-internal delegation carries `{speechInputPrepared:true}` outside the speech
 payload after its owner selects text treatment, preventing a second
 non-idempotent cleanup pass or cleanup of explicitly plain input.
@@ -1019,8 +1104,9 @@ playback timing are not changed by the filter.
 
 Direct native `provider.prepare()` and `provider.play()` preserve their complete
 `input` as supplied. The native route of `ai.prepareTTSPlayback()` also preserves
-that input; shared streaming and `SpeechPlayback` perform their existing cleanup
-before calling it. Choose the high-level narration path when that speech-only
+that input; shared streaming and default `SpeechPlayback` perform cleanup before
+calling it. Plain `SpeechPlayback` preserves the complete input instead.
+Choose the high-level narration path when that speech-only
 formatting cleanup is desired.
 
 The shared helper is public for code that needs the speech-only

package/docs/reference/inventory/package-api.json

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.74.0",
+  "sdkVersion": "0.76.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",

package/docs/reference/inventory/runtime-modules.json

@@ -10,13 +10,14 @@
   },
   "artifactCount": 93,
   "javascriptArtifactCount": 91,
-  "esmExportCount": 373,
+  "esmExportCount": 374,
   "artifacts": [
     {
       "file": "runtime/arcane/modules/AI.js",
       "name": "AI.js",
       "kind": "esm",
       "exports": [
+        "AI_AUDIO_OUTPUT_STATE_EVENT",
         "AI_BROWSER_SPEECH_CONFIGURATION_PROTOCOL",
         "AI_BROWSER_SPEECH_ERROR_CODES",
         "AI_BROWSER_SPEECH_EVENT_TYPES",
@@ -30,7 +31,7 @@
       "availability": "Browser + native bridge + TWiN Cloud",
       "protocol": "arcane-ai-browser-speech-configuration/1, AIProviderRuntime arcane-ai-provider/2 routes, globalThis.arcaneEvents, TWiN Cloud HTTPS, Arcane.ollama, Arcane.speech, Android WebView bridge",
       "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized Whisper STT and Kokoro TTS execution with default capacities 1 and 4 respectively, explicit provider-neutral execution snapshots through status(role,{execution:true}), sticky readiness, canonical window.user readiness without compatibility-event object-identity admission or polling, exact ordered structural calls with required arguments.message, atomic nonblank all-ID tool-result sequencing, complete all-choice streaming/data validation, native Ollama structural adaptation, complete-response then all validated tool callbacks then completion ordering, observed async callbacks, Blob/File transcription, default repeated-formatting-mark removal from cloned outbound TTS input, explicit textFormat:'plain' preservation for complete synthesis/preparation while streaming cleanup remains automatic and caller/visible content stays exact, immediate exact-segment synthesis, per-call voice/speed capture, optional final-segment pause on the existing audio clock, optional per-call terminal playback completion, detached preparation with complete semantic DBOPFS audio reuse and same-owner pending request sharing; each preparation owns its pending activation interest, final-interest cancellation aborts that activation while other interests preserve it, complete cache hits start no model, and cancellation after readiness leaves the ready model loaded; independent prepared playback without a model load for cached audio, ordered audio-clock scheduling, playable audio, active-generation TTS operation-failure routing, mute, and cancellation are normalized; provider/model/runtime/voice policy remains caller-owned. Both speech roles default execution.device to auto: webnn-npu when navigator.ml.createContext is exposed, then webgpu when navigator.gpu is exposed, then wasm for CPU execution. Failed backend loads clean up the pool before trying fresh Workers with the same prepared model and dtype; explicit devices never fall back. STT capacity only accepts 1; TTS accepts 1 through 4. Execution snapshots expose requestedDevice, selectedDevice, maxConcurrentRequests, and activeRequestCount for both roles; selectedDevice is null while unloaded and names the successful upstream session backend request when loaded. It does not prove every operation used the physical NPU: WebNN unsupported operations may use WASM, and compatibility depends on the browser, driver, hardware, and graph.",
-      "surface": "Native fetchTTS(payload,signal) and fetchSTT(audio,signal) forward caller cancellation separately from their complete Core speech payloads, normalize aborts to AbortError and suppress late results; actual engine interruption remains service-owned. prepareTTSPlayback(payload,signal) silently returns a real Blob or native-speech descriptor; native controls expose finished/released/state/error/pause/resume/stop, and actual release owns the playback lane. fetchTTS and durable prepareTTS report ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE for native voices. Request-local model overrides remain exact and never mutate the configured model. Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; default speech-input cleanup with SDK-internal preparation metadata and explicit complete-call textFormat:'plain' consumed before engine dispatch; `prepareTTS({parts,storage,identity,textFormat,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); `playPreparedTTS(prepared,{signal,onState})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
+      "surface": "Native fetchTTS(payload,signal) and fetchSTT(audio,signal) forward caller cancellation separately from their complete Core speech payloads, normalize aborts to AbortError and suppress late results; actual engine interruption remains service-owned. prepareTTSPlayback(payload,signal) silently returns a real Blob or native-speech descriptor; native controls expose finished/released/state/error/pause/resume/stop, and actual release owns the playback lane. fetchTTS and durable prepareTTS report ARCANE_AI_TTS_AUDIO_EXPORT_UNAVAILABLE for native voices. Request-local model overrides remain exact and never mutate the configured model. Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; `streamTTS(text,end,options={})` with optional voice, speed, pauseAfterMs, and waitForPlayback; default speech-input cleanup with SDK-internal preparation metadata and explicit complete-call textFormat:'plain' consumed before engine dispatch; `prepareTTS({parts,storage,identity,textFormat,signal,onState})` returning ordered segments, state, ready, getAudio(index), and cancel(); `prepareAudioOutput()` returning the persistent WebAudio handle {kind,state,contextState,error,subscribe,resume,dispose} without resume, unmute, model load, sources, sound, or gesture listeners; current-state replay and output-specific canonical `AI_AUDIO_OUTPUT_STATE_EVENT` (`ai-audio-output-state`), with ready only for an actually running context; explicit owner disposal observes context-bound cleanup and close; `playPreparedTTS(prepared,{signal,onState,audioOutput})` returning state, error, finished, pause(), resume(), and stop() with one playback lane per AI and observational state/error callbacks; explicit live same-AI audioOutput borrows its context until owner disposal, while omission or null preserves per-playback terminal close; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls; optional streamRequest toolText:{name,field} and onToolText(text,call,displayId) for decoded selected argument text with actual call identity, distinct from ordinary prose and terminal tool execution; synthesis/transcription and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
     },
     {
       "file": "runtime/arcane/modules/AIModelSelectionController.js",
@@ -1262,11 +1263,11 @@
         "default",
         "splitSpeechText"
       ],
-      "summary": "Preserves exact nonblank stored segment text; removes repeated formatting marks from only each outbound synthesis copy; eagerly submits complete parts to a capacity-advertising fetchTTS provider while keeping playback indexed; and retains serialized one-segment lookahead for other clients.",
+      "summary": "Preserves exact nonblank stored segment text; removes repeated formatting marks from the outbound synthesis copy by default or forwards exact input with constructor/prepare textFormat:'plain'; eagerly submits complete parts to a capacity-advertising fetchTTS provider while keeping playback indexed; and retains serialized one-segment lookahead for other clients.",
       "availability": "Browser + compatible AI/native bridge",
       "protocol": "AI.prepareTTSPlayback or AI.fetchTTS plus providerRuntime TTS execution capacity, native provider.prepare, or compatible serialized Arcane.speech.synthesize; globalThis.arcaneEvents, Blob URLs/audio element, and native playback controls",
-      "normalization": "Exact nonblank split/part input strings are preserved in mutable records. Each synthesis request clones that part, removes repeated formatting marks from only the outbound input, and carries SDK-internal preparation metadata to prevent a second cleanup pass. A capable provider receives complete segments immediately and owns bounded FIFO admission; URLs and playback stay in exact input order. Native/custom clients remain serialized. Canonical state dispatch precedes the optional synchronous onState callback. Cancellation, Replay recovery, Blob results, and lifecycle state are normalized; provider failures remain external.",
-      "surface": "prepareTTSPlayback or direct native provider.prepare may return silent native-speech descriptors. autoplay:false stays silent; actual completion advances ordered parts and failed cancellation retains controls until released. Replay preserves completed segments and retries only missing failed generation. SpeechPlayback class/default, mutable `SPEECH_VOICE_OPTIONS` records, mutable `SPEECH_VOICE_ALIASES` membership, `SPEECH_PLAYBACK_STATE_EVENT`, optional constructor `onState(detail)`, `splitSpeechText()`, canonical playback lifecycle events, cancellation, and destroy APIs."
+      "normalization": "Exact nonblank split/part input strings are preserved in mutable records. Each synthesis request copies that input, preserves it exactly for constructor/prepare textFormat:'plain' or applies default formatting cleanup, and carries SDK-internal preparation metadata to prevent a second cleanup pass. A capable provider receives complete segments immediately and owns bounded FIFO admission; URLs and playback stay in exact input order. Native/custom clients remain serialized. Canonical state dispatch precedes the optional synchronous onState callback. Cancellation, Replay recovery, Blob results, and lifecycle state are normalized; provider failures remain external.",
+      "surface": "prepareTTSPlayback or direct native provider.prepare may return silent native-speech descriptors. autoplay:false stays silent; actual completion advances ordered parts and failed cancellation retains controls until released. Current native finished:false without error reports ready with reason native-playback-stopped; natural final completion reports ended. Replay preserves completed segments and retries only missing failed generation. SpeechPlayback class/default, mutable `SPEECH_VOICE_OPTIONS` records, mutable `SPEECH_VOICE_ALIASES` membership, `SPEECH_PLAYBACK_STATE_EVENT`, optional constructor `onState(detail)`, `splitSpeechText()`, canonical playback lifecycle events, cancellation, and destroy APIs."
     },
     {
       "file": "runtime/arcane/modules/StaticDocumentCatalog.js",

package/docs/reference/runtime-modules.md

@@ -132,7 +132,7 @@ own asynchronous work, cancellation, and backpressure.
 | [`ScamRiskPolicy.js`](#scamriskpolicyjs) | esm | Combines deterministic scam signals with optional Arcane blocked-domain evidence and safety guidance. | Cross-host | Complete mutable results; blocked-domain policy requires `secure:true`. |
 | [`ScopedOPFSCache.js`](#scopedopfscachejs) | esm | Provides a narrow exact-key JSON cache inside one app-owned OPFS namespace. | Browser / native WebView | Filename-safe keys, complete JSON values, and malformed-cache cleanup normalized; storage errors mixed. |
 | [`ScreenCapture.js`](#screencapturejs) | esm | Captures a display surface as image, video, or GIF with explicit lifecycle events. | Browser / native WebView | State/events normalized; permission and codec errors mixed. |
-| [`SpeechPlayback.js`](#speechplaybackjs) | esm | Admits complete speech segments to a capacity-advertising provider immediately, retains serialized native/custom lookahead, and plays every result in exact indexed order. | Browser + native bridge | Stored part text stays exact; the outbound speech-input copy receives automatic formatting-mark cleanup; provider/media failures remain mixed. |
+| [`SpeechPlayback.js`](#speechplaybackjs) | esm | Admits complete speech segments to a capacity-advertising provider immediately, retains serialized native/custom lookahead, and plays every result in exact indexed order. | Browser + native bridge | Stored part text stays exact; outbound input receives default formatting cleanup or explicit plain-text preservation; provider/media failures remain mixed. |
 | [`StaticDocumentCatalog.js`](#staticdocumentcatalogjs) | esm | Loads a positive static document inventory with cache, search, and complete context. | Browser / native WebView / server with fetch | Mutable complete catalog/content normalization; malformed data and transport failures remain visible. |
 | [`SystemAppearance.js`](#systemappearancejs) | esm | Reads or applies native appearance, returning an explicit unsupported result when the bridge or optional namespace is absent. | Browser/native hybrid | Exact absent optional namespace normalized with its complete error; partial-method and genuine native errors preserved. |
 | [`SystemPlatformPresentation.js`](#systemplatformpresentationjs) | classic-script | Maps kernel names to presentation labels/classes without granting platform authority. | Browser / native WebView classic script | Fully normalized presentation only. |
@@ -171,10 +171,11 @@ default `AI`; read-only `providerRuntime`, `speechActivationPending`, `browserSp
 read-only `ttsSegmentation`, `configureTTSSegmentation()`,
 `streamTTS(text='',end=false,options={})`,
 `prepareTTS({parts,textFormat,storage,identity,signal,onState})`,
-`playPreparedTTS(prepared,{signal,onState})`,
+`prepareAudioOutput()`, `playPreparedTTS(prepared,{signal,onState,audioOutput})`,
 `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`.
+installs `window.ai`, and emits `ai-ready`, `ai-tts-failure`, and
+`AI_AUDIO_OUTPUT_STATE_EVENT` (`'ai-audio-output-state'`).
 
 `fetch(...)` and `fetchRequest(options)` are asynchronous complete-response
 entry points. `streamMessage(...)` and `streamRequest(options)` deliver
@@ -496,7 +497,7 @@ cancelling one handle does not cancel another active matching caller.
 Preparation cancellation prevents later synthesis and releases its activation
 interest. The provider's operation remains responsible for actual cleanup.
 
-`playPreparedTTS(prepared,{signal,onState})` can attach immediately. Its returned
+`playPreparedTTS(prepared,{signal,onState,audioOutput})` can attach immediately. Its returned
 `{state,error,finished,pause(),resume(),stop()}` handle schedules segments in
 their original order using the existing AI audio clock. `finished` resolves `true` after
 natural completion and `false` after stop, cancellation, or failure; genuine
@@ -521,6 +522,38 @@ model even when the AI starts muted. Missing audio alone requests the shared
 TTS readiness path. See [prepared narration](ai/browser-speech.md#prepare-narration-once-and-replay-stored-audio)
 for full record shapes, storage ownership, and a complete example.
 
+`prepareAudioOutput()` synchronously creates or reuses this AI's persistent
+WebAudio context and returns the same handle until disposed or closed. It is
+silent: no resume, unmute, model load, source creation, test sound, or gesture
+listener registration. The handle exposes `kind:'web-audio'`, current
+`state`, `contextState`, and complete `error` getters, plus
+`subscribe(listener)`, `resume()`, and `dispose()`.
+`subscribe` immediately replays `{kind,state,contextState,error}`, observes
+future changes for this output, and returns an idempotent unsubscribe function.
+The named `AI_AUDIO_OUTPUT_STATE_EVENT` export identifies canonical occurrences
+with that snapshot as `detail` and an output-specific `operationId`.
+
+Output `ready` means its context is actually `running`, independently of model
+readiness, HTML audio, native speech, future autoplay permission, or audible
+delivery. Other states are the platform's current state (including `suspended`
+or `interrupted`), `gesture-required` after an actual `NotAllowedError`,
+`unavailable` when context creation fails, `error`, `disposing`, `disposed`,
+or `closed`. Explicit `resume()` resolves a boolean for actual readiness;
+unavailable/disposed, superseded, or paused-playback cases resolve `false`.
+Platform rejection rejects with the actual error and retains observable state.
+
+Pass `{audioOutput}` to `playPreparedTTS` to borrow that same AI's live output;
+another owner's, closed, or disposing handle throws `TypeError`. Borrowed
+playback leaves the context open after completion or stop. Omission or `null`
+preserves the existing per-playback context and terminal context close.
+Owner `dispose()` stops context-bound playback and dependent clock work,
+observes cleanup, and awaits actual close without cancelling detached speech
+preparation or deleting saved audio. Concurrent disposal calls share their
+promise; failures remain observable and a failed close can be retried.
+Disposal/closure releases handle subscriptions after their final notification.
+See [silent reusable output](ai/browser-speech.md#prepare-a-silent-reusable-webaudio-output)
+for state details and usage.
+
 Streaming speech retains sentence
 segmentation by default. `configureTTSSegmentation({punctuation,wordCadence})`
 accepts `punctuation:'sentence'|'any'|'none'` and a `wordCadence` that is either
@@ -3973,8 +4006,8 @@ console.log(Object.keys(module));
 
 Preserves exact nonblank text, admits complete speech segments according to the
 selected client's advertised capacity, and plays indexed HTML audio in exact
-input order. Stored parts remain exact; only each outbound synthesis payload
-copy receives automatic formatting-mark cleanup.
+input order. Stored parts remain exact; each outbound synthesis payload copy
+receives default formatting-mark cleanup or explicit plain-text preservation.
 
 ### Public surface
 
@@ -3992,6 +4025,7 @@ new SpeechPlayback({
   model=null,
   voice=null,
   responseFormat=null,
+  textFormat=null,
   speed=1,
   onState=()=>{},
   createObjectURL,
@@ -4006,7 +4040,7 @@ 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,
+`prepare({key,parts,model,voice,responseFormat,textFormat,
 speed,autoplay=true})` uses only caller-supplied model, voice, and response-format
 values; those three omitted values remain omitted so the selected AI/model
 catalog may provide its documented defaults. Speed defaults to `1`, is normalized
@@ -4020,13 +4054,25 @@ There is no hard-coded model, response format, voice, or cloud/browser fallback.
 the caller's exact string in one mutable array without trimming, splitting, or
 freezing it. `prepare()` likewise preserves each nonblank part's exact `input`
 string while normalizing its other playback fields into a new mutable record.
-At synthesis time, `requestSpeech()` copies that record, removes repeated same
-formatting marks from only the outbound `input`, and delegates with the
+At synthesis time, default `requestSpeech()` behavior copies that record, removes
+repeated same formatting marks from only the outbound `input`, and delegates with the
 SDK-internal `{speechInputPrepared:true}` argument so downstream SDK boundaries
 do not apply the non-idempotent filter again. Original part objects, stored
 parts, displayed text, and all non-input payload fields remain unchanged. The
 class applies no part-count, character-count, pause, or input upper cap.
 
+Set `textFormat:'plain'` in the constructor or `prepare()` options to forward
+every part's exact `input` without formatting cleanup. The selection is captured
+with the prepared parts, including queued and lookahead requests. A `prepare()`
+override becomes the instance's selection for later omitted options, like its
+voice and speed options; explicit `null` or another non-`undefined` value other
+than `'plain'` selects the existing cleanup. Plain requests carry `textFormat:'plain'` to every
+supported speech client along with the existing internal preparation marker;
+default requests keep their existing payload shape. Original part objects stay
+unchanged, and per-part voices, ordering, cancellation, and silent
+`autoplay:false` preparation retain their existing behavior. This controls SDK
+text treatment, not the selected speech engine's pronunciation or input capacity.
+
 ### Admission and playback order
 
 When `speech` exposes both `fetchTTS(payload, signal)` and
@@ -4053,6 +4099,11 @@ 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.
+When current native `finished` resolves `false` without an error, the existing
+`ready` event carries `reason:'native-playback-stopped'` and its operation ID;
+initial prepared `ready` has no such reason. Only natural completion of the last
+part emits `ended`. Errors never establish native resource release; failed
+controls remain retained through their existing `released` boundary.
 Selecting a native part hides and clears the HTML audio source while preserving
 the same shared playback state events and complete original parts.
 
@@ -4087,7 +4138,7 @@ Exact lifecycle reasons are `playback-replaced`, `playback-stopped`,
 `playback-destroyed`, `speech-playback-cancelled`,
 `speech-synthesis-superseded`, `speech-synthesis-cancelled`,
 `speech-synthesizer-unavailable`, `synthesized-audio-contract-mismatch`,
-`audio-playback-rejected`, `audio-autoplay-rejected`,
+`audio-playback-rejected`, `audio-autoplay-rejected`, `native-playback-stopped`,
 `speech-playback-request-contract-mismatch`, and
 `speech-synthesis-rejected`, as applicable to the emitted state.
 

package/docs/reference/sdk-api.md

@@ -8357,7 +8357,8 @@ mediaType}` and copies the supplied view at acceptance. Its explicit finite
 `strength` is from `0` through `1`, takes precedence over model/parameter
 defaults and is never clamped. It decodes in the existing worker and uses the
 same selected context, queue, progress, cancellation and complete result
-contract. SD1.4 advertises `txt2img` and `img2img`. See the
+contract. SD1.4 and [SDXL Base 1.0](local-image-sdxl.md#edit-a-whole-image)
+advertise `txt2img` and whole-image `img2img`. See the
 [editing contract](local-image-editing.md#core-and-native-request) for supported
 PNG input, native preprocessing, alpha and strength-zero semantics; the
 original file remains unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.75.0",
+  "version": "0.77.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -125,7 +125,7 @@
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/app-selection.test.mjs test/contracts.test.mjs test/conversation-closing-report.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/native-windows-icon.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
     "test:functional": "node ./bin/arcane-test.mjs test/ai-ollama-readiness.test.mjs test/core-ollama-lifecycle.test.mjs test/ai-request-model.test.mjs test/ai-request-retry.test.mjs test/ai-stream-cancellation.test.mjs test/browser-decisions.test.mjs test/browser-kokoro-complete-input.test.mjs test/browser-speech-providers.test.mjs test/browser-speech-artifacts.test.mjs test/browser-speech-resource-bridge.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/chat-input.test.mjs test/chat-stream-speech.test.mjs test/chat-transcript-scroll.test.mjs test/chat-transient-retention.test.mjs test/cli.test.mjs test/continuous-voice-capture.test.mjs test/codex-app-server.test.mjs test/mcp-stdio-server.test.mjs test/core-classic-source.test.mjs test/core-client.test.mjs test/core-client-installation.test.mjs test/core-ai-installation.test.mjs test/core-llama-lifecycle.test.mjs test/core-development.test.mjs test/core-host.test.mjs test/core-shared-host.test.mjs test/core-model-assets.test.mjs test/core-native-services.test.mjs test/core-packaged-web.test.mjs test/core-runtime.test.mjs test/core-stdio.test.mjs test/dbopfs-committed-events.test.mjs test/dbopfs-document-library.test.mjs test/dbopfs-model-resources.test.mjs test/dbopfs-png.test.mjs test/dbopfs.test.mjs test/dev-server.test.mjs test/dev-pwa.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/file-preview.test.mjs test/import-map.test.mjs test/local-image-editing.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/markdown-editor.test.mjs test/markdown-media.test.mjs test/markdown-source-map.test.mjs test/modal.test.mjs test/model-resource-bridge.test.mjs test/native-decisions.test.mjs test/native-onnx.test.mjs test/native-module-packaging.test.mjs test/native-module-resource-references.test.mjs test/packaging.test.mjs test/pwa-packaging.test.mjs test/pwa-client.test.mjs test/pwa-install.test.mjs test/pwa-worker.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/rendered-print.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/theme-manager.test.mjs test/twin-cloud-images.test.mjs test/twin-cloud.test.mjs test/websocket-client-import-map.test.mjs test/websocket.test.mjs test/update-check.test.mjs test/user-explicit-updates.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/installed-package-runtime.test.mjs test/root-app-layout.test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-macos-provider.test.mjs test/native-plan.test.mjs test/native-portable-provider.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/browser-wasm-cpu.test.mjs test/wllama-webgpu-runtime.test.mjs",
-    "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/html-import-packaged-script.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
+    "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/html-import-registration.test.mjs test/html-import-packaged-script.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/prepared-speech.test.mjs test/ai-audio-output.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",
     "check:release": "node tools/check-source.mjs --package-only && npm run test:release",
     "pack:local": "npm pack --ignore-scripts",

package/runtime/arcane/modules/AI.js

@@ -51,6 +51,7 @@ credentials='omit';
 const BUILT_IN_AI_SERVICES=new Set(['TWIN','OLLAMA','LOCAL_SPEACH']);
 const AI_REASONING_EFFORTS=new Set(['none','low','medium','high','max']);
 export const AI_READY_EVENT='ai-ready';
+export const AI_AUDIO_OUTPUT_STATE_EVENT='ai-audio-output-state';
 const AI_TTS_FAILURE_EVENT='ai-tts-failure';
 export const AI_INITIALIZATION_ERROR_CODES=completeValue({
     userReadyRegistrationCollision:
@@ -1128,6 +1129,7 @@ class AI {
                 eventTypes:completeValue(
                     [
                         AI_READY_EVENT,
+                        AI_AUDIO_OUTPUT_STATE_EVENT,
                         AI_TTS_FAILURE_EVENT,
                         ...Object.values(AI_BROWSER_SPEECH_EVENT_TYPES)
                     ]
@@ -1183,8 +1185,12 @@ class AI {
     #stopOllamaReady=null;
     #ttsSegmentation={...DEFAULT_TTS_SEGMENTATION};
     #preparedSpeechPlaybacks = new Set();
+    #activePreparedSpeechPlayback = null;
     #nativeSpeechPlaybacks = new Set();
     #speechUnlockContext = null;
+    #speechResumeContext = null;
+    #audioOutput = null;
+    #audioOutputSequence = 0;
 
     #traceSpeech(phase,detail={}){
         if(!arcaneLogging.enabled)return null;
@@ -6434,7 +6440,7 @@ class AI {
         );
     }
 
-    playPreparedTTS(prepared, {signal = null, onState = null} = {}) {
+    playPreparedTTS(prepared, {signal = null, onState = null, audioOutput = null} = {}) {
         if(!is.array(prepared?.segments) || !is.function(prepared?.getAudio)) {
             throw new TypeError('AI.playPreparedTTS requires a speech preparation handle.');
         }
@@ -6442,9 +6448,19 @@ class AI {
         if(onState !== null && !is.function(onState)) {
             throw new TypeError('Prepared playback onState must be a function when provided.');
         }
+        const output = audioOutput === null ? null : this.#audioOutput;
+        if(audioOutput !== null && (output?.handle !== audioOutput
+            || output.disposing || output.disposed || !output.context
+            || output.context.state === 'closed')) {
+            throw new TypeError('Prepared playback requires a live audio output from this AI.');
+        }
         // One playback lane per AI; detached preparation has its own lifetime.
         this.stopAudio();
-        const group = {jobs: [], context: null, paused: false, stopped: false, state: 'waiting', error: null};
+        const group = {
+            jobs: [], context: output?.context ?? null, output,
+            paused: false, stopped: false, state: 'waiting', error: null
+        };
+        this.#activePreparedSpeechPlayback = group;
         const completions = [];
         const generation = this.speechGeneration;
         this.#traceSpeech('playPreparedTTS.call', {segments: prepared.segments});
@@ -6464,8 +6480,16 @@ class AI {
         function stopPreparedPlayback() {
             if(group.stopped) return false;
             group.stopped = true;
-            runtime.speechResumeAttempt += 1;
-            runtime.speechResumePending = false;
+            if(runtime.#activePreparedSpeechPlayback === group) {
+                runtime.#activePreparedSpeechPlayback = null;
+                runtime.speechResumeAttempt += 1;
+                runtime.speechResumePending = false;
+                if(runtime.#speechUnlockContext === group.context) runtime.#clearSpeechUnlock();
+                if(runtime.speechScheduleContext === group.context) {
+                    runtime.speechScheduleContext = null;
+                    runtime.speechScheduleTime = 0;
+                }
+            }
             publishPreparedPlaybackState('stopped');
             for(const job of group.jobs) {
                 if(job.state === 'complete') continue;
@@ -6481,13 +6505,10 @@ class AI {
                 }
                 runtime.#cancelSpeechJob(job);
             }
-            if(runtime.speechScheduleContext === group.context) {
-                runtime.speechScheduleContext = null;
-                runtime.speechScheduleTime = 0;
-            }
             runtime.#requestSpeechPlayback();
             return true;
         }
+        group.stop = stopPreparedPlayback;
         const control = {
             finished: null,
             get state() { return group.state; },
@@ -6496,9 +6517,23 @@ class AI {
                 if(group.stopped || !group.context || group.context.state === 'closed') return false;
                 group.paused = true;
                 if(runtime.#speechUnlockContext === group.context) runtime.#clearSpeechUnlock();
-                await group.context.suspend();
-                if(!group.stopped) publishPreparedPlaybackState('paused');
-                return true;
+                let suspension;
+                try {
+                    suspension = Promise.resolve(group.context.suspend());
+                    if(output) output.suspending = suspension;
+                    await suspension;
+                    if(group.stopped || generation !== runtime.speechGeneration) return false;
+                    publishPreparedPlaybackState('paused');
+                    return true;
+                } catch(error) {
+                    if(output) {
+                        output.reportError(error);
+                        if(!group.stopped) group.fail(error);
+                    }
+                    throw error;
+                } finally {
+                    if(output?.suspending === suspension) output.suspending = null;
+                }
             },
             async resume() {
                 if(group.stopped || !group.context || group.context.state === 'closed') return false;
@@ -6558,15 +6593,18 @@ class AI {
             async function finishPreparedPlayback(results) {
                 const completed = !group.stopped && results.every(Boolean);
                 group.stopped = true;
+                if(runtime.#activePreparedSpeechPlayback === group) {
+                    runtime.#activePreparedSpeechPlayback = null;
+                    if(runtime.#speechUnlockContext === group.context) runtime.#clearSpeechUnlock();
+                    if(runtime.speechScheduleContext === group.context) {
+                        runtime.speechScheduleContext = null;
+                        runtime.speechScheduleTime = 0;
+                    }
+                }
                 publishPreparedPlaybackState(completed ? 'complete' : group.error ? 'error' : 'stopped');
                 signal?.removeEventListener('abort', stopPreparedPlayback);
                 runtime.#preparedSpeechPlaybacks.delete(control);
-                if(runtime.#speechUnlockContext === group.context) runtime.#clearSpeechUnlock();
-                if(runtime.speechScheduleContext === group.context) {
-                    runtime.speechScheduleContext = null;
-                    runtime.speechScheduleTime = 0;
-                }
-                if(group.context && group.context.state !== 'closed') {
+                if(!output && group.context && group.context.state !== 'closed') {
                     try {
                         await group.context.close();
                     } catch(error) {
@@ -6577,17 +6615,25 @@ class AI {
                 return completed;
             }
         );
+        group.finished = control.finished;
         signal?.addEventListener('abort', stopPreparedPlayback, {once: true});
         publishPreparedPlaybackState('waiting');
+        if(group.stopped) return control;
         if(signal?.aborted) {
             stopPreparedPlayback();
         } else if(group.jobs.length) {
             // Playing saved audio does not require activating a synthesis provider.
             this.muted = false;
             try {
-                const AudioContext = globalThis.AudioContext || globalThis.webkitAudioContext;
-                if(!is.function(AudioContext)) throw new TypeError('Audio playback is unavailable in this browser.');
-                group.context = new AudioContext();
+                if(output) {
+                    if(output.disposing || output.disposed || output.context.state === 'closed') {
+                        throw new Error('The prepared playback audio output has been disposed.');
+                    }
+                } else {
+                    const AudioContext = globalThis.AudioContext || globalThis.webkitAudioContext;
+                    if(!is.function(AudioContext)) throw new TypeError('Audio playback is unavailable in this browser.');
+                    group.context = new AudioContext();
+                }
                 this.resumeAudio(group.context, true).catch(
                     function failPreparedSpeechUnlock(error) {
                         for(const job of group.jobs) runtime.#failSpeechJob(job, error, 'playback-resume');
@@ -7096,12 +7142,209 @@ class AI {
         return new Blob(normalized.chunks,{type:normalized.type||this.audioType});
     }
 
+    prepareAudioOutput(){
+        if(this.#audioOutput && !this.#audioOutput.disposed
+            && this.#audioOutput.context?.state !== 'closed') {
+            return this.#audioOutput.handle;
+        }
+        const runtime = this;
+        const output = {
+            context: null, handle: null, error: null,
+            disposing: false, disposed: false, suspending: null,
+            resumeAttempt: 0, disposal: null, reportError: null, publish: null
+        };
+        const operationId = `${this.#events.instanceId}:audio-output:${++this.#audioOutputSequence}`;
+        const subscriptions = new Set();
+        function snapshot(){
+            const contextState = output.context?.state ?? null;
+            const state = output.disposed ? 'disposed'
+                : output.disposing ? 'disposing'
+                : !output.context ? 'unavailable'
+                : contextState === 'closed' ? 'closed'
+                : output.error?.name === 'NotAllowedError' && contextState !== 'running' ? 'gesture-required'
+                : output.error ? 'error'
+                : contextState === 'running' ? 'ready'
+                : contextState;
+            return {kind: 'web-audio', state, contextState, error: output.error};
+        }
+        function publish(){
+            runtime.#events.dispatch(AI_AUDIO_OUTPUT_STATE_EVENT, snapshot(), {operationId});
+        }
+        output.publish = publish;
+        function reportError(error){
+            output.error = error;
+            publish();
+            if(error?.name !== 'NotAllowedError') {
+                arcaneLogging.error('AI audio output operation failed.', error);
+            }
+        }
+        output.reportError = reportError;
+        function observeContextState(){
+            if(output.context.state === 'running') output.error = null;
+            publish();
+            if(output.context.state === 'closed' && !output.disposing) {
+                output.context.removeEventListener?.('statechange', observeContextState);
+                for(const unsubscribe of [...subscriptions]) unsubscribe();
+            }
+        }
+        function observeRejection(promise, attempt = null){
+            // The owner retains failures even when a caller observes state only.
+            promise.catch(function observeOutputFailure(error){
+                if(attempt === null || (attempt === output.resumeAttempt && !output.disposing && !output.disposed)) {
+                    reportError(error);
+                } else {
+                    arcaneLogging.error('A retired AI audio output resume failed.', error);
+                }
+            });
+            return promise;
+        }
+        async function resumeOutput(attempt){
+            const context = output.context;
+            if(!context || output.disposing || output.disposed || context.state === 'closed') return false;
+            // A pending suspend targets this exact context; resume must follow it.
+            if(output.suspending) await output.suspending;
+            if(output.disposing || output.disposed || attempt !== output.resumeAttempt) return false;
+            const paused = runtime.speechJobs.some(function hasPausedOutputPlayback(job){
+                return job.preparedPlayback?.context === context && job.preparedPlayback.paused;
+            });
+            if(paused) return false;
+            await context.resume();
+            if(output.disposing || output.disposed || attempt !== output.resumeAttempt) return false;
+            output.error = null;
+            publish();
+            if(context.state !== 'running') return false;
+            if(runtime.#speechUnlockContext === context) runtime.#clearSpeechUnlock();
+            if(runtime.speechJobs.some(function usesResumedOutput(job){
+                return job.audioContext === context || job.preparedPlayback?.context === context;
+            })) runtime.#requestSpeechPlayback();
+            return true;
+        }
+        async function disposeOutput(){
+            const context = output.context;
+            const errors = [];
+            const groups = new Set();
+            output.disposing = true;
+            output.resumeAttempt += 1;
+            publish();
+            if(context) {
+                if(runtime.#speechUnlockContext === context) runtime.#clearSpeechUnlock();
+                if(runtime.#speechResumeContext === context) {
+                    runtime.speechResumeAttempt += 1;
+                    runtime.speechResumePending = false;
+                    runtime.#speechResumeContext = null;
+                }
+                for(const job of [...runtime.speechJobs]) {
+                    if(job.preparedPlayback?.context === context) {
+                        groups.add(job.preparedPlayback);
+                    } else if(job.audioContext === context || job.sourceNode?.context === context
+                        || job.precedingSpeechContext === context) {
+                        if(job.sourceNode) {
+                            job.sourceNode.onended = null;
+                            if(job.sourceNode.__arcaneStarted) {
+                                try { job.sourceNode.stop(); }
+                                catch(error) { errors.push(error); }
+                            }
+                        }
+                        try { runtime.#cancelSpeechJob(job); }
+                        catch(error) { errors.push(error); }
+                    }
+                }
+                for(const group of groups) {
+                    try { group.stop(); }
+                    catch(error) { errors.push(error); }
+                }
+                if(runtime.speechScheduleContext === context) {
+                    runtime.speechScheduleContext = null;
+                    runtime.speechScheduleTime = 0;
+                }
+                if(runtime.audioContext === context) runtime.audioContext = null;
+                const completions = await Promise.allSettled(
+                    [...groups].map(function finishOutputPlayback(group){ return group.finished; })
+                );
+                for(const completion of completions) {
+                    if(completion.status === 'rejected') errors.push(completion.reason);
+                }
+                try {
+                    if(context.state !== 'closed') await context.close();
+                } catch(error) {
+                    errors.push(error);
+                    output.disposing = false;
+                    output.disposal = null;
+                    if(runtime.#audioOutput === output && runtime.audioContext === null) {
+                        runtime.audioContext = context;
+                    }
+                    throw errors.length === 1 ? errors[0] : new AggregateError(errors, 'AI audio output disposal failed.');
+                }
+                context.removeEventListener?.('statechange', observeContextState);
+            }
+            output.disposing = false;
+            output.disposed = true;
+            output.error = !errors.length ? null : errors.length === 1
+                ? errors[0] : new AggregateError(errors, 'AI audio output playback cleanup failed.');
+            publish();
+            for(const unsubscribe of [...subscriptions]) unsubscribe();
+            runtime.#requestSpeechPlayback();
+            if(errors.length) throw output.error;
+            return true;
+        }
+        output.handle = {
+            kind: 'web-audio',
+            get state(){ return snapshot().state; },
+            get contextState(){ return output.context?.state ?? null; },
+            get error(){ return output.error; },
+            subscribe(listener){
+                if(!is.function(listener)) throw new TypeError('Audio output subscriber must be a function.');
+                const remove = output.disposed || output.context?.state === 'closed' ? null : runtime.#events.subscribe(
+                    AI_AUDIO_OUTPUT_STATE_EVENT,
+                    function observeAudioOutput(occurrence){
+                        if(occurrence.operationId === operationId) listener(occurrence.detail);
+                    }
+                );
+                function unsubscribe(){
+                    remove?.();
+                    subscriptions.delete(unsubscribe);
+                }
+                if(remove) subscriptions.add(unsubscribe);
+                try { listener(snapshot()); }
+                catch(error) { arcaneLogging.error('AI audio output state observer failed.', error); }
+                return unsubscribe;
+            },
+            resume(){
+                const attempt = ++output.resumeAttempt;
+                return observeRejection(resumeOutput(attempt), attempt);
+            },
+            dispose(){
+                if(output.disposed) return output.disposal ?? Promise.resolve(true);
+                if(!output.disposal) {
+                    let resolve;
+                    let reject;
+                    output.disposal = observeRejection(new Promise(function retainOutputDisposal(accept, decline){
+                        resolve = accept;
+                        reject = decline;
+                    }));
+                    disposeOutput().then(resolve, reject);
+                }
+                return output.disposal;
+            }
+        };
+        this.#audioOutput = output;
+        try {
+            output.context = this.#getSpeechAudioContext();
+            output.context.addEventListener?.('statechange', observeContextState);
+            publish();
+        } catch(error) {
+            reportError(error);
+        }
+        return output.handle;
+    }
+
     #getSpeechAudioContext(){
         if(this.audioContext&&this.audioContext.state!=='closed'){
             return this.audioContext;
         }
 
-        const AudioContext=window.AudioContext||window.webkitAudioContext;
+        const AudioContext=globalThis.AudioContext||globalThis.webkitAudioContext
+            ||window.AudioContext||window.webkitAudioContext;
 
         if(!is.function(AudioContext)){
             throw new TypeError('Audio playback is unavailable in this browser.');
@@ -7396,6 +7639,7 @@ class AI {
         this.speechGeneration+=1;
         this.speechResumeAttempt+=1;
         this.speechResumePending=false;
+        this.#speechResumeContext=null;
         this.speechScheduleGeneration=this.speechGeneration;
         this.speechScheduleContext=null;
         this.speechScheduleTime=0;
@@ -7461,13 +7705,20 @@ class AI {
         let attempt=0;
         let context;
         let preparedGroup = null;
+        let output = null;
 
         try{
             context=audioContext||this.#getSpeechAudioContext();
+            output = this.#audioOutput?.context === context ? this.#audioOutput : null;
+            if(output?.disposing || output?.disposed) return false;
             preparedGroup = this.speechJobs.find(function findPreparedResumeOwner(job) {
                 return job.preparedPlayback?.context === context;
             })?.preparedPlayback ?? null;
             if(preparedGroup?.paused || preparedGroup?.stopped) return false;
+            if(output?.suspending) {
+                await output.suspending;
+                if(output.disposing || output.disposed || preparedGroup?.paused || preparedGroup?.stopped) return false;
+            }
             this.#traceSpeech('resumeAudio.context',{
                 callId,state:context.state,audioTime:context.currentTime,
                 sampleRate:context.sampleRate
@@ -7490,11 +7741,26 @@ class AI {
 
             attempt=++this.speechResumeAttempt;
             this.speechResumePending=true;
+            this.#speechResumeContext=context;
             await context.resume();
+            if(output?.disposing || output?.disposed) return false;
             if(preparedGroup?.stopped) return false;
             if(preparedGroup?.paused) {
-                await context.suspend();
-                this.speechResumePending = false;
+                let suspension;
+                try {
+                    suspension = Promise.resolve(context.suspend());
+                    if(output) output.suspending = suspension;
+                    await suspension;
+                } catch(error) {
+                    output?.reportError(error);
+                    throw error;
+                } finally {
+                    if(output?.suspending === suspension) output.suspending = null;
+                }
+                if(attempt === this.speechResumeAttempt) {
+                    this.speechResumePending = false;
+                    this.#speechResumeContext = null;
+                }
                 return false;
             }
             this.#traceSpeech('resumeAudio.resumed',{
@@ -7509,6 +7775,11 @@ class AI {
             }
 
             this.speechResumePending=false;
+            this.#speechResumeContext=null;
+            if(output) {
+                output.error = null;
+                output.publish();
+            }
 
             if(context.state==='running'){
                 this.#clearSpeechUnlock();
@@ -7518,6 +7789,7 @@ class AI {
             }
         }catch(error){
             this.#traceSpeech('resumeAudio.error',{callId,error,state:context?.state});
+            if(output?.disposing || output?.disposed) return false;
             if(preparedGroup?.stopped || preparedGroup?.paused) return false;
             if(attempt&&attempt!==this.speechResumeAttempt){
                 return context?.state==='running';
@@ -7525,7 +7797,9 @@ class AI {
 
             if(attempt===this.speechResumeAttempt){
                 this.speechResumePending=false;
+                this.#speechResumeContext=null;
             }
+            output?.reportError(error);
             if(preparedGroup && error?.name !== 'NotAllowedError') {
                 for(const job of preparedGroup.jobs) this.#failSpeechJob(job, error, 'playback-resume');
                 return false;
@@ -7600,6 +7874,9 @@ class AI {
             const playbackContext=sourceNode?.context
                 ||audioContext
                 ||this.#getSpeechAudioContext();
+            // Retain the actual output before asynchronous decoding so disposal
+            // can cancel this job without cancelling unrelated synthesis.
+            job.audioContext=playbackContext;
             const audioBlob=new Blob(audioChunks,{type:audioType});
             const arrayBuffer=await audioBlob.arrayBuffer();
             const audioBuffer=await playbackContext.decodeAudioData(arrayBuffer);
@@ -7683,12 +7960,17 @@ class AI {
         const deadline=this.speechScheduleTime;
         if(!context||deadline<=context.currentTime)return Promise.resolve(true);
         const signal=job.abortController.signal;
+        job.precedingSpeechContext=context;
         return new Promise(function waitForScheduledSpeechGap(resolve,reject){
             let timer=null;
+            let settled=false;
             function finish(value,error=null){
+                if(settled)return;
+                settled=true;
                 globalThis.clearTimeout(timer);
                 signal.removeEventListener('abort',cancel);
                 context.removeEventListener('statechange',schedule);
+                if(job.precedingSpeechContext===context)job.precedingSpeechContext=null;
                 if(error)reject(error);
                 else resolve(value);
             }
@@ -7755,7 +8037,8 @@ class AI {
                     // the next turn, including when it follows buffered audio.
                     if(index!==0||job.state!=='ready')break;
                     if(!await this.#waitForPrecedingSpeechClock(job)
-                        ||job.generation!==this.speechGeneration||this.muted){
+                        ||job.generation!==this.speechGeneration||this.muted
+                        ||['cancelled','failed'].includes(job.state)){
                         return this.#cancelSpeechJob(job);
                     }
                     job.state='scheduled';
@@ -7783,6 +8066,10 @@ class AI {
                 const audioContext=job.sourceNode.context||job.audioContext;
 
                 if(job.preparedPlayback?.paused) break;
+                if(this.#audioOutput?.context === audioContext && this.#audioOutput.suspending) {
+                    this.resumeAudio(audioContext, false);
+                    return scheduled;
+                }
 
                 if(audioContext.state!=='running'){
                     this.#waitForSpeechGesture(null,audioContext);
@@ -7871,6 +8158,7 @@ class AI {
             return false;
         }finally{
             this.speechPlaybackStarting=false;
+            const output = this.#audioOutput;
             const nextJob=this.speechJobs.find(function findFirstUnscheduledSpeechJob(job){
                 return job.state!=='scheduled';
             });
@@ -7879,6 +8167,10 @@ class AI {
                 !this.muted
                 &&!this.speechAwaitingGesture
                 &&!this.speechResumePending
+                &&!this.speechJobs.some(function hasPendingOutputSuspension(job){
+                    return output?.suspending && (job.audioContext === output.context
+                        || job.preparedPlayback?.context === output.context);
+                })
                 &&!this.speechJobs.some(function hasPausedPreparedPlayback(job) {
                     return job.preparedPlayback?.paused;
                 })

package/runtime/arcane/modules/SpeechPlayback.js

@@ -42,7 +42,7 @@ function splitSpeechText(value=''){
     return text.trim()?[text]:[];
 }
 
-function normalizeParts(parts,defaultVoice=null,defaultSpeed=1){
+function normalizeParts(parts,defaultVoice=null,defaultSpeed=1,textFormat=null){
     if(!is.array(parts)||!parts.length){
         throw new TypeError('Narration text cannot be blank. The full visual content remains available.');
     }
@@ -63,6 +63,7 @@ function normalizeParts(parts,defaultVoice=null,defaultSpeed=1){
         if(!is.finite(speed)||speed<=0)throw new RangeError('Every speech segment requires a positive speech speed.');
         return {
             input,
+            ...(textFormat==='plain'?{textFormat:'plain'}:{}),
             pauseAfterMs,
             role:String(candidate?.role||'narration'),
             speed,
@@ -425,6 +426,7 @@ class SpeechPlayback{
         model=null,
         voice=null,
         responseFormat=null,
+        textFormat=null,
         speed=1,
         onState=function noop(){},
         createObjectURL,
@@ -485,6 +487,7 @@ class SpeechPlayback{
         this.responseFormat=responseFormat===null||responseFormat===undefined
             ?null
             :String(responseFormat);
+        this.textFormat=textFormat==='plain'?'plain':null;
         this.speed=normalizedSpeed;
         this.key='';
         this.state='idle';
@@ -622,10 +625,13 @@ class SpeechPlayback{
     }
 
     async requestSpeech(part,signal){
-        const input=stripSpeechFormatting(part.input);
+        const input=part.textFormat==='plain'
+            ?part.input
+            :stripSpeechFormatting(part.input);
         const preparation={speechInputPrepared:true};
         const payload={
             input,
+            ...(part.textFormat==='plain'?{textFormat:'plain'}:{}),
             speed:part.speed,
             ...(this.model?{model:this.model}:{}),
             ...(part.voice?{voice:part.voice}:{}),
@@ -799,6 +805,7 @@ class SpeechPlayback{
         model=this.model,
         voice=this.voice,
         responseFormat=this.responseFormat,
+        textFormat=this.textFormat,
         speed=this.speed,
         autoplay=true
     }={}){
@@ -843,10 +850,12 @@ class SpeechPlayback{
             this.model=selectedModel;
             this.voice=selectedVoice;
             this.responseFormat=selectedResponseFormat;
+            this.textFormat=textFormat==='plain'?'plain':null;
             normalized=normalizeParts(
                 is.function(parts)?parts():parts,
                 selectedVoice,
-                numericSpeed
+                numericSpeed,
+                this.textFormat
             );
             this.parts=normalized;
         }catch(error){
@@ -1036,7 +1045,12 @@ class SpeechPlayback{
                 playback.abortControllers.delete(active.controller);
                 if(completed===true)return await playback.advance();
                 if(active.control.error)playback.fail(active.control.error);
-                else playback.emit('ready',playback.message('stopped'));
+                else playback.emit(
+                    'ready',
+                    playback.message('stopped'),
+                    playback.key,
+                    {reason:'native-playback-stopped'}
+                );
                 return false;
             }catch(error){
                 console.error('[Arcane speech playback] Native speech failed.',error);