@appilots/sdk 0.2.0 → 0.4.0

package/dist/hooks/index.d.mts

@@ -1,2 +1,2 @@
-export { x as SuggestedPrompt, z as UseAppilotsFieldOptions, B as UseAppilotsSliderOptions, D as UseAppilotsTargetOptions, G as UseAppilotsToggleOptions, H as UseSuggestedPromptsOptions, I as UseSuggestedPromptsReturn, X as useAppilots, Y as useAppilotsActions, Z as useAppilotsChat, $ as useAppilotsField, a1 as useAppilotsNavigation, a2 as useAppilotsSlider, a3 as useAppilotsTarget, a4 as useAppilotsToggle, a5 as useSuggestedPrompts } from '../index-BDb1WVNo.mjs';
+export { H as SuggestedPrompt, O as UseAppilotsFieldOptions, Q as UseAppilotsSliderOptions, V as UseAppilotsTargetOptions, W as UseAppilotsToggleOptions, X as UseSuggestedPromptsOptions, Y as UseSuggestedPromptsReturn, a8 as useAppilots, a9 as useAppilotsActions, aa as useAppilotsChat, ac as useAppilotsField, ad as useAppilotsNavigation, ae as useAppilotsSlider, af as useAppilotsTarget, ag as useAppilotsToggle, ah as useSuggestedPrompts } from '../index-Cb0D6uKH.mjs';
 import 'react';

package/dist/hooks/index.d.ts

@@ -1,2 +1,2 @@
-export { x as SuggestedPrompt, z as UseAppilotsFieldOptions, B as UseAppilotsSliderOptions, D as UseAppilotsTargetOptions, G as UseAppilotsToggleOptions, H as UseSuggestedPromptsOptions, I as UseSuggestedPromptsReturn, X as useAppilots, Y as useAppilotsActions, Z as useAppilotsChat, $ as useAppilotsField, a1 as useAppilotsNavigation, a2 as useAppilotsSlider, a3 as useAppilotsTarget, a4 as useAppilotsToggle, a5 as useSuggestedPrompts } from '../index-BDb1WVNo.js';
+export { H as SuggestedPrompt, O as UseAppilotsFieldOptions, Q as UseAppilotsSliderOptions, V as UseAppilotsTargetOptions, W as UseAppilotsToggleOptions, X as UseSuggestedPromptsOptions, Y as UseSuggestedPromptsReturn, a8 as useAppilots, a9 as useAppilotsActions, aa as useAppilotsChat, ac as useAppilotsField, ad as useAppilotsNavigation, ae as useAppilotsSlider, af as useAppilotsTarget, ag as useAppilotsToggle, ah as useSuggestedPrompts } from '../index-Cb0D6uKH.js';
 import 'react';

package/dist/hooks/index.js

@@ -1,43 +1,43 @@
 'use strict';
 
