arcane-os 0.76.0 → 0.77.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # 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

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.76.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;

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

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

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.75.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",

package/docs/reference/runtime-modules.md

@@ -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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.76.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;
                 })