arcane-os 0.5.16 → 0.5.17

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.16",
+    "sdkVersion": "0.5.17",
     "protocol": "arcane/1"
   },
   "artifactCount": 85,
   "javascriptArtifactCount": 83,
-  "esmExportCount": 354,
+  "esmExportCount": 356,
   "artifacts": [
     {
       "file": "runtime/arcane/modules/AI.js",
@@ -29,8 +29,8 @@
       "summary": "Owns provider-selectable chat and the one-time caller-authority browser STT/TTS configuration, lifecycle, synthesis, transcription, and playback boundary.",
       "availability": "Browser + native bridge + TWiN Cloud",
       "protocol": "arcane-ai-browser-speech-configuration/1, AIProviderRuntime arcane-ai-provider/2 routes, globalThis.arcaneEvents, TWiN Cloud HTTPS, Arcane.ollama, Arcane.speech, Android WebView bridge",
-      "normalization": "Complete mutable caller-owned browser speech authority, SDK-owned provider registration/replacement/disposal, explicit STT/TTS activation, normalized Kokoro TTS execution with default capacity 4, explicit provider-neutral execution snapshots through status(role,{execution:true}), sticky readiness, canonical window.user readiness without compatibility-event object-identity admission or polling, exact ordered structural calls with required arguments.message, atomic nonblank all-ID tool-result sequencing, complete all-choice streaming/data validation, native Ollama structural adaptation, complete-response then all validated tool callbacks then completion ordering, observed async callbacks, Blob/File transcription, immediate exact-segment synthesis, 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, 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`."
+      "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, automatic repeated-formatting-mark removal from cloned outbound TTS input while caller and visible content stays exact, immediate exact-segment synthesis, per-call voice/speed capture, optional final-segment pause on the existing audio clock, optional per-call terminal playback completion, 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; automatic speech-input cleanup with SDK-internal preparation metadata; 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",
@@ -76,8 +76,8 @@
       "summary": "Provider-neutral selection, lifecycle, routing, startup, request, streaming, cancellation, and independent LLM/STT/TTS state.",
       "availability": "Cross-host in-process runtime; registered providers remain browser, native, or cloud specific",
       "protocol": "arcane-ai-runtime/2, arcane-ai-provider/2, arcane-ai-model-authority/1",
-      "normalization": "Normalizes mutable complete per-role routes, lifecycle/status, cancellation, streaming cleanup, capacity-1 FIFO LLM/STT lanes, bounded provider-declared parallel TTS requests with FIFO overflow, local-only selection, direct LLM history/declaration/terminal structural contracts, complete all-choice content/reasoning FIFO iteration, private automatic provider draining with result-first buffering, terminal-only structural calls, exact per-choice observed/terminal correlation, and a separate complete validated terminal result without creating a fallback.",
-      "surface": "Protocol constants; singleton-only `AIProviderRuntime`; `aiProviderRuntime`; `getAIProviderRuntime()`; provider registration/identity/selection, closed three-role and STT/TTS-only validation/configuration/replacement, status/catalog/inspection, startup, per-role load/unload/dispose/cancel, dispose-all, request/stream/speech aliases, and mute controls."
+      "normalization": "Normalizes mutable complete per-role routes, lifecycle/status, cancellation, streaming cleanup, capacity-1 FIFO LLM/STT lanes, bounded provider-declared parallel TTS requests with FIFO overflow, automatic repeated-formatting-mark removal from cloned direct TTS payloads, local-only selection, direct LLM history/declaration/terminal structural contracts, complete all-choice content/reasoning FIFO iteration, private automatic provider draining with result-first buffering, terminal-only structural calls, exact per-choice observed/terminal correlation, and a separate complete validated terminal result without creating a fallback.",
+      "surface": "Protocol constants; singleton-only `AIProviderRuntime`; `aiProviderRuntime`; `getAIProviderRuntime()`; provider registration/identity/selection, closed three-role and STT/TTS-only validation/configuration/replacement, status/catalog/inspection, startup, per-role load/unload/dispose/cancel, dispose-all, request/stream/speech aliases, SDK-internal speech-input preparation metadata, and mute controls."
     },
     {
       "file": "runtime/arcane/modules/AIResponseLength.js",
@@ -831,10 +831,10 @@
       "exports": [
         "MarkdownSpeech"
       ],
-      "summary": "Removes repeated same Markdown formatting marks from streamed narration before speech segmentation.",
+      "summary": "Re-exports the shared MarkdownSpeech class that removes repeated same 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.",
+      "protocol": "Shared arcane-os/speech-text package entrypoint",
+      "normalization": "The runtime projection and public package subpath share dependency-free 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()`."
     },
     {
@@ -1162,15 +1162,17 @@
       "kind": "esm",
       "exports": [
         "SPEECH_PLAYBACK_STATE_EVENT",
+        "SPEECH_VOICE_ALIASES",
+        "SPEECH_VOICE_OPTIONS",
         "SpeechPlayback",
         "default",
         "splitSpeechText"
       ],
-      "summary": "Preserves exact nonblank segment text without trimming, splitting, or freezing it; eagerly submits complete parts to a capacity-advertising fetchTTS provider while keeping playback indexed, and retains serialized one-segment lookahead for other clients.",
+      "summary": "Preserves exact nonblank stored segment text; removes repeated formatting marks from only each outbound synthesis copy; eagerly submits complete parts to a capacity-advertising fetchTTS provider while keeping playback indexed; and retains serialized one-segment lookahead for other clients.",
       "availability": "Browser + compatible AI/native bridge",
       "protocol": "AI.fetchTTS plus providerRuntime TTS execution capacity, or compatible serialized Arcane.speech.synthesize; globalThis.arcaneEvents, Blob URLs, audio element",
-      "normalization": "Exact nonblank split/part input strings are preserved in mutable records. A capable provider receives complete segments immediately and owns bounded FIFO admission; URLs and playback stay in exact input order. Native/custom clients remain serialized. Cancellation, Replay recovery, Blob results, and lifecycle state are normalized; provider failures remain external.",
-      "surface": "SpeechPlayback class/default, `SPEECH_PLAYBACK_STATE_EVENT`, `splitSpeechText()`, canonical playback lifecycle events, cancellation, and destroy APIs."
+      "normalization": "Exact nonblank split/part input strings are preserved in mutable records. Each synthesis request clones that part, removes repeated formatting marks from only the outbound input, and carries SDK-internal preparation metadata to prevent a second cleanup pass. A capable provider receives complete segments immediately and owns bounded FIFO admission; URLs and playback stay in exact input order. Native/custom clients remain serialized. Canonical state dispatch precedes the optional synchronous onState callback. Cancellation, Replay recovery, Blob results, and lifecycle state are normalized; provider failures remain external.",
+      "surface": "SpeechPlayback class/default, mutable `SPEECH_VOICE_OPTIONS` records, mutable `SPEECH_VOICE_ALIASES` membership, `SPEECH_PLAYBACK_STATE_EVENT`, optional constructor `onState(detail)`, `splitSpeechText()`, canonical playback lifecycle events, cancellation, and destroy APIs."
     },
     {
       "file": "runtime/arcane/modules/StaticDocumentCatalog.js",

package/docs/reference/protocols.md

@@ -61,11 +61,13 @@ explicit identity fails, and the selected page then must pass exact path-relativ
 base validation.
 Included HTML with neither signal is a component fragment and remains a
 complete package file.
-`arcane-os/preference-store` and
-`arcane-os/speech-playback` are the two portable runtime subpaths: Node package
-exports and managed browser keys both resolve directly to the canonical runtime
-module namespaces, while `arcane/PreferenceStore` and
-`arcane/SpeechPlayback` are the established browser import-map names. There is
+`arcane-os/preference-store` and `arcane-os/speech-playback` are the two
+portable subpaths that resolve directly to canonical runtime-module namespaces
+from both Node package exports and managed browser keys;
+`arcane/PreferenceStore` and `arcane/SpeechPlayback` remain their established
+browser import-map names. The additional portable `arcane-os/speech-text`
+subpath owns shared dependency-free speech-input cleanup and has the same
+managed browser key. There is
 no exported `importMapApplication()` function, `generateImportMap()` function, or
 `arcane-os/import-map` package subpath.
 
@@ -159,7 +161,7 @@ imports such as:
 import ollama from 'arcane/Ollama';
 ```
 
-The physical-v1 tree lives entirely beneath `arcane/`. SDK `0.5.16` projects the
+The physical-v1 tree lives entirely beneath `arcane/`. SDK `0.5.17` 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,13 +176,13 @@ 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.16` map derives its complete entries from the selected runtime graph;
+The `0.5.17` 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
 managed graph exposes `arcane-os/event-manager`, `arcane-os/ai/browser-wasm`,
 `arcane-os/ai/browser-speech`, `arcane-os/preference-store`, and
-`arcane-os/speech-playback`; dependency compatibility mappings are added when
+`arcane-os/speech-playback` plus `arcane-os/speech-text`; dependency compatibility mappings are added when
 runtime or SDK root traversal observes them.
 
 The focused physical targets remain stable when their bindings are reached:
@@ -190,6 +192,7 @@ The focused physical targets remain stable when their bindings are reached:
 | `arcane-os/event-manager` | `./arcane/sdk/event-manager.mjs` |
 | `arcane-os/ai/browser-wasm` | `./arcane/sdk/ai/browser-wasm.mjs` |
 | `arcane-os/ai/browser-speech` | `./arcane/sdk/ai/browser-speech.mjs` |
+| `arcane-os/speech-text` | `./arcane/sdk/speech-text.mjs` |
 | `arcane-os/preference-store` | `./arcane/modules/PreferenceStore.js` |
 | `arcane-os/speech-playback` | `./arcane/modules/SpeechPlayback.js` |
 | `event-pubsub` | `./arcane/sdk/dependencies/event-pubsub/index.js` |
@@ -202,8 +205,9 @@ invented package bindings. Development serves the selected app plus the
 complete selected tree.
 Packaging copies the same map, app entry, and physical content into `dist/<id>`;
 targets never resolve through the consumer workspace's root `node_modules/`.
-The two lowercase static runtime package specifiers above are also exact npm
-package exports, so Node and managed-browser source can share those specifiers
+The two lowercase static runtime package specifiers above and the shared
+speech-text helper are exact npm package exports, so Node and managed-browser
+source can share those specifiers
 without data URLs, copied modules, or a consumer-owned loader.
 
 `generateImportMap()` is an internal toolchain operation, not a package export.
@@ -239,8 +243,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.16`; the physical package manifest must still identify
-exactly as `arcane-os@0.5.16`. Canonical-plus-alias duplicates, multiple aliases,
+`npm:arcane-os@0.5.17`; the physical package manifest must still identify
+exactly as `arcane-os@0.5.17`. 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 +355,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.16` requires WebGPU. Load requests full offload and waits for the runtime
+SDK `0.5.17` 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

@@ -366,14 +366,15 @@ 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 forwarded to
-`AI.streamTTS(text,false,{textFormat:'markdown'})` in arrival order. The AI
-owner removes repeated Markdown formatting marks from narration before the
+Each visible model chunk is forwarded to `AI.streamTTS(text)` in arrival
+order. The AI owner automatically removes repeated formatting marks from an
+outbound speech-input copy 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.
+second speech queue. No app option selects or disables this cleanup. 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

@@ -109,7 +109,7 @@ own asynchronous work, cancellation, and backpressure.
 | [`ScamRiskPolicy.js`](#scamriskpolicyjs) | esm | Combines deterministic scam signals with optional Arcane blocked-domain evidence and safety guidance. | Cross-host | Complete mutable results; blocked-domain policy requires `secure:true`. |
 | [`ScopedOPFSCache.js`](#scopedopfscachejs) | esm | Provides a narrow exact-key JSON cache inside one app-owned OPFS namespace. | Browser / native WebView | Filename-safe keys, complete JSON values, and malformed-cache cleanup normalized; storage errors mixed. |
 | [`ScreenCapture.js`](#screencapturejs) | esm | Captures a display surface as image, video, or GIF with explicit lifecycle events. | Browser / native WebView | State/events normalized; permission and codec errors mixed. |
-| [`SpeechPlayback.js`](#speechplaybackjs) | esm | Preserves exact nonblank text as one speech segment, queues latest-request synthesis, and controls lookahead HTML audio playback. | Browser + native bridge | Exact input text and state normalized; provider/media failures mixed. |
+| [`SpeechPlayback.js`](#speechplaybackjs) | esm | Admits complete speech segments to a capacity-advertising provider immediately, retains serialized native/custom lookahead, and plays every result in exact indexed order. | Browser + native bridge | Stored part text stays exact; the outbound speech-input copy receives automatic formatting-mark cleanup; provider/media failures remain mixed. |
 | [`StaticDocumentCatalog.js`](#staticdocumentcatalogjs) | esm | Loads a positive static document inventory with cache, search, and complete context. | Browser / native WebView / server with fetch | Mutable complete catalog/content normalization; malformed data and transport failures remain visible. |
 | [`SystemAppearance.js`](#systemappearancejs) | esm | Reads or applies native appearance, returning an explicit unsupported browser state when no bridge exists. | Browser/native hybrid | Absent bridge normalized; native result/error preserved. |
 | [`SystemPlatformPresentation.js`](#systemplatformpresentationjs) | classic-script | Maps kernel names to presentation labels/classes without granting platform authority. | Browser / native WebView classic script | Fully normalized presentation only. |
@@ -263,7 +263,7 @@ reports `requestedDevice`, `selectedDevice`, `maxConcurrentRequests`, and
 WASM fallback after a successful load. Calling `status()` without options keeps
 the existing sticky lifecycle snapshot and does not inspect provider execution.
 Provider inspection failures are surfaced to the caller.
-`fetchTTS({model,voice,input,responseFormat,speed},signal)` accepts the public
+`fetchTTS({model,voice,input,responseFormat,speed},signal,preparation={})` accepts the public
 provider-neutral synthesis shape, requires any explicit model to match the
 selected route, and fills an omitted voice only from the selected model
 catalog's `defaultVoice`. An omitted response format preserves the instance's
@@ -273,9 +273,14 @@ the setting is the instance's `opus` default and the model rejects it, the catal
 `speech.defaultResponseFormat` is used, while any other unsupported setting is
 rejected. It propagates the caller-owned signal and returns a playable `Blob`;
 it does not independently choose a provider, cloud fallback, model, runtime, or
-voice policy for the application. `streamTTS(text='',end=false,options={})` and
+voice policy for the application. Every call removes repeated same formatting
+marks from a cloned outbound input before delegation; the caller's payload stays
+unchanged. The third `preparation` argument is reserved for SDK-internal
+delegation, where `{speechInputPrepared:true}` prevents a second cleanup pass;
+applications omit it. `streamTTS(text='',end=false,options={})` and
 `finishTTS()` use this same request boundary. The third-argument options below
-are available in SDK `0.5.12`, with `textFormat` added in SDK `0.5.16`:
+are available in SDK `0.5.12`. The `textFormat` compatibility extra added in
+SDK `0.5.16` is ignored beginning in `0.5.17`:
 
 | Field | Default | Meaning |
 | --- | --- | --- |
@@ -283,24 +288,23 @@ are available in SDK `0.5.12`, with `textFormat` added in SDK `0.5.16`:
 | `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. |
+| `textFormat` | Ignored compatibility extra | Repeated same formatting marks are removed automatically from every TTS call. This value no longer selects or disables cleanup. |
 
 The voice and speed use the existing `fetchTTS()` validation and error path.
-Plain mode preserves the submitted text. Markdown mode changes narration only;
-it leaves displayed, stored, and model content untouched. It is a narrow
+The automatic cleanup changes only the outbound speech-input copy; displayed,
+stored, model, and caller-owned content remains exact. 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.
+text, single marks, ordinary punctuation, 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 pending
+formatting state. `textFormat` is not an opt-out.
 
 Voice, speed, pause, and playback overrides belong to the segments
 extracted in that invocation, including any text buffered by an earlier call.
 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`
+while flushing any pending formatting mark. 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`.
@@ -324,8 +328,9 @@ commas, and hyphens remain inside a segment when they join Unicode letters or
 numbers. A potentially joining mark at the current end of an incremental stream
 waits for the next character or terminal flush before the boundary is decided;
 `wordCadence` completes one after that many whole words. The earliest available
-boundary wins. Segmentation preserves every character, including punctuation
-and whitespace. Every completed segment enters synthesis immediately; provider
+boundary wins. Segmentation preserves every character of the already prepared
+speech text, including punctuation and whitespace. Every completed segment
+enters synthesis immediately; provider
 capacity supplies FIFO backpressure while allowing bounded TTS work to overlap.
 A later segment may finish synthesis first, but playback schedules only the
 contiguous ready prefix in original order. Decoded buffers with known duration
@@ -662,9 +667,11 @@ The singleton exposes read-only `protocol`, `configured`, and `speechMuted`;
 `status(role=null,options={})`; `catalog(role)`;
 `inspect(role,options={})`; `start(options)`; `load(role,options={})`;
 `unload(role,options={})`; `dispose(role,options={})`;
-`disposeAll(options={})`; `cancel(role)`; `request(role,options={})`;
+`disposeAll(options={})`; `cancel(role)`;
+`request(role,options={},preparation={})`;
 `chat(payload,options={})`; `stream(payload,options={})`;
-`transcribe(payload,options={})`; `synthesize(payload,options={})`; and
+`transcribe(payload,options={})`;
+`synthesize(payload,options={},preparation={})`; and
 `setSpeechMuted(muted)`. Provider payloads must be data-only; callbacks,
 accessors, symbols, and cycles are rejected at the provider boundary.
 
@@ -680,6 +687,14 @@ records are the closed `{llm,stt,tts}`, `{stt,tts}`, or
 `{providers,routes,expectedProviders}` shapes described below.
 `configureFromTuple()` accepts exactly six provider/model preference entries.
 
+Every direct TTS `request()` or `synthesize()` call removes repeated same
+formatting marks from a cloned outbound payload's `input` or `text` field. The
+caller's payload and request records remain unchanged. The optional
+`preparation` argument is reserved for SDK-owned delegation;
+`{speechInputPrepared:true}` prevents a second pass after another SDK speech
+boundary has already cleaned the copy. Applications omit that argument. LLM
+and STT payloads are unaffected.
+
 `register()` returns the provider's single unregister closure; caller-
 registered providers remain caller-owned. The high-level
 `AI.configureBrowserSpeech()` boundary is different: AI constructs, registers,
@@ -2261,11 +2276,12 @@ console.log(Object.keys(module));
 
 ### 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.
+Re-exports the streaming `MarkdownSpeech` filter from the shared
+`arcane-os/speech-text` package entrypoint. The filter removes repeated runs of
+`*`, `#`, `_`, backtick, and `~` before speech segmentation, 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
 
@@ -2275,7 +2291,8 @@ Exact exports: `MarkdownSpeech`.
 
 ### Availability and normalization
 
-**Cross-host.** Plain JavaScript with no dependencies. `append()` returns only
+**Cross-host.** The runtime projection and public package entrypoint share the
+same dependency-free implementation. `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()`
@@ -2899,15 +2916,17 @@ console.log(Object.keys(module));
 
 Preserves exact nonblank text, admits complete speech segments according to the
 selected client's advertised capacity, and plays indexed HTML audio in exact
-input order.
+input order. Stored parts remain exact; only each outbound synthesis payload
+copy receives automatic formatting-mark cleanup.
 
 ### Public surface
 
-`SpeechPlayback` class/default, `SPEECH_PLAYBACK_STATE_EVENT`,
-`splitSpeechText()`, and playback lifecycle APIs.
+`SpeechPlayback` class/default, the shared voice compatibility catalogs,
+`SPEECH_PLAYBACK_STATE_EVENT`, `splitSpeechText()`, the optional constructor
+state callback, and playback lifecycle APIs.
 
-Exact exports: `SPEECH_PLAYBACK_STATE_EVENT`, `SpeechPlayback`, `default`, and
-`splitSpeechText`.
+Exact exports: `SPEECH_PLAYBACK_STATE_EVENT`, `SPEECH_VOICE_ALIASES`,
+`SPEECH_VOICE_OPTIONS`, `SpeechPlayback`, `default`, and `splitSpeechText`.
 
 ```text
 new SpeechPlayback({
@@ -2917,6 +2936,7 @@ new SpeechPlayback({
   voice=null,
   responseFormat=null,
   speed=1,
+  onState=()=>{},
   createObjectURL,
   revokeObjectURL,
   delay,
@@ -2925,17 +2945,28 @@ new SpeechPlayback({
 ```
 
 `speech` must expose either `fetchTTS(payload, signal)` or
-`synthesize(payload, {signal})`. `prepare({key,parts,model,voice,responseFormat,
+`synthesize(payload, {signal})`. `SpeechPlayback` also supplies a third
+SDK-internal preparation object; existing two-argument clients may ignore it.
+`prepare({key,parts,model,voice,responseFormat,
 speed,autoplay=true})` uses only caller-supplied model, voice, and response-format
 values; those three omitted values remain omitted so the selected AI/model
 catalog may provide its documented defaults. Speed defaults to `1`, is normalized
-as a positive number, and is always sent. There is no
-hard-coded model, response format, voice, or cloud/browser fallback.
+as a positive number, and is always sent. `SPEECH_VOICE_OPTIONS` is the ordered
+mutable compatibility array `{value,label}` for `alloy`, `ash`, `ballad`,
+`coral`, `echo`, `fable`, `nova`, `onyx`, `sage`, and `shimmer`;
+`SPEECH_VOICE_ALIASES` is the mutable `Set` of those values. The class does not
+select either catalog or promise that a selected provider supports its values.
+There is no hard-coded model, response format, voice, or cloud/browser fallback.
 `splitSpeechText(value)` uses trimming only to detect blank input, then returns
 the caller's exact string in one mutable array without trimming, splitting, or
 freezing it. `prepare()` likewise preserves each nonblank part's exact `input`
 string while normalizing its other playback fields into a new mutable record.
-The class applies no part-count, character-count, pause, or input upper cap.
+At synthesis time, `requestSpeech()` copies that record, removes repeated same
+formatting marks from only the outbound `input`, and delegates with the
+SDK-internal `{speechInputPrepared:true}` argument so downstream SDK boundaries
+do not apply the non-idempotent filter again. Original part objects, stored
+parts, displayed text, and all non-input payload fields remain unchanged. The
+class applies no part-count, character-count, pause, or input upper cap.
 
 ### Admission and playback order
 
@@ -2961,8 +2992,13 @@ Every preparation owns an operation ID and one AbortController for each active
 synthesis segment or playback delay. Replacement,
 `stop()`, `cancel()`, and `destroy()` abort their owned signals, suppress stale
 settlement, release Blob URLs, and publish synchronous
-`speech-playback-state` occurrences through `globalThis.arcaneEvents`.
-Subscribers receive mutable public state detail. The detail contains
+`speech-playback-state` occurrences through `globalThis.arcaneEvents` before
+calling the optional `onState(detail)` function synchronously. Canonical
+subscribers and the callback observe the same public field values at dispatch
+time, but object identity is not promised. Both surfaces expose mutable public
+state detail. A callback failure is reported through `globalThis.reportError`
+when available, otherwise `console.error`, and does not replace playback
+settlement. The detail contains
 `state`, `message`, `key`, `index`, `total`, `producing`, `buffered`, `hasAudio`,
 `operationId`, `code`, and `reason`; a first-segment provider rejection remains
 preserved to the `prepare()` caller. Later failures surface when ordered
@@ -3004,7 +3040,10 @@ const audio = document.body.appendChild(document.createElement('audio'));
 audio.controls = true;
 const speech = new SpeechPlayback({
   audio,
-  speech: globalThis.ai
+  speech: globalThis.ai,
+  onState(detail) {
+    console.log('Speech state:', detail.state);
+  }
 });
 const button = document.body.appendChild(document.createElement('button'));
 button.textContent = 'Speak';
@@ -3020,6 +3059,19 @@ button.addEventListener('click', async function speakCompleteSegments() {
 });
 ```
 
+The shared compatibility catalogs are also available directly. They do not
+select a voice for `SpeechPlayback`:
+
+```javascript
+import {
+  SPEECH_VOICE_ALIASES,
+  SPEECH_VOICE_OPTIONS
+} from '/arcane/modules/SpeechPlayback.js';
+
+console.log(SPEECH_VOICE_OPTIONS[0]); // {value: 'alloy', label: 'Alloy'}
+console.log(SPEECH_VOICE_ALIASES.has('alloy')); // true
+```
+
 With the default browser speech configuration, both parts enter its capacity-4
 queue immediately and still play first, then second. Inspect the selected
 execution device without guessing from console warnings: