@fiodos/web-core 0.1.14 → 0.1.17

package/dist/esm/api/backendClient.d.ts

@@ -6,7 +6,7 @@
  * way. The only platform dependency is `fetch` + `AbortController` (native in
  * the browser). No client source code is ever sent — only the manifest payload.
  */
-import { type AgentBackendClient, type AppManifest } from '@fiodos/core';
+import { type ActionRegistries, type AgentBackendClient, type AppManifest } from '@fiodos/core';
 export interface FiodosBackendClientOptions {
     baseUrl: string;
     /** Client API key sent as x-api-key. */
@@ -19,8 +19,15 @@ export interface FiodosBackendClientOptions {
     ttsTimeoutMs?: number;
 }
 export declare function createFiodosBackendClient(options: FiodosBackendClientOptions): AgentBackendClient;
-/** Serializes the manifest payloads for a turn request (used by AgentController). */
-export declare function buildManifestPayload(manifest: AppManifest): {
+/**
+ * Serializes the manifest payloads for a turn request (used by AgentController).
+ *
+ * When the live registries are provided, actions with no registered handler
+ * are dropped from the payload (runtime "wired or nonexistent"): the LLM never
+ * hears about an action this mounted app cannot execute, so it can never
+ * promise it. Fail-open without registries.
+ */
+export declare function buildManifestPayload(manifest: AppManifest, registries?: ActionRegistries | null): {
     appFlow?: string | undefined;
     appType?: string | undefined;
     manifestVersion: string;

package/dist/esm/api/backendClient.js

@@ -6,7 +6,7 @@
  * way. The only platform dependency is `fetch` + `AbortController` (native in
  * the browser). No client source code is ever sent — only the manifest payload.
  */
-import { manifestActionsForBackend, manifestRoutesForBackend, parseAgentAction, } from '@fiodos/core';
+import { manifestActionsForBackend, manifestRoutesForBackend, parseAgentAction, withExecutableActions, } from '@fiodos/core';
 import { AgentApiError } from './errors.js';
 const DEFAULT_TURN_TIMEOUT_MS = 15000;
 const DEFAULT_TTS_TIMEOUT_MS = 12000;
@@ -141,6 +141,10 @@ export function createFiodosBackendClient(options) {
                         intent: request.lastStep.intent,
                         ...(request.lastStep.label ? { label: request.lastStep.label } : {}),
                         success: request.lastStep.success,
+                        // Bounded result payload of the executed step (product search
+                        // results…): the backend renders it so the model can read real
+                        // ids for the NEXT step's parameters.
+                        ...(request.lastStep.data ? { data: request.lastStep.data } : {}),
                     };
                 }
             }
@@ -198,15 +202,23 @@ export function createFiodosBackendClient(options) {
         },
     };
 }
