arcane-os 0.5.16 → 0.5.17

package/docs/reference/sdk-api.md

@@ -1,8 +1,9 @@
 # Arcane OS SDK JavaScript API
 
 The npm package exposes a Node.js ESM control plane, the portable
-`arcane-os/event-manager`, `arcane-os/logging`, `arcane-os/mail`, `arcane-os/preference-store`, and
-`arcane-os/speech-playback` entrypoints, and the browser-only
+`arcane-os/event-manager`, `arcane-os/logging`, `arcane-os/mail`,
+`arcane-os/preference-store`, `arcane-os/speech-playback`, and
+`arcane-os/speech-text` entrypoints, and the browser-only
 `arcane-os/ai/browser-wasm` and `arcane-os/ai/browser-speech` entrypoints.
 Those package subpaths are distinct from application-facing projection modules
 in the managed browser map, such as `arcane/AIProviderRuntime`,
@@ -18,7 +19,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.16`.
+for the installed-inventory-derived physical-runtime contract in SDK `0.5.17`.
 
 | Specifier | Purpose |
 | --- | --- |
@@ -36,6 +37,7 @@ for the installed-inventory-derived physical-runtime contract in SDK `0.5.16`.
 | `arcane-os/logging` | Shared console diagnostics controlled by the existing `user.developer` preference. |
 | `arcane-os/preference-store` | Portable preference records and injected storage adapters. |
 | `arcane-os/speech-playback` | Portable speech preparation, playback state, and injected media adapters. |
+| `arcane-os/speech-text` | Dependency-free speech-input formatting cleanup for complete text and streamed chunks. |
 | `arcane-os/ai/browser-wasm` | Caller-selected browser-local Wllama inference, complete DBOPFS model storage, streaming, cancellation, and structural tool-call results. |
 | `arcane-os/ai/browser-speech` | Caller-selected browser-local Whisper STT and Kokoro TTS provider mechanisms, ordinary upstream assets, materialized/native routing, Workers, and cancellation. |
 | `arcane-os/mail` | Portable Mail runtime, durable outbox, complete transport responses, and provider-neutral acceptance contracts. |
@@ -143,6 +145,7 @@ browser map are cataloged separately in [Runtime modules](runtime-modules.md).
 | `loadSdkBrowserRuntimeRelease()` | function | `arcane-os` | Runtime and app descriptors | Node |
 | `materializeInstalledSdkRuntime()` | function | `arcane-os` | Runtime and app descriptors | Node |
 | `materializeWorkspaceRuntimeContent()` | function | `arcane-os` | Runtime and app descriptors | Node |
+| `MarkdownSpeech` | class | `arcane-os/speech-text` | Portable runtime modules | Node and browser |
 | `NATIVE_BUILD_PLAN_PROTOCOL` | constant | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
 | `NATIVE_BUILDER_PROTOCOL` | constant | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
 | `normalizeError()` | function | `arcane-os` | Errors | Node |
@@ -187,8 +190,11 @@ browser map are cataloged separately in [Runtime modules](runtime-modules.md).
 | `selectApp()` | function | `arcane-os` | Workspace, doctor, repository, and server | Node |
 | `SpeechPlayback default export` | class | `arcane-os/speech-playback` | Portable runtime modules | Node with injected media adapters, or browser/native WebView media |
 | `SPEECH_PLAYBACK_STATE_EVENT` | constant | `arcane-os/speech-playback` | Portable runtime modules | Node and browser |
+| `SPEECH_VOICE_ALIASES` | constant | `arcane-os/speech-playback` | Portable runtime modules | Node and browser |
+| `SPEECH_VOICE_OPTIONS` | constant | `arcane-os/speech-playback` | Portable runtime modules | Node and browser |
 | `SpeechPlayback` | class | `arcane-os/speech-playback` | Portable runtime modules | Node with injected media adapters, or browser/native WebView media |
 | `splitSpeechText()` | function | `arcane-os/speech-playback` | Portable runtime modules | Node and browser |
+| `stripSpeechFormatting()` | function | `arcane-os/speech-text` | Portable runtime modules | Node and browser |
 | `startDevServer()` | function | `arcane-os` | Workspace, doctor, repository, and server | Node control plane; browser data plane |
 | `startSourceExampleServer()` | function | `arcane-os` | Workspace, doctor, repository, and server | Node control plane; browser data plane |
 | `TARGET_ADAPTER_PROTOCOL` | constant | `arcane-os` | Targets, native plans, and providers | Node; selected browser/native target or provider as documented |
@@ -751,7 +757,7 @@ deterministic map. The package root also contains the public
 {
   schemaVersion: 1,
   kind: 'arcane-app-runtime-projection',
-  sdkVersion: '0.5.16',
+  sdkVersion: '0.5.17',
   pathPrefix: 'arcane/',
   files: [{path}]
 }
@@ -1507,6 +1513,16 @@ bounded FIFO queue (browser Kokoro defaults to four), while Blob URLs and
 playback remain in exact input order. A native or custom client without that
 advertised capacity stays serialized with one lookahead. Replay keeps completed
 URLs and pending requests while retrying failed missing provider segments.
+The optional constructor `onState(detail)` callback runs synchronously after
+the canonical state occurrence is dispatched; callback failures are reported
+without replacing playback settlement.
+
+`prepare()` keeps every nonblank stored part exact. At synthesis time,
+`SpeechPlayback` copies the part and automatically removes repeated formatting
+marks from only that outbound speech input. It passes SDK-internal preparation
+metadata so a downstream SDK speech boundary does not apply the filter again;
+applications do not supply that metadata. Original part objects, displayed or
+stored content, and every non-input payload field remain unchanged.
 
 ### Signature and result
 
@@ -1526,7 +1542,13 @@ runtime module; provider and media availability remain host-owned.
 import SpeechPlayback from 'arcane-os/speech-playback';
 
 const audio=document.body.appendChild(document.createElement('audio'));
-const playback=new SpeechPlayback({audio,speech:globalThis.ai});
+const playback=new SpeechPlayback({
+  audio,
+  speech:globalThis.ai,
+  onState(detail) {
+    console.log(detail.state);
+  }
+});
 const button=document.body.appendChild(document.createElement('button'));
 button.textContent='Speak';
 button.addEventListener('click',async function speakCompleteSegments(){
@@ -1561,18 +1583,91 @@ import {SPEECH_PLAYBACK_STATE_EVENT} from 'arcane-os/speech-playback';
 console.log(SPEECH_PLAYBACK_STATE_EVENT);
 ```
 
