arcane-os 0.5.15 → 0.5.16

package/CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Unreleased
 
+## 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.16` 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.16 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';
@@ -301,6 +305,14 @@ 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.
 
+For raw Markdown narration, use
+`ai.streamTTS(text,false,{textFormat:'markdown'})`. The SDK removes repeated
+same formatting marks (`*`, `#`, `_`, backtick, `~`) before segmentation,
+including runs split across chunks. Single punctuation and ordinary repeated
+punctuation remain literal. The format lasts through `finishTTS()`; new
+streams default to exact plain text. Shared chat selects Markdown mode while
+preserving original messages for display and storage.
+
 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 +334,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.16 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run dev
@@ -332,7 +344,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.16
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -348,7 +360,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.16` 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 +380,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.16.tgz
 npm ci
 ```
 
@@ -377,7 +389,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.16` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -516,7 +528,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.5.15` exposes one browser target and five explicitly paired
+Version `0.5.16` 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.15` runtime requires Arcane `0.8.12` or newer. Compatibility
+The SDK `0.5.16` 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.16
 ```
 
 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.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. |
 | 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.16`. 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.15 new hello-speech --path ./hello-speech --target browser
+npx arcane-os@0.5.16 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,9 @@ 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. The optional text format below lasts through that flush.
 A call extracting no segments returns `true` without waiting for earlier jobs.
 An already muted call returns `false`.
 
@@ -337,6 +349,30 @@ 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
+
+Select `textFormat:'markdown'` for raw model text that contains formatting:
+
+```javascript
+ai.streamTTS('## Heading\n**Hello', false, {textFormat:'markdown'});
+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.
+
+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.
+
 ## Choose a device or reduce memory use
 
 Omitting `tts.execution` selects `{device:'auto',maxConcurrentRequests:4}`.
@@ -401,6 +437,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
 
@@ -875,7 +913,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.16 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.15` preserves the physical workspace route count and ordered include
+SDK `0.5.16` 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.16` has two related but separate normalized boundaries:
 
 | Boundary | Use | Host |
 |---|---|---|

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

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.5.15",
+  "sdkVersion": "0.5.16",
   "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.15"
+    "sdkVersion": "0.5.16"
   },
   "componentCount": 39,
   "loader": "/arcane/modules/HTMLImport.js",

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

@@ -5,12 +5,12 @@
     "repository": "https://github.com/TheWizardNexus/arcane-os-sdk.git",
     "branch": "main",
     "path": "runtime/arcane",
-    "sdkVersion": "0.5.15",
+    "sdkVersion": "0.5.16",
     "protocol": "arcane/1"
   },
