arcane-os 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.5.5
+
+- Added configurable complete text-to-speech stream segmentation through
+  `AI.configureTTSSegmentation()`. Applications can speak on Unicode punctuation
+  or a whole-word cadence without discarding any text, while apostrophes,
+  commas, and hyphens that join Unicode letters or numbers remain intact.
+  Synthesis and playback stay sequential, and mute or cancellation still stops
+  the complete queue.
+
 ## 0.5.4
 
 - Reduced Browser-WASM HTTP Range parts from roughly 128 MB to roughly 4 MB

package/README.md

@@ -19,7 +19,7 @@ version-locked SDK runtime, while an integrated Arcane checkout uses its live
 `arcane/` runtime. Both profiles preserve the same app URLs, theme, packaging,
 event, cancellation, and browser run contracts.
 
-This checkout defines the `0.5.4` SDK contract. Applications pin one exact npm
+This checkout defines the `0.5.5` SDK contract. Applications pin one exact npm
 version and lockfile; registry state is deliberately not baked into application
 artifacts.
 
@@ -153,6 +153,24 @@ must supply each runtime/model selection explicitly. Speech roles
 load, cancel, unload, fail, and recover independently, so speech failure never
 silently falls back or prevents text chat.
 
+Applications that need faster spoken-response onset can configure the shared
+TTS stream without taking over synthesis or playback:
+
+```js
+ai.configureTTSSegmentation({
+    punctuation:'any',
+    wordCadence:4
+});
+```
+
+The compatibility default remains sentence punctuation with no word cadence.
+The configured stream preserves every character and punctuation mark, chooses
+the earliest complete boundary, and keeps synthesis and playback sequential.
+Any-punctuation mode recognizes boundaries without requiring whitespace while
+keeping apostrophes, commas, and hyphens that join Unicode letters or numbers
+inside the same segment.
+Mute, stop, provider transition, and cancellation still govern the whole queue.
+
 The SDK runtime also owns `DBOPFSDocumentLibrary`,
 `DocumentLexicalSearch`, and `PersistentAIChatSession`. Document bootstrap is
 schema-driven and explicit; chat never searches a corpus unless the app wires
@@ -168,7 +186,7 @@ uses the same controller for automatic memory extraction.
 Create a new repository-shaped Arcane application with the exact stable SDK:
 
 ```bash
-npx arcane-os@0.5.4 new my-app --path ./my-app --target portable --git
+npx arcane-os@0.5.5 new my-app --path ./my-app --target portable --git
 cd my-app
 npm install
 npm run check
@@ -179,7 +197,7 @@ To enroll an existing repository, install the exact SDK and initialize only
 missing Arcane files:
 
 ```bash
-npm install --save-dev --save-exact arcane-os@0.5.4
+npm install --save-dev --save-exact arcane-os@0.5.5
 npm exec -- arcane init my-app --target portable
 ```
 
@@ -195,7 +213,7 @@ npm exec -- arcane-os targets
 No global SDK install or standalone Arcane CLI is required. The application
 repository's exact npm dependency and lockfile own the CLI and toolchain version.
 
-Use `npx arcane-os@0.5.4` for the initial bootstrap because it names this npm
+Use `npx arcane-os@0.5.5` for the initial bootstrap because it names this npm
 package explicitly; bare `npx arcane` outside an installed project could resolve
 a different package. Both installed commands invoke the same headless toolchain.
 Project-local npm scripts use the SDK pinned by that app's `package-lock.json`,
@@ -216,7 +234,7 @@ node ./bin/arcane.mjs new local-app --path ../local-app --target portable --git
 
 # From the generated app repository
 cd ../local-app
-npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.5.4.tgz
+npm install --save-dev --save-exact ../arcane-os-sdk/arcane-os-0.5.5.tgz
 npm run check
 npm ci
 ```
@@ -226,7 +244,7 @@ same location. The lockfile retains the selected package dependency while
 Arcane uses the installed package name and version. Local directory `file:` dependencies are not
 accepted because npm may install them as links; use a packed `.tgz`. A GitHub
 runner also needs that tarball at the locked path. After publication, replace
-the local declaration with the exact `arcane-os@0.5.4` registry package and
+the local declaration with the exact `arcane-os@0.5.5` registry package and
 commit the regenerated lock.
 
 Generated repositories use `npm ci --ignore-scripts` in CI. Run dependency
@@ -364,7 +382,7 @@ package installation, or assertions.
 
 ## Current target support
 
-Version `0.5.4` exposes one browser target and five explicitly paired
+Version `0.5.5` exposes one browser target and five explicitly paired
 native development targets: a non-runnable portable directory, a
 Windows x64 unsigned-local-test EXE bundle, Linux x64 and Linux ARM64
 unsigned-local-test DEBs, and an Android development-signed APK. The

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arcane-os",
-  "version": "0.5.4",
+  "version": "0.5.5",
   "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/AI.js

@@ -17,6 +17,16 @@ const completeValue=(value)=>value;
 
 let credentials='include';
 const LEGACY_TTS_RESPONSE_FORMAT='opus';
+const DEFAULT_TTS_SEGMENTATION={
+    punctuation:'sentence',
+    wordCadence:null
+};
+const TTS_PUNCTUATION_MODES=new Set(['sentence','any','none']);
+// A complete punctuation run is a boundary unless the whole run consists of
+// apostrophe, comma, or dash punctuation joining Unicode letters or numbers.
+// The streaming expression leaves a trailing joining run for the next chunk.
+const TTS_ANY_PUNCTUATION=/(?<!\p{P})(?:(?<![\p{L}\p{N}])\p{P}+(?!\p{P})(?=[\s\S])|\p{P}+(?!\p{P})(?=[^\p{L}\p{N}])|\p{P}*[^\P{P}'\u2019\uFF07,\u060C\u3001\uFF0C\p{Pd}]\p{P}*)(?!\p{P})/gu;
+const TTS_ANY_PUNCTUATION_AT_END=/(?<!\p{P})(?:(?<![\p{L}\p{N}])\p{P}+|\p{P}+(?![\p{L}\p{N}])|\p{P}*[^\P{P}'\u2019\uFF07,\u060C\u3001\uFF0C\p{Pd}]\p{P}*)(?!\p{P})/gu;
 credentials='omit';
 
 const LEGACY_AI_SERVICES=new Set(['OPENAI','OLLAMA','LOCAL_SPEACH']);
@@ -142,6 +152,38 @@ function isPlainAIRecord(value){
     return prototype===Object.prototype||prototype===null;
 }
 
+function normalizeTTSSegmentation(value,current=DEFAULT_TTS_SEGMENTATION){
+    if(value===undefined||value===null){
+        return {...current};
+    }
+    if(!isPlainAIRecord(value)){
+        throw new TypeError('TTS segmentation must be a plain object.');
+    }
+
+    const punctuation=value.punctuation===undefined
+        ?current.punctuation
+        :value.punctuation;
+    if(!TTS_PUNCTUATION_MODES.has(punctuation)){
+        throw new TypeError(
+            'TTS segmentation punctuation must be sentence, any, or none.'
+        );
+    }
+
+    const wordCadence=value.wordCadence===undefined
+        ?current.wordCadence
+        :value.wordCadence;
+    if(
+        wordCadence!==null
+        &&(!Number.isSafeInteger(wordCadence)||wordCadence<1)
+    ){
+        throw new RangeError(
+            'TTS segmentation wordCadence must be null or a positive integer.'
+        );
+    }
+
+    return {punctuation,wordCadence};
+}
+
 function requireAIToolMessageSchemas(value,label='AI tools'){
     if(!Array.isArray(value)){
         throw aiStructuralError(
@@ -1069,6 +1111,7 @@ class AI {
     #speechControlGeneration=0;
     #speechFailureSequence=0;
     #stopOllamaReady=null;
+    #ttsSegmentation={...DEFAULT_TTS_SEGMENTATION};
     #preferenceTuple=completeValue([
         'OPENAI',
         'LOCAL_SPEACH',
@@ -5512,6 +5555,18 @@ class AI {
         return responseJSON;
     }
 
+    get ttsSegmentation(){
+        return {...this.#ttsSegmentation};
+    }
+
+    configureTTSSegmentation(options={}){
+        this.#ttsSegmentation=normalizeTTSSegmentation(
+            options,
+            this.#ttsSegmentation
+        );
+        return this.ttsSegmentation;
+    }
+
     streamTTS(
         text='',
         end=false
@@ -5563,10 +5618,16 @@ class AI {
         let remainder=this.audioMessageChunks;
 
         while(remainder.length>0){
-            const terminator=this.#findSpeechTerminator(remainder,end);
-            let boundary=terminator
-                ?terminator.index+terminator[0].length
-                :-1;
+            const punctuationBoundary=this.#findSpeechPunctuationBoundary(
+                remainder,
+                end
+            );
+            const cadenceBoundary=this.#findSpeechCadenceBoundary(remainder,end);
+            let boundary=punctuationBoundary;
+
+            if(boundary<0||(cadenceBoundary>0&&cadenceBoundary<boundary)){
+                boundary=cadenceBoundary;
+            }
 
             if(boundary<0&&end){
                 boundary=remainder.length;
@@ -5588,7 +5649,14 @@ class AI {
         return segments;
     }
 
-    #findSpeechTerminator(text,end=false){
+    #findSpeechPunctuationBoundary(text,end=false){
+        if(this.#ttsSegmentation.punctuation==='none'){
+            return -1;
+        }
+        if(this.#ttsSegmentation.punctuation==='any'){
+            return this.#findAnySpeechPunctuationBoundary(text,end);
+        }
+
         const pattern=end
             ?/(?:[\u3002\uFF01\uFF1F]|[.!?](?=\s|$))/g
             :/(?:[\u3002\uFF01\uFF1F]|[.!?](?=\s+\S))/g;
@@ -5602,10 +5670,71 @@ class AI {
                 continue;
             }
 
-            return terminator;
+            return this.#includeSpeechBoundaryWhitespace(
+                text,
+                terminator.index+terminator[0].length
+            );
         }
 
-        return null;
+        return -1;
+    }
+
+    #findAnySpeechPunctuationBoundary(text,end=false){
+        const pattern=end
+            ?TTS_ANY_PUNCTUATION_AT_END
+            :TTS_ANY_PUNCTUATION;
+        pattern.lastIndex=0;
+        const firstContent=text.search(/\S/u);
+        let punctuation;
+
+        while((punctuation=pattern.exec(text))){
+            if(firstContent<0||punctuation.index<=firstContent){
+                continue;
+            }
+            const boundary=punctuation.index+punctuation[0].length;
+            return this.#includeSpeechBoundaryWhitespace(text,boundary);
+        }
+
+        return -1;
+    }
+
+    #findSpeechCadenceBoundary(text,end=false){
+        const wordCadence=this.#ttsSegmentation.wordCadence;
+        if(wordCadence===null){
+            return -1;
+        }
+
+        const words=/\S+/gu;
+        let word;
+        let wordCount=0;
+
+        while((word=words.exec(text))){
+            wordCount+=1;
+            if(wordCount!==wordCadence){
+                continue;
+            }
+            const boundary=word.index+word[0].length;
+            if(boundary===text.length&&!end){
+                return -1;
+            }
+            if(boundary<text.length&&!/\s/u.test(text[boundary])){
+                return -1;
+            }
+            return this.#includeSpeechBoundaryWhitespace(text,boundary);
+        }
+
+        return -1;
+    }
+
+    #includeSpeechBoundaryWhitespace(text,boundary){
+        let completeBoundary=boundary;
+        while(
+            completeBoundary<text.length
+            &&/\s/u.test(text[completeBoundary])
+        ){
+            completeBoundary+=1;
+        }
+        return completeBoundary;
     }
 
     #isSpeechAbbreviation(text,periodIndex){