arcane-os 0.5.11 → 0.5.12

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## Unreleased
+
+## 0.5.12
+
+- Add optional `voice`, `speed`, `pauseAfterMs`, and `waitForPlayback` fields to
+  `AI.streamTTS(text, end, options)`. Complete passages can enter the existing
+  segmented generation queue immediately, retain their authored pauses on the
+  audio clock, and await their own playback completion. Existing calls still
+  return after preparation; stop and terminal failure settle playback waits
+  as `false`, while autoplay permission waiting remains pending.
+- Restore `AI.fetch(...)` and `AI.streamMessage(...)` after their unintended
+  removal during source cleanup. Their existing signatures, callbacks, return
+  behavior, and private inference plumbing remain available alongside
+  `fetchRequest({...})` and `streamRequest({...})`; callers do not need to
+  migrate. Restore chat-memory callers and document both public forms as
+  sharing the current provider implementations.
+- Update maintained SDK references and their generated pages, omit obsolete
+  provider context-token guidance, and describe current native defaults and
+  Winlogon bindings without treating them
+  as retired SDK APIs. Native Core implementations and upstream dependencies
+  are not changed by this SDK cleanup.
+
 ## 0.5.11
 
 - Default browser Kokoro TTS to four concurrent synthesis slots in both the

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.5.11` SDK contract. Applications pin one exact npm
+This checkout defines the `0.5.12` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -35,7 +35,7 @@ Create one browser application, install its pinned SDK, and start its source
 server:
 
 ```bash
-npx arcane-os@0.5.11 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.5.12 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 npm run dev
@@ -297,7 +297,7 @@ uses the same controller for automatic memory extraction.
 Create a new repository-shaped Arcane application with the exact stable SDK:
 
 ```bash
-npx arcane-os@0.5.11 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.5.12 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run dev
@@ -307,7 +307,7 @@ To enroll an existing repository, install the exact SDK and initialize only
 missing Arcane files:
 
 ```bash
-npm install --save-dev --save-exact arcane-os@0.5.11
+npm install --save-dev --save-exact arcane-os@0.5.12
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -323,7 +323,7 @@ npm exec -- arcane-os targets
 No global SDK install or standalone Arcane CLI is required. The application
 repository's exact npm dependency and lockfile own the CLI and toolchain version.
 
-Use `npx arcane-os@0.5.11` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.5.12` for the initial bootstrap because it names this npm
 package explicitly; bare `npx arcane` outside an installed project could resolve
 a different package. Both installed commands invoke the same headless toolchain.
 Project-local npm scripts use the SDK pinned by that app's `package-lock.json`,
@@ -343,7 +343,7 @@ node ./bin/arcane.mjs new local-app --path ../local-app --target portable --git
 
 # From the generated app repository
 cd ../local-app
-npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.5.11.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.5.12.tgz
 npm ci
 ```
 
@@ -352,7 +352,7 @@ same location. The lockfile retains the selected package dependency while
 Arcane uses the installed package name and version. Local directory `file:` dependencies are not
 accepted because npm may install them as links; use a packed `.tgz`. A GitHub
 runner also needs that tarball at the locked path. After publication, replace
-the local declaration with the exact `arcane-os@0.5.11` registry package and
+the local declaration with the exact `arcane-os@0.5.12` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -491,7 +491,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.5.11` exposes one browser target and five explicitly paired
+Version `0.5.12` exposes one browser target and five explicitly paired
 native development targets: a non-runnable portable directory, a
 Windows x64 unsigned-local-test EXE bundle, Linux x64 and Linux ARM64
 unsigned-local-test DEBs, and an Android development-signed APK. The

package/docs/architecture.md

@@ -279,7 +279,7 @@ paths are withheld from the native provider. The provider copies the complete
 selected release rather than accepting an unrelated source path. Verification
 is a separate explicit operation for a selected release artifact.
 
-The SDK `0.5.11` runtime requires Arcane `0.8.12` or newer. Compatibility
+The SDK `0.5.12` runtime requires Arcane `0.8.12` or newer. Compatibility
 is contractual rather than exact-version pinning: the prepared Core must meet
 the highest minimum declared by the runtime, selected app, and bundled app
 dependencies; keep each app's Arcane protocol generation; and provide every

package/docs/reference/README.md

@@ -17,7 +17,7 @@ high-level page links to the relevant deep section instead of repeating it.
 Install the SDK in your application:
 
 ```sh
