@fiodos/web-core 0.1.4 → 0.1.7

package/dist/cjs/adapters/webVoiceAdapter.js

@@ -2,6 +2,43 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createWebVoiceAdapter = createWebVoiceAdapter;
 const core_1 = require("@fiodos/core");
+// ── Device TTS (SpeechSynthesis) helpers ────────────────────────────────────
+// Chrome loads voices asynchronously: calling speak() before getVoices() is
+// populated produces NO sound. Resolve the voice list once (event or timeout).
+function loadVoicesOnce(synth) {
+    const ready = synth.getVoices();
+    if (ready.length)
+        return Promise.resolve(ready);
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(synth.getVoices());
+        };
+        try {
+            synth.addEventListener('voiceschanged', finish, { once: true });
+        }
+        catch {
+            /* older engines: the timeout below is the only path */
+        }
+        // Some engines never emit `voiceschanged` — never block the reply forever.
+        setTimeout(finish, 600);
+    });
+}
+/** Best voice for a BCP-47 locale: exact → region-agnostic → language → default. */
+function pickVoiceForLocale(voices, locale) {
+    if (!voices.length)
+        return undefined;
+    const lc = locale.toLowerCase();
+    const lang = lc.split('-')[0] ?? lc;
+    return (voices.find((v) => v.lang?.toLowerCase() === lc) ??
+        voices.find((v) => v.lang?.toLowerCase().startsWith(`${lang}-`)) ??
+        voices.find((v) => v.lang?.toLowerCase().startsWith(lang)) ??
+        voices.find((v) => v.default) ??
+        voices[0]);
+}
 function getRecognitionCtor() {
     if (typeof window === 'undefined')
         return null;
@@ -33,6 +70,9 @@ function createWebVoiceAdapter(options = {}) {
     let aborted = false;
     let settled = false;
     let audioEl = null;
+    // Strong reference to the in-flight utterance: Chrome garbage-collects it
+    // otherwise, cutting device speech off mid-sentence (or producing silence).
+    let ttsUtterance = null;
     // ── Wake-word state (separate recognition instance; the browser allows only
     // one active session, so push-to-talk stops wake first). Desktop-only:
     // foreground tab while the page is visible — there is no passive background
@@ -361,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) {
@@ -412,15 +472,61 @@ function createWebVoiceAdapter(options = {}) {
                 return;
             if (typeof window === 'undefined' || !window.speechSynthesis)
                 return;
+            const synth = window.speechSynthesis;
+            // 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 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;
-                    utter.onend = () => resolve();
-                    utter.onerror = () => resolve();
-                    window.speechSynthesis.speak(utter);
+                    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)
+                            ttsUtterance = null;
+                        resolve();
+                    };
+                    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

@@ -74,6 +74,8 @@ export declare class AgentController {
     private abort;
     private watchdog;
     private confirmWindow;
+    private speakTimer;
+    private serverTtsUnavailable;
     private pendingConsentIntent;
     private readonly listeners;
     private unsubscribeSpeech;
@@ -95,7 +97,14 @@ export declare class AgentController {
     private setPhase;
     private clearWatchdog;
     private clearConfirmWindow;
+    private clearSpeakTimer;
     private speakReply;
+    /**
+     * Never let the 'speaking' phase hang. If playback/TTS never reports
+     * completion (a stalled engine, a never-firing onend), stop it and continue
+     * after a generous, length-based cap so the orb returns to idle on its own.
+     */
+    private raceSpeakingWatchdog;
     private beginConfirmationVoiceWindow;
     confirmPendingAction(): Promise<void>;
     cancelPendingAction(): void;

package/dist/cjs/controller/AgentController.js

@@ -51,6 +51,12 @@ class AgentController {
         this.abort = null;
         this.watchdog = null;
         this.confirmWindow = null;
+        // 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 +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,
@@ -179,6 +189,12 @@ class AgentController {
         }
         this.confirmationVoiceActive = false;
     }
+    clearSpeakTimer() {
+        if (this.speakTimer) {
+            clearTimeout(this.speakTimer);
+            this.speakTimer = null;
+        }
+    }
     // ── Speech playback (ONE consistent voice) ─────────────────────────────────
     async speakReply(text, audioBase64) {
         if (this.silentTurn)
@@ -188,24 +204,62 @@ class AgentController {
         this.setPhase('speaking');
         try {
             let audio = audioBase64;
-            if (!audio && text) {
-                audio = await this.config.backend.previewTts(this.getTtsVoice() ?? '', text);
-            }
             if (audio) {
-                await this.config.voice.playAudioBase64Mp3(audio);
+                this.serverTtsUnavailable = false; // server voice is working
             }
-            else if (text) {
-                await this.config.voice.speakWithDeviceTts(text, { locale: this.ttsLocale });
+            // 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
+                ? this.config.voice.playAudioBase64Mp3(audio)
+                : text
+                    ? this.config.voice.speakWithDeviceTts(text, { locale: this.ttsLocale })
+                    : Promise.resolve();
+            await this.raceSpeakingWatchdog(playback, text);
         }
         catch {
             /* playback best-effort */
         }
         finally {
+            this.clearSpeakTimer();
             if (this.phase === 'speaking')
                 this.setPhase('idle');
         }
     }
+    /**
+     * Never let the 'speaking' phase hang. If playback/TTS never reports
+     * completion (a stalled engine, a never-firing onend), stop it and continue
+     * after a generous, length-based cap so the orb returns to idle on its own.
+     */
+    raceSpeakingWatchdog(playback, text) {
+        const capMs = Math.min(60000, 5000 + text.length * 90);
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.clearSpeakTimer();
+                resolve();
+            };
+            this.clearSpeakTimer();
+            this.speakTimer = setTimeout(() => {
+                this.config.voice.stopPlayback();
+                finish();
+            }, capMs);
+            playback.then(finish, finish);
+        });
+    }
     // ── Confirmation resolution ─────────────────────────────────────────────────
     beginConfirmationVoiceWindow() {
         const pending = this.pending;
@@ -378,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,
@@ -544,8 +602,14 @@ class AgentController {
             this.setPhase('thinking');
             return;
         }
-        if (this.phase === 'thinking' || this.phase === 'speaking')
+        if (this.phase === 'speaking') {
+            // Tap while the assistant is talking → stop the reply and reset, so the
+            // orb is immediately usable again (no more "stuck pulsing").
+            this.cancelAll();
             return;
+        }
+        if (this.phase === 'thinking')
+            return; // a turn is in flight; let it finish
         const consented = await this.consent.hasConsented();
         if (!consented) {
             this.pendingConsentIntent = 'voice';
@@ -597,6 +661,7 @@ class AgentController {
         this.abort = null;
         this.clearWatchdog();
         this.clearConfirmWindow();
+        this.clearSpeakTimer();
         this.speech.cancel();
         this.config.voice.stopPlayback();
         this.pending = null;

package/dist/cjs/orb/mountOrb.js

@@ -46,6 +46,7 @@ const CSS = `
 @keyframes fyodos-blink{0%,100%{opacity:.25}50%{opacity:.9}}
 @keyframes fy-spin{to{transform:rotate(360deg)}}
 @keyframes fy-opulse{0%,100%{transform:scale(1);opacity:1}50%{transform:scale(1.06);opacity:.85}}
+@keyframes fy-voice{0%{transform:scale(0.6);opacity:.7}100%{transform:scale(1.35);opacity:0}}
 .fyodos-overlay{position:fixed;inset:0;display:flex;align-items:center;justify-content:center;padding:24px;background:rgba(4,6,12,0.6);}
 .fyodos-modal{width:min(420px,100%);border-radius:16px;padding:22px 24px;box-shadow:0 24px 60px rgba(0,0,0,0.5);}
 .fyodos-modal h3{margin:0 0 10px;font-size:17px;font-weight:600;}

package/dist/cjs/orb/orbView.js

@@ -215,6 +215,52 @@ function buildThinkingSpinner(orbSizePx, color) {
     wrap.appendChild(spin);
     return wrap;
 }
+// ── Speaking pulse (port of the dashboard's no-logo "speaking" state) ─────────
+// Two expanding rings + a pulsing centre dot — the default "talking" drawing the
+// dashboard orb editor shows when there is no custom photo. Ratios are taken
+// from the editor (118 / 30 / 2 px on its 380px reference orb) so the embedded
+// orb matches it at any size.
+const SPEAK_RING_RATIO = 118 / 380;
+const SPEAK_DOT_RATIO = 30 / 380;
+const SPEAK_BORDER_RATIO = 2 / 380;
+function buildSpeakingPulse(orbSize, color) {
+    const wrap = document.createElement('div');
+    Object.assign(wrap.style, {
+        position: 'absolute',
+        inset: '0',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        pointerEvents: 'none',
+    });
+    const ringPx = orbSize * SPEAK_RING_RATIO;
+    const borderPx = Math.max(1, orbSize * SPEAK_BORDER_RATIO);
+    for (const delay of [0, 0.85]) {
+        const ring = document.createElement('div');
+        Object.assign(ring.style, {
+            position: 'absolute',
+            width: `${ringPx}px`,
+            height: `${ringPx}px`,
+            borderRadius: '50%',
+            border: `${borderPx}px solid ${color}`,
+            opacity: '0.55',
+            animation: `fy-voice 1.7s ease-out infinite ${delay}s`,
+        });
+        wrap.appendChild(ring);
+    }
+    const dotPx = orbSize * SPEAK_DOT_RATIO;
+    const dot = document.createElement('div');
+    Object.assign(dot.style, {
+        width: `${dotPx}px`,
+        height: `${dotPx}px`,
+        borderRadius: '50%',
+        background: color,
+        opacity: '0.9',
+        animation: 'fy-opulse 1s ease-in-out infinite',
+    });
+    wrap.appendChild(dot);
+    return wrap;
+}
 // ── Keyboard chip icon (port of ChipIconSvg) ──────────────────────────────────
 function buildChipIcon(icon, size, color) {
     const spec = (0, core_1.chipIconSpec)(icon);
@@ -369,7 +415,10 @@ function createOrbVisual(initial) {
         waveform?.stop();
         waveform = null;
         fillEl.replaceChildren();
-        wrapper.style.animation = state === 'speaking' ? 'fy-opulse 1.1s ease-in-out infinite' : '';
+        // The "speaking" feedback now lives INSIDE the fill (a pulsing logo, or the
+        // rings + dot when there's no photo) to mirror the dashboard editor, so the
+        // orb no longer pulses as a whole.
+        wrapper.style.animation = '';
         if (state === 'thinking') {
             fillEl.appendChild(buildThinkingSpinner(size, waveColor));
             return;
@@ -397,10 +446,17 @@ function createOrbVisual(initial) {
                 userSelect: 'none',
                 webkitUserSelect: 'none',
                 webkitUserDrag: 'none',
+                // While speaking, the photo gently pulses (matches the dashboard).
+                animation: state === 'speaking' ? 'fy-opulse 1s ease-in-out infinite' : '',
             });
             fillEl.appendChild(img);
             return;
         }
+        if (state === 'speaking') {
+            // No photo → the default "talking" drawing (expanding rings + centre dot).
+            fillEl.appendChild(buildSpeakingPulse(size, waveColor));
+            return;
+        }
         if (state === 'idle') {
             fillEl.appendChild(buildOrbMark(size));
         }

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.3";
+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.3';
+exports.SDK_VERSION = '0.1.7';
 exports.SDK_PACKAGE = '@fiodos/web-core';

package/dist/esm/adapters/webVoiceAdapter.js

@@ -1,4 +1,41 @@
 import { detectWakePhrase } from '@fiodos/core';
+// ── Device TTS (SpeechSynthesis) helpers ────────────────────────────────────
+// Chrome loads voices asynchronously: calling speak() before getVoices() is
+// populated produces NO sound. Resolve the voice list once (event or timeout).
+function loadVoicesOnce(synth) {
+    const ready = synth.getVoices();
+    if (ready.length)
+        return Promise.resolve(ready);
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(synth.getVoices());
+        };
+        try {
+            synth.addEventListener('voiceschanged', finish, { once: true });
+        }
+        catch {
+            /* older engines: the timeout below is the only path */
+        }
+        // Some engines never emit `voiceschanged` — never block the reply forever.
+        setTimeout(finish, 600);
+    });
+}
+/** Best voice for a BCP-47 locale: exact → region-agnostic → language → default. */
+function pickVoiceForLocale(voices, locale) {
+    if (!voices.length)
+        return undefined;
+    const lc = locale.toLowerCase();
+    const lang = lc.split('-')[0] ?? lc;
+    return (voices.find((v) => v.lang?.toLowerCase() === lc) ??
+        voices.find((v) => v.lang?.toLowerCase().startsWith(`${lang}-`)) ??
+        voices.find((v) => v.lang?.toLowerCase().startsWith(lang)) ??
+        voices.find((v) => v.default) ??
+        voices[0]);
+}
 function getRecognitionCtor() {
     if (typeof window === 'undefined')
         return null;
@@ -30,6 +67,9 @@ export function createWebVoiceAdapter(options = {}) {
     let aborted = false;
     let settled = false;
     let audioEl = null;
+    // Strong reference to the in-flight utterance: Chrome garbage-collects it
+    // otherwise, cutting device speech off mid-sentence (or producing silence).
+    let ttsUtterance = null;
     // ── Wake-word state (separate recognition instance; the browser allows only
     // one active session, so push-to-talk stops wake first). Desktop-only:
     // foreground tab while the page is visible — there is no passive background
@@ -358,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) {
@@ -409,15 +469,61 @@ export function createWebVoiceAdapter(options = {}) {
                 return;
             if (typeof window === 'undefined' || !window.speechSynthesis)
                 return;
+            const synth = window.speechSynthesis;
+            // 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 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;
-                    utter.onend = () => resolve();
-                    utter.onerror = () => resolve();
-                    window.speechSynthesis.speak(utter);
+                    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)
+                            ttsUtterance = null;
+                        resolve();
+                    };
+                    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

@@ -74,6 +74,8 @@ export declare class AgentController {
     private abort;
     private watchdog;
     private confirmWindow;
+    private speakTimer;
+    private serverTtsUnavailable;
     private pendingConsentIntent;
     private readonly listeners;
     private unsubscribeSpeech;
@@ -95,7 +97,14 @@ export declare class AgentController {
     private setPhase;
     private clearWatchdog;
     private clearConfirmWindow;
+    private clearSpeakTimer;
     private speakReply;
+    /**
+     * Never let the 'speaking' phase hang. If playback/TTS never reports
+     * completion (a stalled engine, a never-firing onend), stop it and continue
+     * after a generous, length-based cap so the orb returns to idle on its own.
+     */
+    private raceSpeakingWatchdog;
     private beginConfirmationVoiceWindow;
     confirmPendingAction(): Promise<void>;
     cancelPendingAction(): void;

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';
@@ -48,6 +48,12 @@ export class AgentController {
         this.abort = null;
         this.watchdog = null;
         this.confirmWindow = null;
+        // 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;
@@ -84,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,
@@ -176,6 +186,12 @@ export class AgentController {
         }
         this.confirmationVoiceActive = false;
     }
+    clearSpeakTimer() {
+        if (this.speakTimer) {
+            clearTimeout(this.speakTimer);
+            this.speakTimer = null;
+        }
+    }
     // ── Speech playback (ONE consistent voice) ─────────────────────────────────
     async speakReply(text, audioBase64) {
         if (this.silentTurn)
@@ -185,24 +201,62 @@ export class AgentController {
         this.setPhase('speaking');
         try {
             let audio = audioBase64;
-            if (!audio && text) {
-                audio = await this.config.backend.previewTts(this.getTtsVoice() ?? '', text);
-            }
             if (audio) {
-                await this.config.voice.playAudioBase64Mp3(audio);
+                this.serverTtsUnavailable = false; // server voice is working
             }
-            else if (text) {
-                await this.config.voice.speakWithDeviceTts(text, { locale: this.ttsLocale });
+            // 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
+                ? this.config.voice.playAudioBase64Mp3(audio)
+                : text
+                    ? this.config.voice.speakWithDeviceTts(text, { locale: this.ttsLocale })
+                    : Promise.resolve();
+            await this.raceSpeakingWatchdog(playback, text);
         }
         catch {
             /* playback best-effort */
         }
         finally {
+            this.clearSpeakTimer();
             if (this.phase === 'speaking')
                 this.setPhase('idle');
         }
     }
+    /**
+     * Never let the 'speaking' phase hang. If playback/TTS never reports
+     * completion (a stalled engine, a never-firing onend), stop it and continue
+     * after a generous, length-based cap so the orb returns to idle on its own.
+     */
+    raceSpeakingWatchdog(playback, text) {
+        const capMs = Math.min(60000, 5000 + text.length * 90);
+        return new Promise((resolve) => {
+            let settled = false;
+            const finish = () => {
+                if (settled)
+                    return;
+                settled = true;
+                this.clearSpeakTimer();
+                resolve();
+            };
+            this.clearSpeakTimer();
+            this.speakTimer = setTimeout(() => {
+                this.config.voice.stopPlayback();
+                finish();
+            }, capMs);
+            playback.then(finish, finish);
+        });
+    }
     // ── Confirmation resolution ─────────────────────────────────────────────────
     beginConfirmationVoiceWindow() {
         const pending = this.pending;
@@ -375,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,
@@ -541,8 +599,14 @@ export class AgentController {
             this.setPhase('thinking');
             return;
         }
-        if (this.phase === 'thinking' || this.phase === 'speaking')
+        if (this.phase === 'speaking') {
+            // Tap while the assistant is talking → stop the reply and reset, so the
+            // orb is immediately usable again (no more "stuck pulsing").
+            this.cancelAll();
             return;
+        }
+        if (this.phase === 'thinking')
+            return; // a turn is in flight; let it finish
         const consented = await this.consent.hasConsented();
         if (!consented) {
             this.pendingConsentIntent = 'voice';
@@ -594,6 +658,7 @@ export class AgentController {
         this.abort = null;
         this.clearWatchdog();
         this.clearConfirmWindow();
+        this.clearSpeakTimer();
         this.speech.cancel();
         this.config.voice.stopPlayback();
         this.pending = null;

package/dist/esm/orb/mountOrb.js

@@ -43,6 +43,7 @@ const CSS = `
 @keyframes fyodos-blink{0%,100%{opacity:.25}50%{opacity:.9}}
 @keyframes fy-spin{to{transform:rotate(360deg)}}
 @keyframes fy-opulse{0%,100%{transform:scale(1);opacity:1}50%{transform:scale(1.06);opacity:.85}}
+@keyframes fy-voice{0%{transform:scale(0.6);opacity:.7}100%{transform:scale(1.35);opacity:0}}
 .fyodos-overlay{position:fixed;inset:0;display:flex;align-items:center;justify-content:center;padding:24px;background:rgba(4,6,12,0.6);}
 .fyodos-modal{width:min(420px,100%);border-radius:16px;padding:22px 24px;box-shadow:0 24px 60px rgba(0,0,0,0.5);}
 .fyodos-modal h3{margin:0 0 10px;font-size:17px;font-weight:600;}

package/dist/esm/orb/orbView.js

@@ -210,6 +210,52 @@ function buildThinkingSpinner(orbSizePx, color) {
     wrap.appendChild(spin);
     return wrap;
 }
+// ── Speaking pulse (port of the dashboard's no-logo "speaking" state) ─────────
+// Two expanding rings + a pulsing centre dot — the default "talking" drawing the
+// dashboard orb editor shows when there is no custom photo. Ratios are taken
+// from the editor (118 / 30 / 2 px on its 380px reference orb) so the embedded
+// orb matches it at any size.
+const SPEAK_RING_RATIO = 118 / 380;
+const SPEAK_DOT_RATIO = 30 / 380;
+const SPEAK_BORDER_RATIO = 2 / 380;
+function buildSpeakingPulse(orbSize, color) {
+    const wrap = document.createElement('div');
+    Object.assign(wrap.style, {
+        position: 'absolute',
+        inset: '0',
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        pointerEvents: 'none',
+    });
+    const ringPx = orbSize * SPEAK_RING_RATIO;
+    const borderPx = Math.max(1, orbSize * SPEAK_BORDER_RATIO);
+    for (const delay of [0, 0.85]) {
+        const ring = document.createElement('div');
+        Object.assign(ring.style, {
+            position: 'absolute',
+            width: `${ringPx}px`,
+            height: `${ringPx}px`,
+            borderRadius: '50%',
+            border: `${borderPx}px solid ${color}`,
+            opacity: '0.55',
+            animation: `fy-voice 1.7s ease-out infinite ${delay}s`,
+        });
+        wrap.appendChild(ring);
+    }
+    const dotPx = orbSize * SPEAK_DOT_RATIO;
+    const dot = document.createElement('div');
+    Object.assign(dot.style, {
+        width: `${dotPx}px`,
+        height: `${dotPx}px`,
+        borderRadius: '50%',
+        background: color,
+        opacity: '0.9',
+        animation: 'fy-opulse 1s ease-in-out infinite',
+    });
+    wrap.appendChild(dot);
+    return wrap;
+}
 // ── Keyboard chip icon (port of ChipIconSvg) ──────────────────────────────────
 function buildChipIcon(icon, size, color) {
     const spec = chipIconSpec(icon);
@@ -364,7 +410,10 @@ export function createOrbVisual(initial) {
         waveform?.stop();
         waveform = null;
         fillEl.replaceChildren();
-        wrapper.style.animation = state === 'speaking' ? 'fy-opulse 1.1s ease-in-out infinite' : '';
+        // The "speaking" feedback now lives INSIDE the fill (a pulsing logo, or the
+        // rings + dot when there's no photo) to mirror the dashboard editor, so the
+        // orb no longer pulses as a whole.
+        wrapper.style.animation = '';
         if (state === 'thinking') {
             fillEl.appendChild(buildThinkingSpinner(size, waveColor));
             return;
@@ -392,10 +441,17 @@ export function createOrbVisual(initial) {
                 userSelect: 'none',
                 webkitUserSelect: 'none',
                 webkitUserDrag: 'none',
+                // While speaking, the photo gently pulses (matches the dashboard).
+                animation: state === 'speaking' ? 'fy-opulse 1s ease-in-out infinite' : '',
             });
             fillEl.appendChild(img);
             return;
         }
+        if (state === 'speaking') {
+            // No photo → the default "talking" drawing (expanding rings + centre dot).
+            fillEl.appendChild(buildSpeakingPulse(size, waveColor));
+            return;
+        }
         if (state === 'idle') {
             fillEl.appendChild(buildOrbMark(size));
         }

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.3";
+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.3';
+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.4",
+  "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": {
@@ -25,7 +25,8 @@
   "scripts": {
     "build": "tsc -p tsconfig.cjs.json && tsc -p tsconfig.esm.json && node ../../scripts/fix-esm-extensions.mjs dist/esm && node ../../scripts/mark-dual.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "node --import tsx --test test/*.test.ts"
+    "test": "node --import tsx --test test/*.test.ts",
+    "prepublishOnly": "node ../../scripts/sync-sdk-version.mjs && npm run build"
   },
   "dependencies": {
     "@fiodos/core": "^0.1.0"