arcane-os 0.5.15 → 0.5.17

package/CHANGELOG.md

@@ -2,6 +2,36 @@
 
 ## Unreleased
 
+## 0.5.17
+
+- Restore the public `SPEECH_VOICE_OPTIONS` ordered records and
+  `SPEECH_VOICE_ALIASES` membership set used by existing speech controls. Both
+  remain ordinary mutable compatibility values, and `SpeechPlayback` does not
+  select a voice from them automatically.
+- Restore the optional `SpeechPlayback` constructor `onState(detail)` callback.
+  Canonical state dispatch remains first; callback failures are reported
+  without replacing playback settlement. Preserve capability-gated eager
+  submission, the provider-owned default capacity of four, indexed playback
+  order, native/custom serialization, cancellation, and Replay behavior.
+- Apply the shared repeated-formatting-mark cleanup automatically to every TTS
+  entry path, including direct fetch, provider-runtime synthesis, browser
+  Kokoro requests, streaming chunks, and `SpeechPlayback`. Export the shared
+  `MarkdownSpeech` and `stripSpeechFormatting()` owner from
+  `arcane-os/speech-text`; keep original caller records unchanged and use
+  operation-local SDK metadata to prevent a second cleanup pass. No application
+  option is required, and the prior `textFormat` extra no longer disables or
+  selects cleanup.
+
+## 0.5.16
+
+- Add optional Markdown narration filtering before `AI.streamTTS()`
+  segmentation. Omit repeated same formatting marks across streamed chunks,
+  preserve single marks and ordinary punctuation, and clear formatting state
+  on terminal flush or cancellation. Keep plain speech, displayed and stored
+  text, language, voice, synthesis capacity, and audio scheduling unchanged.
+- Select Markdown narration in shared chat and include focused filter test
+  source without adding a parser dependency.
+
 ## 0.5.15
 
 - Let `SpeechPlayback.prepare()` submit every complete segment immediately when

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.15` SDK contract. Applications pin one exact npm
+This checkout defines the `0.5.17` 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.15 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.5.17 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 npm run dev
@@ -51,6 +51,10 @@ For a first spoken sentence, copy the application-owned
 beside `App.js`, then use this module. That one configuration file defines the
 upstream runtime, model, dtype, and voice. This module creates the application's
 DBOPFS store; the SDK creates and manages its speech providers and Workers.
+The linked automatic/WebGPU-first selection uses `fp32` because
+[Kokoro.js recommends `fp32` when using WebGPU](https://github.com/hexgrad/kokoro/tree/main/kokoro.js#usage).
+Its `selectedDevice` status reports the loaded route, not speech correctness or
+audio quality.
 
 ```javascript
 import arcaneThemeReady from 'arcane/ThemeBootstrap';
@@ -111,7 +115,13 @@ import SpeechPlayback from 'arcane/SpeechPlayback';
 
 const audio = document.body.appendChild(document.createElement('audio'));
 audio.controls = true;