+## SPEECH_VOICE_ALIASES
+
+### Overview
+
+Mutable compatibility membership for the ten shared voice identifiers used by
+existing speech controls. `SpeechPlayback` does not select a voice from this
+set, and membership does not promise support from the selected provider.
+
+### Signature and result
+
+```text
+const SPEECH_VOICE_ALIASES
+```
+
+### Availability and normalization
+
+**Node and browser.** Ordinary mutable `Set`, derived once in
+`SPEECH_VOICE_OPTIONS` order, containing `alloy`, `ash`, `ballad`, `coral`,
+`echo`, `fable`, `nova`, `onyx`, `sage`, and `shimmer`.
+
+### Example
+
+```javascript
+import {SPEECH_VOICE_ALIASES} from 'arcane-os/speech-playback';
+console.log(SPEECH_VOICE_ALIASES.has('alloy')); // true
+```
+
+## SPEECH_VOICE_OPTIONS
+
+### Overview
+
+Mutable ordered compatibility records for existing speech voice controls.
+Each record has a lowercase `value` and matching title-case `label`. Provider
+support and voice selection remain caller-owned.
+
+### Signature and result
+
+```text
+const SPEECH_VOICE_OPTIONS
+```
+
+### Availability and normalization
+
+**Node and browser.** Ordinary mutable array and mutable `{value,label}`
+records ordered as Alloy, Ash, Ballad, Coral, Echo, Fable, Nova, Onyx, Sage,
+and Shimmer.
+
+### Example
+
+```javascript
+import {SPEECH_VOICE_OPTIONS} from 'arcane-os/speech-playback';
+console.log(SPEECH_VOICE_OPTIONS[0]); // {value: 'alloy', label: 'Alloy'}
+```
+
 ## SpeechPlayback
 
 ### Overview
 
 Named binding for the same capability-aware, exact-order canonical class exposed
 as the speech-playback default. `prepare()` preserves each nonblank part's exact