-/** Serializes the manifest payloads for a turn request (used by AgentController). */
-export function buildManifestPayload(manifest) {
+/**
+ * Serializes the manifest payloads for a turn request (used by AgentController).
+ *
+ * When the live registries are provided, actions with no registered handler
+ * are dropped from the payload (runtime "wired or nonexistent"): the LLM never
+ * hears about an action this mounted app cannot execute, so it can never
+ * promise it. Fail-open without registries.
+ */
+export function buildManifestPayload(manifest, registries) {
+    const effective = withExecutableActions(manifest, registries);
     return {
-        manifestVersion: manifest.version,
-        manifestRoutes: manifestRoutesForBackend(manifest),
-        manifestActions: manifestActionsForBackend(manifest),
-        appName: manifest.appName,
-        appDescription: manifest.appDescription,
-        ...(manifest.appType ? { appType: manifest.appType } : {}),
-        ...(manifest.appFlow ? { appFlow: manifest.appFlow } : {}),
+        manifestVersion: effective.version,
+        manifestRoutes: manifestRoutesForBackend(effective),
+        manifestActions: manifestActionsForBackend(effective),
+        appName: effective.appName,
+        appDescription: effective.appDescription,
+        ...(effective.appType ? { appType: effective.appType } : {}),
+        ...(effective.appFlow ? { appFlow: effective.appFlow } : {}),
     };
 }

package/dist/esm/config/types.d.ts

@@ -44,6 +44,13 @@ export interface FiodosWebAgentConfig {
     manifest: AppManifest;
     /** Agent locale (reply language, message catalogs). MANDATORY. */
     locale: string;
+    /**
+     * LIVE locale resolver. When set, the orb re-reads it periodically so the
+     * thought bubble follows the app's ACTIVE language (host language switcher,
+     * `<html lang>`, i18n runtime) without remounting. Falls back to `locale`
+     * whenever it returns nothing.
+     */
+    getLocale?: () => string | null | undefined;
     /** Speech recognition locale, e.g. 'en-US', 'es-ES'. MANDATORY. */
     sttLocale: string;
     /** Device-TTS fallback locale. Defaults to sttLocale. */

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, buildBubbleExchangeWindow, BUBBLE_PAGE_EXCHANGES, clearPersistedConversation, conversationIdentityKey, conversationRetentionOptions, createConversationSession, persistConversationSession, restoreConversationSession, defaultRouteContextText, formatMessage, prepareConversationForTurn, recordConversationExchange, resolveConfirmationLexicon, resolveMessages, validateManifest, } from '@fiodos/core';
+import { combineContexts, createActionExecutor, createConsentManager, createSafeTelemetry, createSanitizer, buildBubbleExchangeWindow, BUBBLE_PAGE_EXCHANGES, clearPersistedConversation, conversationIdentityKey, conversationRetentionOptions, createConversationSession, persistConversationSession, restoreConversationSession, defaultRouteContextText, formatMessage, prepareConversationForTurn, recordConversationExchange, resolveConfirmationLexicon, resolveMessages, trimChainStepData, validateManifest, } from '@fiodos/core';
 import { createWebCredentialAutofillAdapter } from '../adapters/webCredentialAutofillAdapter.js';
 import { AgentApiError } from '../api/errors.js';
 import { formatAgentTurnError } from '../api/formatTurnError.js';
@@ -713,9 +713,22 @@ export class AgentController {
                 /* keep the assistant's guiding reply; never speak a refusal. */
             }
             else if (r.message) {
+                // FEEDBACK GUARANTEE: the handler's outcome message (success,
+                // idempotent or failure) is the ground truth that the action ran;
+                // speak it instead of the LLM's optimistic reply.
                 outReply = r.message;
                 outAudio = null;
             }
+            else if (!r.success) {
+                // Same guarantee for a handler that failed WITHOUT setting `message`
+                // (e.g. a declarative Shopify/OData `execution` call that hit a
+                // network/HTTP/template error — apiActions.ts never throws, so
+                // runManifestAction's catch never runs either). Without this, the
+                // LLM's pre-action narration ("Adding X to your cart…") stays on
+                // screen as if it had happened — a silent false success.
+                outReply = this.messages.actionFailed;
+                outAudio = null;
+            }
             // Chain signal: only a cleanly EXECUTED, non-recoverable step may advance,
             // and only when the backend asked to continue (task_status=in_progress).
             if (turn.action &&
@@ -723,11 +736,16 @@ export class AgentController {
                 r.success &&
                 !r.recoverable) {
                 const intent = turn.action.intent ?? '';
+                // Feed the step's RESULT DATA back to the next chain turn (bounded):
+                // it is how the model reads real technical values (variant ids, line
+                // numbers) out of a data action instead of inventing them.
+                const chainData = trimChainStepData(r.data);
                 lastStep = {
                     type: turn.action.type,
                     intent,
                     label: turn.action.type === 'navigate' ? this.routeLabel(intent) : this.actionLabel(intent),
                     success: true,
+                    ...(chainData ? { data: chainData } : {}),
                 };
                 actionKey = `${turn.action.type}:${intent}`;
                 canContinue = turn.taskStatus === 'in_progress';
@@ -827,7 +845,7 @@ export class AgentController {
                         lastStep,
                         platformCapabilities: this.platformCapabilities(),
                         sessionContext: this.sessionContext(),
-                        ...buildManifestPayload(this.config.manifest),
+                        ...buildManifestPayload(this.config.manifest, this.config.registries),
                     }, { signal: controller.signal });
                     oc = await this.applyOutcome(turn, routeNow, snap?.context ?? {}, state.userMessage);
                 }
@@ -986,7 +1004,7 @@ export class AgentController {
                 sessionId: this.sessionId,
                 platformCapabilities: this.platformCapabilities(),
                 sessionContext: this.sessionContext(),
-                ...buildManifestPayload(this.config.manifest),
+                ...buildManifestPayload(this.config.manifest, this.config.registries),
             }, { signal: controller.signal });
             outcome = await this.applyOutcome(turn, currentRoute, snapshot?.context ?? {}, text);
         }