-npm install --save-exact arcane-os@0.5.11
+npm install --save-exact arcane-os@0.5.12
 ```
 
 For your first AI call, follow the [TWiN Cloud quick start](ai/twin-cloud.md).
@@ -56,9 +56,9 @@ This repository contains explicitly versioned surfaces with different owners:
 
 | Surface | Source identity | Meaning |
 | --- | --- | --- |
-| SDK and CLI | `arcane-os` `0.5.11` | The Node.js toolchain, portable `arcane-os/event-manager`, `arcane-os/mail`, `arcane-os/preference-store`, and `arcane-os/speech-playback` entrypoints, plus the browser-only `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints in this checkout. |
-| Browser runtime | SDK `0.5.11`, protocol `arcane/1`, `runtime/` | The SDK-canonical runtime tree. `listRuntimeFiles()`, `readRuntimeFile()`, and `loadRuntimeRelease()` derive its current inventory directly from the selected directory. |
-| Browser SDK runtime | SDK `0.5.11`, `browser-runtime/` | The browser closure for events, Wllama, and Browser Speech mechanisms. `listSdkBrowserRuntimeFiles()`, `readSdkBrowserRuntimeFile()`, and `loadSdkBrowserRuntimeRelease()` derive its current inventory directly from the selected directory. |
+| SDK and CLI | `arcane-os` `0.5.12` | The Node.js toolchain, portable `arcane-os/event-manager`, `arcane-os/mail`, `arcane-os/preference-store`, and `arcane-os/speech-playback` entrypoints, plus the browser-only `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints in this checkout. |
+| Browser runtime | SDK `0.5.12`, protocol `arcane/1`, `runtime/` | The SDK-canonical runtime tree. `listRuntimeFiles()`, `readRuntimeFile()`, and `loadRuntimeRelease()` derive its current inventory directly from the selected directory. |
+| Browser SDK runtime | SDK `0.5.12`, `browser-runtime/` | The browser closure for events, Wllama, and Browser Speech mechanisms. `listSdkBrowserRuntimeFiles()`, `readSdkBrowserRuntimeFile()`, and `loadSdkBrowserRuntimeRelease()` derive its current inventory directly from the selected directory. |
 | Core reference snapshot | Arcane OS commit `567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e`, protocol `arcane/1` | The application-facing Core contract imported into `docs/reference/core/`, with SDK-local links and package-boundary notes added explicitly. |
 
 The SDK runtime source and Core reference have different owners. A browser
@@ -73,7 +73,7 @@ and the distinction between a documentation snapshot and the selected runtime.
 
 ## Installed documentation and release identity
 
-This reference accompanies `arcane-os@0.5.11`. The installed package includes
+This reference accompanies `arcane-os@0.5.12`. The installed package includes
 the maintained `docs/` tree and `examples/wasm-ai-demo/` source alongside
 README and CHANGELOG. Open `node_modules/arcane-os/docs/reference/README.md`
 for the matching local reference. The generated website and test suites remain

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

@@ -13,7 +13,7 @@ import map resolves `arcane/AI` and `arcane/DBOPFS`. These browser modules are
 not Node inference APIs. To create an application:
 
 ```bash
