arcane-os 0.75.0 → 0.76.0

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.76.0
+
+- Add public `textFormat:'plain'` to the `SpeechPlayback` constructor and
+  `prepare()` options. Preserve every prepared part's exact input through
+  audio-file, native and custom speech clients, including queued narration;
+  omitted selection retains the existing formatting cleanup.
+- Distinguish a current native utterance's non-error stopped completion from
+  initial preparation with `reason:'native-playback-stopped'` on the existing
+  `ready` event. Natural final completion remains `ended`; an error does not
+  establish native resource release.
+- Preserve per-part voices, ordered playback, cancellation, replay and silent
+  preparation. No model, dependency, native host or activation changes are
+  included. Focused source fixtures are authored separately from the selected
+  package verification; no live speech result is claimed.
+
 ## 0.75.0
 
 - Advertise whole-image `img2img` alongside `txt2img` for the built-in

package/README.md

@@ -20,7 +20,7 @@ selected SDK projection or an explicit live SDK source mount. Both profiles
 share the theme, packaging, event, cancellation,
 and browser run contracts while retaining their selected application layout.
 
-This checkout defines the `0.75.0` SDK contract. Development applications declare
+This checkout defines the `0.76.0` SDK contract. Development applications declare
 `arcane-os` as `latest` and retain their lockfile. Exact SDK pins begin when Roshi
 designates a production build. Follow [Consumer updates](docs/consumer-updates.md)
 to refresh and compare the installed SDK and lockfile with the published channel;
@@ -476,9 +476,10 @@ ordinary repeated punctuation remain literal. Complete synthesis calls may
 select `textFormat:'plain'` to preserve exact input: supply it in `prepareTTS`
 options or the payload of `fetchTTS`, provider-runtime TTS requests, or direct
 Kokoro requests. The SDK consumes this control before engine/host dispatch;
-omission keeps the default cleanup. Streaming narration and `SpeechPlayback`
-retain their existing formatting behavior. This option does not change the
-selected engine's input capacity or establish complete upstream synthesis. Original
+omission keeps the default cleanup. `SpeechPlayback` accepts the same option in
+its constructor or `prepare()` call and forwards each part's exact input.
+Streaming narration retains its existing formatting behavior. This option does
+not change the selected engine's input capacity or establish complete upstream synthesis. Original
 messages and caller payloads remain unchanged for display, storage, and model
 input. The `arcane-os/speech-text` entrypoint exports the same
 `MarkdownSpeech` streaming class and `stripSpeechFormatting()` one-pass helper

package/docs/reference/ai/browser-speech.md

@@ -1008,8 +1008,11 @@ waits for its next character or the final flush.
 state. `fetchTTS()`, provider-runtime TTS requests, direct Kokoro provider
 requests, and `SpeechPlayback` apply the same default cleanup to complete input.
 Complete-input APIs can explicitly select `textFormat:'plain'` as described
-below. The streaming `streamTTS()` options still ignore `textFormat`;
-streaming narration and `SpeechPlayback` keep their existing cleanup.
+below. `SpeechPlayback` accepts `textFormat:'plain'` in its constructor or
+`prepare()` options and forwards each prepared part's exact input through every
+supported speech client. Omitted options reuse its current selection; explicit
+`null` restores default cleanup. The streaming `streamTTS()` options still ignore
+`textFormat` and streaming narration keeps its existing cleanup.
 SDK-internal delegation carries `{speechInputPrepared:true}` outside the speech
 payload after its owner selects text treatment, preventing a second
 non-idempotent cleanup pass or cleanup of explicitly plain input.
@@ -1019,8 +1022,9 @@ playback timing are not changed by the filter.
 
 Direct native `provider.prepare()` and `provider.play()` preserve their complete
 `input` as supplied. The native route of `ai.prepareTTSPlayback()` also preserves
-that input; shared streaming and `SpeechPlayback` perform their existing cleanup
-before calling it. Choose the high-level narration path when that speech-only
+that input; shared streaming and default `SpeechPlayback` perform cleanup before
+calling it. Plain `SpeechPlayback` preserves the complete input instead.
+Choose the high-level narration path when that speech-only
 formatting cleanup is desired.
 
 The shared helper is public for code that needs the speech-only

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

@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
-  "sdkVersion": "0.74.0",
+  "sdkVersion": "0.75.0",
   "environment": {
     "runtime": "Node.js for Node entrypoints; browser for browser-only entrypoints",
     "minimumVersion": "22.23.2 for Node entrypoints",

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

@@ -1262,11 +1262,11 @@
         "default",
         "splitSpeechText"
       ],