-var chunkIASJ7YHC_js = require('../chunk-IASJ7YHC.js');
-require('../chunk-SIBKF7AA.js');
+var chunkY7EA6R2G_js = require('../chunk-Y7EA6R2G.js');
+require('../chunk-V3TUIIT2.js');
 
 
 
 Object.defineProperty(exports, "useAppilots", {
   enumerable: true,
-  get: function () { return chunkIASJ7YHC_js.useAppilots; }
+  get: function () { return chunkY7EA6R2G_js.useAppilots; }
 });
 Object.defineProperty(exports, "useAppilotsActions", {
   enumerable: true,
-  get: function () { return chunkIASJ7YHC_js.useAppilotsActions; }
+  get: function () { return chunkY7EA6R2G_js.useAppilotsActions; }
 });
 Object.defineProperty(exports, "useAppilotsChat", {
   enumerable: true,
-  get: function () { return chunkIASJ7YHC_js.useAppilotsChat; }
+  get: function () { return chunkY7EA6R2G_js.useAppilotsChat; }
 });
 Object.defineProperty(exports, "useAppilotsField", {
   enumerable: true,
-  get: function () { return chunkIASJ7YHC_js.useAppilotsField; }
+  get: function () { return chunkY7EA6R2G_js.useAppilotsField; }
 });
 Object.defineProperty(exports, "useAppilotsNavigation", {
   enumerable: true,
-  get: function () { return chunkIASJ7YHC_js.useAppilotsNavigation; }
+  get: function () { return chunkY7EA6R2G_js.useAppilotsNavigation; }
 });
 Object.defineProperty(exports, "useAppilotsSlider", {
   enumerable: true,
-  get: function () { return chunkIASJ7YHC_js.useAppilotsSlider; }
+  get: function () { return chunkY7EA6R2G_js.useAppilotsSlider; }
 });
 Object.defineProperty(exports, "useAppilotsTarget", {
   enumerable: true,
-  get: function () { return chunkIASJ7YHC_js.useAppilotsTarget; }
+  get: function () { return chunkY7EA6R2G_js.useAppilotsTarget; }
 });
 Object.defineProperty(exports, "useAppilotsToggle", {
   enumerable: true,
-  get: function () { return chunkIASJ7YHC_js.useAppilotsToggle; }
+  get: function () { return chunkY7EA6R2G_js.useAppilotsToggle; }
 });
 Object.defineProperty(exports, "useSuggestedPrompts", {
   enumerable: true,
-  get: function () { return chunkIASJ7YHC_js.useSuggestedPrompts; }
+  get: function () { return chunkY7EA6R2G_js.useSuggestedPrompts; }
 });

package/dist/hooks/index.mjs

@@ -1,2 +1,2 @@
-export { useAppilots, useAppilotsActions, useAppilotsChat, useAppilotsField, useAppilotsNavigation, useAppilotsSlider, useAppilotsTarget, useAppilotsToggle, useSuggestedPrompts } from '../chunk-GEM6TPAK.mjs';
-import '../chunk-HDLZGXNF.mjs';
+export { useAppilots, useAppilotsActions, useAppilotsChat, useAppilotsField, useAppilotsNavigation, useAppilotsSlider, useAppilotsTarget, useAppilotsToggle, useSuggestedPrompts } from '../chunk-42WI3UDB.mjs';
+import '../chunk-JBOLV5AM.mjs';

package/dist/{index-BDb1WVNo.d.mts → index-Cb0D6uKH.d.mts}

