@appilots/web-sdk 0.2.0 → 0.3.0

package/README.md

@@ -115,6 +115,25 @@ messages when reading older replies.
 they never send automatically. Markdown supports headings, lists, bold, italic,
 inline/fenced code and HTTP(S) links. HTML is rendered as text.
 
+### Voice dictation (opt-in)
+
+```tsx
+<AppilotsChatFab locale="pt-BR" speech="browser" />
+```
+
+`speech="browser"` adds a mic button that uses the Web Speech API. The button
+is hidden where the browser has no speech recognition (Firefox, many WebViews).
+It is a toggle (`aria-pressed`), so it works with a keyboard or a switch device
+and nobody has to hold it down. The recognised text fills the composer as the
+user speaks, can be edited, and is never sent automatically. Escape discards the
+dictation. A status region announces when listening starts and stops.
+
+**In Chrome and Edge the audio is sent to the browser vendor's speech service**,
+so it leaves the device. To use an engine you control, pass your own `SpeechHost`
+instead (`speech={host}`). See the
+[Voice Input guide](https://docs.appilots.com/docs/guides/voice-input) for the
+contract and the LGPD notes.
+
 “Talk to a person” uses the existing escalation API: waiting/connected status,
 operator replies, and user messages all stay in the same transcript. The API
 and an operator in the dashboard must be available for a person to answer.

package/dist/{chunk-T5TUFZ6T.js → chunk-H4ITA2QP.js}

@@ -4511,18 +4511,27 @@ var WRITE_SUCCESS = {
     "a\\s+[e\xE9]t[e\xE9]\\s+(?:enregistr|cr[e\xE9]|ajout|sauvegard)[e\xE9]e?"
   ]
 };