-const narration = new SpeechPlayback({audio, speech: ai});
+const narration = new SpeechPlayback({
+  audio,
+  speech: ai,
+  onState(detail) {
+    console.log('Speech state:', detail.state);
+  }
+});
 const speakAll = document.body.appendChild(document.createElement('button'));
 speakAll.textContent = 'Speak all segments';
 speakAll.addEventListener('click', async function speakAllSegments() {
@@ -128,6 +138,20 @@ segments enter the provider queue immediately, up to four synthesize at once,
 and the audio still plays first, second, third. Native or custom speech without
 advertised provider execution capacity stays serialized with one lookahead.
 
+Existing speech controls can also import the shared compatibility catalogs.
+They list the ten existing value/label choices but do not choose a voice for
+the application or prove that a selected provider supports one:
+
+```javascript
+import {
+  SPEECH_VOICE_ALIASES,
+  SPEECH_VOICE_OPTIONS
+} from 'arcane/SpeechPlayback';
+
+console.log(SPEECH_VOICE_OPTIONS[0]); // {value: 'alloy', label: 'Alloy'}
+console.log(SPEECH_VOICE_ALIASES.has('alloy')); // true
+```
+
 Continue with [streaming chunks, device selection, cancellation, status, and cleanup](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/reference/ai/browser-speech.md),
 the [tiny TWiN Cloud request and saved-preference migration](https://github.com/TheWizardNexus/arcane-os-sdk/blob/main/docs/reference/ai/twin-cloud.md),
 or the [maintained WASM voice-chat example](https://github.com/TheWizardNexus/arcane-os-sdk/tree/main/examples/wasm-ai-demo).
@@ -286,13 +310,14 @@ TTS stream without taking over synthesis or playback:
 ```js
 ai.configureTTSSegmentation({
     punctuation:'any',
-    wordCadence:4
+    wordCadence:null
 });
 ```
 
 The compatibility default remains sentence punctuation with no word cadence.
-The configured stream preserves every character and punctuation mark, chooses
-the earliest complete boundary, begins synthesis as each segment becomes
+Within the already prepared speech text, the configured segmentation preserves
+every character and punctuation mark, chooses the earliest complete boundary,
+begins synthesis as each segment becomes
 available, and plays the completed audio in exact segment order. Ready adjacent
 buffers are scheduled consecutively on the browser audio clock rather than
 waiting for an `ended` callback before the next start.
@@ -301,6 +326,16 @@ keeping apostrophes, commas, and hyphens that join Unicode letters or numbers
 inside the same segment.
 Mute, stop, provider transition, and cancellation still govern the whole queue.
 
+Every TTS call automatically removes repeated same formatting marks (`*`, `#`,
+`_`, backtick, `~`) from its outbound speech-input copy before synthesis.
+Streaming calls also recognize a run split across chunks. Single marks and
+ordinary repeated punctuation remain literal. No application option is needed;
+an existing `textFormat` extra is ignored and cannot disable cleanup. Original
+messages and caller payloads remain unchanged for display, storage, and model
+input. The dependency-free `arcane-os/speech-text` entrypoint exports the same
+`MarkdownSpeech` streaming class and `stripSpeechFormatting()` one-pass helper
+for code that needs the speech-only transformation directly.
+
 The SDK runtime also owns `DBOPFSDocumentLibrary`,
 `DocumentLexicalSearch`, and `PersistentAIChatSession`. Document bootstrap is
 schema-driven and explicit; chat never searches a corpus unless the app wires
@@ -322,7 +357,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.15 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.5.17 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run dev
@@ -332,7 +367,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.15
+npm install --save-dev --save-exact arcane-os@0.5.17
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -348,7 +383,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.15` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.5.17` 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`,
@@ -368,7 +403,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.15.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.5.17.tgz
 npm ci
 ```
 
@@ -377,7 +412,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.15` registry package and
+the local declaration with the exact `arcane-os@0.5.17` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -516,7 +551,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.5.15` exposes one browser target and five explicitly paired
+Version `0.5.17` 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/browser-runtime/ai/browser-speech-providers.mjs

@@ -5,6 +5,7 @@ import {
   isBrowserSpeechAuthority,
   isDbopfsSpeechArtifactStore,
 } from "./browser-speech-artifacts.mjs";
+import { stripSpeechFormatting } from "../speech-text.mjs";
 
 const completeValue = (value) => value;
 import {
@@ -896,7 +897,7 @@ function cloneNativeTranscriptionPayload(payload, authority) {
   });
 }
 
-function normalizeSynthesisPayload(payload, authority) {
+function normalizeSynthesisPayload(payload, authority, speechInputPrepared) {
   const shared = Object.hasOwn(payload, "input");
   let descriptors;
   let textValue;
@@ -932,7 +933,8 @@ function normalizeSynthesisPayload(payload, authority) {
     assertPayloadModel(payload, authority, { operationSubject: "tts-synthesis" });
     textValue = descriptors.text.value;
   }
-  const text = typeof textValue === "string" ? textValue : "";
+  const suppliedText = typeof textValue === "string" ? textValue : "";
+  const text = speechInputPrepared === true ? suppliedText : stripSpeechFormatting(suppliedText);
   const voiceValue = Object.hasOwn(descriptors, "voice")
     ? descriptors.voice.value
     : authority.defaultVoice;
@@ -983,6 +985,7 @@ async function normalizeRequestPayload(
   authority,
   signal,
   cancellationReason,
+  speechInputPrepared,
 ) {
   if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
     throw providerError(
@@ -1009,7 +1012,7 @@ async function normalizeRequestPayload(
     }
     return cloneNativeTranscriptionPayload(payload, authority);
   }
-  return normalizeSynthesisPayload(payload, authority);
+  return normalizeSynthesisPayload(payload, authority, speechInputPrepared);
 }
 
 function encodeSharedSynthesisResult(result, authority) {
@@ -1619,7 +1622,7 @@ function createBrowserSpeechProvider({
       }, role);
     },
 
-    async request(context = {}) {
+    async request(context = {}, { speechInputPrepared = false } = {}) {
       let requestContext;
       try {
         requestContext = providerContext(context, role, "request");
@@ -1713,6 +1716,7 @@ function createBrowserSpeechProvider({
           authority,
           linked.controller.signal,
           browserSpeechRequestAbortReason,
+          speechInputPrepared,
         );
         throwIfAborted(
           linked.controller.signal,

package/browser-runtime/speech-text.mjs

@@ -0,0 +1,31 @@
+function stripSpeechFormatting(text=''){
+    return text.replace(/([*#_`~])\1+/g,'');
+}
+
+// Speech-only filtering; single markers and all other text remain literal.
+class MarkdownSpeech {
+    #pending='';
+
+    append(text='',end=false){
+        if(typeof text!=='string'){
+            throw new TypeError('Markdown speech input must be text.');
+        }
+
+        const source=this.#pending+text;
+        const trailing=end?null:/([*#_`~])\1*$/u.exec(source);
+        // Two copies retain the fact that a run repeats without retaining it all.
+        this.#pending=trailing
+            ?trailing[1].repeat(trailing[0].length===1?1:2)
+            :'';
+
+        return stripSpeechFormatting(
+            trailing?source.slice(0,trailing.index):source
+        );
+    }
+
+    reset(){
+        this.#pending='';
+    }
+}
+
+export {MarkdownSpeech,stripSpeechFormatting};

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.15` runtime requires Arcane `0.8.12` or newer. Compatibility
+The SDK `0.5.17` 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.15
+npm install --save-exact arcane-os@0.5.17
 ```
 
 For your first AI call, follow the [TWiN Cloud quick start](ai/twin-cloud.md).
@@ -58,9 +58,9 @@ This repository contains explicitly versioned surfaces with different owners:
 
 | Surface | Source identity | Meaning |
 | --- | --- | --- |
-| SDK and CLI | `arcane-os` `0.5.15` | The Node.js toolchain, portable `arcane-os/event-manager`, `arcane-os/logging`, `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.15`, 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.15`, `browser-runtime/` | The browser closure for events, shared logging, 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.17` | The Node.js toolchain, portable `arcane-os/event-manager`, `arcane-os/logging`, `arcane-os/mail`, `arcane-os/preference-store`, `arcane-os/speech-playback`, and `arcane-os/speech-text` 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.17`, 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.17`, `browser-runtime/` | The browser closure for events, shared logging, speech-text cleanup, 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
@@ -75,7 +75,7 @@ and the distinction between a documentation snapshot and the selected runtime.
 
 ## Installed documentation and release identity
 
-This reference accompanies `arcane-os@0.5.15`. The installed package includes
+This reference accompanies `arcane-os@0.5.17`. 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
@@ -124,11 +124,11 @@ Public reference entries follow the established Arcane documentation model:
 
 ## Public runtime inventory
 
-The package exposes 198 semantic JavaScript records across 17 JavaScript
+The package exposes 202 semantic JavaScript records across 18 JavaScript
 entrypoints, plus eight JSON Schemas and package metadata. Ten entrypoints are
 Node.js control-plane surfaces,
 `arcane-os/event-manager`, `arcane-os/logging`, `arcane-os/mail`, `arcane-os/preference-store`, and
-`arcane-os/speech-playback` run in Node and browsers, and
+`arcane-os/speech-playback` plus `arcane-os/speech-text` run in Node and browsers, and
 `arcane-os/ai/browser-wasm` plus `arcane-os/ai/browser-speech` are browser-only.
 The [machine-readable package
 inventory](inventory/package-api.json) and [SDK member reference](sdk-api.md)
@@ -139,7 +139,7 @@ download, install, or self-update.
 
 The synchronized browser payload exposes:
 
-- 82 JavaScript module artifacts under `runtime/arcane/modules/`, including
+- 83 JavaScript module artifacts under `runtime/arcane/modules/`, including
   ESM modules, classic vendor globals, one worker protocol, and one Node-oriented
   mail transport;
 - 14 shared entity modules under `runtime/arcane/entities/`;

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.15 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.5.17 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 npm run dev
@@ -37,7 +37,7 @@ export const speechSelection = {
     id: 'onnx-community/Kokoro-82M-v1.0-ONNX',
     repository: 'onnx-community/Kokoro-82M-v1.0-ONNX',
     revision: '1939ad2a8e416c0acfeecc08a694d14ef25f2231',
-    dtype: 'q8',
+    dtype: 'fp32',
     defaultVoice: 'af_heart'
   },
   runtime: {
@@ -55,6 +55,15 @@ export const speechSelection = {
 };
 ```
 
+The omitted execution record below uses the SDK's WebGPU-first automatic
+selection, so this basic configuration uses `fp32` because
+[Kokoro.js recommends `fp32` when using WebGPU](https://github.com/hexgrad/kokoro/tree/main/kokoro.js#usage).
+Automatic fallback carries this same selected model and dtype to WASM; the SDK
+does not rewrite the application selection. If you intentionally choose
+another dtype, evaluate that exact model, browser, and execution route.
+`selectedDevice` reports routing after load, not pronunciation, text fidelity,
+or audio quality.
+
 Then use this **`App.js`**. The application creates and owns the DBOPFS
 instance. Configuration selects the provider without loading it; the button
 explicitly loads and unmutes TTS before requesting speech.
@@ -221,8 +230,10 @@ only failed missing segments.
 
 The default `{device:'auto',maxConcurrentRequests:4}` attempts the full ONNX
 Worker/session pool on WebGPU, then recreates that pool on WASM only if WebGPU
-loading fails. Use the status example below to read `selectedDevice`; console
-node-assignment warnings alone do not identify the selected execution device.
+loading fails. The basic configuration above keeps `fp32` for this WebGPU-first
+path and any automatic WASM fallback. Use the status example below to read
+`selectedDevice`; console node-assignment warnings alone do not identify the
+selected execution device or assess the generated audio.
 
 ## Queue complete passages and wait for playback
 
@@ -275,8 +286,10 @@ all speech owned by that AI instance and settles pending playback results
 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.
+Voice, speed, pause, and playback options are not retained with an unfinished
+`end:false` remainder. A later call supplies its own options, and `finishTTS()`
+uses their defaults while flushing any pending single formatting mark through
+the same automatic speech-input cleanup.
 A call extracting no segments returns `true` without waiting for earlier jobs.
 An already muted call returns `false`.
 
@@ -331,12 +344,55 @@ if (finalPrepared === false) {
 ```
 
 The segmentation default uses sentence punctuation. To submit smaller complete
-segments, call `ai.configureTTSSegmentation({punctuation:'any',wordCadence:4})`
+segments, call `ai.configureTTSSegmentation({punctuation:'any',wordCadence:null})`
 before feeding the stream. Chunk boundaries themselves do not force a sentence
 boundary; `finishTTS()` flushes any remaining text. It is not a playback-ended
 notification. Do not mute or dispose immediately after it if playback should
 continue.
 
+## Automatic speech-input formatting cleanup
+
+Every TTS entrypoint removes repeated same formatting marks from the outbound
+speech-input copy automatically. No application option is required:
+
+```javascript
+ai.streamTTS('## Heading\n**Hello');
+ai.streamTTS('**. Next sentence.');
+await ai.finishTTS();
+```
+
+The SDK omits runs of two or more of the same `*`, `#`, `_`, backtick, or `~`
+before speech segmentation. A candidate run split across chunks is still
+recognized. Single marks, ellipses, quoted endings, and all other text are
+preserved. This is a small narration filter, not a full Markdown parser.
+Ordinary prose is forwarded immediately; only a trailing formatting candidate
+waits for its next character or the final flush.
+
+`end:true`, `finishTTS()`, or cancellation clears pending streaming formatting
+state. `fetchTTS()`, provider-runtime TTS requests, direct Kokoro provider
+requests, and `SpeechPlayback` apply the same cleanup to complete input. An
+existing `textFormat` extra is ignored and cannot disable or select cleanup.
+SDK-internal delegation carries `{speechInputPrepared:true}` outside the speech
+payload only after one cleanup pass, preventing a second non-idempotent pass.
+Applications omit that internal metadata. Displayed messages, saved history,
+model input, caller payload objects, language, voice, synthesis capacity, and
+playback timing are not changed by the filter.
+
+The dependency-free helper is public for code that needs the speech-only
+transformation directly:
+
+```javascript
+import {
+  MarkdownSpeech,
+  stripSpeechFormatting
+} from 'arcane-os/speech-text';
+
+console.log(stripSpeechFormatting('**Hello**')); // Hello
+const speechText = new MarkdownSpeech();
+console.log(speechText.append('## Head', false)); // ' Head'
+console.log(speechText.append('ing', true)); // ing
+```
+
 ## Choose a device or reduce memory use
 
 Omitting `tts.execution` selects `{device:'auto',maxConcurrentRequests:4}`.
@@ -401,6 +457,8 @@ until a pool is selected and returns to `null` on unload. Providers without an
 execution report omit `execution`; do not infer a device from `navigator.gpu`
 or a configured preference alone. An explicit inspection can throw a provider
 status error; handle it with the same `error.code` / `error.message` pattern.
+Treat `selectedDevice` as route status only; evaluate actual speech output for
+the model, dtype, browser, and device combinations your application supports.
 
 ## Stop, mute, cancel, and release
 
@@ -438,7 +496,8 @@ in place; it does not erase the application's data.
 For a cancellable individual synthesis, unmute first. A fresh browser speech
 configuration is muted, so calling `providerRuntime.load('tts')` directly at
 that point rejects with `ARCANE_AI_TTS_MUTED`. `fetchTTS()` accepts an
-`AbortSignal` as its second argument and returns a WAV `Blob` without playing it:
+`AbortSignal` as its second argument, cleans repeated formatting marks from the
+outbound input copy, and returns a WAV `Blob` without playing it:
 
 ```javascript
 const synthesisController = new AbortController();
@@ -875,7 +934,8 @@ cache state, and warnings. Kokoro status also includes an `execution` record
 with requested and selected device, request limit, and active request count. A
 successful `selectedDevice:'webgpu'` reports the execution provider selected by
 the upstream model load; it does not claim that browser, driver, or GPU kernels
-overlap physically. A security field is absent in ordinary mode.
+overlap physically or that generated audio has been quality-validated. A
+security field is absent in ordinary mode.
 
 The provider/2 load context accepts an optional progress callback for interface
 compatibility, but the current browser-speech artifact and Worker transport

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.15 new hello-twin --path ./hello-twin --target browser
+npx arcane-os@0.5.17 new hello-twin --path ./hello-twin --target browser
 cd hello-twin
 npm install
 npm run dev

package/docs/reference/availability-and-normalization.md

@@ -32,12 +32,13 @@ version; WebKitGTK availability must not be generalized to macOS.
 | Select and observe independent LLM/STT/TTS roles | `/arcane/modules/AIProviderRuntime.js` and `AIRuntimeState.js` | **Cross-host** controller/state; registered providers retain their own host requirements | Required/projected provider members, route/configuration records, and status fields; per-role lifecycle, cancellation, stream cleanup, sticky state, and startup barriers are normalized. `localOnly` creates no fallback. |
 | Run a caller-selected local LLM entirely in a browser renderer | `arcane-os/ai/browser-wasm` through `createArcaneAI()` | **Browser** only; secure context, WebAssembly, OPFS/DBOPFS, WebGPU, and requested full offload are required; no CPU fallback | The public AI API module normalizes multi-model lifecycle, status, complete all-choice streaming, cancellation, exact ordered structural tool-call visibility, and session persistence. Model sources are canonical ordered file descriptors; licenses and model choice remain application policy. |
 | Run caller-selected Whisper or Kokoro in a browser renderer | `arcane-os/ai/browser-speech` registered with `AIProviderRuntime` | **Browser** only; DBOPFS, Web Locks, Workers, Fetch/object URLs, and a caller-supplied self-contained runtime/model closure are required | STT/TTS use independent provider/2 lifecycle and status. Kokoro adds bounded Worker/session concurrency and explicit `auto`, `webgpu`, or `wasm` execution. Complete model/runtime selection, offline behavior, cancellation, Worker teardown, and request/result shapes are normalized. No runtime/model content or cloud fallback is supplied. |
+| Prepare ordered speech playback or reuse the speech-input formatting filter | `arcane-os/speech-playback` and `arcane-os/speech-text` | **Node** with injected media adapters, or **Browser / Native WebView** media; the text filter itself is **Cross-host** | Stored and caller-owned text stays exact. Only the outbound synthesis copy automatically loses repeated same formatting marks. A capacity-advertising provider receives complete segments immediately while retaining indexed playback; native/custom synthesis stays serialized. |
 | Preserve complete chat history and memory | `/arcane/modules/PersistentAIChatSession.js` | **Browser / native WebView** with ChatEntity/DBOPFS and a configured chat function | Existing DBOPFS names and memory semantics are preserved. Live-context commit is atomic; durable persistence is explicit and coherent across user/assistant turns and atomic all-ID tool-result batches. |
 | Search an app-owned document corpus for explicit chat context | `/arcane/modules/DBOPFSDocumentLibrary.js` | **Browser** or compatible injected DBOPFS adapter | Generation/manifest completion, complete lexical search, partial read failures, and untrusted context labels are normalized. Construction does not search; an explicitly wired context builder performs retrieval for each prepared chat send. |
 | Read host identity, capabilities, storage, preferences, appearance, or platform state | `globalThis.Arcane` | **Cross-host** where the method is implemented and admitted | Promise behavior and `Arcane.Error` are normalized. Result fields are normalized unless the method explicitly documents a platform-dependent snapshot. |
 | Use local AI without coupling app code to Ollama HTTP | `Arcane.localAI`, `Arcane.ai`, or `/arcane/modules/Ollama.js` | Primarily **Native**; Android exposes a narrower admitted inference projection | Admission, errors, and managed-operation events are normalized. Direct Ollama response envelopes remain **Provider-native**. |
 | Use TWiN Cloud from the renderer profile | `/arcane/modules/AI.js` | **Cloud** from an allowed browser/native renderer | High-level chat behavior is normalized by the module. The TWiN access key authenticates remote LLM chat; raw provider diagnostics remain provider-specific. No automatic cloud fallback is inferred from local failure. |
-| Use speech through one application helper | `/arcane/modules/AI.js` and `Arcane.speech` | **Browser** or **Native** | The helper keeps audio on device: Whisper owns STT and Kokoro owns TTS. It normalizes application-facing audio/text behavior while browser and native request/response plumbing differs below that boundary. |
+| Use speech through one application helper | `/arcane/modules/AI.js` and `Arcane.speech` | **Browser** or **Native** | The helper keeps audio on device: Whisper owns STT and Kokoro owns TTS. It automatically cleans only the outbound speech-input copy and normalizes application-facing audio/text behavior while browser and native request/response plumbing differs below that boundary. |
 | Inspect or manage raw Ollama models | `Arcane.ollama` or `/arcane/modules/Ollama.js` | **Native** desktop Core for management; narrower Android inference only | Wrapper method names, errors, streaming correlation, and admission are Arcane-controlled. Direct Ollama success envelopes are intentionally provider-native. |
 | Use native terminal, installation, user, provisioning, or machine controls | matching `Arcane.*` namespace | **Native** and app/capability restricted | Calls and errors use the common bridge contract. Platform results can be host-specific and are marked in the method guide. |
 

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.15` preserves the physical workspace route count and ordered include
+SDK `0.5.17` 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.15` has two related but separate normalized boundaries:
+The SDK `0.5.17` has two related but separate normalized boundaries:
 
 | Boundary | Use | Host |
 |---|---|---|

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

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.5.15",
+  "sdkVersion": "0.5.17",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",
     "moduleSystem": "ESM"
   },
-  "memberCount": 198,
+  "memberCount": 202,
   "members": [
     {
       "id": "root:APP_BUNDLE_DESCRIPTOR_NAME",
@@ -1395,7 +1395,7 @@
       "summary": "Default binding for the canonical SpeechPlayback runtime class, with capability-gated eager provider submission and exact-order playback.",
       "availability": "Node with injected media adapters, or browser/native WebView media",
       "protocol": "SpeechPlayback runtime contract",
-      "normalization": "Binding identity and namespace come directly from the canonical runtime module; a fetchTTS client with positive advertised TTS execution capacity receives all complete segments immediately while its provider owns bounded admission and SpeechPlayback retains indexed order; other clients remain serialized"
+      "normalization": "Binding identity and namespace come directly from the canonical runtime module; stored part input remains exact while only each outbound synthesis copy receives automatic repeated-formatting-mark cleanup and SDK-internal preparation metadata; a fetchTTS client with positive advertised TTS execution capacity receives all complete segments immediately while its provider owns bounded admission and SpeechPlayback retains indexed order; other clients remain serialized; canonical state dispatch precedes the optional synchronous onState callback"
     },
     {
       "id": "speech-playback:SPEECH_PLAYBACK_STATE_EVENT",
@@ -1411,6 +1411,34 @@
       "protocol": "SpeechPlayback runtime contract",
       "normalization": "Exact immutable speech-playback-state event name"
     },
+    {
+      "id": "speech-playback:SPEECH_VOICE_ALIASES",
+      "name": "SPEECH_VOICE_ALIASES",
+      "displayName": "SPEECH_VOICE_ALIASES",
+      "kind": "constant",
+      "signature": "const SPEECH_VOICE_ALIASES",
+      "entrypoints": ["arcane-os/speech-playback"],
+      "primaryImport": "arcane-os/speech-playback",
+      "group": "Portable runtime modules",
+      "summary": "Mutable compatibility membership set for the ten shared speech voice identifiers.",
+      "availability": "Node and browser",
+      "protocol": "SpeechPlayback runtime contract",
+      "normalization": "Derived once from SPEECH_VOICE_OPTIONS in published order; ordinary mutable Set containing alloy, ash, ballad, coral, echo, fable, nova, onyx, sage, and shimmer; SpeechPlayback does not select it automatically"
+    },
+    {
+      "id": "speech-playback:SPEECH_VOICE_OPTIONS",
+      "name": "SPEECH_VOICE_OPTIONS",
+      "displayName": "SPEECH_VOICE_OPTIONS",
+      "kind": "constant",
+      "signature": "const SPEECH_VOICE_OPTIONS",
+      "entrypoints": ["arcane-os/speech-playback"],
+      "primaryImport": "arcane-os/speech-playback",
+      "group": "Portable runtime modules",
+      "summary": "Mutable ordered compatibility value/label records for existing speech controls.",
+      "availability": "Node and browser",
+      "protocol": "SpeechPlayback runtime contract",
+      "normalization": "Ordinary mutable array and mutable records ordered as Alloy, Ash, Ballad, Coral, Echo, Fable, Nova, Onyx, Sage, and Shimmer; provider support and selection remain caller-owned"
+    },
     {
       "id": "speech-playback:SpeechPlayback",
       "name": "SpeechPlayback",
@@ -1423,7 +1451,7 @@
       "summary": "Named binding for the same capability-aware, exact-order canonical class exposed as the subpath default.",
       "availability": "Node with injected media adapters, or browser/native WebView media",
       "protocol": "SpeechPlayback runtime contract",
-      "normalization": "Binding identity equals the default export; prepare preserves each nonblank part input exactly without trimming, splitting, or freezing it; provider-advertised capacity enables eager submission while the provider owns its bound, native and custom clients remain serialized, and media availability remains host-owned"
+      "normalization": "Binding identity equals the default export; prepare preserves each nonblank part input exactly without trimming, splitting, or freezing it; requestSpeech changes only the cloned outbound input through automatic repeated-formatting-mark cleanup and carries SDK-internal preparation metadata; provider-advertised capacity enables eager submission while the provider owns its bound, native and custom clients remain serialized, canonical state dispatch precedes optional synchronous onState delivery, and media availability remains host-owned"
     },
     {
       "id": "speech-playback:splitSpeechText",
@@ -1439,6 +1467,34 @@
       "protocol": "SpeechPlayback runtime contract",
       "normalization": "Uses trimming only to detect blank input; nonblank text is returned unchanged in one mutable array without trimming, splitting, or freezing"
     },
+    {
+      "id": "speech-text:MarkdownSpeech",
+      "name": "MarkdownSpeech",
+      "displayName": "MarkdownSpeech",
+      "kind": "class",
+      "signature": "new MarkdownSpeech()",
+      "entrypoints": ["arcane-os/speech-text"],
+      "primaryImport": "arcane-os/speech-text",
+      "group": "Portable runtime modules",
+      "summary": "Streams speech-only repeated-formatting-mark removal across input chunk boundaries.",
+      "availability": "Node and browser",
+      "protocol": "Speech text normalization",
+      "normalization": "append(text='',end=false) emits newly available narration, retains only a trailing candidate formatting mark across chunks, and resets after a terminal append; reset() discards that pending state; caller text remains unchanged"
+    },
+    {
+      "id": "speech-text:stripSpeechFormatting",
+      "name": "stripSpeechFormatting",
+      "displayName": "stripSpeechFormatting()",
+      "kind": "function",
+      "signature": "stripSpeechFormatting(text='')",
+      "entrypoints": ["arcane-os/speech-text"],
+      "primaryImport": "arcane-os/speech-text",
+      "group": "Portable runtime modules",
+      "summary": "Removes repeated runs of speech formatting marks from one complete text value.",
+      "availability": "Node and browser",
+      "protocol": "Speech text normalization",
+      "normalization": "Calls the supplied value's replace method and returns its result with runs of two or more identical *, #, _, backtick, or ~ marks removed; single marks and every other character remain literal; it does not parse Markdown or modify the supplied value; values without callable replace fail with the native TypeError"
+    },
     {
       "id": "root:readRuntimeFile",
       "name": "readRuntimeFile",