-  "artifactCount": 84,
-  "javascriptArtifactCount": 82,
-  "esmExportCount": 353,
+  "artifactCount": 85,
+  "javascriptArtifactCount": 83,
+  "esmExportCount": 354,
   "artifacts": [
     {
       "file": "runtime/arcane/modules/AI.js",
@@ -30,7 +30,7 @@
       "availability": "Browser + native bridge + TWiN Cloud",
       "protocol": "arcane-ai-browser-speech-configuration/1, AIProviderRuntime arcane-ai-provider/2 routes, globalThis.arcaneEvents, TWiN Cloud HTTPS, Arcane.ollama, Arcane.speech, Android WebView bridge",
       "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized 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`."
+      "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, waitForPlayback, and speech-only textFormat plain/markdown; 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",
@@ -824,6 +824,19 @@
       "normalization": "Endpoint, timeout, cancellation, network, HTTP, and response-contract errors are normalized.",
       "surface": "`MailTransportError`, `normalizeMailEndpoint()`, `serializeMailReport()`, and `sendMailReport()`."
     },
+    {
+      "file": "runtime/arcane/modules/MarkdownSpeech.js",
+      "name": "MarkdownSpeech.js",
+      "kind": "esm",
+      "exports": [
+        "MarkdownSpeech"
+      ],
+      "summary": "Removes repeated same Markdown formatting marks from streamed narration before speech segmentation.",
+      "availability": "Cross-host",
+      "protocol": "In-process only",
+      "normalization": "Speech-only filtering of repeated *, #, _, backtick, and ~ runs across chunks; single marks and all other characters remain literal; terminal flush and reset clear pending formatting state.",
+      "surface": "`MarkdownSpeech`; `append(text='',end=false)`, `reset()`."
+    },
     {
       "file": "runtime/arcane/modules/Marked.min.js",
       "name": "Marked.min.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.15` projects the
+The physical-v1 tree lives entirely beneath `arcane/`. SDK `0.5.16` 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.15` map derives its complete entries from the selected runtime graph;
+The `0.5.16` 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.15`; the physical package manifest must still identify
-exactly as `arcane-os@0.5.15`. Canonical-plus-alias duplicates, multiple aliases,
+`npm:arcane-os@0.5.16`; the physical package manifest must still identify
+exactly as `arcane-os@0.5.16`. 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.15` requires WebGPU. Load requests full offload and waits for the runtime
+SDK `0.5.16` 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

@@ -360,17 +360,20 @@ 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()`. Playback-start or playback-resume failures can occur
-after Chat's two-argument `streamTTS()` preparation promise has resolved.
+after Chat's `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
-order. The AI owner preserves exact segmentation, admits completed segments to
-bounded synthesis immediately, and schedules the contiguous ready audio prefix
-on the audio clock. Chat neither creates a second queue nor reorders, combines,
-or rewrites speech text.
+Each visible model chunk is forwarded to
+`AI.streamTTS(text,false,{textFormat:'markdown'})` in arrival order. The AI
+owner removes repeated Markdown formatting marks from narration before the
+configured segmentation, admits completed segments to bounded synthesis
+immediately, and schedules the contiguous ready audio prefix on the audio
+clock. Chat retains the original Markdown for display and storage and owns no
+second speech queue. Single punctuation, ordinary repeated punctuation,
+language, and voice retain their existing behavior.
 
 Events: `chat-ready`, `chat-session-bound`, `chat-session-message`,
 `chat-session-error`, `chat-send-message`, `chat-send-error`,

package/docs/reference/runtime-modules.md

@@ -88,6 +88,7 @@ own asynchronous work, cancellation, and backpressure.
 | [`Mail.js`](#mailjs) | esm | Builds complete reports and prefers the native mail capability with an explicit HTTP transport fallback. | Browser/native hybrid + cloud | Mail inputs/results normalized; transport failures mixed. |
 | [`MailOutbox.mjs`](#mailoutboxmjs) | esm | Persists complete mail reports before delivery and normalizes idempotent enqueue, retry, reconciliation, and invalid-record maintenance. | Browser/native WebView or compatible injected host | Complete records, full work, cancellation, and lifecycle states normalized; storage, lock, and delivery failures coded. |
 | [`MailTransport.mjs`](#mailtransportmjs) | esm | Sends one complete mail report to a normalized HTTP(S) endpoint. | Browser/server with fetch + cloud | Normalized endpoint and transport errors; remote detail preserved. |
+| [`MarkdownSpeech.js`](#markdownspeechjs) | esm | Removes repeated Markdown formatting marks from streamed narration. | Cross-host | Speech-only filtering; single marks and ordinary punctuation remain literal. |
 | [`Marked.min.js`](#markedminjs) | esm | Vendored Marked 18.0.5 Markdown lexer, parser, renderer, extension, and walk-token API. | Cross-host vendor module | Vendor-native Marked contract. |
 | [`MD.js`](#mdjs) | esm | Renders complete Markdown with Marked and exposes the complete rendered markup. | Browser / native WebView | Complete raw and rendered Marked values; parse errors vendor-native. |
 | [`MemoryRecords.js`](#memoryrecordsjs) | esm | Normalizes memory content and detects meaningful stored memory. | Cross-host | Fully normalized string/boolean results. |
@@ -274,7 +275,7 @@ 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. `streamTTS(text='',end=false,options={})` and
 `finishTTS()` use this same request boundary. The third-argument options below
-are available in SDK `0.5.12`:
+are available in SDK `0.5.12`, with `textFormat` added in SDK `0.5.16`:
 
 | Field | Default | Meaning |
 | --- | --- | --- |
@@ -282,12 +283,24 @@ are available in SDK `0.5.12`:
 | `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. |
+| `textFormat` | `plain` for a new stream | `markdown` removes repeated same formatting marks (`*`, `#`, `_`, backtick, `~`) before segmentation. Single marks and ordinary punctuation remain literal. The selected format lasts through this producer's terminal flush. |
 
 The voice and speed use the existing `fetchTTS()` validation and error path.
-No option rewrites the submitted text. Overrides belong to the segments
+Plain mode preserves the submitted text. Markdown mode changes narration only;
+it leaves displayed, stored, and model content untouched. It is a narrow
+formatting-mark filter, not a full Markdown parser: links, code contents, list
+text, and other characters remain literal. A trailing candidate mark waits for
+the next character so a repeated run split across chunks is still omitted.
+Ordinary prose streams immediately. `end:true`, `finishTTS()`, muted terminal
+calls, and `stopAudio()` clear the formatting state. An explicit format change
+flushes pending formatting marks under the preceding mode before accepting
+the next text. `fetchTTS()` retains its exact-text contract.
+
+Voice, speed, pause, and playback 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`
+Those overrides are not retained with an unfinished `end:false` remainder; a
+later call supplies its own options, and `finishTTS()` uses their defaults
+while retaining the active text format. 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`.
@@ -2244,6 +2257,41 @@ import * as module from '/arcane/modules/MailTransport.mjs';
 console.log(Object.keys(module));
 ```
 
+## MarkdownSpeech.js
+
+### Overview
+
+Filters repeated same Markdown formatting marks from narration before speech
+segmentation. The filter recognizes `*`, `#`, `_`, backtick, and `~` runs of two
+or more, including runs arriving across separate chunks. Single marks,
+ellipses, quoted sentence endings, whitespace, and all other text remain
+literal. It neither interprets links nor changes language or voice.
+
+### Public surface
+
+`MarkdownSpeech`; `append(text='',end=false)`, `reset()`.
+
+Exact exports: `MarkdownSpeech`.
+
+### Availability and normalization
+
+**Cross-host.** Plain JavaScript with no dependencies. `append()` returns only
+the newly available narration. Only a trailing candidate marker and whether
+it repeats are retained; ordinary text is emitted immediately. Terminal
+`append(text,true)` flushes a single pending mark and resets state. `reset()`
+clears pending formatting state when its narration is cancelled. Non-string
+input throws `TypeError`.
+
+### Example
+
+```javascript
+import {MarkdownSpeech} from '/arcane/modules/MarkdownSpeech.js';
+
+const speech = new MarkdownSpeech();
+const first = speech.append('**Hello'); // Hello
+const last = speech.append('**...', true); // ...
+```
+
 ## Marked.min.js
 
 ### Overview

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.15`.
+for the installed-inventory-derived physical-runtime contract in SDK `0.5.16`.
 
 | Specifier | Purpose |
 | --- | --- |
@@ -751,7 +751,7 @@ deterministic map. The package root also contains the public
 {
   schemaVersion: 1,
   kind: 'arcane-app-runtime-projection',
-  sdkVersion: '0.5.15',
+  sdkVersion: '0.5.16',
   pathPrefix: 'arcane/',
   files: [{path}]
 }
@@ -3463,7 +3463,7 @@ workspace it additionally returns the exact installed package authority:
     packageSource,
     canonicalPackageRoot,
     packageName: 'arcane-os',
-    packageVersion: '0.5.15',
+    packageVersion: '0.5.16',
     runtimeRoot,
     browserRuntimeRoot
   }
@@ -3471,9 +3471,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.15`. The selected installation must still be one direct,
+`npm:arcane-os@0.5.16`. The selected installation must still be one direct,
 physical, non-link package directory whose manifest identifies exactly as
-`arcane-os@0.5.15`; duplicate canonical/alias declarations reject.
+`arcane-os@0.5.16`; duplicate canonical/alias declarations reject.
 `allowMissingManagedImportMap` is an internal packaging/development seam. An
 ordinary caller should leave it `false`.
 

package/examples/wasm-ai-demo/README.md

@@ -8,6 +8,8 @@ For the smallest first request, start with the [browser speech quick start](../.
 
 The demo deliberately omits `tts.execution` in `speechConfiguration(dbopfs)` so it consumes the SDK default `{device:'auto',maxConcurrentRequests:4}`. Change that application's TTS record to `execution:{device:'wasm',maxConcurrentRequests:1}` to use less memory, or choose `webgpu` explicitly. Allowed capacities are 1 through 4; Whisper and the LLM retain capacity one.
 
+The maintained Kokoro selection uses `fp32` because [Kokoro.js recommends `fp32` when using WebGPU](https://github.com/hexgrad/kokoro/tree/main/kokoro.js#usage). Automatic fallback keeps the same dtype on WASM. `selectedDevice` identifies the loaded route; it does not validate speech correctness or audio quality, so evaluate actual output for each browser and device combination your application supports.
+
 Capacity 4 means up to four segments synthesize at once. Segment 5 and later wait in the SDK's FIFO queue; they are not dropped. Synthesis may finish out of order, but playback waits for earlier segments and plays exact input order. Each slot owns a Worker/model session, so raising capacity trades memory for latency.
 
 Use the shared Speech component to load/unmute speech, then select **Inspect speech execution** below Chat. The button reads `ai.providerRuntime.status('tts',{execution:true}).execution` and displays requested device, selected device, capacity, active requests, and automatic WASM fallback. It is a snapshot at the moment clicked. `selectedDevice:null` means no pool is selected; `webgpu` reports the upstream execution-provider selection and does not prove physical GPU kernel overlap or audio quality. Auto may fall back to WASM with the same selected model/dtype; explicit WebGPU reports an error when it cannot load.
@@ -39,7 +41,7 @@ Model weights are deliberately excluded from Git. Place the maintained GGUF shar
 
 The maintained model descriptors include each shard's known byte length as progress metadata. During a cold install, the SDK reports aggregate loaded and remaining bytes, transfer speed, estimated time, and active file or Range transfers while Chat presents the existing activation progress bar. Completed shards and completed Range parts within a shard remain available after interruption, so retry downloads only missing work.
 
-The app gives the SDK browser-speech owner the existing Whisper tiny.en FP32 and Kokoro 82M Q8 descriptors. The app does not import those runtimes or create a speech worker itself.
+The app gives the SDK browser-speech owner the existing Whisper tiny.en FP32 and Kokoro 82M FP32 descriptors. The app does not import those runtimes or create a speech worker itself.
 
 ## Local retrieval
 

package/examples/wasm-ai-demo/app.js

@@ -435,12 +435,13 @@ function speechConfiguration(dbopfs) {
     },
     tts: {
       // Omit execution to use the SDK's auto device and four synthesis slots.
+      // Kokoro.js recommends fp32 for the WebGPU route attempted by auto.
       providerId: "wasm-ai-demo-browser-kokoro",
       model: {
         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: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.5.15",
+  "version": "0.5.16",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -66,7 +66,7 @@
     "test:unit": "node ./bin/arcane-test.mjs test/app-descriptor.test.mjs test/app-schema.test.mjs test/contracts.test.mjs test/doctor.test.mjs test/mail-credentials.test.mjs test/mail-outbox.test.mjs test/mail-public-api.test.mjs test/mail-send.test.mjs test/mail-transport.test.mjs test/targets.test.mjs test/workspace-operation-lock.test.mjs",
     "test:functional": "node ./bin/arcane-test.mjs test/browser-speech-providers.test.mjs test/browser-wasm-gpu-notice.test.mjs test/browser-wasm-download-resume.test.mjs test/cli.test.mjs test/dbopfs-document-library.test.mjs test/dev-server.test.mjs test/dom-event-instrumentation.test.mjs test/event-manager.test.mjs test/events.test.mjs test/import-map.test.mjs test/mail-cli.test.mjs test/mail-runtime.test.mjs test/mail-server.test.mjs test/packaging.test.mjs test/persistent-ai-chat-session.test.mjs test/reference-completeness.test.mjs test/runtime-api-behavior.test.mjs test/runtime.test.mjs test/scaffold.test.mjs test/speech-playback.test.mjs test/site.test.mjs test/update-check.test.mjs",
     "test:integration": "node ./bin/arcane-test.mjs test/integrated-shared.test.mjs test/integrated-workspace.test.mjs test/mail-browser.test.mjs test/native-plan.test.mjs test/native-provider-loader.test.mjs test/npm-release.test.mjs test/release-bundle.test.mjs test/release-capability-smoke.test.mjs test/shared-payload-batch.test.mjs test/tarball.test.mjs test/wllama-webgpu-runtime.test.mjs",
-    "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/logging-regression.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
+    "test:regression": "node ./bin/arcane-test.mjs test/channel-workflows.test.mjs test/logging-regression.test.mjs test/markdown-speech.test.mjs test/native-provider-generation.test.mjs test/speech-queue-regression.test.mjs test/testing.test.mjs test/test-sets.test.mjs",
     "check": "node tools/check-source.mjs && npm test",
     "check:release": "node tools/check-source.mjs --package-only && npm run test:release",
     "pack:local": "npm pack --ignore-scripts",

package/runtime/arcane/components/chat.html

@@ -2817,7 +2817,9 @@
         ){
             const aiRuntime=boundChatAI??globalThis.ai;
             if(typeof aiRuntime?.streamTTS==='function'){
-                void Promise.resolve(aiRuntime.streamTTS(text)).catch(
+                void Promise.resolve(aiRuntime.streamTTS(
+                    text,false,{textFormat:'markdown'}
+                )).catch(
                     reportTTSError
                 );
             }else{

package/runtime/arcane/modules/AI.js

@@ -13,6 +13,7 @@ import {
 } from './AIProviderRuntime.js';
 import {normalizeOllamaModelIdentifier} from './OllamaModelIdentifier.js';
 import {arcaneLogging} from 'arcane-os/logging';
+import {MarkdownSpeech} from './MarkdownSpeech.js';
 
 const completeValue=(value)=>value;
 
@@ -2029,6 +2030,8 @@ class AI {
     }
 
     audioMessageChunks='';
+    #speechTextFormat='plain';
+    #markdownSpeech=new MarkdownSpeech();
     sourceNodes=[];
     isSpeaking=false;
     audioContext=null;
@@ -5731,6 +5734,8 @@ class AI {
         if(this.muted){
             if(end){
                 this.audioMessageChunks='';
+                this.#speechTextFormat='plain';
+                this.#markdownSpeech.reset();
             }
             this.#traceSpeech('streamTTS.result',{callId,result:false,reason:'muted'});
             return Promise.resolve(false);
@@ -5742,11 +5747,24 @@ class AI {
             throw new RangeError('Speech pauses must be a nonnegative number of milliseconds.');
         }
 
-        this.audioMessageChunks+=String(text||'');
+        const textFormat=options.textFormat??this.#speechTextFormat;
+        if(textFormat!=='plain'&&textFormat!=='markdown'){
+            throw new TypeError('Speech textFormat must be plain or markdown.');
+        }
+        let speechText='';
+        if(textFormat!==this.#speechTextFormat){
+            speechText=this.#markdownSpeech.append('',true);
+        }
+        const incomingText=String(text||'');
+        speechText+=textFormat==='markdown'
+            ?this.#markdownSpeech.append(incomingText,end)
+            :incomingText;
+        this.#speechTextFormat=end?'plain':textFormat;
+        this.audioMessageChunks+=speechText;
         const outputs=this.#extractSpeechSegments(end);
         this.#traceSpeech('streamTTS.segments',{
             callId,segments:outputs,remainder:this.audioMessageChunks,
-            segmentation:this.ttsSegmentation
+            segmentation:this.ttsSegmentation,textFormat,speechText
         });
 
         if(!outputs.length){
@@ -6414,6 +6432,8 @@ class AI {
         this.speechScheduleContext=null;
         this.speechScheduleTime=0;
         this.audioMessageChunks='';
+        this.#speechTextFormat='plain';
+        this.#markdownSpeech.reset();
         this.#clearSpeechUnlock();
 
         for(const job of this.speechJobs){

package/runtime/arcane/modules/MarkdownSpeech.js

@@ -0,0 +1,50 @@
+const FORMATTING_MARKERS=new Set(['*','#','_','`','~']);
+
+// Speech-only filtering; single markers and all other text remain literal.
+class MarkdownSpeech {
+    #pendingMarker='';
+    #repeated=false;
+
+    append(text='',end=false){
+        if(typeof text!=='string'){
+            throw new TypeError('Markdown speech input must be text.');
+        }
+
+        let narration='';
+
+        for(const character of text){
+            if(character===this.#pendingMarker){
+                this.#repeated=true;
+                continue;
+            }
+
+            if(this.#pendingMarker&&!this.#repeated){
+                narration+=this.#pendingMarker;
+            }
+            this.reset();
+
+            if(FORMATTING_MARKERS.has(character)){
+                // Wait for the next character to distinguish one mark from a run.
+                this.#pendingMarker=character;
+            }else{
+                narration+=character;
+            }
+        }
+
+        if(end){
+            if(this.#pendingMarker&&!this.#repeated){
+                narration+=this.#pendingMarker;
+            }
+            this.reset();
+        }
+
+        return narration;
+    }
+
+    reset(){
+        this.#pendingMarker='';
+        this.#repeated=false;
+    }
+}
+
+export {MarkdownSpeech};