+var SENTENCE_START = "(?:^|[.!?:;*\\n]\\s*)";
 var COMPLETION_CLAIM = {
   pt: [
     "j[a\xE1]\\s+(?:cadastrei|registrei|salvei|criei)",
     "conclu[i\xED]\\s+o\\s+cadastro",
-    "cadastro\\s+(?:foi\\s+)?(?:conclu[i\xED]do|realizado|feito)"
+    "cadastro\\s+(?:foi\\s+)?(?:conclu[i\xED]do|realizado|feito)",
+    `${SENTENCE_START}(?:eu\\s+)?(?:cadastrei|registrei|salvei|criei|adicionei|enviei)\\b`
   ],
   en: [
     "i(?:'|\u2019)?ve\\s+(?:registered|saved|created|added)",
-    "i\\s+have\\s+(?:registered|saved|created|added)"
+    "i\\s+have\\s+(?:registered|saved|created|added)",
+    `${SENTENCE_START}i\\s+(?:registered|saved|created|added|submitted)\\b`
   ],
-  es: ["ya\\s+(?:lo\\s+|la\\s+)?(?:registr[e\xE9]|guard[e\xE9]|cre[e\xE9])"],
-  fr: ["j(?:e\\s+l(?:'|\u2019)ai|(?:'|\u2019)ai)\\s+(?:enregistr|cr[e\xE9]|ajout|sauvegard)[e\xE9]"]
+  es: [
+    "ya\\s+(?:lo\\s+|la\\s+)?(?:registr[e\xE9]|guard[e\xE9]|cre[e\xE9])",
+    `${SENTENCE_START}(?:ya\\s+)?he\\s+(?:registrado|guardado|creado|enviado|a[\xF1n]adido)\\b`
+  ],
+  fr: [
+    "j(?:e\\s+l(?:'|\u2019)ai|(?:'|\u2019)ai)\\s+(?:enregistr|cr[e\xE9]|ajout|sauvegard)[e\xE9]",
+    `${SENTENCE_START}c(?:'|\u2019)est\\s+(?:enregistr|cr[e\xE9]|ajout|sauvegard)[e\xE9]`
+  ]
 };
 var SUBMIT_CONTROL = {
   pt: ["cadastrar", "registrar", "salvar", "enviar", "confirmar"],
@@ -4640,6 +4649,7 @@ var AppilotsClient = class {
   mcpVersion;
   introspectionReporter;
   user;
+  plainLanguage;
   sessionId = null;
   mission = null;
   missionDispatchPaused = false;
@@ -4658,6 +4668,7 @@ var AppilotsClient = class {
     this.mcpVersion = options.mcpVersion;
     this.introspectionReporter = options.introspectionReporter;
     this.user = options.user;
+    this.plainLanguage = options.plainLanguage;
     this.headers = {
       "Content-Type": "application/json",
       // Version telemetry: lets the server correlate behavior per SDK
@@ -4807,6 +4818,19 @@ var AppilotsClient = class {
       return {};
     }
   }
+  /**
+   * Per-session plain-language override — e.g. from the signed-in user's
+   * accessibility profile. `undefined` hands the decision back to the
+   * project setting. Applies from the next request on.
+   */
+  setPlainLanguage(value) {
+    this.plainLanguage = value;
+  }
+  /** Every relay-bound context carries the reply-style preference. */
+  withPreferences(context) {
+    if (this.plainLanguage === void 0) return context;
+    return { ...context ?? {}, plainLanguage: this.plainLanguage };
+  }
   // ── Messages ──────────────────────────────────────────────────
   async sendMessage(content, context) {
     if (this.sessionStorage && !this.sessionId) await this.loadStoredSession();
@@ -4820,7 +4844,7 @@ var AppilotsClient = class {
       body: JSON.stringify({
         content,
         sessionId: this.sessionId,
-        context,
+        context: this.withPreferences(context),
         // Optional MCP version bundled with this app build. Server
         // compares vs the active MCP doc to detect stale uploads.
         ...this.mcpVersion ? { mcpVersion: this.mcpVersion } : {},
@@ -5085,7 +5109,7 @@ var AppilotsClient = class {
         JSON.stringify({
           content,
           sessionId: this.sessionId,
-          context,
+          context: this.withPreferences(context),
           ...this.mcpVersion ? { mcpVersion: this.mcpVersion } : {},
           ...this.introspectionFragment()
         })
@@ -5104,7 +5128,9 @@ var AppilotsClient = class {
         body: JSON.stringify({
           sessionId: this.sessionId,
           results,
-          context: this.mission ? { ...context, missionProtocol: 1, missionId: this.mission.scope.id } : context,
+          context: this.withPreferences(
+            this.mission ? { ...context, missionProtocol: 1, missionId: this.mission.scope.id } : context
+          ),
           hop
         })
       },
@@ -5192,7 +5218,7 @@ var AppilotsClient = class {
       body: JSON.stringify({
         command,
         missionId: this.mission.scope.id,
-        context
+        context: this.withPreferences(context)
       })
     });
     if (command === "resume") this.missionDispatchPaused = false;
@@ -5579,6 +5605,11 @@ var AppilotsClient = class {
     };
   }
 };
+function isSpeechHost(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return typeof candidate.start === "function" && typeof candidate.stop === "function" && typeof candidate.cancel === "function";
+}
 var DESTRUCTIVE_LABEL_RE = /\b(cancelar?\w*|cancel(?:ar|led|ation|amento)?|delete\w*|exclu\w*|delet\w*|remov\w*|remove|apag\w*|destroy\w*|unsubscribe\w*)\b/i;
 function looksDestructiveActionLabel(value) {
   if (typeof value !== "string" || !value.trim()) return false;
@@ -6720,6 +6751,10 @@ function actionHasCompletedConfirmGate(action, actions) {
     return payload.destructive === true || payload.severity === "danger";
   });
 }
+function confirmExpiresAt(confirm) {
+  const scope = readPayload(confirm).missionApproval;
+  return typeof scope?.expiresAt === "number" ? scope.expiresAt : void 0;
+}
 var ActionQueueMachine = class {
   deps;
   options;
@@ -7225,6 +7260,20 @@ var ActionQueueMachine = class {
     return this.state.actions.filter((a) => a.status === "completed" || a.status === "failed");
   }
 };
+var STILL_WORKING_FIRST_MS = 1e4;
+var STILL_WORKING_EVERY_MS = 2e4;
+function startStillWorkingTimer(onTick) {
+  let elapsedMs = STILL_WORKING_FIRST_MS;
+  let timer = setTimeout(function tick() {
+    onTick(Math.round(elapsedMs / 1e3));
+    elapsedMs += STILL_WORKING_EVERY_MS;
+    timer = setTimeout(tick, STILL_WORKING_EVERY_MS);
+  }, STILL_WORKING_FIRST_MS);
+  return () => clearTimeout(timer);
+}
+function normalize3(s) {
+  return s.toLowerCase().normalize("NFD").replace(/[\u0300-\u036f]/g, "").replace(/[^a-z0-9]/g, "");
+}
 function matchScore(needle, hay) {
   if (!needle || !hay) return 0;
   if (needle === hay) return 100;
@@ -7925,7 +7974,7 @@ function parseInlineMarkdown(text) {
 }
 
 // src/version.ts
-var SDK_VERSION2 = "0.2.0";
+var SDK_VERSION2 = "0.3.0";
 
 // src/introspection/locators.ts
 var APPILOTS_ID_ATTR = "data-appilots-id";
@@ -9320,7 +9369,9 @@ function stripComponentPrefix(componentId) {
     /^(?:button|btn|switch|toggle|slider|input|field|link)[-_](.+)$/i
   );
   if (kebab?.[1]) return kebab[1];
-  const camel = componentId.match(/^(?:button|btn|switch|toggle|slider|input|field|link)([A-Z].*)$/);
+  const camel = componentId.match(
+    /^(?:button|btn|switch|toggle|slider|input|field|link)([A-Z].*)$/
+  );
   if (camel?.[1]) return camel[1].charAt(0).toLowerCase() + camel[1].slice(1);
   return null;
 }
@@ -9348,7 +9399,8 @@ function matchesKind(el, kind) {
     return !["checkbox", "radio", "button", "submit", "reset", "image"].includes(type);
   }
   if (kind === "toggle") {
-    if (tag === "input" && (el.getAttribute("type") ?? "").toLowerCase() === "checkbox") return true;
+    if (tag === "input" && (el.getAttribute("type") ?? "").toLowerCase() === "checkbox")
+      return true;
     const role2 = (el.getAttribute("role") ?? "").toLowerCase();
     return role2 === "switch" || role2 === "checkbox";
   }
@@ -9367,7 +9419,9 @@ function findListItemElements(listIndex, options = {}) {
   const root = rootOf(options);
   if (typeof root.querySelectorAll !== "function") return void 0;
   const containers = Array.from(
-    root.querySelectorAll(`[${APPILOTS_LIST_ID_ATTR}], ul, ol, table, [role="list"], [role="listbox"], [role="grid"]`)
+    root.querySelectorAll(
+      `[${APPILOTS_LIST_ID_ATTR}], ul, ol, table, [role="list"], [role="listbox"], [role="grid"]`
+    )
   ).filter((el) => !hidesSubtree(el));
   const container = containers[listIndex];
   if (!container) return void 0;
@@ -9462,6 +9516,14 @@ function resolveTargetElement(rawId, options = {}) {
       return { element: el, via: "exact-id" };
     }
   }
+  const folded = normalize3(id);
+  if (folded) {
+    for (const el of candidates) {
+      if (idCandidatesFor(el).some((candidate) => normalize3(candidate) === folded)) {
+        return { element: el, via: "exact-id" };
+      }
+    }
+  }
   const stripped = stripComponentPrefix(id);
   if (stripped) {
     const strippedLower = stripped.toLowerCase();
@@ -9476,9 +9538,10 @@ function resolveTargetElement(rawId, options = {}) {
   let best;
   let tied = false;
   for (const el of candidates) {
+    if (isSensitiveField(el, bestId(el), accessibleName(el))) continue;
     let score = 0;
     for (const candidate of idCandidatesFor(el)) {
-      score = Math.max(score, matchScore(id, candidate));
+      score = Math.max(score, matchScore(folded, normalize3(candidate)));
     }
     if (score < MIN_FUZZY_SCORE) continue;
     if (!best || score > best.score) {
@@ -9508,7 +9571,9 @@ function isOccludedByModal(el, options = {}) {
   const root = rootOf(options);
   if (typeof root.querySelectorAll !== "function") return false;
   const modals = Array.from(
-    root.querySelectorAll('[aria-modal="true"], [role="dialog"], [role="alertdialog"], dialog[open]')
+    root.querySelectorAll(
+      '[aria-modal="true"], [role="dialog"], [role="alertdialog"], dialog[open]'
+    )
   ).filter((modal) => !hidesSubtree(modal) && isVisible(modal));
   if (modals.length === 0) return false;
   return !modals.some((modal) => modal === el || modal.contains(el));
@@ -9517,7 +9582,9 @@ function modalCandidateLabels(options = {}, limit = 8) {
   const root = rootOf(options);
   if (typeof root.querySelectorAll !== "function") return [];
   const modal = Array.from(
-    root.querySelectorAll('[aria-modal="true"], [role="dialog"], [role="alertdialog"], dialog[open]')
+    root.querySelectorAll(
+      '[aria-modal="true"], [role="dialog"], [role="alertdialog"], dialog[open]'
+    )
   ).find((candidate) => !hidesSubtree(candidate));
   if (!modal) return [];
   const out = [];
@@ -9552,6 +9619,21 @@ function readVisibleValidation(context) {
   const snapshot = captureSnapshot({ root: rootElement(context) });
   return snapshot.texts.find((text) => FORM_VALIDATION_TEXT_RE2.test(text));
 }
+var SUBMIT_SETTLE_MAX_MS = 6e3;
+function readAlertTexts(context) {
+  const root = rootElement(context) ?? (typeof document !== "undefined" ? document.body : void 0);
+  if (!root) return [];
+  return Array.from(root.querySelectorAll('[role="alert"], [aria-live="assertive"]')).filter((el) => !hidesSubtree(el)).map((el) => (el.textContent ?? "").trim()).filter(Boolean);
+}
+async function waitForSubmitSettle(submit, context) {
+  const busy = () => submit.isConnected && (submit.disabled || submit.getAttribute("aria-disabled") === "true") || captureSnapshot({ root: rootElement(context) }).loading;
+  const started = Date.now();
+  while (busy()) {
+    if (context.signal?.aborted || Date.now() - started >= SUBMIT_SETTLE_MAX_MS) return !busy();
+    await sleep2(100);
+  }
+  return true;
+}
 function rootElement(context) {
   const root = context.root;
   if (!root) return void 0;
@@ -9757,6 +9839,18 @@ async function formFillHandler(payload, context, permissions) {
       setToggleValue(el, value2);
       continue;
     }
+    if (el.tagName.toLowerCase() === "input" && el.type === "file") {
+      failures.push({
+        fieldId: field.fieldId,
+        error: `Field "${field.fieldId}" is a file picker; only the user can attach a file`,
+        diagnose: diagnose(context, "validation", {
+          fieldId: field.fieldId,
+          recoverable: false,
+          requiresUserInput: true
+        })
+      });
+      continue;
+    }
     const value = field.value == null ? "" : String(field.value);
     const written = setControlValue(el, value);
     if (!written) {
@@ -9824,6 +9918,7 @@ async function formFillHandler(payload, context, permissions) {
       context
     );
     if (blocked) return { success: false, ...blocked };
+    const alertsBefore = new Set(readAlertTexts(context));
     clickElement(submit);
     await sleep2(120);
     if (context.signal?.aborted) return { success: false, error: "Session ended" };
@@ -9836,6 +9931,30 @@ async function formFillHandler(payload, context, permissions) {
         effect: "partial"
       };
     }
+    const settled = await waitForSubmitSettle(submit, context);
+    if (context.signal?.aborted) return { success: false, error: "Session ended" };
+    if (!settled) {
+      return {
+        success: false,
+        error: `Submit still in progress after ${SUBMIT_SETTLE_MAX_MS / 1e3}s \u2014 outcome unknown, do not report it as saved`,
+        diagnose: diagnose(context, "screen-timeout", { recoverable: false }),
+        effect: "unknown"
+      };
+    }
+    const lateValidation = readVisibleValidation(context);
+    const rejection = lateValidation ?? readAlertTexts(context).find((text) => !alertsBefore.has(text));
+    if (rejection) {
+      return {
+        success: false,
+        error: `Submit was rejected: ${rejection}`,
+        diagnose: lateValidation ? diagnose(context, "validation", { visibleMessage: rejection, recoverable: true }) : (
+          // Server-side failure (5xx, expired session, timeout): retrying
+          // blindly can double-submit or loop, so hand it to the user.
+          diagnose(context, "unknown", { visibleMessage: rejection, recoverable: false })
+        ),
+        effect: "partial"
+      };
+    }
     return { success: true, effect: "completed" };
   }
   return { success: true, effect: "changed" };
@@ -10154,6 +10273,14 @@ async function withSuppressedConfirm(context, fn) {
 }
 
 // src/runtime/AppilotsWebRuntime.ts
+function browserLocale() {
+  if (typeof navigator === "undefined") return void 0;
+  for (const language of navigator.languages ?? [navigator.language]) {
+    const locale = normalizeAppilotsLocale(language);
+    if (locale) return locale;
+  }
+  return void 0;
+}
 var POST_ACTION_LOADING_MAX_MS = 6e3;
 var AppilotsWebRuntime = class {
   client;
@@ -10179,13 +10306,15 @@ var AppilotsWebRuntime = class {
       apiKey: options.apiKey,
       apiBaseUrl: options.apiBaseUrl,
       debug: options.debug,
+      timeout: options.timeout,
       appVersion: options.appVersion,
       mcpVersion: options.mcpVersion,
       // This package's own version, so the server can tell a web
       // client apart from an RN one by more than the platform field
       // (issue #312).
       sdkVersion: SDK_VERSION2,
-      user: options.user
+      user: options.user,
+      plainLanguage: options.plainLanguage
     });
     this.navigation = new WebNavigationAdapter({
       routes: options.routes,
@@ -10251,6 +10380,8 @@ var AppilotsWebRuntime = class {
   buildContext(extras = {}) {
     if (extras.newMission === true) this.deltaTracker.reset();
     const context = { platform: "web" };
+    const deviceLocale = browserLocale();
+    if (deviceLocale) context.deviceLocale = deviceLocale;
     const screen = this.navigation.getCurrentScreen();
     if (screen) context.currentScreen = screen;
     const navigationState = this.navigation.getNavigationState();
@@ -10381,6 +10512,108 @@ var AppilotsWebRuntime = class {
   }
 };
 
+// src/speech/webSpeechHost.ts
+var MAX_SILENT_RESTARTS = 5;
+function recognitionCtor() {
+  const g = globalThis;
+  return g.SpeechRecognition ?? g.webkitSpeechRecognition ?? null;
+}
+function isWebSpeechSupported() {
+  return recognitionCtor() !== null;
+}
+function createWebSpeechHost() {
+  const Ctor = recognitionCtor();
+  if (!Ctor) return null;
+  let live = null;
+  let committed = "";
+  let current = "";
+  let silentRestarts = 0;
+  let pendingStop = null;
+  const partialListeners = /* @__PURE__ */ new Set();
+  const endListeners = /* @__PURE__ */ new Set();
+  const text = () => `${committed} ${current}`.replace(/\s+/g, " ").trim();
+  const ended = (error) => endListeners.forEach((l) => l(error));
+  const open = (locale) => new Promise((resolve, reject) => {
+    const r = new Ctor();
+    live = r;
+    r.lang = locale;
+    r.continuous = true;
+    r.interimResults = true;
+    let started = false;
+    let failure;
+    r.onstart = () => {
+      started = true;
+      resolve();
+    };
+    r.onresult = ({ results }) => {
+      if (live !== r) return;
+      let next = "";
+      for (let i = 0; i < results.length; i++) next += results[i]?.[0]?.transcript ?? "";
+      current = next;
+      silentRestarts = 0;
+      const t = text();
+      partialListeners.forEach((l) => l(t));
+    };
+    r.onerror = ({ error }) => {
+      if (error !== "no-speech") failure = error;
+    };
+    r.onend = () => {
+      if (live !== r) return;
+      if (pendingStop) {
+        const done = pendingStop;
+        pendingStop = null;
+        live = null;
+        done(text());
+        return;
+      }
+      live = null;
+      if (!started) {
+        reject(new Error(failure ?? "speech recognition did not start"));
+        return;
+      }
+      if (failure) return ended(new Error(failure));
+      if (silentRestarts >= MAX_SILENT_RESTARTS) return ended();
+      silentRestarts++;
+      committed = text();
+      current = "";
+      open(locale).catch(ended);
+    };
+    r.start();
+  });
+  return {
+    start({ locale }) {
+      live?.abort();
+      committed = "";
+      current = "";
+      silentRestarts = 0;
+      pendingStop = null;
+      return open(locale);
+    },
+    stop() {
+      const r = live;
+      if (!r) return Promise.resolve(text());
+      return new Promise((resolve) => {
+        pendingStop = resolve;
+        r.stop();
+      });
+    },
+    async cancel() {
+      const r = live;
+      live = null;
+      pendingStop = null;
+      r?.abort();
+    },
+    onPartial(listener) {
+      partialListeners.add(listener);
+      return () => partialListeners.delete(listener);
+    },
+    onEnd(listener) {
+      endListeners.add(listener);
+      return () => endListeners.delete(listener);
+    }
+  };
+}
+
 exports.APPILOTS_CHAT_ATTR = APPILOTS_CHAT_ATTR;
 exports.APPILOTS_ID_ATTR = APPILOTS_ID_ATTR;
 exports.APPILOTS_ITEM_COUNT_ATTR = APPILOTS_ITEM_COUNT_ATTR;
@@ -10398,11 +10631,14 @@ exports.RateLimitedError = RateLimitedError;
 exports.SDK_VERSION = SDK_VERSION2;
 exports.WebNavigationAdapter = WebNavigationAdapter;
 exports.accessibleName = accessibleName;
+exports.appilotsDebugWarn = appilotsDebugWarn;
 exports.bestId = bestId;
 exports.buildPath = buildPath;
 exports.candidateIds = candidateIds;
 exports.captureSnapshot = captureSnapshot;
 exports.clickElement = clickElement;
+exports.confirmExpiresAt = confirmExpiresAt;
+exports.createWebSpeechHost = createWebSpeechHost;
 exports.describeAction = describeAction;
 exports.elementRole = elementRole;
 exports.executeAction = executeAction;
@@ -10413,7 +10649,9 @@ exports.getRegisteredElement = getRegisteredElement;
 exports.hidesSubtree = hidesSubtree;
 exports.humanizeError = humanizeError;
 exports.isOccludedByModal = isOccludedByModal;
+exports.isSpeechHost = isSpeechHost;
 exports.isVisible = isVisible;
+exports.isWebSpeechSupported = isWebSpeechSupported;
 exports.longPressElement = longPressElement;
 exports.matchRoute = matchRoute;
 exports.modalCandidateLabels = modalCandidateLabels;
@@ -10436,6 +10674,7 @@ exports.scrollIntoView = scrollIntoView;
 exports.scrollToOffset = scrollToOffset;
 exports.setControlValue = setControlValue;
 exports.setToggleValue = setToggleValue;
+exports.startStillWorkingTimer = startStillWorkingTimer;
 exports.stripComponentPrefix = stripComponentPrefix;
 exports.waitForLoadingSettle = waitForLoadingSettle;
 exports.waitForScreenSettle = waitForScreenSettle;