@@ -119,113 +119,20 @@ type PartialThemeTokens = {
 declare function mergeThemeTokens(base: AppilotsThemeTokens, partial?: PartialThemeTokens | null): AppilotsThemeTokens;
 
 /**
- * i18n keys — the canonical list of every translatable string in the
- * SDK chat UI. Adding UI copy means adding a key here AND a value in
- * every bundle under `./bundles/` (TypeScript will fail the bundle if a
- * key is missing). BACKLOG 4.1.
- */
-interface AppilotsStrings {
-    /** Default chat header title when the dev hasn't supplied one. */
-    chatTitle: string;
-    /** Header button that wipes the conversation. */
-    clearButton: string;
-    /** Placeholder for the message input. */
-    inputPlaceholder: string;
-    /** Empty state heading. */
-    emptyTitle: string;
-    /** Empty state subtitle / one-liner under the heading. */
-    emptySubtitle: string;
-    /** "Thinking..." placeholder shown while the assistant is replying. */
-    thinking: string;
-    /** Status shown while the assistant is planning from the current screen. */
-    statusAnalyzing: string;
-    /** Status shown while the SDK waits for the app to settle after an action. */
-    statusWaitingApp: string;
-    /** Status shown while the assistant adjusts after a recoverable failure. */
-    statusAdjusting: string;
-    /** Footer line shown when poweredByVisible !== false. */
-    poweredBy: string;
-    /** Approve button on a pending action row in the breadcrumb. */
-    approve: string;
-    /** Reject button on a pending action row in the breadcrumb. */
-    reject: string;
-    /** Generic "cancelled by the user" message after a reject. */
-    cancelledByUser: string;
-    /** Fallback humanised name for an unknown action type. */
-    unknownAction: string;
-    /** Generic friendly error when nothing else fits. */
-    somethingWentWrong: string;
-    /** Open chat accessibility label for the floating bubble. */
-    openChatA11y: string;
-    /** Close chat accessibility label. */
-    closeChatA11y: string;
-    /** A11y label for the stop-generation button (OKR-008 KR4). */
-    stopGeneratingA11y: string;
-    /** A11y label for the "talk to a human" header button. */
-    talkToHumanA11y: string;
-    /** Sender label above a human operator's bubble. */
-    humanAgentLabel: string;
-    /** System line right after the user (or the offer chip) escalates. */
-    escalationRequested: string;
-    /** System line when an operator claims the conversation. */
-    escalationConnected: string;
-    /** System line when the operator resolves — AI takes over again. */
-    escalationResolved: string;
-    /** System line offering the handoff after the agent gives up. */
-    escalationOffer: string;
-    /** Label of the tappable chip under the offer line. */
-    escalationOfferChip: string;
-    /** Thin banner under the header while waiting in the queue. */
-    escalationPendingBanner: string;
-    /** Thin banner under the header while connected to an operator. */
-    escalationActiveBanner: string;
-}
-type AppilotsStringKey = keyof AppilotsStrings;
-
-/**
- * SDK locale code. Adding a locale = adding a bundle file in
- * `./bundles/` AND a branch in `BUNDLES` below. BACKLOG 4.1.
+ * SDK locale code. Canonical source of truth for `AppilotsLocale` — moved
+ * here (out of the React Native-coupled `i18n/I18nProvider`) so that
+ * platform-agnostic contract types (`RemotePersonalization.defaultLocale`)
+ * don't pull in a React/React Native import just for a string union type.
+ *
+ * `@appilots/sdk`'s `i18n/I18nProvider.tsx` re-exports this type from its
+ * original public path (`@appilots/sdk`'s `./i18n` barrel) so nothing
+ * downstream of the SDK's public API changes.
+ *
+ * Adding a locale = adding a bundle file in `@appilots/sdk`'s
+ * `i18n/bundles/` AND a branch in `i18n/I18nProvider.tsx`'s `BUNDLES`
+ * map AND a variant here. BACKLOG 4.1.
  */
 type AppilotsLocale = 'pt-BR' | 'en' | 'es';
-/**
- * Best-effort device-locale detection. Returns the closest supported
- * locale or `null` if we can't tell. Designed to never throw — RN's
- * native modules are platform-specific and can be missing in test
- * harnesses.
- */
-declare function detectDeviceLocale(): AppilotsLocale | null;
-/**
- * Resolve the locale to use given the prop and the device default.
- * Order: explicit prop → device-detected → DEFAULT_LOCALE.
- */
-declare function resolveLocale(prop?: AppilotsLocale | null): AppilotsLocale;
-interface I18nContextValue {
-    locale: AppilotsLocale;
-    strings: AppilotsStrings;
-    /**
-     * Helper to read a single key. Components can also destructure
-     * `strings` directly if they need many in one render.
-     */
-    t: (key: AppilotsStringKey) => string;
-}
-interface AppilotsI18nProviderProps {
-    /** Force a locale. Falls through to device detection when omitted. */
-    locale?: AppilotsLocale | null;
-    /**
-     * Per-key overrides to merge on top of the bundle. Useful when the
-     * dev wants to rename only "Powered by Appilots" while keeping the
-     * rest in the default language.
-     */
-    overrides?: Partial<AppilotsStrings> | null;
-    children: React__default.ReactNode;
-}
-declare function AppilotsI18nProvider({ locale, overrides, children, }: AppilotsI18nProviderProps): React__default.JSX.Element;
-/**
- * Read the locale + strings from context. Falls back to the default
- * locale bundle if no provider is mounted, so components don't need a
- * provider to be safe — they just lose the dev's overrides.
- */
-declare function useAppilotsI18n(): I18nContextValue;
 
 /**
  * Core types for the Appilots SDK.
@@ -459,6 +366,16 @@ interface SendMessageStreamOptions {
 }
 /** Runtime context sent with every user message. */
 interface SendMessageContext {
+    /**
+     * Which client platform this observation came from — `'react-native'`,
+     * `'web'`, `'android'`, `'ios'`, or any other client-defined string.
+     * The server treats an absent value as `'react-native'` (see
+     * `docs/agent-contract.md`'s "The `platform` field" section), so
+     * setting it is optional but forward-compatible: a client that sends
+     * it explicitly isn't relying on that default staying `'react-native'`
+     * forever.
+     */
+    platform?: string;
     currentScreen?: string;
     formState?: Record<string, unknown>;
     /** Design-time screen metadata from registerScreen() or the MCP doc */
@@ -684,6 +601,339 @@ declare class AppilotsClient {
     }): () => void;
 }
 
