arcane-os 0.5.16 → 0.5.18

package/browser-runtime/speech-text.mjs

@@ -0,0 +1,35 @@
+import Is from './dependencies/strong-type/index.js';
+
+const is=new Is(false);
+
+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(!is.string(text)){
+            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.16` 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.16
+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.16` | 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.16`, 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.16`, `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.16`. 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.16 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.5.18 new hello-speech --path ./hello-speech --target browser
 cd hello-speech
 npm install
 npm run dev
@@ -280,15 +280,17 @@ 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`.
+streamed speech and prepared playback owned by that AI instance and settles
+pending playback results `false`. Detached preparation described below keeps
+its independent lifetime.
 
 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.
 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. The optional text format below lasts through that flush.
+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`.
 
@@ -300,6 +302,198 @@ 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.
 
+## Prepare narration once and replay stored audio
+
+Use `ai.prepareTTS()` when preparation must continue independently of playback,
+or when a later visit should reuse generated audio. It returns a handle
+synchronously and starts preparing the supplied complete parts without speaking
+them. Attach `ai.playPreparedTTS()` immediately to play those parts as their
+audio becomes available, or omit playback to prepare them silently.
+
+Use the configured `ai` and ready, application-owned `dbopfs` from the quick
+start. Configuration itself does not load Kokoro. This path reads stored audio
+first: a complete match can replay while the AI starts muted, with no model
+load. Only missing audio requests the selected provider's shared load/unmute
+path. Do not eagerly call `setSpeechMuted(false)` before this path if fully
+cached playback should avoid loading the model.
+
+```javascript
+ai.configureTTSSegmentation(
+    {
+        punctuation: 'any',
+        wordCadence: null
+    }
+);
+
+function prepareNarration(text, key) {
+    return ai.prepareTTS(
+        {
+            parts: [
+                {
+                    input: text,
+                    voice: speechSelection.model.defaultVoice,
+                    speed: 1,
+                    pauseAfterMs: 0
+                }
+            ],
+            storage: {
+                db: dbopfs,
+                table: 'saved_narration',
+                key
+            },
+            identity: {
+                model: speechSelection.model,
+                runtime: speechSelection.runtime
+            },
+            onState: reportNarrationPreparation
+        }
+    );
+}
+
+function reportNarrationPreparation(state) {
+    console.log('Narration preparation:', state);
+}
+
+function reportNarrationPlayback(state) {
+    console.log('Narration playback:', state);
+}
+
+async function readNarration(text, key) {
+    const prepared = prepareNarration(text, key);
+    const playback = ai.playPreparedTTS(
+        prepared,
+        {onState: reportNarrationPlayback}
+    );
+    const [record, ended] = await Promise.all(
+        [prepared.ready, playback.finished]
+    );
+    return {record, ended};
+}
+```
+
+Call `readNarration('**Hello**. Welcome back.', 'welcome')` from an owned user
+action and handle its rejection. Calling only `prepareNarration(...)` prepares
+silently; observe that handle's `ready` promise to receive its complete record
+or error. A storage key groups application content. The application owns its
+keys, preparation priority, semantic identity, and retention policy; the SDK
+does not select another page or speak background work.
+
+### Preparation inputs and reuse
+
+`ai.prepareTTS({parts,storage,identity,signal,onState})` accepts an ordered array
+of strings or `{input,voice?,speed?,pauseAfterMs?}` records. An omitted voice
+uses the selected model default; omitted speed uses `ai.voiceSpeed`; omitted
+pause is zero. The SDK snapshots the selected speech configuration and current
+punctuation/word-cadence options for that preparation. A part's pause applies
+after its final extracted segment. Complete original input remains available
+for semantic comparison; automatic Markdown cleanup affects only the speech
+copy and occurs once before segmentation.
+
+`storage` is optional. When supplied, `{db,table,key}` names the caller's ready
+DBOPFS instance and its application-owned table/key. The SDK stores complete
+generated audio as raw files and retains MIME metadata separately so subsequent
+`Blob` playback preserves its content type. Reuse compares complete semantic
+inputs, including parts, selection, segmentation, and separate application
+`identity`. A changed voice, speed, source text, or other semantic selection
+prepares the changed request. An SDK patch version alone does not invalidate
+stored speech.
+
+The storage key is encoded as `encodeURIComponent(key) + '.json'` for its
+manifest. That version-1 manifest keeps an `entries` array of semantic variants
+under the key. Each entry records
+`{id,parts,originalParts,selection,segmentation,identity,segments}`; the ordered
+stored segment entries name `{audioFile,contentType}`. `originalParts` retains
+the complete source text, including whitespace. These persistent semantic
+inputs and `identity` must be JSON-compatible. Raw audio filenames contain the
+generated record ID and segment index. Storage writes preserve existing
+variants; the application chooses when its records should be removed.
+
+Matching pending requests on the same AI instance and the same storage
+`db`/`table`/`key` share synthesis. Each caller receives its own handle and
+cancellation signal. Cancelling one handle detaches that caller; the shared
+preparation is aborted only when its last pending caller cancels. Different AI
+instances do not share an in-flight synthesis operation. Complete stored
+results remain reusable through the same application storage.
+After a durable preparation completes, a later preparation call rereads its
+manifest and saved-file presence, regenerating only missing segments. A
+completed preparation without storage reuses its retained Blobs.
+
+Preparation requests retain call order for synthesis admission. Within each
+request, punctuation segments use the existing bounded provider queue: the
+default Kokoro capacity admits up to four at once, with later segments waiting
+in FIFO order. Completion may be out of order; segment metadata and playback
+remain in input order. Preparing another request does not attach it to playback.
+
+### Preparation handle and progress
+
+| Member | Contract |
+| --- | --- |
+| `state` | Current string: `queued`, `preparing`, `ready`, `error`, or `cancelled`. |
+| `segments` | Ordered segment metadata with `input`, `voice`, `speed`, `pauseAfterMs`, `index`, `state`, `audioFile`, `contentType`, and `error`. |
+| `ready` | Promise resolving the complete ordered record when every segment is generated or reused and, when storage is supplied, durably saved. Rejects with the complete error or `AbortError` if cancelled while pending. |
+| `getAudio(index)` | Promise waiting for that ordered segment and returning its complete `Blob` with the recorded MIME type. |
+| `cancel()` | Cancels this preparation handle without erasing successful stored segments. |
+
+The optional synchronous `onState` callback receives
+`{state,completed,total,segments,error}`. It observes preparation only; it is
+not a playback-state callback. `completed` counts settled segments, including
+failed segments; inspect `state`, segment errors, and `ready` for the outcome.
+`total` is the number of ordered segments.
+Without `storage`, the handle retains generated Blobs for its lifetime; the
+same result shape has `audioFile:null` and the actual `contentType`.
+The supplied signal observes preparation until `ready` settles. Manual
+`cancel()` remains available afterward to stop further reads through that
+handle. If a raw audio write has already begun when cancellation arrives,
+its metadata transaction finishes so that successful audio can be reused;
+no later queued write starts for that cancelled preparation.
+Cancelling preparation prevents later synthesis, but the existing shared
+provider load/unmute operation has no per-preparation signal and may finish.
+Cancellation does not claim to stop an already-started shared model load.
+
+### Playback controls and independent lifetimes
+
+`ai.playPreparedTTS(prepared,{signal,onState})` 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
+pauses separate adjacent parts; a final trailing pause does not delay
+`finished`, which resolves after the final audio buffer ends.
+
+`state` and `error` are current-state getters. The optional synchronous
+`onState` callback receives `{state,error}` and is observational. Playback
+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.
+
+`finished` resolves `true` after natural playback completion and `false` after
+stop, playback cancellation, or failure. Real failures also reach the existing
+`ai-tts-failure` event and complete SDK diagnostics. `pause()`
+and `resume()` control only this handle's audio context, and `stop()` stops
+that playback handle. The controls return booleans; pause and resume are
+asynchronous. Each AI has one playback lane: a new `playPreparedTTS()` call
+stops its preceding streamed or prepared playback, and `streamTTS()` interrupts
+active prepared playback. This replacement preserves detached preparation.
+None of these playback controls cancels preparation or deletes saved audio.
+Use the preparation handle's `cancel()` or its separate `signal` when the
+application also wants to stop preparation. Successful saved segments survive
+cancellation or failure for later reuse.
+
+`ai.stopAudio()` stops streamed speech and all prepared playback on that AI,
+while detached preparation continues. `ai.setSpeechMuted(true)` additionally
+cancels provider TTS work and unloads the provider. Replacing the speech
+configuration cancels missing generation tied to the earlier selection.
+Neither action deletes completed stored audio. Apply those broader lifecycle
+controls deliberately when the application intends to stop provider work.
+
+Preparation `ready` and playback `finished` are separate promises. Natural
+playback completion must not be used as a signal to cancel other background
+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.
+
 ## Stream chunks as they arrive
 
 Use the configured `ai` created above. Run this snippet from an owned user
@@ -343,18 +537,19 @@ 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.
 
-## Omit Markdown formatting marks from narration
+## Automatic speech-input formatting cleanup
 
-Select `textFormat:'markdown'` for raw model text that contains formatting:
+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', false, {textFormat:'markdown'});
+ai.streamTTS('## Heading\n**Hello');
 ai.streamTTS('**. Next sentence.');
 await ai.finishTTS();
 ```
@@ -366,12 +561,30 @@ 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.
 
-The format stays active until `end:true`, `finishTTS()`, or cancellation. New
-streams default to `plain`, which preserves exact submitted text. The shared
-chat component selects Markdown mode automatically. Applications already
-speaking visible DOM text can keep plain mode. Displayed messages, saved
-history, model input, language, voice, synthesis capacity, and playback timing
-are not changed by the filter.
+`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 shared 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
 
@@ -446,7 +659,7 @@ These are actions for your own controls, using the same `ai` instance:
 
 ```javascript
 function stopSpeech() {
-  ai.stopAudio(); // Cancels queued speech and stops scheduled/playing audio.
+  ai.stopAudio(); // Stops streamed speech and all prepared playback.
 }
 
 async function muteSpeech() {
@@ -476,7 +689,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();

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.16 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

@@ -3,6 +3,46 @@
 Use this page to choose an API by capability. The compact labels tell you where
 it runs; the [protocol guide](protocols.md) contains the implementation detail.
 
+## Shared type predicates
+
+SDK-owned JavaScript uses the declared `strong-type` dependency for type
+predicates. Node and managed renderer modules import `Is` from `strong-type`;
+browser providers and workers use their shipped relative dependency path.
+Component scripts import it within their own asynchronous component scope.
+Publication bootstrap tools import the shipped runtime dependency by relative
+path so they remain available before npm dependency installation.
+The dependency pin and both shipped projections use 2.0.1. Update them together
+through the published dependency workflow when another version is needed.
+
+Reuse one non-throwing instance per module or component:
+
+```javascript
+import Is from 'strong-type';
+
+const is=new Is(false);
+
+function requireText(value){
+    if(!is.string(value))throw new TypeError('Text is required.');
+    return value;
+}
+```
+
+The predicates classify values without coercing them. Existing API owners keep
+their defaults, domain constraints, complete payloads, and public error behavior.
+Use `number` for primitive numbers, `finite` for finite numbers, and `integer`
+or `safeInteger` for the corresponding integer contract. `object` includes null;
+retain a contract's separate null and array handling. `plainObject` is narrower
+than a general non-array object check and must not silently reject previously
+accepted class instances.
+
+Constructor identity checks, diagnostic type labels, foreign-language source,
+and isolated generated script bodies retain native operators where a replacement
+would change their contract or execution scope. `DBOPFSWorker.js` and
+`SystemPlatformPresentation.js` retain their few native predicates to preserve
+classic-script loading and synchronous availability. Upstream dependency source is
+consumed unchanged. Non-throwing strong-type array and constructor probes return
+false when a probe throws; SDK branching continues through its owning error path.
+
 ## Availability labels
 
 | Label | Meaning |
@@ -32,12 +72,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.16` 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.16` 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.16",
+  "sdkVersion": "0.5.18",
   "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",

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.16"
+    "sdkVersion": "0.5.18"
   },
   "componentCount": 39,
   "loader": "/arcane/modules/HTMLImport.js",
@@ -171,7 +171,7 @@
       ],
       "availability": "Browser and supported native WebViews",
       "transport": "HTMLImport + DOM; injected Arcane/provider modules where listed",
-      "normalization": "UI/runtime state, honest model progress, complete timestamped transcript including ui_hidden stored records, user-facing structural arguments.message, nonblank all-ID tool-result restoration, collapsed complete raw inspection, ordered parallel-call replay validation, per-choice streamed/terminal complete-envelope correlation, complete nonstructural stream rendering, generic visible failure outcomes with complete console diagnostics, atomic executed/declined/cancelled/not-executed result batches with one continuation, plural pending-call reload recovery, reentrant terminal-event ownership, and BFCache-preserving page lifecycle are normalized; destroy aborts observation and returns true once/false thereafter; AI/storage/media behavior remains mixed"
+      "normalization": "UI/runtime state, honest model progress, complete timestamped transcript including ui_hidden stored records, user-facing structural arguments.message, nonblank all-ID tool-result restoration, collapsed complete raw inspection, ordered parallel-call replay validation, per-choice streamed/terminal complete-envelope correlation, complete nonstructural stream rendering, automatic repeated-formatting-mark removal from only the outbound speech-input copy while displayed and stored Markdown stays exact, generic visible failure outcomes with complete console diagnostics, atomic executed/declined/cancelled/not-executed result batches with one continuation, plural pending-call reload recovery, reentrant terminal-event ownership, and BFCache-preserving page lifecycle are normalized; destroy aborts observation and returns true once/false thereafter; AI/storage/media behavior remains mixed"
     },
     {
       "file": "runtime/arcane/components/conversation-view.html",