arcane-os 0.5.16 → 0.5.18

package/docs/reference/runtime-modules.md

@@ -4,6 +4,13 @@ Every file shipped under `runtime/arcane/modules/` appears here. Start with the
 
 Apps import renderer ESM from `/arcane/modules/<file>`. Classic scripts, the OPFS worker, uPlot stylesheet, and vendor license are called out explicitly. Importing a module does not grant a native capability.
 
+Applications own response-detail preferences, their saved values, and any
+verbosity instruction appended to the system prompt. The former
+`AIResponseLength.js` module and its exports have been removed. Before adopting
+this source change, consumers must normalize preferences in their application
+and pass their complete system prompt directly instead of calling the former
+no-op `applyAIResponseLength()` helper. Existing saved preferences are unchanged.
+
 ## Availability shorthand
 
 - **Cross-host** means in-process logic built from standard JavaScript/Web APIs.
@@ -44,8 +51,7 @@ own asynchronous work, cancellation, and backpressure.
 | [`AIPreferenceRuntime.js`](#aipreferenceruntimejs) | esm | Applies and reads non-persistent per-user AI preference overrides. | Cross-host | Normalized six-slot preference state. |
 | [`AIPreferenceTuple.js`](#aipreferencetuplejs) | esm | Normalizes and compares the six provider/model preference slots. | Cross-host | Fully normalized frozen tuple. |
 | [`AIProviderRuntime.js`](#aiproviderruntimejs) | esm | Owns provider-neutral selection, lifecycle, routing, startup, requests, streaming, cancellation, and independent LLM/STT/TTS state. | Cross-host runtime; provider-specific availability | Normalized required provider members plus route/status contracts, with explicit local-only selection and no implicit fallback. |
-| [`AIResponseLength.js`](#airesponselengthjs) | esm | Normalizes current low/medium/high response-preference selectors while preserving complete prompts. | Cross-host | Current selector normalization; prompt content remains unchanged. |
-| [`AIResponseURLPolicy.js`](#airesponseurlpolicyjs) | esm | Extracts and audits links from AI Markdown, rendered HTML, CSS, srcset, bare URLs, and email text. | Cross-host | Normalized frozen allowlist audit. |
+| [`AIResponseURLPolicy.js`](#airesponseurlpolicyjs) | esm | Extracts and audits links from AI Markdown, rendered HTML, CSS, srcset, bare URLs, and email text. | Cross-host | Mutable audit with exact link comparison after renderer-level decoding. |
 | [`AIRuntimeState.js`](#airuntimestatejs) | esm | Publishes sticky mutable role snapshots, lifecycle intents, and startup-settlement barriers. | Cross-host state contract | Closed monotonic state records; events report state but grant no authority. |
 | [`AnsiText.js`](#ansitextjs) | esm | Parses terminal ANSI sequences into display spans or strips them to plain text. | Cross-host | Normalized text/span output. |
 | [`ApiModelDatabase.js`](#apimodeldatabasejs) | esm | Fetches an injectable HTTP JSON model with parser, cache, redacted public endpoint records, and request lifecycle events. | Browser / native WebView / server with fetch | Request records are normalized; fetch/provider failures remain mixed. |
@@ -100,6 +106,7 @@ own asynchronous work, cancellation, and backpressure.
 | [`OpenMeteoWeatherProvider.js`](#openmeteoweatherproviderjs) | esm | Searches and loads Open-Meteo data into complete mutable Arcane weather entities. | Browser / native WebView / server with fetch + cloud | Provider data normalized to mutable entities; transport errors mixed. |
 | [`PersistentAIChatSession.js`](#persistentaichatsessionjs) | esm | Adds explicit retained-history/memory policy to complete configured chat without changing DBOPFS or ChatEntity semantics. | Browser / native WebView with DBOPFS and configured chat | Retained context commits atomically; `persist:false` turns are one-operation-only. |
 | [`PreferenceStore.js`](#preferencestorejs) | esm | Loads and updates schema-defined app preferences through native storage with a narrow browser fallback. | Browser/native hybrid | Complete ordinary values remain mutable; setAll uses one optional atomic adapter batch for every selected value when advertised, otherwise performs complete ordered serial writes, and only exact unsupported native capability changes future operations to the browser fallback. |
+| [`PreparedSpeech.js`](#preparedspeechjs) | esm | Owns detached ordered preparation, semantic audio reuse, and per-caller cancellation behind AI.prepareTTS. | Browser / native WebView with injected synthesis and optional DBOPFS | Complete original inputs, ordered audio metadata, durable reuse, and observable preparation results. |
 | [`QRCode.min.js`](#qrcodeminjs) | classic-script | Vendored QRCode generator for DOM, canvas, SVG, and image output. | Browser vendor script | Vendor-native. |
 | [`Questionnaire.js`](#questionnairejs) | esm | Evaluates whether a one-time questionnaire prompt is due without performing the prompt. | Cross-host | Normalized conservative boolean. |
 | [`RecordLinkIndex.js`](#recordlinkindexjs) | esm | Parses record links and builds their normalized index. | Cross-host | Fully normalized. |
@@ -109,7 +116,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. |
@@ -144,6 +151,8 @@ default `AI`; read-only `providerRuntime`, `browserSpeechConfiguration`, and
 `streamRequest()`, `streamMessage()`, `fetchRequest()`, `fetch()`,
 read-only `ttsSegmentation`, `configureTTSSegmentation()`,
 `streamTTS(text='',end=false,options={})`,
+`prepareTTS({parts,storage,identity,signal,onState})`,
+`playPreparedTTS(prepared,{signal,onState})`,
 `finishTTS()`, `fetchTTS()`, `fetchSTT()`, `stopAudio()`, `resumeAudio()`,
 `playAudio()`; consumes `user-entity-loaded` and `arcane-ollama-ready`,
 installs `window.ai`, and emits `ai-ready` and `ai-tts-failure`.
@@ -263,7 +272,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 +282,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 +297,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`.
@@ -308,13 +321,63 @@ flush, not a queue-wide playback barrier. A muted call resolves `false`.
 Playback completion stays pending while the browser waits for an audio-unlock
 gesture or a recoverable resume attempt. If resuming a closed `AudioContext`
 fails, the affected jobs terminate and their playback results settle `false`.
-`stopAudio()` cancels all speech owned
-by this AI instance and settles pending playback promises `false`. A trailing
+`stopAudio()` cancels streamed speech and prepared playback owned
+by this AI instance and settles pending playback promises `false`; detached
+preparation retains its own cancellation lifetime. A trailing
 pause delays the next queued audio; the preceding promise resolves when its
 last audio buffer ends, without waiting out that pause. Completion describes
 the playback lifecycle, not proof that a listener heard the sound. See the
 [complete-passage example](ai/browser-speech.md#queue-complete-passages-and-wait-for-playback).
 
+`prepareTTS({parts,storage,identity,signal,onState})` returns an immediate
+`{segments,state,ready,getAudio(index),cancel()}` handle for detached complete
+speech preparation. Parts are strings or `{input,voice?,speed?,pauseAfterMs?}`
+records. It retains the full source for semantic matching, snapshots the
+selected speech configuration and segmentation, and applies automatic
+formatting cleanup once to the speech copy. Generation uses the existing
+bounded provider queue without adding playback. Optional
+`storage:{db,table,key}` saves complete audio files and their MIME metadata in
+the caller's ready DBOPFS instance; the separate JSON-compatible `identity`
+adds application-owned semantic context. Reuse compares complete inputs rather
+than an SDK version alone.
+
+`state` is `queued`, `preparing`, `ready`, `error`, or `cancelled`.
+`onState({state,completed,total,segments,error})` synchronously observes
+preparation progress. `ready` resolves the complete record after every segment
+is ready and, when storage is selected, durably saved. `getAudio(index)` waits
+for the corresponding ordered segment and returns its complete `Blob` with
+the retained MIME type. Preparation failure rejects; cancellation rejects as
+`AbortError` and preserves successfully stored segments. Matching pending
+requests share synthesis only on the same AI instance and storage group;
+cancelling one handle does not cancel another active matching caller.
+Preparation cancellation prevents later synthesis, but an already-started
+shared provider load/unmute has no per-preparation signal and may finish.
+
+`playPreparedTTS(prepared,{signal,onState})` can attach immediately. Its returned
+`{state,error,finished,pause(),resume(),stop()}` handle schedules segments in
+their original order using the existing AI audio clock. `finished` resolves `true` after
+natural completion and `false` after stop, cancellation, or failure; genuine
+failures also use the existing complete diagnostics and `ai-tts-failure` event.
+Part pauses separate adjacent audio; the final trailing pause does not delay
+`finished` after the final audio buffer ends. State/error getters and the
+optional synchronous `onState({state,error})` callback expose `waiting`,
+`waiting-for-gesture`, `scheduled`, `paused`, `complete`, `stopped`, or `error`.
+Use `waiting-for-gesture` for audio-unlock UI; a `false` result from `resume()`
+alone is not a first-segment-ready signal.
+Pause and resume are asynchronous boolean controls scoped to that handle's
+audio context; stop is synchronous. Playback completion and these controls do
+not cancel independent preparation. One AI has one playback lane: attaching
+prepared playback replaces its preceding streamed or prepared audio, and
+`streamTTS()` interrupts active prepared playback. `stopAudio()` stops all
+this AI's playback but keeps detached preparation running; `setSpeechMuted(true)` also cancels
+provider TTS work and unloads it. Replacing the selected speech configuration
+cancels missing generation for that earlier selection. Completed stored audio
+remains in application storage.
+Fully stored replay enables playback without loading the selected speech
+model even when the AI starts muted. Missing audio alone requests the shared
+TTS readiness path. See [prepared narration](ai/browser-speech.md#prepare-narration-once-and-replay-stored-audio)
+for full record shapes, storage ownership, and a complete example.
+
 Streaming speech retains sentence
 segmentation by default. `configureTTSSegmentation({punctuation,wordCadence})`
 accepts `punctuation:'sentence'|'any'|'none'` and a `wordCadence` that is either
@@ -324,8 +387,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 +726,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 +746,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,
@@ -794,35 +868,6 @@ const runtime = getAIProviderRuntime();
 console.log(runtime.protocol, runtime.status());
 ```
 
-## AIResponseLength.js
-
-### Overview
-
-Normalizes current low/medium/high response-preference selectors while
-preserving complete prompts unchanged.
-
-### Public surface
-
-Response-preference constants plus `normalizeAIResponseLength()`,
-`aiResponseLengthInstruction()`, and `applyAIResponseLength()`. Every option is
-labeled `Complete`, the instruction helper returns an empty string, and the
-application helper returns its complete `systemPrompt` unchanged.
-
-Exact exports: `AI_RESPONSE_LENGTH_DEFAULT`, `AI_RESPONSE_LENGTH_OPTIONS`, `aiResponseLengthInstruction`, `applyAIResponseLength`, `normalizeAIResponseLength`.
-
-### Availability and normalization
-
-**Cross-host.** Current selector normalization with no prompt transformation.
-Transport: In-process only. [Deep protocol details](protocols.md).
-
-### Example
-
-```javascript
-import * as module from '/arcane/modules/AIResponseLength.js';
-
-console.log(Object.keys(module));
-```
-
 ## AIResponseURLPolicy.js
 
 ### Overview
@@ -837,7 +882,19 @@ Exact exports: `auditAIResponseLinks`, `decodeHTMLCharacterReferences`, `extract
 
 ### Availability and normalization
 
-**Cross-host.** Normalized frozen allowlist audit. Transport: In-process; bundled Marked parser. [Deep protocol details](protocols.md).
+**Cross-host.** Returns a mutable `{ok, links, unsupportedLinks, allowedLinks}`
+audit. Browsers use detached native HTML elements to parse rendered markup and
+decode character references. Hosts without a document retain lexical extraction
+and the existing limited entity decoder. Rendered values are decoded only once.
+Markdown destinations, CSS URLs, srcset candidates, and authored source positions
+remain part of the audit; DOM-only attribute links use document order after
+authored links because the DOM does not expose source offsets.
+
+Comparison uses exact values after entity and Markdown escape decoding. URI
+encoding, decoding, or URL canonicalization would change those values and is
+not applied. The audit neither changes the response content nor fetches or
+navigates to links. Transport: In-process; bundled Marked parser.
+[Deep protocol details](protocols.md).
 
 ### Example
 
@@ -2261,11 +2318,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 +2333,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 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()`
@@ -2673,6 +2732,54 @@ import * as module from '/arcane/modules/PreferenceStore.js';
 console.log(Object.keys(module));
 ```
 
+## PreparedSpeech.js
+
+### Overview
+
+Shared preparation mechanism used by `AI.prepareTTS()`. It owns ordered
+generation admission, same-owner request sharing, complete audio storage and
+semantic reuse, and each caller's preparation lifetime. It does not construct
+an audio context, play speech, or select application content.
+
+### Public surface
+
+Named `prepareSpeech({owner,parts,originalParts=parts,selection=null,
+segmentation=null,storage=null,identity=null,signal=null,onState,synthesize})`.
+The owning AI supplies already segmented speech parts, complete original parts,
+its selection snapshot, and its synthesis callback. The returned handle is
+`{segments,state,ready,getAudio(index),cancel()}`. Applications use
+`AI.prepareTTS()` and `AI.playPreparedTTS()` so the existing AI owner retains
+automatic formatting cleanup, segmentation, provider readiness/capacity, and
+ordered playback. See the [complete preparation contract](ai/browser-speech.md#prepare-narration-once-and-replay-stored-audio).
+
+`storage:{db,table,key}` is optional; the ready DBOPFS instance supplies
+`get`, `set`, `readFile`, and `writeFile`. JSON-compatible semantic inputs stay
+complete in the version-1 manifest. Raw audio is persisted separately and its
+MIME type is retained in metadata. Storage mutation serializes by database,
+table, and key within the realm. Synthesis sharing is scoped to the same owner
+and matching semantic inputs/storage; playback remains outside this module.
+
+Exact exports: `prepareSpeech`.
+
+### Availability and normalization
+
+**Browser or native WebView with Blob, AbortController, an injected synthesis
+callback, and optional ready DBOPFS.** Import creates no provider or
+playback. Calling the preparation function starts owned asynchronous work.
+`ready` rejects complete synthesis/storage failures or `AbortError` after
+cancellation; successful audio remains available for reuse. Malformed part,
+storage, or semantic metadata inputs throw `TypeError`; an invalid segment
+index rejects with `RangeError`. No Core capability is selected here.
+
+### Example
+
+```javascript
+import {prepareSpeech} from '/arcane/modules/PreparedSpeech.js';
+
+// Applications use AI.prepareTTS; this import only exposes the SDK mechanism.
+console.log(typeof prepareSpeech); // function
+```
+
 ## QRCode.min.js
 
 ### Overview
@@ -2899,15 +3006,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 +3026,7 @@ new SpeechPlayback({
   voice=null,
   responseFormat=null,
   speed=1,
+  onState=()=>{},
   createObjectURL,
   revokeObjectURL,
   delay,
@@ -2925,17 +3035,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 +3082,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 +3130,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 +3149,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: