@fiodos/web-core 0.1.5 → 0.1.7

package/dist/cjs/adapters/webVoiceAdapter.js

@@ -401,20 +401,40 @@ function createWebVoiceAdapter(options = {}) {
             // later programmatic playback (after the network round-trip) is allowed
             // and audible even with the silent switch on.
             const ctx = ensureAudioCtx();
-            if (!ctx)
-                return;
-            try {
-                if (ctx.state === 'suspended')
-                    void ctx.resume();
-                // A 1-frame silent buffer fully unlocks playback on iOS Safari.
-                const buffer = ctx.createBuffer(1, 1, ctx.sampleRate);
-                const source = ctx.createBufferSource();
-                source.buffer = buffer;
-                source.connect(ctx.destination);
-                source.start(0);
+            if (ctx) {
+                try {
+                    if (ctx.state === 'suspended')
+                        void ctx.resume();
+                    // A 1-frame silent buffer fully unlocks playback on iOS Safari.
+                    const buffer = ctx.createBuffer(1, 1, ctx.sampleRate);
+                    const source = ctx.createBufferSource();
+                    source.buffer = buffer;
+                    source.connect(ctx.destination);
+                    source.start(0);
+                }
+                catch {
+                    /* best-effort unlock */
+                }
             }
-            catch {
-                /* best-effort unlock */
+            // Unlock device TTS (SpeechSynthesis) too. The spoken reply happens AFTER
+            // the network round-trip — outside this gesture — and Safari/Chrome stay
+            // SILENT for a first programmatic speak that wasn't preceded by a
+            // gesture-initiated one. Warm the engine here: kick off voice loading and
+            // speak a zero-volume blank utterance inside the tap so the real reply is
+            // allowed to play later.
+            if (!options.disableDeviceTtsFallback && typeof window !== 'undefined' && window.speechSynthesis) {
+                try {
+                    const synth = window.speechSynthesis;
+                    synth.getVoices(); // triggers async voice loading on Chrome
+                    if (synth.paused)
+                        synth.resume();
+                    const warm = new SpeechSynthesisUtterance(' ');
+                    warm.volume = 0;
+                    synth.speak(warm);
+                }
+                catch {
+                    /* best-effort unlock */
+                }
             }
         },
         async playAudioBase64Mp3(base64) {
@@ -456,20 +476,32 @@ function createWebVoiceAdapter(options = {}) {
             // Voices load lazily on Chrome — speaking before they exist is silent.
             const voices = await loadVoicesOnce(synth);
             return new Promise((resolve) => {
+                let keepAlive = null;
+                const cleanup = () => {
+                    if (keepAlive) {
+                        clearInterval(keepAlive);
+                        keepAlive = null;
+                    }
+                };
                 try {
-                    // Clear any utterance the engine wedged on (a known Chrome failure
-                    // mode) and unpause before queuing the reply.
-                    if (synth.speaking || synth.pending)
-                        synth.cancel();
-                    if (synth.paused)
-                        synth.resume();
+                    // Clear any previous/wedged queue. After a prior cancel() (e.g. the
+                    // stopPlayback() fired when listening started) Chrome on macOS can sit
+                    // in a stuck "paused" state that does NOT report paused===true, so a
+                    // conditional resume() never fires and every later speak() is silent.
+                    synth.cancel();
                     const utter = new SpeechSynthesisUtterance(text);
                     utter.lang = ttsOptions.locale;
                     const voice = pickVoiceForLocale(voices, ttsOptions.locale);
                     if (voice)
                         utter.voice = voice;
+                    utter.volume = 1;
+                    utter.rate = 1;
+                    utter.pitch = 1;
+                    // Keep a strong ref so Chrome can't GC the utterance mid-speech.
                     ttsUtterance = utter;
                     const finish = () => {
+                        cleanup();
+                        utter.onstart = null;
                         utter.onend = null;
                         utter.onerror = null;
                         if (ttsUtterance === utter)
@@ -479,8 +511,22 @@ function createWebVoiceAdapter(options = {}) {
                     utter.onend = finish;
                     utter.onerror = finish;
                     synth.speak(utter);
+                    // THE FIX: resume() unconditionally right after queuing. This un-wedges
+                    // the engine from the silent stuck-paused state described above.
+                    synth.resume();
+                    // Chrome desktop stops speaking after ~15s; pulse pause/resume to keep
+                    // long replies going, and stop the timer once it has finished.
+                    keepAlive = setInterval(() => {
+                        if (!synth.speaking && !synth.pending) {
+                            cleanup();
+                            return;
+                        }
+                        synth.pause();
+                        synth.resume();
+                    }, 9000);
                 }
                 catch {
+                    cleanup();
                     resolve();
                 }
             });

package/dist/cjs/controller/AgentController.d.ts

@@ -75,6 +75,7 @@ export declare class AgentController {
     private watchdog;
     private confirmWindow;
     private speakTimer;
+    private serverTtsUnavailable;
     private pendingConsentIntent;
     private readonly listeners;
     private unsubscribeSpeech;

package/dist/cjs/controller/AgentController.js

@@ -54,6 +54,9 @@ class AgentController {
         // Safety cap so the orb can never get stuck in 'speaking' if playback/TTS
         // never reports completion (e.g. a stalled SpeechSynthesis engine).
         this.speakTimer = null;
+        // Once the backend shows it has no server-side TTS (a reply arrives with null
+        // audio), skip the extra /preview-tts round-trip and speak via device voice.
+        this.serverTtsUnavailable = false;
         this.pendingConsentIntent = null;
         this.listeners = new Set();
         this.unsubscribeSpeech = null;
@@ -90,7 +93,11 @@ class AgentController {
                 });
         this.screenStore = (0, screenContextStore_1.createScreenContextStore)({
             getCurrentRoute: () => config.navigation.getCurrentRoute(),
-            routeFallback: config.routeContextFallback,
+            // The integrator's fallback wins; otherwise the orb gets screen awareness
+            // out of the box from the matched manifest route (label + description +
+            // available actions). Null when no route matches → raw route, as today.
+            routeFallback: config.routeContextFallback ??
+                ((route) => (0, core_1.defaultRouteContextText)(route, config.manifest, this.messages)),
         });
         this.speech = (0, speechSession_1.createSpeechSession)({
             adapter: config.voice,
@@ -197,13 +204,20 @@ class AgentController {
         this.setPhase('speaking');
         try {
             let audio = audioBase64;
-            if (!audio && text) {
-                // A server-TTS failure must NOT skip the device-voice fallback below.
+            if (audio) {
+                this.serverTtsUnavailable = false; // server voice is working
+            }
+            // Once we know the backend ships no server TTS, skip the dead
+            // /preview-tts round-trip (pure latency) and use the device voice.
+            if (!audio && text && !this.serverTtsUnavailable) {
                 try {
                     audio = await this.config.backend.previewTts(this.getTtsVoice() ?? '', text);
+                    if (!audio)
+                        this.serverTtsUnavailable = true;
                 }
                 catch {
                     audio = null;
+                    this.serverTtsUnavailable = true;
                 }
             }
             const playback = audio
@@ -418,6 +432,10 @@ class AgentController {
             }, { signal: controller.signal });
             reply = turn.reply;
             audioBase64 = turn.audioBase64;
+            // Learn whether this backend ships server-side TTS: a non-empty reply
+            // with no audio means it doesn't — later lines then speak instantly.
+            if (reply)
+                this.serverTtsUnavailable = !audioBase64;
             const decision = await (0, turnEngine_1.decideAction)({
                 action: turn.action,
                 manifest: this.config.manifest,

package/dist/cjs/version.d.ts

@@ -5,5 +5,5 @@
  * Auto-generated by scripts/sync-sdk-version.mjs from package.json. Do not edit
  * by hand — change package.json `version` and re-run the sync/release script.
  */
-export declare const SDK_VERSION = "0.1.5";
+export declare const SDK_VERSION = "0.1.7";
 export declare const SDK_PACKAGE = "@fiodos/web-core";

package/dist/cjs/version.js

@@ -8,5 +8,5 @@ exports.SDK_PACKAGE = exports.SDK_VERSION = void 0;
  * Auto-generated by scripts/sync-sdk-version.mjs from package.json. Do not edit
  * by hand — change package.json `version` and re-run the sync/release script.
  */
-exports.SDK_VERSION = '0.1.5';
+exports.SDK_VERSION = '0.1.7';
 exports.SDK_PACKAGE = '@fiodos/web-core';

package/dist/esm/adapters/webVoiceAdapter.js

@@ -398,20 +398,40 @@ export function createWebVoiceAdapter(options = {}) {
             // later programmatic playback (after the network round-trip) is allowed
             // and audible even with the silent switch on.
             const ctx = ensureAudioCtx();
-            if (!ctx)
-                return;
-            try {
-                if (ctx.state === 'suspended')
-                    void ctx.resume();
-                // A 1-frame silent buffer fully unlocks playback on iOS Safari.
-                const buffer = ctx.createBuffer(1, 1, ctx.sampleRate);
-                const source = ctx.createBufferSource();
-                source.buffer = buffer;
-                source.connect(ctx.destination);
-                source.start(0);
+            if (ctx) {
+                try {
+                    if (ctx.state === 'suspended')
+                        void ctx.resume();
+                    // A 1-frame silent buffer fully unlocks playback on iOS Safari.
+                    const buffer = ctx.createBuffer(1, 1, ctx.sampleRate);
+                    const source = ctx.createBufferSource();
+                    source.buffer = buffer;
+                    source.connect(ctx.destination);
+                    source.start(0);
+                }
+                catch {
+                    /* best-effort unlock */
+                }
             }
-            catch {
-                /* best-effort unlock */
+            // Unlock device TTS (SpeechSynthesis) too. The spoken reply happens AFTER
+            // the network round-trip — outside this gesture — and Safari/Chrome stay
+            // SILENT for a first programmatic speak that wasn't preceded by a
+            // gesture-initiated one. Warm the engine here: kick off voice loading and
+            // speak a zero-volume blank utterance inside the tap so the real reply is
+            // allowed to play later.
+            if (!options.disableDeviceTtsFallback && typeof window !== 'undefined' && window.speechSynthesis) {
+                try {
+                    const synth = window.speechSynthesis;
+                    synth.getVoices(); // triggers async voice loading on Chrome
+                    if (synth.paused)
+                        synth.resume();
+                    const warm = new SpeechSynthesisUtterance(' ');
+                    warm.volume = 0;
+                    synth.speak(warm);
+                }
+                catch {
+                    /* best-effort unlock */
+                }
             }
         },
         async playAudioBase64Mp3(base64) {
@@ -453,20 +473,32 @@ export function createWebVoiceAdapter(options = {}) {
             // Voices load lazily on Chrome — speaking before they exist is silent.
             const voices = await loadVoicesOnce(synth);
             return new Promise((resolve) => {
+                let keepAlive = null;
+                const cleanup = () => {
+                    if (keepAlive) {
+                        clearInterval(keepAlive);
+                        keepAlive = null;
+                    }
+                };
                 try {
-                    // Clear any utterance the engine wedged on (a known Chrome failure
-                    // mode) and unpause before queuing the reply.
-                    if (synth.speaking || synth.pending)
-                        synth.cancel();
-                    if (synth.paused)
-                        synth.resume();
+                    // Clear any previous/wedged queue. After a prior cancel() (e.g. the
+                    // stopPlayback() fired when listening started) Chrome on macOS can sit
+                    // in a stuck "paused" state that does NOT report paused===true, so a
+                    // conditional resume() never fires and every later speak() is silent.
+                    synth.cancel();
                     const utter = new SpeechSynthesisUtterance(text);
                     utter.lang = ttsOptions.locale;
                     const voice = pickVoiceForLocale(voices, ttsOptions.locale);
                     if (voice)
                         utter.voice = voice;
+                    utter.volume = 1;
+                    utter.rate = 1;
+                    utter.pitch = 1;
+                    // Keep a strong ref so Chrome can't GC the utterance mid-speech.
                     ttsUtterance = utter;
                     const finish = () => {
+                        cleanup();
+                        utter.onstart = null;
                         utter.onend = null;
                         utter.onerror = null;
                         if (ttsUtterance === utter)
@@ -476,8 +508,22 @@ export function createWebVoiceAdapter(options = {}) {
                     utter.onend = finish;
                     utter.onerror = finish;
                     synth.speak(utter);
+                    // THE FIX: resume() unconditionally right after queuing. This un-wedges
+                    // the engine from the silent stuck-paused state described above.
+                    synth.resume();
+                    // Chrome desktop stops speaking after ~15s; pulse pause/resume to keep
+                    // long replies going, and stop the timer once it has finished.
+                    keepAlive = setInterval(() => {
+                        if (!synth.speaking && !synth.pending) {
+                            cleanup();
+                            return;
+                        }
+                        synth.pause();
+                        synth.resume();
+                    }, 9000);
                 }
                 catch {
+                    cleanup();
                     resolve();
                 }
             });

package/dist/esm/controller/AgentController.d.ts

@@ -75,6 +75,7 @@ export declare class AgentController {
     private watchdog;
     private confirmWindow;
     private speakTimer;
+    private serverTtsUnavailable;
     private pendingConsentIntent;
     private readonly listeners;
     private unsubscribeSpeech;

package/dist/esm/controller/AgentController.js

@@ -15,7 +15,7 @@
  *    deliberate modal tap; a loose "yes" never confirms them.
  *  - The agent only ever executes actions declared in the manifest.
  */
-import { combineContexts, createActionExecutor, createConsentManager, createSafeTelemetry, createSanitizer, createConversationSession, formatMessage, prepareConversationForTurn, recordConversationExchange, resolveConfirmationLexicon, resolveMessages, validateManifest, } from '@fiodos/core';
+import { combineContexts, createActionExecutor, createConsentManager, createSafeTelemetry, createSanitizer, createConversationSession, defaultRouteContextText, formatMessage, prepareConversationForTurn, recordConversationExchange, resolveConfirmationLexicon, resolveMessages, validateManifest, } from '@fiodos/core';
 import { AgentApiError } from '../api/errors.js';
 import { formatAgentTurnError } from '../api/formatTurnError.js';
 import { buildManifestPayload } from '../api/backendClient.js';
@@ -51,6 +51,9 @@ export class AgentController {
         // Safety cap so the orb can never get stuck in 'speaking' if playback/TTS
         // never reports completion (e.g. a stalled SpeechSynthesis engine).
         this.speakTimer = null;
+        // Once the backend shows it has no server-side TTS (a reply arrives with null
+        // audio), skip the extra /preview-tts round-trip and speak via device voice.
+        this.serverTtsUnavailable = false;
         this.pendingConsentIntent = null;
         this.listeners = new Set();
         this.unsubscribeSpeech = null;
@@ -87,7 +90,11 @@ export class AgentController {
                 });
         this.screenStore = createScreenContextStore({
             getCurrentRoute: () => config.navigation.getCurrentRoute(),
-            routeFallback: config.routeContextFallback,
+            // The integrator's fallback wins; otherwise the orb gets screen awareness
+            // out of the box from the matched manifest route (label + description +
+            // available actions). Null when no route matches → raw route, as today.
+            routeFallback: config.routeContextFallback ??
+                ((route) => defaultRouteContextText(route, config.manifest, this.messages)),
         });
         this.speech = createSpeechSession({
             adapter: config.voice,
@@ -194,13 +201,20 @@ export class AgentController {
         this.setPhase('speaking');
         try {
             let audio = audioBase64;
-            if (!audio && text) {
-                // A server-TTS failure must NOT skip the device-voice fallback below.
+            if (audio) {
+                this.serverTtsUnavailable = false; // server voice is working
+            }
+            // Once we know the backend ships no server TTS, skip the dead
+            // /preview-tts round-trip (pure latency) and use the device voice.
+            if (!audio && text && !this.serverTtsUnavailable) {
                 try {
                     audio = await this.config.backend.previewTts(this.getTtsVoice() ?? '', text);
+                    if (!audio)
+                        this.serverTtsUnavailable = true;
                 }
                 catch {
                     audio = null;
+                    this.serverTtsUnavailable = true;
                 }
             }
             const playback = audio
@@ -415,6 +429,10 @@ export class AgentController {
             }, { signal: controller.signal });
             reply = turn.reply;
             audioBase64 = turn.audioBase64;
+            // Learn whether this backend ships server-side TTS: a non-empty reply
+            // with no audio means it doesn't — later lines then speak instantly.
+            if (reply)
+                this.serverTtsUnavailable = !audioBase64;
             const decision = await decideAction({
                 action: turn.action,
                 manifest: this.config.manifest,

package/dist/esm/version.d.ts

@@ -5,5 +5,5 @@
  * Auto-generated by scripts/sync-sdk-version.mjs from package.json. Do not edit
  * by hand — change package.json `version` and re-run the sync/release script.
  */
-export declare const SDK_VERSION = "0.1.5";
+export declare const SDK_VERSION = "0.1.7";
 export declare const SDK_PACKAGE = "@fiodos/web-core";

package/dist/esm/version.js

@@ -5,5 +5,5 @@
  * Auto-generated by scripts/sync-sdk-version.mjs from package.json. Do not edit
  * by hand — change package.json `version` and re-run the sync/release script.
  */
-export const SDK_VERSION = '0.1.5';
+export const SDK_VERSION = '0.1.7';
 export const SDK_PACKAGE = '@fiodos/web-core';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiodos/web-core",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "Framework-agnostic browser layer for the Fiodos agent: a vanilla AgentController (orchestrator), DOM adapters (navigation/voice/storage), HTTP client and decision engine over @fiodos/core. Shared base for @fiodos/vue, @fiodos/svelte and @fiodos/angular (no framework imports).",
   "license": "SEE LICENSE IN LICENSE",
   "publishConfig": {