+/**
+ * Snapshot types — the platform-agnostic "view model" of what the user
+ * is currently seeing on screen, sent to the AI agent so it has
+ * accurate visible state.
+ *
+ * Every platform walker (React Native fiber walk, web DOM walk, ...)
+ * produces this same shape; the wire contract it feeds is
+ * `agentSnapshotSchema` in `@appilots/shared`.
+ */
+interface InputSnapshot {
+    /** Best identifier — testID/data-testid, accessibilityLabel/aria-label, or placeholder */
+    id?: string;
+    /** Human-readable label inferred from accessibility metadata or sibling text */
+    label?: string;
+    /** Current value (only present for controlled inputs) */
+    value?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Whether the input is editable */
+    editable?: boolean;
+    /** Whether the input is secure (password field) */
+    secure?: boolean;
+    /** Inferred type based on the platform's input-type metadata */
+    type?: 'text' | 'email' | 'number' | 'phone' | 'password';
+    /**
+     * True when this input lives inside a currently-visible modal. When a
+     * modal is open, only inModal elements can actually receive input —
+     * everything else is behind the overlay.
+     */
+    inModal?: boolean;
+}
+interface ButtonSnapshot {
+    /** Best identifier — testID/data-testid, accessibilityLabel/aria-label, or inferred from child text */
+    id?: string;
+    /** Human-readable label — usually the visible text inside the button */
+    label?: string;
+    /** Whether the button is disabled */
+    disabled?: boolean;
+    /**
+     * Whether the button currently appears selected/active — set by
+     * grouped, mutually-exclusive controls (segmented controls, radio
+     * groups) where each option is its own pressable target.
+     */
+    selected?: boolean;
+    /** True when this button lives inside a currently-visible modal. */
+    inModal?: boolean;
+}
+interface ToggleSnapshot {
+    /** Best identifier */
+    id?: string;
+    /** Human-readable label */
+    label?: string;
+    /** Current on/off state */
+    value?: boolean;
+    /** True when this toggle lives inside a currently-visible modal. */
+    inModal?: boolean;
+}
+interface SliderSnapshot {
+    /** Registry id — the executable handle. */
+    id?: string;
+    /** Human-readable label */
+    label?: string;
+    /** Current numeric value */
+    value?: number;
+    /** Lower bound the executor clamps to */
+    min?: number;
+    /** Upper bound the executor clamps to */
+    max?: number;
+    /** Step the executor snaps to (omitted = continuous) */
+    step?: number;
+    /** Whether the slider is currently disabled */
+    disabled?: boolean;
+    /** True when this slider lives inside a currently-visible modal. */
+    inModal?: boolean;
+}
+interface ListItemSnapshot {
+    /** 1-indexed position within the parent list (matches "selecione o terceiro"). */
+    index: number;
+    /**
+     * 0-based index of this row in the list's backing DATA, when known.
+     * For scrolled/virtualized lists this differs from `index`.
+     */
+    dataIndex?: number;
+    /** Framework key of the row, if present (typically the item's domain id). */
+    reactKey?: string;
+    /** Runtime key supplied by list tracking, if available. */
+    itemKey?: string;
+    /** Texts captured from this item's subtree, preserving row association. */
+    texts: string[];
+    /** Buttons inside this item — e.g. an inline "Edit" button on a row. */
+    buttons: ButtonSnapshot[];
+    /** Inputs inside this item — rare but possible (inline edit row). */
+    inputs: InputSnapshot[];
+    /** Toggles inside this item. */
+    toggles: ToggleSnapshot[];
+    /**
+     * Synthetic id assigned by the walker. Stable within a single
+     * snapshot; format `list-<L>-item-<I>` (0-indexed L, 1-indexed I).
+     * Used by tap-by-ordinal resolution in the executor.
+     */
+    syntheticId: string;
+}
+interface ListSnapshot {
+    /** 0-indexed list ordinal — multiple lists on one screen get 0, 1, 2... */
+    index: number;
+    /** Runtime list id when tracking or explicit props provide one. */
+    id?: string;
+    /** The container component/tag name as observed by the walker. */
+    containerType: string;
+    /**
+     * Source that identified this list. `'fiber'`/`'auto-tracked'` are
+     * the walker's own discovery tags (a DOM walker reports
+     * `'auto-tracked'` for app-annotated lists and omits the field for
+     * heuristically-detected ones); `'registry'` means the list came
+     * from the SDK's list registry rather than the tree walk.
+     */
+    source?: 'fiber' | 'auto-tracked' | 'registry';
+    /** Total data-set count when the list exposes it. */
+    itemCount?: number;
+    /** Number of row items captured in this snapshot. */
+    visibleItemCount?: number;
+    /** True when the list reports a refresh/loading state. */
+    refreshing?: boolean;
+    /** True when total item count is known and zero. */
+    empty?: boolean;
+    /** Human-readable label if the app supplied one. */
+    label?: string;
+    /** Items in visible order. */
+    items: ListItemSnapshot[];
+    /**
+     * Lightweight text projection of the list's FULL data set (capped),
+     * so the agent can see/search rows that virtualization keeps
+     * unmounted. Each entry: 0-based data index, stable key, short text.
+     */
+    dataPreview?: ListDataPreviewEntry[];
+    /** Current vertical scroll offset in px, when readable. */
+    scrollOffsetY?: number;
+    /** True when there is scrollable content above the viewport. */
+    canScrollUp?: boolean;
+    /** True when there is scrollable content below the viewport. */
+    canScrollDown?: boolean;
+}
+interface ListDataPreviewEntry {
+    /** 0-based index in the list's backing data. */
+    index: number;
+    /** Stable key from the item's domain id when available. */
+    key?: string;
+    /** Short human-readable projection of the item (capped length). */
+    text: string;
+}
+interface ChoiceOptionSnapshot {
+    /** 1-indexed option position within this group. */
+    index: number;
+    /** Stable-enough id for the current snapshot/action turn. */
+    syntheticId: string;
+    /** Best target id if this option is backed by a pressable component. */
+    targetId?: string;
+    /** Human-readable option label. */
+    label?: string;
+    /** Text segments that belong to this option. */
+    texts: string[];
+    /** Whether this option appears selected. */
+    selected?: boolean;
+    /** Whether this option appears disabled. */
+    disabled?: boolean;
+}
+interface ChoiceGroupSnapshot {
+    /** 0-indexed group ordinal on the current screen. */
+    index: number;
+    /** Runtime id when known, usually inherited from a list/collection. */
+    id?: string;
+    /** Human-readable label when known. */
+    label?: string;
+    /** Source that produced this choice group. */
+    source?: 'list' | 'buttons' | 'heuristic';
+    /** Visible options in order. */
+    options: ChoiceOptionSnapshot[];
+}
+interface InteractionElementListContext {
+    listIndex?: number;
+    listId?: string;
+    listLabel?: string;
+    itemIndex?: number;
+    itemKey?: string;
+    reactKey?: string;
+    syntheticId?: string;
+}
+interface InteractionElementSnapshot {
+    /** Stable id for the current screen/content, preferred for tool calls. */
+    id: string;
+    /** Semantic UI role. */
+    role: 'option' | 'button' | 'input' | 'toggle' | 'slider' | 'listItem';
+    /** Human-readable label. */
+    label?: string;
+    /** Text segments associated with this element. */
+    texts: string[];
+    /** Actions supported by this element. */
+    actions: Array<'press' | 'focus' | 'toggle' | 'setValue'>;
+    /** Whether the element is currently disabled. */
+    disabled?: boolean;
+    /** Whether the element appears selected. */
+    selected?: boolean;
+    /** Source that produced the element. */
+    source?: 'list' | 'button' | 'input' | 'toggle' | 'slider' | 'choice';
+    /** Legacy/fallback target id, if any. */
+    targetId?: string;
+    /** Context for row/list options. */
+    listContext?: InteractionElementListContext;
+    /**
+     * True when the underlying component lives inside a currently-visible
+     * modal — the only targets actually touchable while the overlay is up.
+     */
+    inModal?: boolean;
+}
+interface ScreenSnapshot {
+    /** The currently active route name, if known */
+    route: string | null;
+    /** All visible static text */
+    texts: string[];
+    /** All text inputs currently rendered (and visible) */
+    inputs: InputSnapshot[];
+    /** All button-like components */
+    buttons: ButtonSnapshot[];
+    /** All toggle components */
+    toggles: ToggleSnapshot[];
+    /** Sliders / adjustable numeric controls. */
+    sliders: SliderSnapshot[];
+    /** Whether a loading indicator is visible */
+    loading: boolean;
+    /** Whether a modal is currently open */
+    modalOpen: boolean;
+    /**
+     * Lists detected in the visible tree. Each list's items have their
+     * own per-item texts/buttons/inputs/toggles, NOT duplicated in the
+     * flat top-level arrays — preserving the row association the flat
+     * shape destroys.
+     */
+    lists: ListSnapshot[];
+    /**
+     * Choice groups detected from visible cards/rows/chips/buttons, used
+     * for select-like flows where no text input exists.
+     */
+    choiceGroups: ChoiceGroupSnapshot[];
+    /**
+     * Interaction graph: visible actionable elements with stable ids,
+     * semantic roles, labels, and execution fallbacks. Agents should
+     * prefer these ids over synthetic ordinal handles.
+     */
+    elements: InteractionElementSnapshot[];
+    /** Diagnostic counts for debugging */
+    stats?: {
+        visitedFibers: number;
+        skippedHidden: number;
+    };
+}
+/**
+ * Localized copy for escalation system messages, injected by the chat
+ * surface (the machine has no i18n access — same pattern as errorPrefix).
+ * When omitted, no system messages are appended but the state machine
+ * still works.
+ */
+interface EscalationStrings {
+    /** Appended right after the escalation is created. */
+    requested: string;
+    /** Appended when an operator claims the conversation. */
+    connected: string;
+    /** Appended when the operator resolves — AI takes over again. */
+    resolved: string;
+    /** Content of the offer chip message appended when the agent gives up. */
+    offer: string;
+}
+
+type TraceListener = (entries: AppilotsTraceEntry[]) => void;
+declare function recordAppilotsDebugTrace(entry: Omit<AppilotsTraceEntry, 'id'> & {
+    id?: string;
+}): void;
+declare function getAppilotsDebugTraces(): AppilotsTraceEntry[];
+declare function clearAppilotsDebugTraces(): void;
+declare function subscribeAppilotsDebugTraces(listener: TraceListener): () => void;
+
+/**
+ * Human-readable labels and error messages for the action breadcrumb.
+ *
+ * Strings are PT-BR hardcoded for now. i18n is planned for backlog item
+ * 4.1 (Personalização) — when that lands, these strings move into the
+ * locale bundles.
+ *
+ * Two responsibilities:
+ *   1. `describeAction(action)` — turns a typed AgentAction into a label
+ *      that varies by lifecycle state (pending/running/done/failed).
+ *   2. `humanizeError(raw, action)` — sanitises the raw error string from
+ *      the executor into a short user-facing reason. Stack traces and
+ *      protocol errors are collapsed into "algo deu errado" so users
+ *      aren't shown technical noise.
+ */
+
+type BreadcrumbState = 'pending' | 'running' | 'success' | 'failed';
+interface BreadcrumbItem {
+    /** What to render on the line. */
+    label: string;
+    /** Lifecycle state — drives icon + colour in the breadcrumb. */
+    state: BreadcrumbState;
+}
+/**
+ * Map an AgentAction + its current status to a breadcrumb item ready to
+ * render. The function is intentionally defensive — both the native-tools
+ * and JSON-fallback code paths feed actions through here, and the JSON
+ * path is loose with payload shapes, so every field access has to assume
+ * `unknown`.
+ */
+declare function describeAction(action: AgentAction): BreadcrumbItem;
+/**
+ * Convert the executor's raw error string into a short, user-facing
+ * reason that fits inside parentheses on the breadcrumb line. Returns
+ * `undefined` when there's no useful information to show — caller can
+ * then drop the parenthetical entirely.
+ *
+ * Heuristics:
+ *   - Apply known-pattern rewrites (rejected, not found, network, etc.)
+ *   - If the result looks technical (stack frame, HTTP status, JSON
+ *     dump) or is suspiciously long, fall back to "algo deu errado".
+ *   - Trim and lowercase the first letter so it reads naturally inside
+ *     the parens after the action verb.
+ */
+declare function humanizeError(raw: string | undefined, _action?: AgentAction): string | undefined;
+
+/**
+ * SDK version — bumped by changesets on release. Lives in its own module
+ * so runtime code (AppilotsClient) can import it without pulling the whole
+ * public barrel in and creating an import cycle.
+ */
+declare const SDK_VERSION = "0.1.0";
+
 interface AppilotsConfig {
     /** Project ID from the Appilots dashboard */
     projectId: string;
@@ -800,22 +1050,6 @@ interface UseAppilotsNavigationReturn {
  */
 declare function useAppilotsNavigation(): UseAppilotsNavigationReturn;
 
-/**
- * Localized copy for escalation system messages, injected by the chat
- * surface (the hook has no i18n access — same pattern as errorPrefix).
- * When omitted, no system messages are appended but the state machine
- * still works.
- */
-interface EscalationStrings {
-    /** Appended right after the escalation is created. */
-    requested: string;
-    /** Appended when an operator claims the conversation. */
-    connected: string;
-    /** Appended when the operator resolves — AI takes over again. */
-    resolved: string;
-    /** Content of the offer chip message appended when the agent gives up. */
-    offer: string;
-}
 interface UseAppilotsChatReturn {
     messages: ChatMessage[];
     isLoading: boolean;
@@ -860,6 +1094,12 @@ interface UseAppilotsChatOptions {
 /**
  * Hook for managing chat state and sending messages to the Appilots agent.
  *
+ * This is a thin React binding over `ChatSessionMachine` from
+ * `@appilots/client-core` — the turn/continuation/recovery orchestration
+ * itself is platform-agnostic and shared with the web client. Everything
+ * React Native-specific (Fiber snapshotting, React Navigation settling)
+ * enters through `reactNativeChatAdapter`.
+ *
  * @example
  * ```tsx
  * const { messages, sendMessage, isLoading } = useAppilotsChat();
@@ -894,8 +1134,11 @@ interface UseAppilotsActionsReturn {
 /**
  * Hook for monitoring and controlling agent actions.
  *
- * Now integrates with the ActionExecutor to actually execute actions
- * against live UI components via the ComponentRegistry.
+ * A thin React binding over `ActionQueueMachine` from
+ * `@appilots/client-core`: the queue, its status transitions, the
+ * confirm gate (server-injected and locally synthesized) and sequential
+ * auto-execution are platform-agnostic. React Native execution goes
+ * through the ActionExecutor via `createReactNativeActionRunner`.
  *
  * @example
  * ```tsx
@@ -1297,4 +1540,4 @@ interface UseSuggestedPromptsReturn {
  */
 declare function useSuggestedPrompts(options: UseSuggestedPromptsOptions): UseSuggestedPromptsReturn;
 
-export { useAppilotsField as $, type AppilotsThemeTokens as A, type UseAppilotsSliderOptions as B, type ComponentRegistry as C, type UseAppilotsTargetOptions as D, type EscalationState as E, type FieldEntry as F, type UseAppilotsToggleOptions as G, type UseSuggestedPromptsOptions as H, type UseSuggestedPromptsReturn as I, componentRegistry as J, createComponentRegistry as K, defaultDarkTheme as L, type MessageRole as M, type NavigationPayload as N, defaultLightTheme as O, type PartialThemeTokens as P, detectDeviceLocale as Q, type RemotePersonalization as R, type SliderEntry as S, type TargetEntry as T, type UIInteractionPayload as U, mergeThemeTokens as V, resolveLocale as W, useAppilots as X, useAppilotsActions as Y, useAppilotsChat as Z, useAppilotsContext as _, type AppilotsLocale as a, useAppilotsI18n as a0, useAppilotsNavigation as a1, useAppilotsSlider as a2, useAppilotsTarget as a3, useAppilotsToggle as a4, useSuggestedPrompts as a5, type AgentAction as b, type AgentPermissions as c, type AppilotsTraceEntry as d, type AppilotsEvent as e, type AgentActionType as f, type AgentMessage as g, AppilotsClient as h, type AppilotsClientOptions as i, type AppilotsConfig as j, type AppilotsEventHandler as k, type AppilotsEventType as l, AppilotsI18nProvider as m, type AppilotsI18nProviderProps as n, AppilotsProvider as o, type AppilotsProviderProps as p, type AppilotsStringKey as q, type AppilotsStrings as r, type AppilotsUser as s, type ChatMessage as t, type ComponentEntry as u, type ComponentKind as v, type FormFillPayload as w, type SuggestedPrompt as x, type ToggleEntry as y, type UseAppilotsFieldOptions as z };
+export { createComponentRegistry as $, type AppilotsThemeTokens as A, type BreadcrumbItem as B, type ComponentRegistry as C, SDK_VERSION as D, type EscalationState as E, type FieldEntry as F, type SliderEntry as G, type SuggestedPrompt as H, type InteractionElementSnapshot as I, type ToggleEntry as J, type ToggleSnapshot as K, type ListItemSnapshot as L, type MessageRole as M, type NavigationPayload as N, type UseAppilotsFieldOptions as O, type PartialThemeTokens as P, type UseAppilotsSliderOptions as Q, type RemotePersonalization as R, type ScreenSnapshot as S, type TargetEntry as T, type UIInteractionPayload as U, type UseAppilotsTargetOptions as V, type UseAppilotsToggleOptions as W, type UseSuggestedPromptsOptions as X, type UseSuggestedPromptsReturn as Y, clearAppilotsDebugTraces as Z, componentRegistry as _, type AppilotsLocale as a, defaultDarkTheme as a0, defaultLightTheme as a1, describeAction as a2, getAppilotsDebugTraces as a3, humanizeError as a4, mergeThemeTokens as a5, recordAppilotsDebugTrace as a6, subscribeAppilotsDebugTraces as a7, useAppilots as a8, useAppilotsActions as a9, useAppilotsChat as aa, useAppilotsContext as ab, useAppilotsField as ac, useAppilotsNavigation as ad, useAppilotsSlider as ae, useAppilotsTarget as af, useAppilotsToggle as ag, useSuggestedPrompts as ah, type AgentAction as b, type AgentPermissions as c, type AppilotsEvent as d, type AgentActionType as e, type AgentMessage as f, AppilotsClient as g, type AppilotsClientOptions as h, type AppilotsConfig as i, type AppilotsEventHandler as j, type AppilotsEventType as k, AppilotsProvider as l, type AppilotsProviderProps as m, type AppilotsTraceEntry as n, type AppilotsUser as o, type BreadcrumbState as p, type ButtonSnapshot as q, type ChatMessage as r, type ChoiceGroupSnapshot as s, type ChoiceOptionSnapshot as t, type ComponentEntry as u, type ComponentKind as v, type FormFillPayload as w, type InputSnapshot as x, type InteractionElementListContext as y, type ListSnapshot as z };