-input string without trimming, splitting, or freezing that content.
+input string without trimming, splitting, or freezing that content. An optional
+`onState(detail)` constructor callback receives every state synchronously after
+the canonical occurrence is dispatched. Both surfaces expose the same public
+field values at dispatch time; object identity is not promised. Callback
+failures are reported through `globalThis.reportError` when available,
+otherwise `console.error`, and do not replace playback settlement.
+Only the outbound synthesis copy receives automatic repeated-formatting-mark
+cleanup; the original part and stored preparation record stay exact.
 
 ### Signature and result
 
 ```text
-new SpeechPlayback(options={})
+new SpeechPlayback({
+  audio,
+  speech?,
+  model?,
+  voice?,
+  responseFormat?,
+  speed=1,
+  onState=()=>{},
+  createObjectURL?,
+  revokeObjectURL?,
+  delay?,
+  messages?
+})
 ```
 
 ### Availability and normalization
@@ -1586,7 +1681,15 @@ serialized, and media availability remains host-owned.
 
 ```javascript
 import SpeechPlayback,{SpeechPlayback as NamedSpeechPlayback} from 'arcane-os/speech-playback';
-console.log(SpeechPlayback===NamedSpeechPlayback);
+
+const audio=document.body.appendChild(document.createElement('audio'));
+const playback=new NamedSpeechPlayback({
+  audio,
+  onState(detail) {
+    console.log(detail.state);
+  }
+});
+console.log(playback instanceof SpeechPlayback); // true
 ```
 
 ## splitSpeechText()
@@ -1612,6 +1715,73 @@ import {splitSpeechText} from 'arcane-os/speech-playback';
 console.log(splitSpeechText('Hello world.'));
 ```
 
+## MarkdownSpeech
+
+### Overview
+
+Streams the SDK's dependency-free speech formatting cleanup across input chunk
+boundaries. `append()` removes runs of two or more identical `*`, `#`, `_`,
+backtick, or `~` marks while retaining single marks and every other character.
+It is a narrow speech filter, not a Markdown parser. Normal SDK TTS calls use
+this cleanup automatically; applications do not need to construct this class
+or opt in.
+
+### Signature and result
+
+```text
+new MarkdownSpeech()
+```
+
+`append(text='',end=false)` returns only newly available narration. It retains
+one trailing candidate formatting mark across calls so a repeated run split
+between chunks is still removed. A terminal `end:true` append flushes any
+single pending mark and resets the instance. `reset()` discards pending state.
+
+### Availability and normalization
+
+**Node and browser.** The implementation has no runtime dependency. Caller
+strings remain unchanged. Non-string input throws `TypeError`.
+
+### Example
+
+```javascript
+import {MarkdownSpeech} from 'arcane-os/speech-text';
+
+const speechText=new MarkdownSpeech();
+console.log(speechText.append('*')); // '' (held for the next chunk)
+console.log(speechText.append('*Hello.',true)); // 'Hello.'
+```
+
+## stripSpeechFormatting()
+
+### Overview
+
+Removes repeated same formatting marks from one complete speech text value.
+Single marks, ordinary punctuation, links, code contents, and every other
+character remain literal. Normal SDK TTS calls already apply this function to
+an outbound copy; the public helper is available when another speech-text owner
+needs the same one-pass result.
+
+### Signature and result
+
+```text
+stripSpeechFormatting(text='')
+```
+
+### Availability and normalization
+
+**Node and browser.** Calls the supplied value's `replace()` method and returns
+its filtered result without modifying the supplied value. Pass a string;
+values without a callable `replace()` fail with the native `TypeError`.
+
+### Example
+
+```javascript
+import {stripSpeechFormatting} from 'arcane-os/speech-text';
+
+console.log(stripSpeechFormatting('**Hello**')); // 'Hello'
+```
+
 ## projectNativeDescriptor()
 
 ### Overview
@@ -3463,7 +3633,7 @@ workspace it additionally returns the exact installed package authority:
     packageSource,
     canonicalPackageRoot,
     packageName: 'arcane-os',
-    packageVersion: '0.5.16',
+    packageVersion: '0.5.17',
     runtimeRoot,
     browserRuntimeRoot
   }