-      "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.",
+      "summary": "Preserves exact nonblank stored segment text; removes repeated formatting marks from the outbound synthesis copy by default or forwards exact input with constructor/prepare textFormat:'plain'; 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.prepareTTSPlayback or AI.fetchTTS plus providerRuntime TTS execution capacity, native provider.prepare, or compatible serialized Arcane.speech.synthesize; globalThis.arcaneEvents, Blob URLs/audio element, and native playback controls",
-      "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": "prepareTTSPlayback or direct native provider.prepare may return silent native-speech descriptors. autoplay:false stays silent; actual completion advances ordered parts and failed cancellation retains controls until released. Replay preserves completed segments and retries only missing failed generation. 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."
+      "normalization": "Exact nonblank split/part input strings are preserved in mutable records. Each synthesis request copies that input, preserves it exactly for constructor/prepare textFormat:'plain' or applies default formatting cleanup, 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": "prepareTTSPlayback or direct native provider.prepare may return silent native-speech descriptors. autoplay:false stays silent; actual completion advances ordered parts and failed cancellation retains controls until released. Current native finished:false without error reports ready with reason native-playback-stopped; natural final completion reports ended. Replay preserves completed segments and retries only missing failed generation. 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/runtime-modules.md

@@ -132,7 +132,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 | 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. |
+| [`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; outbound input receives default formatting cleanup or explicit plain-text preservation; 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 result when the bridge or optional namespace is absent. | Browser/native hybrid | Exact absent optional namespace normalized with its complete error; partial-method and genuine native errors 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. |
@@ -3973,8 +3973,8 @@ 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. Stored parts remain exact; only each outbound synthesis payload
-copy receives automatic formatting-mark cleanup.
+input order. Stored parts remain exact; each outbound synthesis payload copy
+receives default formatting-mark cleanup or explicit plain-text preservation.
 
 ### Public surface
 
@@ -3992,6 +3992,7 @@ new SpeechPlayback({
   model=null,
   voice=null,
   responseFormat=null,
+  textFormat=null,
   speed=1,
   onState=()=>{},
   createObjectURL,
@@ -4006,7 +4007,7 @@ native descriptor, a native provider's silent `prepare(payload,{signal})`,
 `fetchTTS(payload, signal)`, or `synthesize(payload, {signal})`.
 The playback-oriented method is preferred. `SpeechPlayback` also supplies a third
 SDK-internal preparation object; existing two-argument clients may ignore it.
-`prepare({key,parts,model,voice,responseFormat,
+`prepare({key,parts,model,voice,responseFormat,textFormat,
 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
@@ -4020,13 +4021,25 @@ There is no hard-coded model, response format, voice, or cloud/browser fallback.
 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.
-At synthesis time, `requestSpeech()` copies that record, removes repeated same
-formatting marks from only the outbound `input`, and delegates with the
+At synthesis time, default `requestSpeech()` behavior 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.
 
+Set `textFormat:'plain'` in the constructor or `prepare()` options to forward
+every part's exact `input` without formatting cleanup. The selection is captured
+with the prepared parts, including queued and lookahead requests. A `prepare()`
+override becomes the instance's selection for later omitted options, like its
+voice and speed options; explicit `null` or another non-`undefined` value other
+than `'plain'` selects the existing cleanup. Plain requests carry `textFormat:'plain'` to every
+supported speech client along with the existing internal preparation marker;
+default requests keep their existing payload shape. Original part objects stay
+unchanged, and per-part voices, ordering, cancellation, and silent
+`autoplay:false` preparation retain their existing behavior. This controls SDK
+text treatment, not the selected speech engine's pronunciation or input capacity.
+
 ### Admission and playback order
 
 When `speech` exposes both `fetchTTS(payload, signal)` and
@@ -4053,6 +4066,11 @@ Replay use the native control; only a successful current native `finished`
 advances the next part. Native errors remain observable, and a failed native
 control stays owned until its optional `released` promise confirms cleanup.
 Stale completion after stop/restart/disposal cannot advance replacement content.
+When current native `finished` resolves `false` without an error, the existing
+`ready` event carries `reason:'native-playback-stopped'` and its operation ID;
+initial prepared `ready` has no such reason. Only natural completion of the last
+part emits `ended`. Errors never establish native resource release; failed
+controls remain retained through their existing `released` boundary.
 Selecting a native part hides and clears the HTML audio source while preserving
 the same shared playback state events and complete original parts.
 
@@ -4087,7 +4105,7 @@ Exact lifecycle reasons are `playback-replaced`, `playback-stopped`,
 `playback-destroyed`, `speech-playback-cancelled`,
 `speech-synthesis-superseded`, `speech-synthesis-cancelled`,
 `speech-synthesizer-unavailable`, `synthesized-audio-contract-mismatch`,
-`audio-playback-rejected`, `audio-autoplay-rejected`,
+`audio-playback-rejected`, `audio-autoplay-rejected`, `native-playback-stopped`,
 `speech-playback-request-contract-mismatch`, and
 `speech-synthesis-rejected`, as applicable to the emitted state.
 

package/docs/reference/sdk-api.md

@@ -8357,7 +8357,8 @@ mediaType}` and copies the supplied view at acceptance. Its explicit finite
 `strength` is from `0` through `1`, takes precedence over model/parameter
 defaults and is never clamped. It decodes in the existing worker and uses the
 same selected context, queue, progress, cancellation and complete result
-contract. SD1.4 advertises `txt2img` and `img2img`. See the
+contract. SD1.4 and [SDXL Base 1.0](local-image-sdxl.md#edit-a-whole-image)
+advertise `txt2img` and whole-image `img2img`. See the
 [editing contract](local-image-editing.md#core-and-native-request) for supported
 PNG input, native preprocessing, alpha and strength-zero semantics; the
 original file remains unchanged.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.75.0",
+  "version": "0.76.0",
   "description": "Arcane OS JavaScript SDK, project-local CLI, browser runtime, and repository-portable application packager.",
   "type": "module",
   "main": "./src/index.mjs",

package/runtime/arcane/modules/SpeechPlayback.js

@@ -42,7 +42,7 @@ function splitSpeechText(value=''){
     return text.trim()?[text]:[];
 }
 
-function normalizeParts(parts,defaultVoice=null,defaultSpeed=1){
+function normalizeParts(parts,defaultVoice=null,defaultSpeed=1,textFormat=null){
     if(!is.array(parts)||!parts.length){
         throw new TypeError('Narration text cannot be blank. The full visual content remains available.');
     }
@@ -63,6 +63,7 @@ function normalizeParts(parts,defaultVoice=null,defaultSpeed=1){
         if(!is.finite(speed)||speed<=0)throw new RangeError('Every speech segment requires a positive speech speed.');
         return {
             input,
+            ...(textFormat==='plain'?{textFormat:'plain'}:{}),
             pauseAfterMs,
             role:String(candidate?.role||'narration'),
             speed,
@@ -425,6 +426,7 @@ class SpeechPlayback{
         model=null,
         voice=null,
         responseFormat=null,
+        textFormat=null,
         speed=1,
         onState=function noop(){},
         createObjectURL,
@@ -485,6 +487,7 @@ class SpeechPlayback{
         this.responseFormat=responseFormat===null||responseFormat===undefined
             ?null
             :String(responseFormat);
+        this.textFormat=textFormat==='plain'?'plain':null;
         this.speed=normalizedSpeed;
         this.key='';
         this.state='idle';
@@ -622,10 +625,13 @@ class SpeechPlayback{
     }
 
     async requestSpeech(part,signal){
-        const input=stripSpeechFormatting(part.input);
+        const input=part.textFormat==='plain'
+            ?part.input
+            :stripSpeechFormatting(part.input);
         const preparation={speechInputPrepared:true};
         const payload={
             input,
+            ...(part.textFormat==='plain'?{textFormat:'plain'}:{}),
             speed:part.speed,
             ...(this.model?{model:this.model}:{}),
             ...(part.voice?{voice:part.voice}:{}),
@@ -799,6 +805,7 @@ class SpeechPlayback{
         model=this.model,
         voice=this.voice,
         responseFormat=this.responseFormat,
+        textFormat=this.textFormat,
         speed=this.speed,
         autoplay=true
     }={}){
@@ -843,10 +850,12 @@ class SpeechPlayback{
             this.model=selectedModel;
             this.voice=selectedVoice;
             this.responseFormat=selectedResponseFormat;
+            this.textFormat=textFormat==='plain'?'plain':null;
             normalized=normalizeParts(
                 is.function(parts)?parts():parts,
                 selectedVoice,
-                numericSpeed
+                numericSpeed,
+                this.textFormat
             );
             this.parts=normalized;
         }catch(error){
@@ -1036,7 +1045,12 @@ class SpeechPlayback{
                 playback.abortControllers.delete(active.controller);
                 if(completed===true)return await playback.advance();
                 if(active.control.error)playback.fail(active.control.error);
-                else playback.emit('ready',playback.message('stopped'));
+                else playback.emit(
+                    'ready',
+                    playback.message('stopped'),
+                    playback.key,
+                    {reason:'native-playback-stopped'}
+                );
                 return false;
             }catch(error){
                 console.error('[Arcane speech playback] Native speech failed.',error);