package/dist/esm/dropin/createFiodosAgent.js

@@ -29,6 +29,11 @@ function browserLocale() {
     const lang = typeof navigator !== 'undefined' && navigator.language ? navigator.language : 'en-US';
     return { locale: lang.split('-')[0] || 'en', sttLocale: lang };
 }
+function documentLocale() {
+    return typeof document !== 'undefined'
+        ? document.documentElement.lang?.split(/[-_]/)[0]?.trim() || ''
+        : '';
+}
 function resolveAgentLocale(options) {
     const fromApp = options.getLocale?.()?.trim();
     if (fromApp)
@@ -38,12 +43,16 @@ function resolveAgentLocale(options) {
     if (options.localeDetection === 'browser')
         return browserLocale().locale;
     if (options.localeDetection === 'document') {
-        const docLang = typeof document !== 'undefined'
-            ? document.documentElement.lang?.split(/[-_]/)[0]?.trim()
-            : '';
+        const docLang = documentLocale();
         if (docLang)
             return docLang;
     }
+    // Default (nothing configured): follow the HOST PAGE's language when the
+    // page declares one (<html lang>), so the orb bubble speaks the language the
+    // end user is actually browsing in. English only as the last resort.
+    const docLang = documentLocale();
+    if (docLang)
+        return docLang;
     return 'en';
 }
 /** Build the controller + adapters from a known manifest (shared by both paths). */
@@ -64,6 +73,10 @@ function assemble(options, manifest, baseUrl) {
     const config = {
         manifest,
         locale,
+        // Live resolver: re-runs the same resolution chain (app getLocale → static
+        // locale → detection) on every read, so the bubble follows the host app's
+        // language switcher / <html lang> without remounting the agent.
+        getLocale: () => resolveAgentLocale(options),
         sttLocale,
         navigation: createWebNavigationAdapter({
             navigate: options.navigate ?? defaultNavigate,

package/dist/esm/embed/global.d.ts

@@ -27,7 +27,7 @@ import { createScreenContextStore } from '../context/screenContextStore.js';
 import { connectDynamicsFormContext, dynamicsFormSnapshot, normalizeDynamicsId } from './dynamics.js';
 import { buildApiActionRegistries, validateManifest } from '@fiodos/core';
 declare const api: {
-    readonly version: "0.1.14";
+    readonly version: "0.1.17";
     readonly createFiodosAgent: typeof createFiodosAgent;
     readonly mountOrb: typeof mountOrb;
     readonly AgentController: typeof AgentController;

package/dist/esm/orb/mountOrb.js

@@ -210,12 +210,13 @@ export function mountOrb(controller, options = {}) {
             const prompt = resolveCurrentBubblePrompt();
             openTextPanel(prompt
                 ? bubblePromptToAffirmative(prompt, {
-                    locale: controller.config.locale,
+                    locale: currentBubbleLocale(),
                     messages: controller.messages,
                 })
                 : undefined);
             return;
         }
+        userTriedVoice = true;
         void controller.toggleListening();
     });
     thoughtBubbleEl.addEventListener('keydown', (event) => {
@@ -394,6 +395,13 @@ export function mountOrb(controller, options = {}) {
     // SAME "active/listening" visual state and reveals the keyboard chip — the
     // user is never blocked, text is always an open avenue (Change 1).
     let micFallbackActive = false;
+    // True once the user actually ATTEMPTED voice (tapped the orb/bubble to
+    // listen). The voiceBlocked→keyboard fallback in render() must only fire for
+    // a mic that failed MID-ATTEMPT: the upfront Permissions-API detection also
+    // sets voiceBlocked at mount (e.g. the site has the mic permission denied),
+    // and without this guard the conversation panel would pop open on page load
+    // with zero interaction.
+    let userTriedVoice = false;
     const bubble = document.createElement('div');
     bubble.className = 'fyodos-bubble';
     bubble.style.display = 'none';
@@ -462,6 +470,12 @@ export function mountOrb(controller, options = {}) {
             signature.endsWith(renderedSignature);
         const fromBottom = exchangeScroll.scrollHeight - exchangeScroll.scrollTop;
         renderedSignature = signature;
+        // Theme colors INLINE at node creation: the embed lives inside arbitrary
+        // host pages (e.g. Shopify themes) whose CSS sets `color` on everything,
+        // so a freshly-rendered message must never wait for the next
+        // applyBubbleTheme() pass to become readable (it would inherit the host's
+        // ink — black on our dark panel — until the next config poll).
+        const t = { ...DEFAULT_MODAL_THEME, ...(modalTheme ?? {}) };
         exchangeList.replaceChildren();
         for (const ex of exchanges) {
             const block = document.createElement('div');
@@ -469,11 +483,13 @@ export function mountOrb(controller, options = {}) {
             const user = document.createElement('div');
             user.className = 'fyodos-bubble-user';
             user.textContent = ex.userText;
+            user.style.color = t.bodyColor;
             block.append(user);
             if (ex.replyText) {
                 const reply = document.createElement('div');
                 reply.className = 'fyodos-bubble-reply';
                 reply.textContent = ex.replyText;
+                reply.style.color = t.titleColor;
                 block.append(reply);
             }
             exchangeList.append(block);
@@ -580,7 +596,8 @@ export function mountOrb(controller, options = {}) {
         if (active) {
             micBtn.style.background = accent;
             micBtn.style.border = 'none';
-            micBtn.style.color = '#000';
+            // Ink readable on the (customizable) accent — dark accents need light ink.
+            micBtn.style.color = fiodosInputInkColor(accent);
             micBtn.style.borderRadius = sendRadius;
         }
         else {
@@ -679,6 +696,9 @@ export function mountOrb(controller, options = {}) {
         textInput.style.color = fiodosInputInkColor(inputBg);
         textInput.style.setProperty('--fyodos-input-placeholder', fiodosInputMutedInkColor(inputBg));
         sendBtn.style.background = accent;
+        // The glyph (↑ / ◼) must stay readable on ANY published accent: dark ink
+        // on light accents, light ink on dark ones (never the hardcoded black).
+        sendBtn.style.color = fiodosInputInkColor(accent);
         sendBtn.style.borderRadius = `${modalTheme?.sendButtonRadius ?? 10}px`;
         syncMicButton();
         busyRow.querySelectorAll('span').forEach((s) => {
@@ -687,13 +707,44 @@ export function mountOrb(controller, options = {}) {
         // Live-activity line: white (reply color), italic — not the faint gray.
         busyStep.style.color = t.titleColor;
     }
+    // The panel's open state survives FULL PAGE LOADS within the tab session:
+    // on multi-page hosts (Shopify storefronts…) every agent navigation reloads
+    // the document, and without this the conversation panel closed mid-dialogue
+    // on every step. sessionStorage is per-tab and cleared when the tab closes,
+    // so a fresh visit never starts with the panel open.
+    const panelOpenKey = `fyodos:panel-open:${controller.config.manifest.appId}`;
+    function persistPanelOpen(open) {
+        try {
+            if (open)
+                window.sessionStorage.setItem(panelOpenKey, '1');
+            else
+                window.sessionStorage.removeItem(panelOpenKey);
+        }
+        catch {
+            /* storage unavailable (private mode) — persistence is best-effort */
+        }
+    }
+    function wasPanelOpen() {
+        try {
+            return window.sessionStorage.getItem(panelOpenKey) === '1';
+        }
+        catch {
+            return false;
+        }
+    }
     function setBubble(open) {
         bubbleOpen = open;
         bubble.style.display = open ? 'flex' : 'none';
+        persistPanelOpen(open);
         if (open) {
             applyBubbleTheme();
             positionBubble();
             textInput.focus();
+            // Paint the CURRENT conversation immediately: exchanges are only
+            // rendered inside render() while the panel is open, so without this
+            // the restored history stayed invisible (an apparently stuck panel)
+            // until the next controller event — i.e. until the user typed.
+            render(controller.getState());
         }
         else {
             bubbleDictation.stop();
@@ -707,6 +758,13 @@ export function mountOrb(controller, options = {}) {
             setBubbleExpanded(false);
         }
         syncChip(controller.getState());
+        // Re-resolve the thought bubble NOW: closing the panel must bring the
+        // screen-aware CTA back immediately. Nothing else is guaranteed to run
+        // right after close (controller state does not change on close, the route
+        // poll only fires on changes, the config poll every ~12s) — without this
+        // the orb sat "naked" until some unrelated event. Opening hides it (the
+        // resolver returns null while the panel is open), so one call covers both.
+        syncThoughtBubble(controller.getState());
     }
     function submitText() {
         // While a turn is in flight the button is a STOP button; never start a new
@@ -771,8 +829,22 @@ export function mountOrb(controller, options = {}) {
         applyDeployment();
     }
     // ── Thought bubble (screen-aware CTA beside the orb) ─────────────────────────
+    // LIVE locale: re-read the host app's active language on every resolution so
+    // the bubble text (analyzer `bubblePrompts` translations) follows the app's
+    // language switcher without remounting. Falls back to the mount-time locale.
+    function currentBubbleLocale() {
+        try {
+            const live = controller.config.getLocale?.();
+            if (typeof live === 'string' && live.trim())
+                return live.trim();
+        }
+        catch {
+            /* live locale read is best-effort */
+        }
+        return controller.config.locale;
+    }
     function resolveCurrentBubblePrompt() {
-        return resolveBubblePrompt(matchRouteIntent(currentRoute, controller.config.manifest.routes), controller.messages, { locale: controller.config.locale, actions: controller.config.manifest.actions });
+        return resolveBubblePrompt(matchRouteIntent(currentRoute, controller.config.manifest.routes), controller.messages, { locale: currentBubbleLocale(), actions: controller.config.manifest.actions });
     }
     // Render the CTA on ONE line at its NATURAL size. When the phrase is too long
     // to fit the max width, scroll it (marquee, right-to-left, looping) instead of
@@ -987,6 +1059,7 @@ export function mountOrb(controller, options = {}) {
         // denied/blocked, in which case we skip voice and go straight to the keyboard.
         if (controller.voiceAvailable && voiceInputEnabled) {
             micFallbackActive = false;
+            userTriedVoice = true;
             void controller.toggleListening();
             return;
         }
@@ -998,6 +1071,7 @@ export function mountOrb(controller, options = {}) {
             openTextPanel();
             return;
         }
+        userTriedVoice = true;
         void controller.toggleListening();
     };
     sendBtn.onclick = () => {
@@ -1036,11 +1110,15 @@ export function mountOrb(controller, options = {}) {
     // Track phase transitions to fire haptics: start/stop listening + response.
     let lastPhase = null;
     function render(state) {
-        // Mic just became unusable mid-attempt (no Permissions API): fall back to the
-        // keyboard so the user always has a working channel.
+        // Mic just became unusable MID-ATTEMPT (no Permissions API): fall back to
+        // the keyboard so the user always has a working channel. Guarded by
+        // userTriedVoice: the upfront permission detection also sets voiceBlocked
+        // right at mount (site-level mic denial), and that must NEVER auto-open
+        // the conversation panel on page load — the user did nothing yet; their
+        // first orb tap will route to the keyboard via the voiceAvailable check.
         if (state.voiceBlocked && !lastVoiceBlocked) {
             lastVoiceBlocked = true;
-            if (enableTextInput && !bubbleOpen && !state.isBusy) {
+            if (userTriedVoice && enableTextInput && !bubbleOpen && !state.isBusy) {
                 openTextPanel();
                 return;
             }
@@ -1109,9 +1187,18 @@ export function mountOrb(controller, options = {}) {
     }
     const unsubscribe = controller.subscribe(render);
     render(controller.getState());
-    // Track the current route so the thought bubble re-resolves its CTA on
-    // navigation. No universal navigation event exists, so poll + listen to
-    // popstate / visibility for snappier updates.
+    // Re-open the conversation panel after a full page load when it was open
+    // before (MPA hosts reload on every navigation): the dialogue visually
+    // continues where it was — the persisted conversation restores async in the
+    // controller and repaints via emit → render once loaded.
+    if (enableTextInput && wasPanelOpen()) {
+        setBubble(true);
+    }
+    // Track the current route AND the app's live locale so the thought bubble
+    // re-resolves its CTA on navigation and on language switches. No universal
+    // navigation/i18n event exists, so poll + listen to popstate / visibility
+    // for snappier updates.
+    let lastBubbleLocale = currentBubbleLocale();
     const readRoute = () => {
         let next = null;
         try {
@@ -1120,8 +1207,10 @@ export function mountOrb(controller, options = {}) {
         catch {
             /* navigation read is best-effort */
         }
-        if (next !== currentRoute) {
+        const nextLocale = currentBubbleLocale();
+        if (next !== currentRoute || nextLocale !== lastBubbleLocale) {
             currentRoute = next;
+            lastBubbleLocale = nextLocale;
             syncThoughtBubble(controller.getState());
         }
     };

package/dist/esm/orb/orbView.js

@@ -74,13 +74,14 @@ function buildDoubleBorder(opts) {
     return { root, fill };
 }
 /**
- * Neutral Fiodos brand mark (idle, no logo). Breathes very gently on web — a
+ * Fiodos brand mark (idle, no logo). Breathes very gently on web — a
  * direct port of the landing hero orbs' waveform easing (see
  * `fiodosOrbMarkIdleHalfHeight` in @fiodos/core) — deliberately subtler than
  * and distinct from the volume-reactive waveform shown while listening.
+ * Tinted with the same "audio color" (waveformColor) as that waveform.
  */
-function buildOrbMark(orbSize) {
-    const { bars, color, radius } = resolveFiodosOrbMarkAnimatedBars(orbSize);
+function buildOrbMark(orbSize, markColor) {
+    const { bars, color, radius } = resolveFiodosOrbMarkAnimatedBars(orbSize, markColor);
     const svg = svgEl('svg', {
         width: orbSize,
         height: orbSize,
@@ -484,7 +485,7 @@ export function createOrbVisual(initial) {
             return;
         }
         if (state === 'idle') {
-            markAnim = buildOrbMark(size);
+            markAnim = buildOrbMark(size, appearance.waveformColor);
             fillEl.appendChild(markAnim.el);
             markAnim.start();
         }

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.14";
+export declare const SDK_VERSION = "0.1.17";
 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.14';
+export const SDK_VERSION = '0.1.17';
 export const SDK_PACKAGE = '@fiodos/web-core';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fiodos/web-core",
-  "version": "0.1.14",
+  "version": "0.1.17",
   "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": {