-npx arcane-os@0.5.11 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.5.12 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 npm run dev
@@ -89,8 +89,8 @@ speakButton.addEventListener('click', async function sayHello() {
   speakButton.disabled = true;
   try {
     await ai.setSpeechMuted(false); // Loads the selected TTS provider.
-    const complete = await ai.streamTTS('Hello from Arcane. ', true);
-    console.log('Speech preparation completed:', complete);
+    const prepared = await ai.streamTTS('Hello from Arcane. ', true);
+    console.log('Speech preparation completed:', prepared);
   } catch (error) {
     console.error(error.code, error.message);
   } finally {
@@ -101,10 +101,12 @@ speakButton.addEventListener('click', async function sayHello() {
 
 The first user action may download the selected runtime, model, and voice.
 The browser may require another audio-unlock gesture after a long load; the SDK
-retains prepared audio for that gesture. `streamTTS()` prepares and schedules
-playback; its promise is not proof that a listener heard the sound. It returns
-`false` for muted, stopped, or failed work, and the SDK reports full synthesis
-or playback failures in its console diagnostics and `ai-tts-failure` event.
+retains prepared audio for that gesture. The two-argument `streamTTS()` call
+resolves after preparing audio for scheduling; it does not wait for playback
+to end. It returns `false` when that preparation is muted, stopped, or fails.
+Later playback failures still reach the SDK's complete console diagnostics
+and `ai-tts-failure` event. Use the optional playback mode below when you need
+to wait for the submitted audio to end. Neither mode proves a listener heard it.
 
 To display complete high-level playback errors in this page, observe its
 existing event. The listener belongs to this example's one `ai` instance:
@@ -133,6 +135,70 @@ Ready adjacent audio buffers use contiguous AudioContext scheduling. Browser
 audio scheduling and selected WebGPU status do not prove physical GPU kernel
 overlap or audio quality. LLM and Whisper/STT capacity remains one.
 
+## Queue complete passages and wait for playback
+
+These options are available in SDK `0.5.12`.
+
+For a complete page or passage, call
+`ai.streamTTS(text, true, {voice, speed, pauseAfterMs, waitForPlayback:true})`.
+The existing AI queue owns segmentation, concurrent synthesis, ordered
+playback, and cancellation. Supply the exact text; there is no need for an
+application sentence queue, audio cache, or playback scheduler.
+
+This function uses the configured `ai` above. Its application-supplied
+`passages` argument is an ordered array of `{text, voice?, speed?, pauseAfterMs?}`
+records. An omitted voice uses the selected model's default voice, an omitted
+speed uses `ai.voiceSpeed`, and an omitted pause is zero. Each supplied voice
+must be supported by the selected model; speed must be positive. A pause is
+finite, nonnegative milliseconds and applies only after that passage's final
+extracted segment. These options do not change the instance defaults.
+
+```javascript
+async function speakPassages(passages) {
+    await ai.setSpeechMuted(false);
+    const pending = passages.map(
+        function queuePassage(passage) {
+            return ai.streamTTS(
+                passage.text,
+                true,
+                {
+                    voice: passage.voice,
+                    speed: passage.speed,
+                    pauseAfterMs: passage.pauseAfterMs,
+                    waitForPlayback: true
+                }
+            );
+        }
+    );
+    return Promise.all(pending);
+}
+```
+
+Call `speakPassages(...)` from your owned user action and handle errors with
+the earlier `error.code` / `error.message` pattern. The `map` submits every
+passage synchronously before `Promise.all` waits, so synthesis can use the
+provider's available capacity. The returned array has one boolean per passage
+in input order: `true` after all its extracted audio buffers naturally end,
+or `false` after terminal cancellation or failure. `ai.stopAudio()` cancels
+all speech owned by that AI instance and settles pending playback results
+`false`.
+
+The selected voice and speed are captured for segments extracted by that call.
+That includes any text left in the same AI instance's partial-stream buffer;
+finish the previous producer before starting a separate complete passage.
+Options are not retained with an unfinished `end:false` remainder. A later
+call supplies its own options, and `finishTTS()` uses defaults.
+A call extracting no segments returns `true` without waiting for earlier jobs.
+An already muted call returns `false`.
+
+Autoplay permission waiting and recoverable audio-resume attempts leave the
+playback promise pending until playback completes or is stopped. A failed
+resume of a closed `AudioContext` terminates the affected jobs and settles
+their playback results `false`. A trailing
+pause delays the next queued audio on the existing `AudioContext` clock; it
+does not delay the preceding promise after that passage's last buffer ends.
+The promise is a playback result, not a listener acknowledgement.
+
 ## Stream chunks as they arrive
 
 Use the configured `ai` created above. Run this snippet from an owned user

package/docs/reference/ai/twin-cloud.md

@@ -9,7 +9,7 @@ same managed browser imports as the [browser speech quick start](browser-speech.
 Create an application and start its source server:
 
 ```bash
-npx arcane-os@0.5.11 new hello-twin --path ./hello-twin --target browser
+npx arcane-os@0.5.12 new hello-twin --path ./hello-twin --target browser
 cd hello-twin
 npm install
 npm run dev

package/docs/reference/cli.md

@@ -214,7 +214,7 @@ portable runtime subpaths such as `arcane-os/preference-store` and
 modules. The result reports the complete map written to the selected
 application; no fixed entry count is a release contract.
 
-SDK `0.5.11` preserves the physical workspace route count and ordered include
+SDK `0.5.12` preserves the physical workspace route count and ordered include
 list. External and modern integrated routes require `components`, `css`,
 `dependencies`, `entities`, `img`, `modules`, and `sdk`; a physical workspace
 may omit only an optional trailing `security` include. The external license

package/docs/reference/core/arcane-ai-contracts.md

@@ -9,7 +9,7 @@ They are not TypeScript declarations.
 
 ## Portable SDK AI and Core AI
 
-The SDK `0.5.11` has two related but separate normalized boundaries:
+The SDK `0.5.12` has two related but separate normalized boundaries:
 
 | Boundary | Use | Host |
 |---|---|---|
@@ -132,7 +132,7 @@ No other message fields are accepted.
 | `model` | `string` | Yes | Effective configured model | Model used by provider-neutral chat. |
 | `configured` | `boolean` | Yes | - | Required provider configuration is present. |
 | `local` | `boolean` | Yes | `true` only for Ollama | Whether inference remains local. |
-| `responseLength` | `"low" \| "medium" \| "high"` | Yes | Legacy invalid/missing state resolves to `"medium"` | Conversational response target, not a provider token limit. |
+| `responseLength` | `"low" \| "medium" \| "high"` | Yes | Invalid/missing state resolves to `"medium"` | Conversational response target, not a provider token limit. |
 
 An OpenAI profile is returned only after Arcane proves a protected credential
 exists and the configured model is available to that account.
@@ -620,7 +620,6 @@ The wrapper supplies the validated `model` field.
 | `format` | JSON value | No | Text, JSON, or schema format | Output format. |
 | `options` | object | No | Provider-native; `num_ctx` is 1,024-262,144 when supplied | Runtime options. |
 | `system`, `template` | `string` | No | Provider-native | Prompt controls. |
-| `context` | `array` | No | Provider-native | Legacy context tokens. |
 | `raw` | `boolean` | No | Provider-native | Raw prompt mode. |
 | `keep_alive` | `string \| number` | No | Provider-native | Residency. |
 | `think`, `logprobs`, `top_logprobs` | JSON value | No | Provider-native | Reasoning/log-probability controls. |

package/docs/reference/core/arcane-api.md

@@ -128,7 +128,7 @@ directly.
 | `Arcane.ollama.saveServiceSettings(settings)` | `settings`: [`OllamaServiceSettingsInput`](arcane-ai-contracts.md#ollama-service-settings-input) | [`Promise<OllamaServiceSettingsResult>`](arcane-ai-contracts.md#ollama-service-settings-result) | Saves managed service settings. |
 
 The native AI profile always returns `responseLength` as `"low"`, `"medium"`,
-or `"high"`; missing or invalid legacy persisted values safely resolve to
+or `"high"`; missing or invalid persisted values safely resolve to
 `"medium"`. New saves reject any other value. Conversational applications may
 use this target to augment their system prompt, but specific user requests and
 required application, structured-output, tool, safety, evidence, warning, or
@@ -537,9 +537,9 @@ exclusive-mutation boundary. Native set results must match the requested name,
 protection decision, and exact ordinary value or protected five-bullet mask
 before Core returns them.
 Microsoft NT rejects a protected-record/plaintext-registry shadow. Linux binds
-new protected values to a random Secret Service generation in a namespace that
-does not overlap legacy entries, fsyncs the metadata file and directory before
-cleaning the prior generation, and keeps legacy lookup compatibility.
+new protected values to a random Secret Service generation and fsyncs the
+metadata file and directory before cleaning the prior generation. Native
+storage implementation details belong to Arcane Core, not the SDK.
 Failure to verify candidate, prior-generation, or deletion cleanup rejects with
 `ENVIRONMENT_PROTECTED_CLEANUP_FAILED`. Linux post-rename durability ambiguity
 rejects with `ENVIRONMENT_METADATA_COMMIT_UNCERTAIN`. Native code retains
@@ -579,7 +579,7 @@ Native storage and preferences resolve below
 cannot provide a different identity. Browser OPFS follows
 `apps/<application-id>/...`, DBLS fallback keys use
 `arcane.apps.<application-id>:`, and native browser profiles are also app-owned.
-Unowned legacy global data is preserved but not guessed into an app. The complete
+Unowned global data is preserved but not guessed into an app. The complete
 layout and same-origin browser limitation are maintained in the repository-only
 [Application data isolation](https://github.com/TheWizardNexus/ARCANE-OS/blob/567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e/docs/application-data-isolation.md); see the public [repository-access boundary](https://github.com/TheWizardNexus/ARCANE-OS/blob/567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e/apps/docs/guides/repository-access.md#private-developer-material).
 

package/docs/reference/core/ollama-module.md

@@ -82,7 +82,7 @@ The service is configured with the global `OLLAMA_MODELS` directory. Arcane clie
 npm run model:ensure -- --target=all --model=3b --smoke
 ```
 
-`--target=arcane` is the backward-compatible platform default. Product-specific targets and definitions remain documented by their owning applications. `--target=all` reuses one base pull across both currently configured targets, selects `arcane:3b` as `arcane:latest`, and preserves unrelated settings. `--smoke` adds one bounded local inference probe per selected alias. The equivalent platform-only raw Ollama sequence is `ollama pull granite4.1:3b-q4_K_M` followed by `ollama create arcane:3b -f arcane/models/Arcane-3B.Modelfile`; the npm command additionally verifies lineage and is the supported repository workflow.
+`--target=arcane` selects the platform model and is the default. Product-specific targets and definitions remain documented by their owning applications. `--target=all` reuses one base pull across both currently configured targets, selects `arcane:3b` as `arcane:latest`, and preserves unrelated settings. `--smoke` adds one bounded local inference probe per selected alias. The equivalent platform-only raw Ollama sequence is `ollama pull granite4.1:3b-q4_K_M` followed by `ollama create arcane:3b -f arcane/models/Arcane-3B.Modelfile`; the npm command additionally verifies lineage and is the supported repository workflow.
 
 The managed service's aliases and model layers are machine-wide, while Arcane model preference and application profile selection remain per-user. `model:ensure` does not install or attest `ArcaneOllama`, does not update an already installed Core or UI after a source pull, and does not create application aliases outside the selected target set. Use the verified Provisioner to establish or repair the machine service and to install current application/runtime bytes. The public [Device and model support](https://github.com/TheWizardNexus/ARCANE-OS/blob/567ad110bf57a1c2d4a3daa22ae93716cc5f4d7e/apps/docs/guides/device-support.md) page tracks the exact product matrix, platform maturity, and COTS physical-validation backlog; 16B and 30B are validation targets, not managed variants.
 

package/docs/reference/core/reference/arcane-api/platform-installation-users-system.md

@@ -516,7 +516,7 @@ recorded binding/security metadata, `canRestoreShell`,
 `shellRecoveryPrepared`, `accountMutationPhase`, and `activationRequired`.
 
 Microsoft NT records include `username`, `sid`, `enabled`, `profile`, `shell`,
-both policy and legacy shell values/presence flags, `shellAssigned`,
+both policy and Winlogon shell values/presence flags, `shellAssigned`,
 `shellBindingVersion`, `assignmentMode`, `verification`, and `source`. Linux
 records include `username`, optional `uid`, `enabled`, `profile`, `shell`,
 `shellAssigned`, `verification`, and `source`. Nullable or recorded-only values
@@ -824,7 +824,7 @@ Provisioner type, elevation, and the exclusive Core mutation boundary. It does
 not delete the account or change its password, but it materially changes what
 starts at the user's next sign-in.
 
-Microsoft NT restores both prior policy and legacy shell bindings, including
+Microsoft NT restores both prior policy and Winlogon shell bindings, including
 their recorded absence. Linux restores the recorded login shell after checking
 the exact uid and ensuring the prior executable still exists. The host refuses
 to overwrite a value changed outside the recorded transaction.

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

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

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

@@ -5,7 +5,7 @@
     "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
     "branch": "main",
     "path": "runtime/arcane/components",
-    "sdkVersion": "0.5.11"
+    "sdkVersion": "0.5.12"
   },
   "componentCount": 39,
   "loader": "/arcane/modules/HTMLImport.js",

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

@@ -5,7 +5,7 @@
     "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
     "branch": "main",
     "path": "runtime/arcane",
-    "sdkVersion": "0.5.11",
+    "sdkVersion": "0.5.12",
     "protocol": "arcane/1"
   },
   "artifactCount": 84,
@@ -29,8 +29,8 @@
       "summary": "Owns provider-selectable chat and the one-time caller-authority browser STT/TTS configuration, lifecycle, synthesis, transcription, and playback boundary.",
       "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 Kokoro TTS execution with default capacity 4, 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, immediate exact-segment synthesis, 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.",
-      "surface": "Browser-speech protocol/event/error/reason constants; default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and `browserSpeechDescriptor`; explicit `providerRuntime.status(role,{execution:true})` snapshots; configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls, synthesis/transcription, and playback controls; initializes from current canonical user readiness, installs `window.ai`, and projects `ai-ready` plus active-generation `ai-tts-failure`."
+      "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized Kokoro TTS execution with default capacity 4, 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, immediate exact-segment synthesis, per-call voice/speed capture, optional final-segment pause on the existing audio clock, optional per-call terminal playback completion, 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.",
+      "surface": "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 (available in SDK 0.5.12); configure/dispose speech, route lifecycle, declaration-validated chat/stream requests with exact ordered calls, 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/AIPreferenceRuntime.js",

package/docs/reference/protocols.md

@@ -159,7 +159,7 @@ imports such as:
 import ollama from 'arcane/Ollama';
 ```
 
-The physical-v1 tree lives entirely beneath `arcane/`. SDK `0.5.11` projects the
+The physical-v1 tree lives entirely beneath `arcane/`. SDK `0.5.12` projects the
 complete canonical runtime and browser runtime selected by the installed SDK
 package. Runtime dependencies stay under
 `arcane/dependencies/`; the SDK event and browser-AI closure stays under
@@ -174,7 +174,7 @@ integrated physical route uses the same ordered include list in its one route.
 Omitting only that final optional entry is compatible. Removing, reordering, or
 renaming any preceding entry changes the physical contract.
 
-The `0.5.11` map derives its complete entries from the selected runtime graph;
+The `0.5.12` map derives its complete entries from the selected runtime graph;
 application source imports do not select a fixed entry count. The operation
 result reports `imports`, `entryCount`, and `excludedModules`; reached-file
 traversal remains internal. The
@@ -239,8 +239,8 @@ exactly `dependencyName`, `packageSource`,
 `canonicalPackageRoot`, `packageName`, `packageVersion`, `runtimeRoot`,
 and `browserRuntimeRoot`. A
 workspace may use the canonical dependency name or one exact npm alias such as
-`npm:arcane-os@0.5.11`; the physical package manifest must still identify
-exactly as `arcane-os@0.5.11`. Canonical-plus-alias duplicates, multiple aliases,
+`npm:arcane-os@0.5.12`; the physical package manifest must still identify
+exactly as `arcane-os@0.5.12`. Canonical-plus-alias duplicates, multiple aliases,
 links/junctions, indirect package roots, or version drift are reported.
 
 For external workspaces, `arcane dev` serves the projected `arcane/` root,
@@ -351,7 +351,7 @@ does not silently delete the app-owned cache. A complete whole member supersedes
 its current resumable fragments. Cleanup failure is warned without hiding the
 usable model.
 
-SDK `0.5.11` requires WebGPU. Load requests full offload and waits for the runtime
+SDK `0.5.12` requires WebGPU. Load requests full offload and waits for the runtime
 to report a loaded model. `navigator.gpu` presence alone is
 not readiness. There is no CPU fallback, partial-offload success mode, or
 silent switch to native/Core/cloud inference.

package/docs/reference/runtime-components.md

@@ -359,8 +359,11 @@ unload.
 
 Chat listens for the bound (or current global) AI runtime's `ai-tts-failure`
 event and forwards its complete Error and exact operation boundary to
-`speech.reportTTSError()`. This includes decode and playback-start failures that
-settle after `streamTTS()` has already resolved. Runtime mute, cancellation,
+`speech.reportTTSError()`. Playback-start or playback-resume failures can occur
+after Chat's two-argument `streamTTS()` preparation promise has resolved.
+SDK `0.5.12` adds a `waitForPlayback:true` mode for the
+terminal result of the segments submitted by one invocation; Chat continues
+to feed chunks without waiting for playback. Runtime mute, cancellation,
 permission waiting, and stale generations remain non-errors.
 
 Each visible model chunk is still forwarded to `AI.streamTTS()` in arrival

package/docs/reference/runtime-modules.md

@@ -141,11 +141,17 @@ default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and
 `configureSpeechProviders()`, `transitionAI()`, `transitionProviders()`,
 `transitionSpeechProviders()`, `startProviders()`, `setSpeechMuted()`,
 `streamRequest()`, `streamMessage()`, `fetchRequest()`, `fetch()`,
-read-only `ttsSegmentation`, `configureTTSSegmentation()`, `streamTTS()`,
+read-only `ttsSegmentation`, `configureTTSSegmentation()`,
+`streamTTS(text='',end=false,options={})`,
 `finishTTS()`, `fetchTTS()`, `fetchSTT()`, `stopAudio()`, `resumeAudio()`,
 `playAudio()`; consumes `user-entity-loaded` and `arcane-ollama-ready`,
 installs `window.ai`, and emits `ai-ready` and `ai-tts-failure`.
 
+`fetch(...)` and `fetchRequest(options)` are asynchronous complete-response
+entry points. `streamMessage(...)` and `streamRequest(options)` deliver
+incremental responses. The positional and object forms share the existing
+provider implementations; neither form is a retired compatibility API.
+
 Initialization uses the canonical realm user's actual readiness state. If
 `window.user?.ready` is already true, AI initializes immediately. Otherwise one
 shared registration observes `user-entity-loaded`, then rechecks readiness
@@ -248,8 +254,37 @@ the setting is the instance's `opus` default and the model rejects it, the catal
 `speech.defaultResponseFormat` is used, while any other unsupported setting is
 rejected. It propagates the caller-owned signal and returns a playable `Blob`;
 it does not independently choose a provider, cloud fallback, model, runtime, or
-voice policy for the application. Existing `streamTTS()` and `finishTTS()` use
-this same request boundary. Streaming speech retains sentence
+voice policy for the application. `streamTTS(text='',end=false,options={})` and
+`finishTTS()` use this same request boundary. The third-argument options below
+are available in SDK `0.5.12`:
+
+| Field | Default | Meaning |
+| --- | --- | --- |
+| `voice` | Current selected model's default voice | A supplied voice is captured for every segment extracted by this call and forwarded unchanged to `fetchTTS()`. It does not change the instance or provider default. |
+| `speed` | Current `ai.voiceSpeed` | A supplied positive speed is captured for those segments and forwarded to `fetchTTS()`. It does not change `ai.voiceSpeed`. |
+| `pauseAfterMs` | `0` | Finite, nonnegative milliseconds placed after the final extracted segment on the existing audio clock. Invalid values throw `RangeError`; no pause is inserted between this call's other segments. |
+| `waitForPlayback` | `false` | Omission retains the preparation promise. With `true`, the promise resolves after every extracted segment reaches a terminal playback state: `true` when all naturally end, or `false` after terminal cancellation or failure. |
+
+The voice and speed use the existing `fetchTTS()` validation and error path.
+No option rewrites the submitted text. Overrides belong to the segments
+extracted in that invocation, including any text buffered by an earlier call.
+Options are not retained with an unfinished `end:false` remainder; a later
+call supplies its own options, and `finishTTS()` uses defaults. Use `end:true`
+for a complete passage. A call extracting no segments resolves
+`true` without waiting for earlier jobs; `finishTTS()` remains a preparation
+flush, not a queue-wide playback barrier. A muted call resolves `false`.
+
+Playback completion stays pending while the browser waits for an audio-unlock
+gesture or a recoverable resume attempt. If resuming a closed `AudioContext`
+fails, the affected jobs terminate and their playback results settle `false`.
+`stopAudio()` cancels all speech owned
+by this AI instance and settles pending playback promises `false`. A trailing
+pause delays the next queued audio; the preceding promise resolves when its
+last audio buffer ends, without waiting out that pause. Completion describes
+the playback lifecycle, not proof that a listener heard the sound. See the
+[complete-passage example](ai/browser-speech.md#queue-complete-passages-and-wait-for-playback).
+
+Streaming speech retains sentence
 segmentation by default. `configureTTSSegmentation({punctuation,wordCadence})`
 accepts `punctuation:'sentence'|'any'|'none'` and a `wordCadence` that is either
 `null` or a positive integer. `punctuation:'any'` completes a segment at a
@@ -1661,7 +1696,7 @@ and `read`, filters source metadata before calling
 **Browser or compatible host with an injected DBOPFS adapter.** The adapter
 keeps the existing `get`, `set`, `getAllKeys`, and `delete` method names; Node
 can use the same class only through an explicitly imported runtime module and a
-compatible storage adapter; SDK `0.5.11` publishes no Node package subpath or
+compatible storage adapter; SDK `0.5.12` publishes no Node package subpath or
 Node storage implementation for it. Bootstrap uses a concurrent
 generation, commits its manifest last, cleans partial data on failure, and
 rejects case-colliding IDs. Search

package/docs/reference/sdk-api.md

@@ -18,7 +18,7 @@ This table is the Node `package.json#exports` map: it defines package
 entrypoints for SDK/tooling code. It is distinct from the generated browser
 import map that resolves application-facing `arcane/*` modules and the focused
 EventManager entry. See [browser runtime delivery](protocols.md#browser-runtime-delivery)
-for the installed-inventory-derived physical-runtime contract in SDK `0.5.11`.
+for the installed-inventory-derived physical-runtime contract in SDK `0.5.12`.
 
 | Specifier | Purpose |
 | --- | --- |
@@ -748,7 +748,7 @@ deterministic map. The package root also contains the public
 {
   schemaVersion: 1,
   kind: 'arcane-app-runtime-projection',
-  sdkVersion: '0.5.11',
+  sdkVersion: '0.5.12',
   pathPrefix: 'arcane/',
   files: [{path}]
 }
@@ -2667,7 +2667,7 @@ The import-map operation also reports the stable operation-specific strings
 `ARCANE_IMPORT_MAP_INVALID`, `ARCANE_IMPORT_MAP_UNRESOLVED`, and
 `ARCANE_IMPORT_MAP_COLLISION`; package assembly can additionally report
 `ARCANE_IMPORT_MAP_CLEANUP_FAILED`. They are normalized `ArcaneError.code`
-values, but are not properties added to this general registry in SDK `0.5.11`.
+values, but are not properties added to this general registry in SDK `0.5.12`.
 
 ### Value and import
 
@@ -3437,7 +3437,7 @@ workspace it additionally returns the exact installed package authority:
     packageSource,
     canonicalPackageRoot,
     packageName: 'arcane-os',
-    packageVersion: '0.5.11',
+    packageVersion: '0.5.12',
     runtimeRoot,
     browserRuntimeRoot
   }
@@ -3445,9 +3445,9 @@ workspace it additionally returns the exact installed package authority:
 ```
 
 The dependency can be named `arcane-os` or be one exact npm alias for
-`npm:arcane-os@0.5.11`. The selected installation must still be one direct,
+`npm:arcane-os@0.5.12`. The selected installation must still be one direct,
 physical, non-link package directory whose manifest identifies exactly as
-`arcane-os@0.5.11`; duplicate canonical/alias declarations reject.
+`arcane-os@0.5.12`; duplicate canonical/alias declarations reject.
 `allowMissingManagedImportMap` is an internal packaging/development seam. An
 ordinary caller should leave it `false`.
 

package/package.json

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

package/runtime/arcane/modules/AI.js

@@ -5673,7 +5673,8 @@ class AI {
 
     streamTTS(
         text='',
-        end=false
+        end=false,
+        options={}
     ){
         if(this.muted){
             if(end){
@@ -5682,6 +5683,12 @@ class AI {
             return Promise.resolve(false);
         }
 
+        const {voice,speed,waitForPlayback=false}=options;
+        const pauseAfterMs=Number(options.pauseAfterMs??0);
+        if(!Number.isFinite(pauseAfterMs)||pauseAfterMs<0){
+            throw new RangeError('Speech pauses must be a nonnegative number of milliseconds.');
+        }
+
         this.audioMessageChunks+=String(text||'');
         const outputs=this.#extractSpeechSegments(end);
 
@@ -5702,8 +5709,13 @@ class AI {
         const generation=this.speechGeneration;
         const jobs=[];
 
-        for(const output of outputs){
-            jobs.push(this.#queueSpeechJob(output,generation));
+        for(const [index,output] of outputs.entries()){
+            jobs.push(this.#queueSpeechJob(output,generation,{
+                voice,
+                speed,
+                waitForPlayback,
+                pauseAfterMs:index===outputs.length-1?pauseAfterMs:0
+            }));
         }
 
         return Promise.all(jobs).then(
@@ -5857,7 +5869,7 @@ class AI {
         return this.#speechAbbreviations.has(token);
     }
 
-    #queueSpeechJob(text,generation){
+    #queueSpeechJob(text,generation,options={}){
         const job={
             abortController:null,
             audioBuffer:null,
@@ -5867,13 +5879,22 @@ class AI {
             scheduledStart:null,
             sourceNode:null,
             state:'queued',
-            text
+            text,
+            voice:options.voice,
+            speed:options.speed,
+            pauseAfterMs:options.pauseAfterMs??0,
+            resolvePlayback:null
         };
         const runtime=this;
+        const playback=options.waitForPlayback===true
+            ?new Promise(function captureSpeechPlaybackCompletion(resolve){
+                job.resolvePlayback=resolve;
+            })
+            :null;
 
         this.speechJobs.push(job);
 
-        return Promise.resolve().then(
+        const preparation=Promise.resolve().then(
             function synthesizeAvailableSpeech(){
                 return runtime.#prepareSpeechJob(job);
             }
@@ -5886,6 +5907,7 @@ class AI {
                 );
             }
         );
+        return playback||preparation;
     }
 
     async #prepareSpeechJob(job){
@@ -5914,16 +5936,18 @@ class AI {
     async #requestSpeechAudio(job){
         job.abortController=new AbortController();
         const selection=this.#providerRuntime.selection('tts');
-        const voice=selection?this.#providerSpeechVoice():null;
+        const voice=job.voice===undefined
+            ?(selection?this.#providerSpeechVoice():null)
+            :job.voice;
         const response=await this.fetchTTS(
             {
                 model:selection?.modelId||this.modelTTS,
                 input:job.text,
-                ...(voice?{voice}:{}),
+                ...(job.voice!==undefined||voice?{voice}:{}),
                 responseFormat:selection
                     ?this.#providerSpeechResponseFormat()
                     :this.audioFormat,
-                speed:this.voiceSpeed
+                speed:job.speed===undefined?this.voiceSpeed:job.speed
             },
             job.abortController.signal
         );
@@ -6294,6 +6318,8 @@ class AI {
         for(const job of this.speechJobs){
             job.abortController?.abort();
             job.state='cancelled';
+            job.resolvePlayback?.(false);
+            job.resolvePlayback=null;
 
             if(job.sourceNode){
                 job.sourceNode.onended=null;
@@ -6370,6 +6396,22 @@ class AI {
             if(attempt===this.speechResumeAttempt){
                 this.speechResumePending=false;
             }
+            if(context?.state==='closed'){
+                this.#clearSpeechUnlock();
+                const jobs=this.speechJobs.filter(function usesClosedSpeechContext(job){
+                    return job.audioContext===context;
+                });
+                if(!jobs.length){
+                    this.#publishTTSFailure(error,{
+                        boundary:'playback-resume',
+                        generation:this.speechGeneration
+                    });
+                }
+                for(const job of jobs){
+                    this.#failSpeechJob(job,error,'playback-resume');
+                }
+                return false;
+            }
             this.#waitForSpeechGesture(error,context);
             if(error?.name!=='NotAllowedError'){
                 this.#publishTTSFailure(error,{
@@ -6543,7 +6585,7 @@ class AI {
                     job.state='scheduled';
                     job.scheduledStart=scheduledStart;
                     job.scheduledEnd=hasKnownDuration
-                        ?scheduledStart+duration
+                        ?scheduledStart+duration+(job.pauseAfterMs??0)/1000
                         :null;
                     job.sourceNode.__arcaneStarted=true;
                     if(!this.currentSpeechJob){
@@ -6606,6 +6648,11 @@ class AI {
             job.sourceNode.onended=null;
         }
 
+        if(job.scheduledEnd===null&&job.pauseAfterMs>0){
+            this.speechScheduleContext=job.audioContext;
+            this.speechScheduleTime=
+                (Number(job.audioContext?.currentTime)||0)+job.pauseAfterMs/1000;
+        }
         job.state='complete';
         this.#removeSpeechJob(job);
 
@@ -6727,6 +6774,8 @@ class AI {
     }
 
     #removeSpeechJob(job){
+        job.resolvePlayback?.(job.state==='complete');
+        job.resolvePlayback=null;
         const jobIndex=this.speechJobs.indexOf(job);
 
         if(jobIndex>=0){