@@ -3471,9 +3641,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.16`. The selected installation must still be one direct,
+`npm:arcane-os@0.5.17`. The selected installation must still be one direct,
 physical, non-link package directory whose manifest identifies exactly as
-`arcane-os@0.5.16`; duplicate canonical/alias declarations reject.
+`arcane-os@0.5.17`; duplicate canonical/alias declarations reject.
 `allowMissingManagedImportMap` is an internal packaging/development seam. An
 ordinary caller should leave it `false`.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.5.16",
+  "version": "0.5.17",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",
@@ -16,6 +16,7 @@
     "./logging": "./browser-runtime/logging.mjs",
     "./preference-store": "./runtime/arcane/modules/PreferenceStore.js",
     "./speech-playback": "./runtime/arcane/modules/SpeechPlayback.js",
+    "./speech-text": "./browser-runtime/speech-text.mjs",
     "./ai/browser-wasm": "./browser-runtime/ai/browser-wasm.mjs",
     "./ai/browser-speech": "./browser-runtime/ai/browser-speech.mjs",
     "./mail": "./src/mail-api.mjs",

package/runtime/arcane/components/chat.html

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

package/runtime/arcane/modules/AI.js

@@ -13,7 +13,7 @@ import {
 } from './AIProviderRuntime.js';
 import {normalizeOllamaModelIdentifier} from './OllamaModelIdentifier.js';
 import {arcaneLogging} from 'arcane-os/logging';
-import {MarkdownSpeech} from './MarkdownSpeech.js';
+import {MarkdownSpeech,stripSpeechFormatting} from 'arcane-os/speech-text';
 
 const completeValue=(value)=>value;
 
@@ -2030,7 +2030,6 @@ class AI {
     }
 
     audioMessageChunks='';
-    #speechTextFormat='plain';
     #markdownSpeech=new MarkdownSpeech();
     sourceNodes=[];
     isSpeaking=false;
@@ -5734,7 +5733,6 @@ class AI {
         if(this.muted){
             if(end){
                 this.audioMessageChunks='';
-                this.#speechTextFormat='plain';
                 this.#markdownSpeech.reset();
             }
             this.#traceSpeech('streamTTS.result',{callId,result:false,reason:'muted'});
@@ -5747,24 +5745,12 @@ class AI {
             throw new RangeError('Speech pauses must be a nonnegative number of milliseconds.');
         }
 
-        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;
+        const speechText=this.#markdownSpeech.append(String(text||''),end);
         this.audioMessageChunks+=speechText;
         const outputs=this.#extractSpeechSegments(end);
         this.#traceSpeech('streamTTS.segments',{
             callId,segments:outputs,remainder:this.audioMessageChunks,
-            segmentation:this.ttsSegmentation,textFormat,speechText
+            segmentation:this.ttsSegmentation,speechText
         });
 
         if(!outputs.length){
@@ -6040,7 +6026,8 @@ class AI {
         this.#traceSpeechJob('generation.request',job,{payload,selection});
         const response=await this.fetchTTS(
             payload,
-            job.abortController.signal
+            job.abortController.signal,
+            {speechInputPrepared:true}
         );
         return this.#normalizeProviderSpeechAudio(response);
     }
@@ -6189,7 +6176,7 @@ class AI {
         return this.audioContext;
     }
 
-    async fetchTTS(payload={},signal=null){
+    async fetchTTS(payload={},signal=null,{speechInputPrepared=false}={}){
         const callId=this.#traceSpeech('fetchTTS.call',{payload,aborted:signal?.aborted});
         try{
             this.#assertServiceConfigured(this.ttsService,'tts');
@@ -6233,12 +6220,15 @@ class AI {
                 throw normalizeAIRequestAbort(signal.reason);
             }
 
-            const input=descriptors.input?.value;
-            if(typeof input!=='string'||!input.trim()){
+            const suppliedInput=descriptors.input?.value;
+            if(typeof suppliedInput!=='string'||!suppliedInput.trim()){
                 const error=new TypeError('AI.fetchTTS input must be nonempty text.');
                 error.code='ARCANE_AI_TTS_INPUT_INVALID';
                 throw error;
             }
+            const input=speechInputPrepared===true
+                ?suppliedInput
+                :stripSpeechFormatting(suppliedInput);
             const selection=this.#providerRuntime.selection('tts');
             const requestedModel=descriptors.model?.value;
             if(requestedModel!==undefined
@@ -6329,7 +6319,8 @@ class AI {
                         payload:{model,voice,input,responseFormat,speed},
                         localOnly:false,
                         signal
-                    }
+                    },
+                    {speechInputPrepared:true}
                 );
                 this.#traceSpeech('fetchTTS.providerResult',{callId,response});
                 if(signal?.aborted)throw normalizeAIRequestAbort(signal.reason);
@@ -6432,7 +6423,6 @@ class AI {
         this.speechScheduleContext=null;
         this.speechScheduleTime=0;
         this.audioMessageChunks='';
-        this.#speechTextFormat='plain';
         this.#markdownSpeech.reset();
         this.#clearSpeechUnlock();
 

package/runtime/arcane/modules/AIProviderRuntime.js

@@ -1,4 +1,5 @@
 import {arcaneLogging} from 'arcane-os/logging';
+import {stripSpeechFormatting} from 'arcane-os/speech-text';
 import {
     AI_RUNTIME_ROLES,
     getAIRuntimeState,
@@ -3343,14 +3344,14 @@ export class AIProviderRuntime {
         return this.#disposeAllPromise;
     }
 
-    request(role, options = {}) {
+    request(role, options = {}, {speechInputPrepared = false} = {}) {
         if (SPEECH_ROLES.includes(role)) {
             arcaneLogging.debug('[Arcane speech runtime] request', role, options);
         }
-        return this.#requestRole(role, options, false);
+        return this.#requestRole(role, options, false, speechInputPrepared);
     }
 
-    #requestRole(role, options, queued) {
+    #requestRole(role, options, queued, speechInputPrepared = false) {
         this.#assertOpen();
         this.#assertNotConfiguring();
         assertRole(role);
@@ -3379,6 +3380,24 @@ export class AIProviderRuntime {
         if (options.signal?.aborted) {
             return Promise.reject(normalizedAbort());
         }
+        if (role === 'tts' && !queued && speechInputPrepared !== true) {
+            const payload = options.payload;
+            const field = Object.hasOwn(payload ?? {}, 'input') ? 'input' : 'text';
+            const text = Object.getOwnPropertyDescriptor(payload ?? {}, field)?.value;
+            if (typeof text === 'string') {
+                const input = stripSpeechFormatting(text);
+                if (input !== text) {
+                    const payloadProperties = Object.getOwnPropertyDescriptors(payload);
+                    payloadProperties[field] = {...payloadProperties[field], value: input};
+                    const requestProperties = Object.getOwnPropertyDescriptors(options);
+                    requestProperties.payload = {
+                        ...requestProperties.payload,
+                        value: Object.create(Object.getPrototypeOf(payload), payloadProperties)
+                    };
+                    options = Object.create(Object.getPrototypeOf(options), requestProperties);
+                }
+            }
+        }
         const slot = this.#slots[role];
         if (slot.disposed) {
             return Promise.reject(
@@ -4001,7 +4020,9 @@ export class AIProviderRuntime {
                 if (SPEECH_ROLES.includes(role)) {
                     arcaneLogging.debug('[Arcane speech runtime] provider.request', {generation, requestSequence, operationId}, providerRequest);
                 }
-                const result = await provider.request(providerRequest);
+                const result = role === 'tts'
+                    ? await provider.request(providerRequest, {speechInputPrepared: true})
+                    : await provider.request(providerRequest);
                 if (SPEECH_ROLES.includes(role)) {
                     arcaneLogging.debug('[Arcane speech runtime] provider.request.result', {role, generation, requestSequence, operationId}, result);
                 }
@@ -4065,9 +4086,9 @@ export class AIProviderRuntime {
         return this.#roleRequestAlias('stt', 'transcribe', payload, options);
     }
 
-    synthesize(payload, options = {}) {
+    synthesize(payload, options = {}, preparation = {}) {
         arcaneLogging.debug('[Arcane speech runtime] synthesize', payload, options);
-        return this.#roleRequestAlias('tts', 'synthesize', payload, options);
+        return this.#roleRequestAlias('tts', 'synthesize', payload, options, preparation);
     }
 
     cancel(role) {
@@ -4159,7 +4180,7 @@ export class AIProviderRuntime {
         ) ?? null;
     }
 
-    #roleRequestAlias(role, operation, payload, options) {
+    #roleRequestAlias(role, operation, payload, options, preparation = {}) {
         assertPlainObject(options, `AI ${operation} options`);
         for (const key of Reflect.ownKeys(options)) {
             if (key !== 'localOnly' && key !== 'signal') {
@@ -4179,7 +4200,8 @@ export class AIProviderRuntime {
                 payload,
                 localOnly,
                 signal
-            }
+            },
+            preparation
         );
     }
 

package/runtime/arcane/modules/MarkdownSpeech.js

@@ -1,50 +1 @@
-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};
+export {MarkdownSpeech} from 'arcane-os/speech-text';

package/runtime/arcane/modules/SpeechPlayback.js

@@ -1,5 +1,18 @@
 import {createArcaneEventSource} from 'arcane-os/event-manager';
+import {stripSpeechFormatting} from 'arcane-os/speech-text';
 
+const SPEECH_VOICE_OPTIONS=[
+    {value:'alloy',label:'Alloy'},
+    {value:'ash',label:'Ash'},
+    {value:'ballad',label:'Ballad'},
+    {value:'coral',label:'Coral'},
+    {value:'echo',label:'Echo'},
+    {value:'fable',label:'Fable'},
+    {value:'nova',label:'Nova'},
+    {value:'onyx',label:'Onyx'},
+    {value:'sage',label:'Sage'},
+    {value:'shimmer',label:'Shimmer'}
+];
 const SUPERSEDED={superseded:true};
 const SPEECH_PLAYBACK_STATE_EVENT='speech-playback-state';
 const SPEECH_PLAYBACK_FAILURE_REASONS={
@@ -17,6 +30,10 @@ const WAV_AUDIO_CONTENT_TYPES=new Set([
 ]);
 const queuesBySpeechClient=new WeakMap();
 
+const SPEECH_VOICE_ALIASES=new Set(
+    SPEECH_VOICE_OPTIONS.map(function voiceAlias(option){return option.value;})
+);
+
 function splitSpeechText(value=''){
     const text=String(value??'');
     return text.trim()?[text]:[];
@@ -401,6 +418,7 @@ class SpeechPlayback{
         voice=null,
         responseFormat=null,
         speed=1,
+        onState=function noop(){},
         createObjectURL,
         revokeObjectURL,
         delay,
@@ -422,6 +440,7 @@ class SpeechPlayback{
                 eventTypes:[SPEECH_PLAYBACK_STATE_EVENT]
             }
         );
+        this.onState=onState;
         this.createObjectURL=createObjectURL||function createAudioURL(blob){return URL.createObjectURL(blob);};
         this.revokeObjectURL=revokeObjectURL||function revokeAudioURL(url){URL.revokeObjectURL(url);};
         this.delay=delay||function playbackDelay(duration,signal){
@@ -515,6 +534,12 @@ class SpeechPlayback{
                 }
             );
         }
+        try{
+            this.onState(detail);
+        }catch(error){
+            if(typeof globalThis.reportError==='function')globalThis.reportError(error);
+            else console.error(error);
+        }
         return detail;
     }
 
@@ -569,8 +594,10 @@ class SpeechPlayback{
     }
 
     async requestSpeech(part,signal){
+        const input=stripSpeechFormatting(part.input);
+        const preparation={speechInputPrepared:true};
         const payload={
-            input:part.input,
+            input,
             speed:part.speed,
             ...(this.model?{model:this.model}:{}),
             ...(part.voice?{voice:part.voice}:{}),
@@ -578,12 +605,12 @@ class SpeechPlayback{
         };
         if(typeof this.speech?.fetchTTS==='function'){
             return playableSpeechBlob(
-                await this.speech.fetchTTS(payload,signal)
+                await this.speech.fetchTTS(payload,signal,preparation)
             );
         }
         if(typeof this.speech?.synthesize==='function'){
             return playableSpeechBlob(
-                await this.speech.synthesize(payload,{signal})
+                await this.speech.synthesize(payload,{signal},preparation)
             );
         }
         const error=new Error(this.message('unavailable'));
@@ -1002,12 +1029,15 @@ class SpeechPlayback{
         this.audio.removeEventListener('error',this.boundError);
         this.destroyed=true;
         this.events.dispose();
+        this.onState=function destroyedSpeechPlaybackStateObserver(){};
         return true;
     }
 }
 
 export {
     SPEECH_PLAYBACK_STATE_EVENT,
+    SPEECH_VOICE_ALIASES,
+    SPEECH_VOICE_OPTIONS,
     SpeechPlayback,
     splitSpeechText
 };

package/src/import-map.mjs

@@ -20,6 +20,7 @@ const STATIC_RUNTIME_PACKAGE_IMPORTS=new Map([
 const SDK_BROWSER_SELF_IMPORTS=new Map([
     ['arcane-os/event-manager',SDK_BROWSER_ENTRY],
     ['arcane-os/logging','sdk/logging.mjs'],
+    ['arcane-os/speech-text','sdk/speech-text.mjs'],
     ['arcane-os/ai/browser-wasm',SDK_BROWSER_AI_ENTRY],
     ['arcane-os/ai/browser-speech',SDK_BROWSER_SPEECH_ENTRY]
 ]);