@appilots/sdk 0.3.0 → 0.4.1

package/dist/index-Cb0D6uKH.d.ts

@@ -0,0 +1,1543 @@
+import * as React$1 from 'react';
+import React__default from 'react';
+
+/**
+ * Theme tokens — the source of truth for any color, font, radius or
+ * shadow used inside the SDK's chat UI. Components must read from these
+ * tokens (via {@link useAppilotsTheme}) rather than hardcoding values, so
+ * a developer who sets a `theme` prop or dashboard config can re-skin
+ * the whole chat without forking the SDK.
+ *
+ * BACKLOG 4.1.
+ *
+ * Adding a new token:
+ *   1. Add a field to `AppilotsThemeTokens` below.
+ *   2. Set a value in BOTH `defaultLight` and `defaultDark` (and ideally
+ *      keep them visually consistent — e.g. dark text on light bg ↔
+ *      light text on dark bg).
+ *   3. Use it in components via `useAppilotsTheme()`.
+ *   4. Mirror the field on `themeTokensSchema` in `@appilots/shared` if
+ *      it should be settable from the dashboard.
+ *
+ * Removing a token is a breaking change — bump the SDK minor.
+ */
+interface AppilotsThemeTokens {
+    /** Hex color values. The 8-digit form (#RRGGBBAA) is allowed. */
+    colors: {
+        /** Brand color — send button, FAB, header dot, links. */
+        primary: string;
+        /** Secondary brand accent — used sparingly (e.g. the human-agent/operator icon accent in message rows). */
+        secondary: string;
+        /** Page/modal background, behind the messages list. */
+        background: string;
+        /** Surface color for assistant message bubbles, input field, chips. */
+        surface: string;
+        /** Default text color (high contrast on background). */
+        text: string;
+        /** Muted text — placeholders, secondary labels, "Powered by". */
+        textSecondary: string;
+        /** 1px hairlines under header, around chips. */
+        border: string;
+        /** Success state — completed action checks in the breadcrumb (ActionBreadcrumb `success` tone). */
+        success: string;
+        /**
+         * Warning / caution state — drives the breadcrumb's `pending` tone
+         * (queued, not-yet-run actions). The default is a neutral gray, not
+         * amber, so it renders pixel-identical to the SDK's pre-4.2 hardcoded
+         * palette out of the box; set an amber/yellow here to make queued
+         * actions visually louder.
+         */
+        warning: string;
+        /** Error state — failed action rows (ActionBreadcrumb `failed` tone) and destructive badges/CTAs (confirm card, reject button). */
+        error: string;
+        /** Text color for chip/button labels (e.g. suggested prompts). */
+        buttonText: string;
+        /** Text color inside the assistant's message bubble (not the user's — that stays white on `primary`). */
+        bubbleText: string;
+        /**
+         * Text color inside the USER's message bubble (on `primary`). Optional
+         * mirror of `bubbleText` for the user side — falls back to white,
+         * matching the SDK's pre-4.2 hardcoded value, when unset.
+         */
+        userBubbleText: string;
+    };
+    typography: {
+        /** Font family applied to ALL chat text. Falls back to system. */
+        fontFamily: string;
+        fontSizeXs: number;
+        fontSizeSm: number;
+        fontSizeBase: number;
+        fontSizeLg: number;
+    };
+    radii: {
+        /** Tight corners — chips, small badges. */
+        sm: number;
+        /** Default — input field, send button, secondary buttons. */
+        md: number;
+        /** Generous — chat sheet, message bubbles. */
+        lg: number;
+    };
+    /** Optional drop-shadows (RN-shaped, applied via View style). */
+    shadows: {
+        /** Tells the developer's dark/light intent. Components don't read
+         *  this directly — they read tokens — but `mode` is forwarded so
+         *  status bar / image color choices can branch on it. */
+        appearance: 'light' | 'dark';
+    };
+}
+/**
+ * Default LIGHT theme — used when the device is in light mode and the
+ * developer hasn't overridden anything. Visually matches the SDK's
+ * pre-4.1 hardcoded palette so existing apps don't change look on
+ * upgrade.
+ */
+declare const defaultLightTheme: AppilotsThemeTokens;
+/**
+ * Default DARK theme — used when the device is in dark mode and the
+ * developer hasn't overridden anything. Picked to roughly mirror the
+ * light theme: same hue family, inverted background/text, slightly
+ * cooler border/surface tones.
+ */
+declare const defaultDarkTheme: AppilotsThemeTokens;
+/**
+ * Deep-partial of the token tree — what a developer hands to the SDK
+ * via the `theme` prop or dashboard config. Every field optional;
+ * unspecified fields fall through to the default.
+ */
+type PartialThemeTokens = {
+    colors?: Partial<AppilotsThemeTokens['colors']>;
+    typography?: Partial<AppilotsThemeTokens['typography']>;
+    radii?: Partial<AppilotsThemeTokens['radii']>;
+    shadows?: Partial<AppilotsThemeTokens['shadows']>;
+};
+/**
+ * Merge a partial token tree on top of a base. Keys present in the
+ * partial win; missing keys keep the base value. Two levels deep is
+ * enough for the current token shape, so we don't need a generic deep
+ * merge — keeps tree-shaking friendly.
+ */
+declare function mergeThemeTokens(base: AppilotsThemeTokens, partial?: PartialThemeTokens | null): AppilotsThemeTokens;
+
+/**
+ * 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';
+
+/**
+ * Core types for the Appilots SDK.
+ */
+
+/**
+ * Payload of `GET /agent/personalization` — what the dev configured in
+ * the dashboard under Projects > Personalization. Fetched once on
+ * `AppilotsProvider` mount and applied by `AppilotsChat` as a fallback
+ * for any prop the dev did NOT set explicitly in code
+ * (prop > remote > SDK default).
+ *
+ * Only JSON-serializable values travel here: URLs/hex/booleans work,
+ * React nodes and local `require()` assets can only come via props.
+ * `null` means "not configured" — fall through to the next source.
+ */
+interface RemotePersonalization {
+    assistantName: string | null;
+    /** Avatar URL shown next to assistant turns. */
+    assistantAvatar: string | null;
+    /** Emoji or image URL for the empty-state badge. */
+    emptyStateIcon: string | null;
+    welcomeMessage: string | null;
+    chatTitle: string | null;
+    poweredByVisible: boolean;
+    /**
+     * Partial token tree merged onto the SDK defaults. `mode` (when set)
+     * plays the role of the `themeMode` prop.
+     */
+    theme: (PartialThemeTokens & {
+        mode?: 'auto' | 'light' | 'dark';
+    }) | null;
+    defaultLocale: AppilotsLocale | null;
+    triggerButtonColor: string | null;
+    triggerButtonImageUrl: string | null;
+}
+type MessageRole = 'user' | 'assistant' | 'system' | 'human_agent';
+interface ChatMessage {
+    id: string;
+    role: MessageRole;
+    content: string;
+    timestamp: number;
+    metadata?: Record<string, unknown>;
+}
+interface AppilotsTraceEntry {
+    id: string;
+    timestamp: number;
+    type: AppilotsEventType | 'agent:trace';
+    messageId?: string;
+    actionId?: string;
+    actionType?: AgentActionType | string;
+    status?: AgentAction['status'] | 'started' | 'error';
+    summary?: string;
+    data: Record<string, unknown>;
+}
+interface AgentMessage extends ChatMessage {
+    role: 'assistant';
+    actions?: AgentAction[];
+    thinking?: string;
+}
+type AgentActionType = 'navigate' | 'form_fill' | 'ui_interaction' | 'scroll_list' | 'confirm' | 'custom';
+interface AgentAction {
+    id: string;
+    type: AgentActionType;
+    payload: NavigationPayload | FormFillPayload | UIInteractionPayload | ScrollListPayload | Record<string, unknown>;
+    status: 'pending' | 'executing' | 'completed' | 'failed';
+    error?: string;
+    /** ID of the assistant message that triggered this action */
+    messageId?: string;
+    /**
+     * BACKLOG 2.2 — When the server flags an action as destructive,
+     * the SDK renders any preceding `confirm` action with the danger
+     * variant and expects the action to be gated by user approval.
+     */
+    destructive?: boolean;
+}
+interface NavigationPayload {
+    screenName: string;
+    params?: Record<string, unknown>;
+    navigationAction: 'push' | 'navigate' | 'replace' | 'goBack' | 'reset';
+    /**
+     * Optional path of parent navigator route names for nested screens.
+     * E.g. ['HomeTab', 'VehiclesTab'] to reach a screen inside
+     * HomeTab → VehiclesTab → screenName.
+     *
+     * React Navigation requires nested navigation params:
+     *   nav.navigate('HomeTab', { screen: 'VehiclesTab', params: { screen: 'VehicleCreate' } })
+     *
+     * The AI model provides this based on the MCP document's navigation graph.
+     */
+    path?: string[];
+}
+interface FormFillPayload {
+    screenName: string;
+    fields: FormFieldAction[];
+    /**
+     * If true, the handler presses the screen's primary submit button
+     * after all fields are filled. The submit button is resolved via
+     * `registerScreen({ actions: [{ type: 'submit', ... }] })` first,
+     * then via the fiber tree and a label heuristic.
+     *
+     * Aligned with the `submitAfterFill` field in the LLM tool schema
+     * (`agentTools.form_fill` in ai-relay.ts).
+     */
+    submitAfterFill?: boolean;
+}
+interface FormFieldAction {
+    fieldId: string;
+    fieldType: 'text' | 'select' | 'toggle' | 'date' | 'number' | 'custom';
+    value: unknown;
+    label?: string;
+}
+interface UIInteractionPayload {
+    componentId: string;
+    /** Canonical server/LLM identifier. `componentId` is kept as SDK alias. */
+    targetId?: string;
+    action: 'press' | 'longPress' | 'scroll' | 'swipe' | 'focus' | 'set_value';
+    /**
+     * Numeric value for `set_value` (sliders / adjustable controls).
+     * The handler clamps to the slider's [min, max] and snaps to its step.
+     */
+    value?: number;
+    params?: Record<string, unknown>;
+}
+/**
+ * Scroll a list/collection so virtualized off-screen rows mount and
+ * show up in the next observation. Mirrors `scrollListPayloadSchema`
+ * in @appilots/shared. At least one of the fields should be present;
+ * the handler falls back to paging one viewport down when only a
+ * listId is given.
+ */
+interface ScrollListPayload {
+    /** Runtime list id from the observation's "Lists visible" block. */
+    listId?: string;
+    /** 1-based index in the list's DATA to scroll to. */
+    toIndex?: number;
+    /** Coarse paging when no target index is known. */
+    direction?: 'up' | 'down';
+}
+interface AgentPermissions {
+    canNavigate: boolean;
+    canFillForms: boolean;
+    canInteractUI: boolean;
+    canSubmitForms: boolean;
+    allowedScreens?: string[];
+    blockedScreens?: string[];
+    allowedActions?: AgentActionType[];
+}
+type AppilotsEventType = 'agent:action:start' | 'agent:action:complete' | 'agent:action:error' | 'agent:message' | 'navigation:change' | 'chat:open' | 'chat:close' | 'chat:escalation:start' | 'chat:escalation:message' | 'chat:escalation:end';
+interface AppilotsEvent {
+    type: AppilotsEventType;
+    timestamp: number;
+    data: Record<string, unknown>;
+}
+type AppilotsEventHandler = (event: AppilotsEvent) => void;
+/**
+ * Client-side view of an open escalation. `resolved` never appears
+ * here — resolution clears the state (after surfacing a system
+ * message in the transcript).
+ */
+interface EscalationState {
+    id: string;
+    status: 'pending' | 'active';
+    /** Set once an operator claims the conversation. */
+    operatorName?: string;
+}
+
+interface AppilotsClientOptions {
+    projectId: string;
+    apiBaseUrl?: string;
+    apiKey?: string;
+    debug?: boolean;
+    timeout?: number;
+    headers?: Record<string, string>;
+    /**
+     * Version of the MCP doc bundled with this app build. The server
+     * compares this against the currently-active MCP doc for the
+     * project and emits a `mcp_version_mismatch` telemetry event when
+     * they differ — the canonical sign that the dev shipped an app
+     * update but forgot to regenerate/upload the MCP.
+     *
+     * Tip: import this from the MCP file the CLI generates, or read it
+     * from your app's package.json so it stays in lockstep with releases.
+     */
+    mcpVersion?: string;
+    /**
+     * The host app's version (e.g. from package.json or
+     * react-native-device-info). Sent as `X-App-Version` on every request
+     * so the server can match the compatible MCP document per app build —
+     * essential for OTA-updated fleets where multiple app versions coexist.
+     */
+    appVersion?: string;
+    /**
+     * Who the app's current user is. `id` becomes the session's
+     * externalUserId; `name`/`identifiers` are upserted into the
+     * workspace's end-users registry (fire-and-forget identify after the
+     * session opens) so support operators see a person, not an anonymous
+     * id. Identifiers are dashboard-only — never sent to the LLM.
+     */
+    user?: AppilotsUser;
+}
+interface AppilotsUser {
+    /** The app's own user id (matches your backend). */
+    id: string;
+    name?: string;
+    /** Free-form lookup keys: { email, phone, cpf, ... }. Max 10. */
+    identifiers?: Record<string, string>;
+}
+interface SendMessageResponse {
+    sessionId: string;
+    message: ChatMessage;
+    /** Summary message to show AFTER actions complete */
+    summaryMessage?: ChatMessage;
+    actions?: AgentAction[];
+    usage?: {
+        tokensUsed: number;
+        modelUsed: string;
+        latencyMs: number;
+    };
+}
+interface SendMessageStreamOptions {
+    /**
+     * Fired per SSE text-delta with the chunk and the accumulated text so
+     * far — render `fullText` directly; chunks may split words/markdown.
+     */
+    onTextDelta?: (chunk: string, fullText: string) => void;
+    /** Fired once when the server announces the session id. */
+    onSession?: (sessionId: string) => void;
+    /** Abort mid-generation (stop button). Rejects with name='AbortError'. */
+    signal?: AbortSignal;
+}
+/** 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 */
+    screenMetadata?: Record<string, unknown>;
+    /** Runtime React Navigation summary captured by the SDK */
+    navigationState?: {
+        currentRouteName?: string;
+        activePath?: string[];
+        rootRouteNames?: string[];
+        currentRouteNames?: string[];
+        routeNames?: string[];
+        canGoBack?: boolean;
+    };
+    /** Runtime snapshot from captureSnapshot() — what's actually visible */
+    snapshot?: Record<string, unknown>;
+    /** Legacy registry snapshot — kept as a fallback signal */
+    registeredComponents?: Array<{
+        id: string;
+        kind: 'field' | 'target' | 'toggle';
+        screen?: string;
+        label?: string;
+    }>;
+    /** Runtime list registry snapshot — collection metadata even when rows are virtualized. */
+    registeredLists?: Array<{
+        kind: 'list';
+        id: string;
+        component: string;
+        itemCount?: number;
+        label?: string;
+        screen?: string;
+        refreshing?: boolean;
+        empty?: boolean;
+    }>;
+}
+declare class AppilotsClient {
+    private readonly baseUrl;
+    private readonly projectId;
+    private readonly headers;
+    private readonly timeout;
+    private readonly debug;
+    private readonly mcpVersion;
+    private readonly user;
+    private sessionId;
+    /** Guard so identify fires at most once per client instance. */
+    private identified;
+    constructor(options: AppilotsClientOptions);
+    private log;
+    private describeNonJsonResponse;
+    private request;
+    createSession(userId?: string, deviceInfo?: Record<string, unknown>): Promise<string>;
+    /**
+     * Upsert the configured user into the end-users registry. Fires once
+     * per client, after the first session opens; fire-and-forget — a
+     * failed identify must never break the chat.
+     */
+    private identifyConfiguredUser;
+    destroySession(): Promise<void>;
+    getSessionId(): string | null;
+    sendMessage(content: string, context?: SendMessageContext): Promise<SendMessageResponse>;
+    /**
+     * Streaming variant of `sendMessage` — consumes the server's SSE
+     * endpoint (`/agent/message/stream`) and fires `onTextDelta` per chunk
+     * so the UI can render tokens as they arrive (OKR-008 KR1). Resolves
+     * with the same `SendMessageResponse` shape once the `done` event lands.
+     *
+     * Uses XMLHttpRequest because React Native's fetch does not expose
+     * `response.body` for incremental reads; RN's XHR delivers progressive
+     * `responseText`, which is the standard SSE transport on RN.
+     *
+     * Errors:
+     * - `StreamTransportError` — transport failed before ANY event; safe
+     *   for the caller to fall back to the non-streaming endpoint.
+     * - `StreamAbortError` (name='AbortError') — options.signal fired;
+     *   carries `partialContent` so the UI can keep what streamed.
+     */
+    sendMessageStream(content: string, context?: SendMessageContext, options?: SendMessageStreamOptions): Promise<SendMessageResponse>;
+    continueAgent(results: Array<{
+        actionId: string;
+        type: string;
+        success: boolean;
+        error?: string;
+        summary?: string;
+        /** BACKLOG 3.2 — structured failure diagnose, server uses for recovery */
+        diagnose?: {
+            category: 'component-not-found' | 'disabled' | 'validation' | 'network-5xx' | 'network-4xx' | 'screen-timeout' | 'ambiguous-target' | 'unknown';
+            visibleMessage?: string;
+            fieldId?: string;
+            targetId?: string;
+            screen?: string;
+            httpStatus?: number;
+            /** Candidate ids when resolution failed due to ambiguity. */
+            candidates?: string[];
+            recoverable?: boolean;
+            requiresUserInput?: boolean;
+        };
+        /** BACKLOG 3.2 — how many times this fingerprint has been retried (1 = first retry). */
+        recoveryAttempt?: number;
+        /** BACKLOG 3.2 — set when SDK has hit the per-action retry cap. */
+        recoveryExhausted?: boolean;
+        /**
+         * Set when a handler reported success but the expected visible
+         * side-effect did not happen, e.g. navigate returned but route stayed.
+         */
+        toolWithoutEffect?: boolean;
+        effect?: 'unknown' | 'none' | 'partial' | 'changed' | 'completed';
+        userVisibleStatusKey?: string;
+    }>, context: Record<string, unknown>, hop: number): Promise<SendMessageResponse & {
+        isDone: boolean;
+        hop: number;
+    }>;
+    executeAction(actionId: string): Promise<AgentAction>;
+    /**
+     * Rewrite an action's type when the AI used a semantically-misclassified
+     * action type. The most common case: the LLM emits
+     *   { type: 'ui_interaction', payload: { action: 'select', targetId, value } }
+     * to mean "set this field's value", which is really a form_fill. We detect
+     * that here and convert it before normalization, so the executor sees the
+     * right action shape and the field's setValue() is called instead of a
+     * meaningless press on a non-pressable component.
+     */
+    private rewriteActionTypeIfNeeded;
+    /**
+     * Normalize API tool call payloads to match SDK's expected payload types.
+     * The AI model may return slightly different field names than what the
+     * SDK executor expects, and may use vocabulary (e.g. "select", "scroll_to",
+     * "open") that the SDK doesn't natively support — we remap those to the
+     * nearest equivalent here so the executor never sees an "unknown action".
+     */
+    private normalizePayload;
+    /**
+     * Legacy per-action status report. The agentic chat loop reports via
+     * `continueAgent` (which carries diagnose + a fresh snapshot); this
+     * endpoint remains for apps driving actions manually through
+     * `useAppilotsActions`. `diagnose` is forwarded when provided so even
+     * the legacy path gives the server a failure category.
+     */
+    completeAction(actionId: string, success: boolean, error?: string, diagnose?: Record<string, unknown>): Promise<void>;
+    /**
+     * Fetch actions the server has persisted but that haven't been
+     * completed yet. Use after an SSE drop or a hard error to recover
+     * the batch without losing the actions the model already decided.
+     *
+     * Returns an empty array if there are no pending actions or if the
+     * call fails — never throws.
+     */
+    recoverPendingActions(sessionId?: string): Promise<AgentAction[]>;
+    /**
+     * Fetch dev-defined and empirically-popular prompts to seed the chat
+     * empty-state with one-tap chips. Cheap (cached server-side for 1h) but
+     * still a network hit, so callers should debounce around chat-open.
+     *
+     * @param screen Optional — when provided, response includes screen-scoped
+     *               popular prompts in addition to globals.
+     */
+    getPopularPrompts(screen?: string, limit?: number): Promise<{
+        devDefined: string[];
+        screenPopular: string[];
+        globalPopular: string[];
+        computedAt: string;
+    }>;
+    /**
+     * Fetch the project's dashboard-configured personalization (theme,
+     * branding, FAB color/image, locale...). Called by `AppilotsProvider`
+     * once on mount — cheap (cached server-side for 1h) and applied by
+     * `AppilotsChat` as a fallback for props not set explicitly in code.
+     *
+     * Throws on network/HTTP failure — the provider treats any failure as
+     * "no remote config" and stays on props/defaults.
+     */
+    getPersonalization(): Promise<RemotePersonalization>;
+    /**
+     * Ask for a human operator. Idempotent: if the session already has
+     * an open escalation the server returns it instead of creating a
+     * duplicate. Creates the session first when the chat had none yet
+     * (the server sends it back and we adopt it, so the whole
+     * conversation stays under one sessionId).
+     */
+    requestEscalation(reason: 'user_requested' | 'agent_gave_up', note?: string): Promise<{
+        escalationId: string;
+        status: 'pending' | 'active';
+    }>;
+    /**
+     * Tell the server the user walked away from the conversation (chat
+     * cleared) so the escalation is closed instead of leaving the
+     * operator talking to nobody. Fire-and-forget: never throws — the
+     * local cleanup must proceed even if the network is gone.
+     */
+    abandonEscalation(escalationId: string): Promise<void>;
+    /** User message routed to the human operator (no LLM involved). */
+    sendEscalationMessage(escalationId: string, content: string): Promise<void>;
+    /**
+     * Poll fallback / reconnect catch-up: status + operator messages
+     * created after `since` (ISO timestamp of the last one we have).
+     */
+    getEscalationUpdates(escalationId: string, since?: string): Promise<{
+        status: 'pending' | 'active' | 'resolved';
+        messages: Array<{
+            id: string;
+            content: string;
+            createdAt: string;
+        }>;
+    }>;
+    /**
+     * Open the escalation SSE channel — operator replies + status
+     * changes pushed live. Same XHR transport as `sendMessageStream`
+     * (RN's fetch can't read a body incrementally).
+     *
+     * Long-lived by design: no idle watchdog — the server pings every
+     * 25s, and a genuinely dead connection surfaces as `onClose`, which
+     * the hook answers with a backoff reconnect + `since` catch-up.
+     * Returns a close function; closing never fires `onClose`.
+     */
+    openEscalationStream(escalationId: string, handlers: {
+        since?: string;
+        onHumanMessage: (message: {
+            id: string;
+            content: string;
+            createdAt: string;
+        }) => void;
+        onStatus: (status: 'pending' | 'active' | 'resolved', operatorName?: string) => void;
+        /** Transport ended (error or server close) — caller decides on reconnect. */
+        onClose: () => void;
+    }): () => 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;
+    /** API base URL (defaults to Appilots cloud) */
+    apiBaseUrl?: string;
+    /** SDK API key (ak_...) for authenticating with the backend */
+    apiKey?: string;
+    /** Agent permissions for this app instance */
+    permissions?: AgentPermissions;
+    /** Enable debug logging */
+    debug?: boolean;
+    /**
+     * Host app version (e.g. package.json version). Forwarded to the API
+     * as `X-App-Version` so the server can serve the MCP document matching
+     * this app build (OTA fleets run several versions at once).
+     */
+    appVersion?: string;
+    /** Version of the MCP doc bundled with this build (stale-doc telemetry). */
+    mcpVersion?: string;
+    /**
+     * Who the app's current user is. Sessions carry `user.id` as
+     * externalUserId, and name/identifiers are upserted into the
+     * end-users registry so the support queue shows a person instead of
+     * "Usuário anônimo". Identifiers never reach the LLM.
+     */
+    user?: AppilotsUser;
+    /**
+     * Fetch the dashboard-configured personalization (theme, branding,
+     * FAB color, locale...) once on provider mount and apply it as a
+     * fallback for AppilotsChat props not set explicitly in code.
+     *
+     * Set to `false` to opt out — this is the SDK's only automatic
+     * network call before the user interacts, so apps with strict
+     * network/privacy posture can keep today's 100%-manual behavior.
+     * @default true
+     */
+    fetchPersonalization?: boolean;
+}
+interface AppilotsProviderProps {
+    /**
+     * SDK config. If omitted, auto-loads from `.appilotsrc` via the Metro
+     * resolver (requires `withAppilots()` in metro.config.js).
+     */
+    config?: AppilotsConfig;
+    children: React__default.ReactNode;
+    /** Optional custom client instance (if not provided, one is auto-created from config) */
+    client?: AppilotsClient;
+}
+interface AppilotsContextValue {
+    config: AppilotsConfig;
+    client: AppilotsClient;
+    subscribe: (handler: AppilotsEventHandler) => () => void;
+    emit: (event: AppilotsEvent) => void;
+    /**
+     * Dashboard-configured personalization fetched on mount. `null` until
+     * the fetch resolves — and forever, if it fails or is opted out
+     * (`fetchPersonalization: false`). Consumers must treat `null` as
+     * "use props/defaults"; the chat renders immediately with defaults
+     * and re-renders once this lands (accepted cold-start flash).
+     */
+    remotePersonalization: RemotePersonalization | null;
+}
+declare function AppilotsProvider({ config: configProp, children, client: externalClient }: AppilotsProviderProps): React__default.JSX.Element;
+declare function useAppilotsContext(): AppilotsContextValue;
+
+/**
+ * Convenience hook that combines all Appilots hooks into a single return value.
+ *
+ * @example
+ * ```tsx
+ * const { messages, sendMessage, currentScreen, pendingActions } = useAppilots();
+ * ```
+ */
+declare function useAppilots(): {
+    config: AppilotsConfig;
+    client: AppilotsClient;
+    messages: ChatMessage[];
+    isLoading: boolean;
+    error: string | null;
+    sendMessage: (content: string) => Promise<void>;
+    clearMessages: () => void;
+    clearError: () => void;
+    currentScreen: string | null;
+    navigationHistory: string[];
+    setCurrentScreen: (screenName: string) => void;
+    navigationRef: React$1.MutableRefObject<any>;
+    pendingActions: AgentAction[];
+    executingActions: AgentAction[];
+    completedActions: AgentAction[];
+    approveAction: (actionId: string) => Promise<boolean>;
+    rejectAction: (actionId: string) => Promise<void>;
+};
+
+interface UseAppilotsNavigationReturn {
+    currentScreen: string | null;
+    navigationHistory: string[];
+    setCurrentScreen: (screenName: string) => void;
+    /** Navigation ref setter — attach to your NavigationContainer */
+    navigationRef: React.MutableRefObject<any>;
+}
+/**
+ * Hook for tracking navigation state and enabling agent-driven navigation.
+ *
+ * @example
+ * ```tsx
+ * const { currentScreen, navigationRef } = useAppilotsNavigation();
+ *
+ * return (
+ *   <NavigationContainer ref={navigationRef}>
+ *     <Stack.Navigator />
+ *   </NavigationContainer>
+ * );
+ * ```
+ */
+declare function useAppilotsNavigation(): UseAppilotsNavigationReturn;
+
+interface UseAppilotsChatReturn {
+    messages: ChatMessage[];
+    isLoading: boolean;
+    loadingStatusKey: 'thinking' | 'statusAnalyzing' | 'statusWaitingApp' | 'statusAdjusting';
+    error: string | null;
+    pendingActions: AgentAction[];
+    /**
+     * Open escalation, or null. While set, `sendMessage` routes to the
+     * human channel — the agent session itself is never interrupted.
+     */
+    escalation: EscalationState | null;
+    /**
+     * Hand the conversation to a human operator (docs/human-escalation.md).
+     * Idempotent while an escalation is open. `agent_gave_up` is used by
+     * the auto-offer chip; the header button sends `user_requested`.
+     */
+    requestHuman: (reason?: 'user_requested' | 'agent_gave_up') => Promise<void>;
+    sendMessage: (content: string) => Promise<void>;
+    /**
+     * Cancels the in-flight generation (OKR-008 KR4). Streamed partial
+     * text is kept in the transcript; a no-op when nothing is in flight.
+     * Cancellation only covers the generation phase — once actions start
+     * executing on-device they run to completion (interrupting a half-done
+     * form fill would leave the app in a worse state than finishing it).
+     */
+    cancelMessage: () => void;
+    clearMessages: () => void;
+    clearError: () => void;
+}
+interface UseAppilotsChatOptions {
+    /** User-facing prefix for client-side failures before the relay can answer. */
+    errorPrefix?: string;
+    /**
+     * Stream assistant replies token-by-token via SSE (default true).
+     * When the streaming transport fails before any output, the hook
+     * falls back to the non-streaming endpoint transparently.
+     */
+    streaming?: boolean;
+    /** Localized escalation copy — see EscalationStrings. */
+    escalationStrings?: EscalationStrings;
+}
+/**
+ * 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();
+ *
+ * const handleSend = () => {
+ *   sendMessage('Navigate to settings');
+ * };
+ * ```
+ */
+declare function useAppilotsChat(options?: UseAppilotsChatOptions): UseAppilotsChatReturn;
+
+interface UseAppilotsActionsOptions {
+    /**
+     * Navigation ref from useAppilotsNavigation().
+     * Required for navigate actions to work.
+     */
+    navigationRef?: React.MutableRefObject<any>;
+    /**
+     * If true, actions are executed automatically without user approval.
+     * Confirm actions always require approval regardless of this setting.
+     * @default false
+     */
+    autoExecute?: boolean;
+}
+interface UseAppilotsActionsReturn {
+    pendingActions: AgentAction[];
+    executingActions: AgentAction[];
+    completedActions: AgentAction[];
+    approveAction: (actionId: string) => Promise<boolean>;
+    rejectAction: (actionId: string) => Promise<void>;
+}
+/**
+ * Hook for monitoring and controlling agent actions.
+ *
+ * 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
+ * const { navigationRef } = useAppilotsNavigation();
+ * const { pendingActions, approveAction, rejectAction } = useAppilotsActions({
+ *   navigationRef,
+ *   autoExecute: false,
+ * });
+ * ```
+ */
+declare function useAppilotsActions(options?: UseAppilotsActionsOptions): UseAppilotsActionsReturn;
+
+/**
+ * ComponentRegistry — Central registry mapping component IDs to their
+ * refs, callbacks, and metadata so the ActionExecutor can find and
+ * interact with live UI elements.
+ *
+ * Screens register their interactive components via hooks
+ * (useAppilotsField, useAppilotsTarget, useAppilotsToggle).
+ * When the AI agent returns an action (e.g. form_fill with fieldId "plate"),
+ * the executor looks up "plate" here and calls the associated setter.
+ */
+type ComponentKind = 'field' | 'target' | 'toggle' | 'slider';
+interface FieldEntry {
+    kind: 'field';
+    /** Current value of the field */
+    getValue: () => string;
+    /** Set the field value programmatically */
+    setValue: (value: string) => void;
+    /** Optional: focus the input */
+    focus?: () => void;
+    /** Field type hint for the executor */
+    fieldType?: 'text' | 'select' | 'toggle' | 'date' | 'number' | 'custom';
+    /** Human-readable label */
+    label?: string;
+    /** Screen where this field is registered */
+    screen?: string;
+}
+interface TargetEntry {
+    kind: 'target';
+    /** Execute the primary action (press) */
+    press: () => void;
+    /** Optional: long press */
+    longPress?: () => void;
+    /** Optional: scroll to this element */
+    scrollTo?: () => void;
+    /** Human-readable label */
+    label?: string;
+    /** Screen where this target is registered */
+    screen?: string;
+}
+interface ToggleEntry {
+    kind: 'toggle';
+    /** Current value */
+    getValue: () => boolean;
+    /** Set the toggle value */
+    setValue: (value: boolean) => void;
+    /** Human-readable label */
+    label?: string;
+    /** Screen where this toggle is registered */
+    screen?: string;
+}
+interface SliderEntry {
+    kind: 'slider';
+    /** Current numeric value */
+    getValue: () => number;
+    /**
+     * Set the slider value. The executor clamps to [min, max] and snaps
+     * to `step` BEFORE calling this, so implementations can trust the
+     * value — but re-validating is harmless.
+     */
+    setValue: (value: number) => void;
+    /** Lower bound (inclusive) */
+    min: number;
+    /** Upper bound (inclusive) */
+    max: number;
+    /** Step to snap to (omitted = continuous) */
+    step?: number;
+    /** Human-readable label */
+    label?: string;
+    /** Screen where this slider is registered */
+    screen?: string;
+}
+type ComponentEntry = FieldEntry | TargetEntry | ToggleEntry | SliderEntry;
+type Listener = (id: string, entry: ComponentEntry | null) => void;
+/**
+ * Public type for a registry instance. Both the singleton and any
+ * instance returned by `createComponentRegistry()` satisfy this.
+ *
+ * The class itself stays internal — devs construct via the factory
+ * to keep the surface minimal and future-proof.
+ */
+type ComponentRegistry = ComponentRegistryImpl;
+declare class ComponentRegistryImpl {
+    private components;
+    private listeners;
+    /**
+     * Register a component. If an entry with the same ID already exists,
+     * it is replaced (this handles re-renders / hot-reload).
+     */
+    register(id: string, entry: ComponentEntry): void;
+    /**
+     * Unregister a component (typically on unmount).
+     */
+    unregister(id: string): void;
+    /**
+     * Look up a component by its ID.
+     */
+    get(id: string): ComponentEntry | undefined;
+    /**
+     * Get a typed entry or undefined.
+     */
+    getField(id: string): FieldEntry | undefined;
+    getTarget(id: string): TargetEntry | undefined;
+    getToggle(id: string): ToggleEntry | undefined;
+    getSlider(id: string): SliderEntry | undefined;
+    /**
+     * Get all components on a given screen.
+     */
+    getByScreen(screen: string): Map<string, ComponentEntry>;
+    /**
+     * Get all components of a given kind.
+     */
+    getByKind(kind: ComponentKind): Map<string, ComponentEntry>;
+    /**
+     * List all registered component IDs with their kind and screen.
+     * Useful for debugging and for the AI to know what's available.
+     */
+    snapshot(): Array<{
+        id: string;
+        kind: ComponentKind;
+        screen?: string;
+        label?: string;
+    }>;
+    /**
+     * Subscribe to registry changes.
+     * Returns an unsubscribe function.
+     */
+    subscribe(listener: Listener): () => void;
+    /**
+     * Clear all entries (useful for testing or full reset).
+     */
+    clear(): void;
+    /** Number of registered components */
+    get size(): number;
+    private notify;
+}
+/**
+ * Singleton registry instance shared across the entire SDK by default.
+ *
+ * Apps with a single Appilots session (the overwhelmingly common case)
+ * never need anything else — hooks, handlers, and auto-tracking all
+ * read from this singleton.
+ *
+ * For multi-tenant or micro-front-end setups where two Appilots
+ * sessions might coexist in the same JS process, use
+ * `createComponentRegistry()` to obtain a fresh instance and pass it
+ * via `<AppilotsRegistryProvider value={...}>`. Hooks resolve via
+ * context first, falling back to this singleton.
+ *
+ * The singleton stays in place to keep the existing public API stable
+ * — pré-mortem 2.8 is "future risk", not "current bug".
+ */
+declare const componentRegistry: ComponentRegistry;
+/**
+ * Create a fresh, isolated ComponentRegistry instance. Pair with
+ * `<AppilotsRegistryProvider value={...}>` to scope auto-tracking and
+ * hooks to that registry instead of the global singleton.
+ *
+ * @example
+ * ```tsx
+ * const tenantRegistry = createComponentRegistry();
+ * <AppilotsRegistryProvider value={tenantRegistry}>
+ *   <TenantApp />
+ * </AppilotsRegistryProvider>
+ * ```
+ */
+declare function createComponentRegistry(): ComponentRegistry;
+
+/**
+ * useAppilotsField — Register a text input (or similar field) with the
+ * ComponentRegistry so the AI agent can fill it via form_fill actions.
+ *
+ * Usage:
+ * ```tsx
+ * const [plate, setPlate] = useState('');
+ * const plateRef = useRef<TextInput>(null);
+ *
+ * useAppilotsField('plate', {
+ *   value: plate,
+ *   onChangeText: setPlate,
+ *   ref: plateRef,           // optional — enables focus()
+ *   fieldType: 'text',       // optional — hint for executor
+ *   label: 'License Plate',  // optional — human-readable name
+ *   screen: 'VehicleForm',   // optional — scoped to screen
+ * });
+ *
+ * return <TextInput ref={plateRef} value={plate} onChangeText={setPlate} />;
+ * ```
+ */
+
+interface UseAppilotsFieldOptions {
+    /** Current value of the field */
+    value: string;
+    /** Callback to update the value (same signature as TextInput.onChangeText) */
+    onChangeText: (text: string) => void;
+    /** Optional ref to the TextInput for focus support */
+    ref?: React.RefObject<any>;
+    /** Field type hint */
+    fieldType?: FieldEntry['fieldType'];
+    /** Human-readable label */
+    label?: string;
+    /** Screen name this field belongs to */
+    screen?: string;
+}
+/**
+ * Register a field with the Appilots ComponentRegistry.
+ * Automatically unregisters on unmount.
+ *
+ * @param id - Unique identifier for this field (e.g. "plate", "customerName")
+ * @param options - Field configuration
+ */
+declare function useAppilotsField(id: string, options: UseAppilotsFieldOptions): void;
+
+/**
+ * useAppilotsTarget — Register a pressable UI element (button, card, link)
+ * with the ComponentRegistry so the AI agent can interact with it.
+ *
+ * Usage:
+ * ```tsx
+ * const handleSubmit = () => { ... };
+ *
+ * useAppilotsTarget('submitVehicle', {
+ *   onPress: handleSubmit,
+ *   label: 'Submit Vehicle',
+ *   screen: 'VehicleForm',
+ * });
+ *
+ * return <Button title="Submit" onPress={handleSubmit} />;
+ * ```
+ */
+interface UseAppilotsTargetOptions {
+    /** Primary press handler */
+    onPress: () => void;
+    /** Optional long-press handler */
+    onLongPress?: () => void;
+    /** Optional scroll-to handler (scroll this element into view) */
+    onScrollTo?: () => void;
+    /** Human-readable label */
+    label?: string;
+    /** Screen name this target belongs to */
+    screen?: string;
+}
+/**
+ * Register a pressable target with the Appilots ComponentRegistry.
+ * Automatically unregisters on unmount.
+ *
+ * @param id - Unique identifier (e.g. "submitVehicle", "openSettings")
+ * @param options - Target configuration
+ */
+declare function useAppilotsTarget(id: string, options: UseAppilotsTargetOptions): void;
+
+/**
+ * useAppilotsToggle — Register a toggle/switch with the ComponentRegistry
+ * so the AI agent can flip it via ui_interaction actions.
+ *
+ * Usage:
+ * ```tsx
+ * const [pushEnabled, setPushEnabled] = useState(false);
+ *
+ * useAppilotsToggle('pushNotifications', {
+ *   value: pushEnabled,
+ *   onValueChange: setPushEnabled,
+ *   label: 'Push Notifications',
+ *   screen: 'Settings',
+ * });
+ *
+ * return <Switch value={pushEnabled} onValueChange={setPushEnabled} />;
+ * ```
+ */
+interface UseAppilotsToggleOptions {
+    /** Current toggle value */
+    value: boolean;
+    /** Callback when value changes */
+    onValueChange: (value: boolean) => void;
+    /** Human-readable label */
+    label?: string;
+    /** Screen name this toggle belongs to */
+    screen?: string;
+}
+/**
+ * Register a toggle with the Appilots ComponentRegistry.
+ * Automatically unregisters on unmount.
+ *
+ * @param id - Unique identifier (e.g. "pushNotifications", "darkMode")
+ * @param options - Toggle configuration
+ */
+declare function useAppilotsToggle(id: string, options: UseAppilotsToggleOptions): void;
+
+/**
+ * useAppilotsSlider — Register a slider / adjustable numeric control with
+ * the ComponentRegistry so the AI agent can set it via
+ * `ui_interaction action="set_value"` actions.
+ *
+ * Registration is what makes a slider agent-operable end to end:
+ * captureSnapshot() reads this entry to advertise the slider (with
+ * min/max/step) in the observation, and the executor dispatches
+ * set_value through the same entry — clamping to [min, max] and
+ * snapping to `step` before calling onValueChange.
+ *
+ * Usage:
+ * ```tsx
+ * const [mileage, setMileage] = useState(0);
+ *
+ * useAppilotsSlider('quilometragem', {
+ *   value: mileage,
+ *   onValueChange: setMileage,
+ *   min: 0,
+ *   max: 300000,
+ *   step: 500,
+ *   label: 'Quilometragem',
+ *   screen: 'VehicleCreate',
+ * });
+ *
+ * return <MySlider value={mileage} onChange={setMileage} min={0} max={300000} />;
+ * ```
+ */
+interface UseAppilotsSliderOptions {
+    /** Current slider value */
+    value: number;
+    /** Callback when value changes */
+    onValueChange: (value: number) => void;
+    /** Lower bound (inclusive) — advertised in the observation and enforced by the executor */
+    min: number;
+    /** Upper bound (inclusive) — advertised in the observation and enforced by the executor */
+    max: number;
+    /** Step the executor snaps to (omit for a continuous slider) */
+    step?: number;
+    /** Human-readable label */
+    label?: string;
+    /** Screen name this slider belongs to */
+    screen?: string;
+}
+/**
+ * Register a slider with the Appilots ComponentRegistry.
+ * Automatically unregisters on unmount.
+ *
+ * @param id - Unique identifier (e.g. "quilometragem", "volume")
+ * @param options - Slider configuration
+ */
+declare function useAppilotsSlider(id: string, options: UseAppilotsSliderOptions): void;
+
+interface SuggestedPrompt {
+    /** Display label shown on the chip and inserted into the input on tap. */
+    text: string;
+    /** Where this prompt came from. Useful for analytics or theming. */
+    source: 'dev-defined' | 'screen-popular' | 'global-popular';
+}
+interface UseSuggestedPromptsOptions {
+    /**
+     * Whether the chat is currently open. Hook only fetches while open, so
+     * suggestions don't waste a roundtrip when the chat is minimised.
+     */
+    enabled: boolean;
+    /** Max chips to return. Default 4. */
+    limit?: number;
+}
+interface UseSuggestedPromptsReturn {
+    prompts: SuggestedPrompt[];
+    isLoading: boolean;
+    /** Re-runs the fetch — call after navigation so chips refresh. */
+    refetch: () => void;
+}
+/**
+ * Returns ranked suggested prompts to render as chips in the chat
+ * empty-state. Three sources are merged in priority order:
+ *
+ *   1. **Dev-defined** — from `registerScreen({ suggestedPrompts })` in the
+ *      current app, read synchronously from the local screen registry.
+ *      First-class signal, always wins.
+ *
+ *   2. **Screen-popular** — historical user prompts sent FROM this screen,
+ *      mined server-side from agentMessages history.
+ *
+ *   3. **Global-popular** — historical user prompts across the project.
+ *      Fallback for screens with no history yet.
+ *
+ * The hook re-fetches whenever the active screen changes so chips always
+ * match where the user is right now. Server response is cached 1h, so
+ * fetches are cheap.
+ *
+ * @example
+ * ```tsx
+ * const { prompts } = useSuggestedPrompts({ enabled: chatVisible });
+ * return prompts.map((p) => (
+ *   <Chip key={p.text} onPress={() => setInput(p.text)}>{p.text}</Chip>
+ * ));
+ * ```
+ */
+declare function useSuggestedPrompts(options: UseSuggestedPromptsOptions): UseSuggestedPromptsReturn;
+
+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 };