@appilots/sdk 0.7.0 → 0.10.0

package/dist/{index-nI-s3Exg.d.ts → index-BPZ0j71S.d.ts}

@@ -210,7 +210,8 @@ interface AgentAction {
     destructive?: boolean;
 }
 interface NavigationPayload {
-    screenName: string;
+    /** Absent only for `goBack`, which has no destination to name (#398). */
+    screenName?: string;
     params?: Record<string, unknown>;
     navigationAction: 'push' | 'navigate' | 'replace' | 'goBack' | 'reset';
     /**
@@ -303,11 +304,13 @@ interface EscalationState {
 /**
  * Mirrors `introspectionDiagnosticsSchema` on the wire. Declared here
  * rather than imported so client-core stays free of the server's
- * validator package.
+ * validator package — which means the two must be kept in step by hand.
+ * Adding a reason to one and not the other is a typecheck failure at
+ * the SDK, not a silent wire mismatch.
  */
 interface IntrospectionDiagnosticsInput {
     captured: boolean;
-    failureReason?: 'sentinel-missing-internals' | 'never-mounted' | null;
+    failureReason?: 'sentinel-missing-internals' | 'never-mounted' | 'render-crashed' | 'names-mangled' | 'walk-recognized-nothing' | null;
     reactVersion?: string | null;
     failureCount?: number;
 }
@@ -347,6 +350,20 @@ interface AppilotsClientOptions {
      * essential for OTA-updated fleets where multiple app versions coexist.
      */
     appVersion?: string;
+    /**
+     * The version of the SDK package driving this client, sent as
+     * `X-Appilots-Sdk-Version`. Each platform SDK passes its OWN published
+     * version (`@appilots/sdk`, `@appilots/web-sdk`); `@appilots/client-core`
+     * is private and never published, so its version means nothing to a
+     * customer and is only the fallback for a caller that constructs
+     * `AppilotsClient` directly.
+     *
+     * This is the server's only evidence of which SDKs are in the field,
+     * and therefore the only input to "is this field safe to tighten yet?"
+     * (issue #312). Leaving it wrong is not cosmetic: it makes the
+     * backward-compatibility promise in CLAUDE.md unverifiable.
+     */
+    sdkVersion?: string;
     /**
      * Who the app's current user is. `id` becomes the session's
      * externalUserId; `name`/`identifiers` are upserted into the
@@ -456,6 +473,7 @@ interface SendMessageContext {
         empty?: boolean;
     }>;
 }
+
 declare class AppilotsClient {
     private readonly baseUrl;
     private readonly projectId;
@@ -469,6 +487,18 @@ declare class AppilotsClient {
     /** Guard so identify fires at most once per client instance. */
     private identified;
     constructor(options: AppilotsClientOptions);
+    /**
+     * A 404 on an `/agent/*` path is almost never a missing record — those
+     * routes are static. It means the request reached SOMETHING that is not
+     * this API, or reached it at the wrong mount point, and the server's own
+     * message ("Route not found") tells the integrator nothing about which.
+     *
+     * The symptom is unmistakable once you have seen it: every message
+     * fails, including a plain "hello" that needs no tool at all, because
+     * nothing ever reaches the agent. Left as-is it reads like the agent is
+     * broken.
+     */
+    private explainIfMisroutedBaseUrl;
     private log;
     private describeNonJsonResponse;
     private request;
@@ -664,9 +694,45 @@ declare class AppilotsClient {
  * produces this same shape; the wire contract it feeds is
  * `agentSnapshotSchema` in `@appilots/shared`.
  */
+/**
+ * How much the walker actually knows about an element's identifier.
+ *
+ * The observation used to say nothing here, so `btn-3` — an ordinal the
+ * walker invented — read to the model exactly like `testID="submit-order"`,
+ * which a developer wrote down on purpose. That is how a confident press on
+ * the wrong control happens.
+ *
+ * - `declared`   the app named it: `testID` / `data-testid` /
+ *                `accessibilityLabel` / `aria-label`. Stable across renders
+ *                and across releases; safe to copy into a tool call.
+ * - `derived`    folded from what the user can see — the button's own text,
+ *                a `label` or `placeholder` prop. Stable as long as the copy
+ *                does not change, and it changes with the app's language.
+ * - `positional` nothing but an ordinal in the current snapshot. Valid for
+ *                this observation only: a re-render, a scroll or an inserted
+ *                sibling moves it.
+ *
+ * ABSENT means unknown, NOT `declared` — clients published before this field
+ * existed send no provenance at all, and a missing value must never be read
+ * as the most trustworthy one.
+ */
+type IdentityProvenance = 'declared' | 'derived' | 'positional';
 interface InputSnapshot {
     /** Best identifier — testID/data-testid, accessibilityLabel/aria-label, or placeholder */
     id?: string;
+    /** How `id` was obtained. See {@link IdentityProvenance}. */
+    provenance?: IdentityProvenance;
+    /**
+     * False when the control is mounted but currently outside the window —
+     * below the fold of a ScrollView, scrolled off the top, pushed sideways
+     * by a carousel.
+     *
+     * ABSENT MEANS UNKNOWN. The old React Native architecture cannot report a
+     * synchronous window-relative rect, and no SDK published before this
+     * field existed reports one at all; reading absence as `false` would make
+     * the agent refuse to press a control the user is looking at.
+     */
+    onScreen?: boolean;
     /** Human-readable label inferred from accessibility metadata or sibling text */
     label?: string;
     /** Current value (only present for controlled inputs) */
@@ -679,6 +745,15 @@ interface InputSnapshot {
     secure?: boolean;
     /** Inferred type based on the platform's input-type metadata */
     type?: 'text' | 'email' | 'number' | 'phone' | 'password';
+    /**
+     * True when pressing return on this field submits — RN's
+     * `onSubmitEditing`, the web's implicit form submit.
+     *
+     * On a search box, a one-field login or a chat composer this IS the
+     * submit; the screen has no button and never will. Absent means the
+     * field declares no such handler, so the form needs a button.
+     */
+    submitsOnReturn?: boolean;
     /**
      * True when this input lives inside a currently-visible modal. When a
      * modal is open, only inModal elements can actually receive input —
@@ -689,14 +764,35 @@ interface InputSnapshot {
 interface ButtonSnapshot {
     /** Best identifier — testID/data-testid, accessibilityLabel/aria-label, or inferred from child text */
     id?: string;
+    /** How `id` was obtained. See {@link IdentityProvenance}. */
+    provenance?: IdentityProvenance;
+    /**
+     * False when the control is mounted but currently outside the window —
+     * below the fold of a ScrollView, scrolled off the top, pushed sideways
+     * by a carousel.
+     *
+     * ABSENT MEANS UNKNOWN. The old React Native architecture cannot report a
+     * synchronous window-relative rect, and no SDK published before this
+     * field existed reports one at all; reading absence as `false` would make
+     * the agent refuse to press a control the user is looking at.
+     */
+    onScreen?: boolean;
     /** 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.
+     * Whether this control is currently in its ON state.
+     *
+     * Covers both accessibility states that mean it, because the agent
+     * needs the same thing from either: `accessibilityState.selected`
+     * (grouped, mutually-exclusive controls — segmented controls, radio
+     * groups, each option its own pressable target) and
+     * `accessibilityState.checked` (an independent checkbox).
+     *
+     * Absent means "not on OR not observable" — the walker cannot tell a
+     * custom checkbox that declares no a11y state from an ordinary button,
+     * so absence is never proof that a box is unticked.
      */
     selected?: boolean;
     /** True when this button lives inside a currently-visible modal. */
@@ -705,6 +801,19 @@ interface ButtonSnapshot {
 interface ToggleSnapshot {
     /** Best identifier */
     id?: string;
+    /** How `id` was obtained. See {@link IdentityProvenance}. */
+    provenance?: IdentityProvenance;
+    /**
+     * False when the control is mounted but currently outside the window —
+     * below the fold of a ScrollView, scrolled off the top, pushed sideways
+     * by a carousel.
+     *
+     * ABSENT MEANS UNKNOWN. The old React Native architecture cannot report a
+     * synchronous window-relative rect, and no SDK published before this
+     * field existed reports one at all; reading absence as `false` would make
+     * the agent refuse to press a control the user is looking at.
+     */
+    onScreen?: boolean;
     /** Human-readable label */
     label?: string;
     /** Current on/off state */
@@ -715,6 +824,19 @@ interface ToggleSnapshot {
 interface SliderSnapshot {
     /** Registry id — the executable handle. */
     id?: string;
+    /** How `id` was obtained. See {@link IdentityProvenance}. */
+    provenance?: IdentityProvenance;
+    /**
+     * False when the control is mounted but currently outside the window —
+     * below the fold of a ScrollView, scrolled off the top, pushed sideways
+     * by a carousel.
+     *
+     * ABSENT MEANS UNKNOWN. The old React Native architecture cannot report a
+     * synchronous window-relative rect, and no SDK published before this
+     * field existed reports one at all; reading absence as `false` would make
+     * the agent refuse to press a control the user is looking at.
+     */
+    onScreen?: boolean;
     /** Human-readable label */
     label?: string;
     /** Current numeric value */
@@ -805,6 +927,51 @@ interface ListDataPreviewEntry {
     /** Short human-readable projection of the item (capped length). */
     text: string;
 }
+/**
+ * A scrollable surface that is NOT a collection — a long form, a detail
+ * page, a settings screen inside a `ScrollView`.
+ *
+ * It exists as its own concept, and not as a `ListSnapshot` with zero
+ * rows, because everything the agent knows how to do with a list
+ * (ordinals, totals, "select the third one") is meaningless here. The
+ * only affordance is paging toward content below the fold — and without
+ * it, a screen taller than the viewport ends at the fold.
+ */
+interface ScrollableSnapshot {
+    /** Runtime id — the handle `scroll_list` addresses. */
+    id: string;
+    /** The container component as observed: ScrollView, ... */
+    containerType: string;
+    /** Human-readable label if the app supplied one. */
+    label?: string;
+    /** Current scroll offset in px. */
+    scrollOffsetY?: number;
+    /** True when there is content above the viewport. */
+    canScrollUp?: boolean;
+    /** True when there is content below the viewport. */
+    canScrollDown?: boolean;
+    /** True when the surface scrolls sideways rather than vertically. */
+    horizontal?: boolean;
+}
+/**
+ * A platform dialog covering the screen — React Native's `Alert.alert`,
+ * an action sheet, an OS permission prompt.
+ *
+ * It renders outside React, so no amount of tree walking finds it. It
+ * has to be reported separately or the agent keeps operating the app
+ * underneath a dialog that blocks every real finger.
+ */
+interface NativeDialogSnapshot {
+    /** Stable for as long as this dialog is open. */
+    id: string;
+    title?: string;
+    message?: string;
+    /** The buttons the user can press. Never empty. */
+    buttons: Array<{
+        label: string;
+        style?: 'default' | 'cancel' | 'destructive';
+    }>;
+}
 interface ChoiceOptionSnapshot {
     /** 1-indexed option position within this group. */
     index: number;
@@ -859,6 +1026,24 @@ interface InteractionElementSnapshot {
     selected?: boolean;
     /** Source that produced the element. */
     source?: 'list' | 'button' | 'input' | 'toggle' | 'slider' | 'choice';
+    /**
+     * How the underlying control's identifier was obtained. Carried up from
+     * the snapshot entry this element was derived from, so a consumer that
+     * only reads `elements` still knows what it is trusting. See
+     * {@link IdentityProvenance}.
+     */
+    provenance?: IdentityProvenance;
+    /**
+     * False when the control is mounted but currently outside the window —
+     * below the fold of a ScrollView, scrolled off the top, pushed sideways
+     * by a carousel.
+     *
+     * ABSENT MEANS UNKNOWN. The old React Native architecture cannot report a
+     * synchronous window-relative rect, and no SDK published before this
+     * field existed reports one at all; reading absence as `false` would make
+     * the agent refuse to press a control the user is looking at.
+     */
+    onScreen?: boolean;
     /** Legacy/fallback target id, if any. */
     targetId?: string;
     /** Context for row/list options. */
@@ -869,6 +1054,37 @@ interface InteractionElementSnapshot {
      */
     inModal?: boolean;
 }
+/** Window-relative box, in the coordinate space the platform reports. */
+interface ElementRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * What the CLIENT keeps about an element, which is strictly more than what
+ * the model is told about it.
+ *
+ * The wire shape (`InteractionElementSnapshot`) is sized for a language
+ * model: names, roles, state, everything it needs to decide. This one adds
+ * what only the executor needs — coordinates it will never read aloud —
+ * and it exists because that data was being measured and then discarded
+ * for want of somewhere to put it that wasn't the wire.
+ *
+ * The split is the point. Anything added here is free: it never reaches
+ * `agentSnapshotSchema`, never crosses the network, and never costs a
+ * token. Anything added to the wire type is paid for on every observation
+ * of every session, so it has to earn the model's attention.
+ */
+interface InteractionElementEntry extends InteractionElementSnapshot {
+    /**
+     * Where the control was on screen when the snapshot was taken. Absent
+     * when the platform cannot measure synchronously (React Native's old
+     * architecture) or when the element came from a source with no fiber
+     * behind it.
+     */
+    rect?: ElementRect;
+}
 interface ScreenSnapshot {
     /** The currently active route name, if known */
     route: string | null;
@@ -886,6 +1102,15 @@ interface ScreenSnapshot {
     loading: boolean;
     /** Whether a modal is currently open */
     modalOpen: boolean;
+    /**
+     * A native dialog covering the screen, when the SDK could observe one.
+     *
+     * Its presence also forces `modalOpen`, because for every purpose the
+     * agent cares about it IS a modal — nothing behind it is touchable.
+     * Absence is not proof there is no dialog: an OS permission prompt or
+     * a share sheet cannot be instrumented at all.
+     */
+    nativeDialog?: NativeDialogSnapshot;
     /**
      * Lists detected in the visible tree. Each list's items have their
      * own per-item texts/buttons/inputs/toggles, NOT duplicated in the
@@ -898,16 +1123,49 @@ interface ScreenSnapshot {
      * for select-like flows where no text input exists.
      */
     choiceGroups: ChoiceGroupSnapshot[];
+    /**
+     * Scrollable surfaces that carry no rows. Absent/empty means either
+     * the screen does not scroll or the SDK could not observe that it
+     * does — never that the visible content is all the content.
+     */
+    scrollables?: ScrollableSnapshot[];
     /**
      * 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[];
+    /**
+     * Set when the walker's output exceeded the wire contract and
+     * `clampSnapshotToWireLimits` dropped part of it (see
+     * `introspection/wireLimits.ts`). Absent means the observation is
+     * complete.
+     *
+     * The server surfaces this to the model: a screen whose text was cut
+     * at 500 entries must not be read as a screen with only 500 things on
+     * it. Without the flag a truncated observation is indistinguishable
+     * from a short one.
+     */
+    truncated?: boolean;
     /** Diagnostic counts for debugging */
     stats?: {
         visitedFibers: number;
         skippedHidden: number;
+        /**
+         * How many controls the walker could name, and how well.
+         *
+         * `WalkDetectorCounts` counts RECOGNITIONS, not emissions, so a screen
+         * whose controls were all silently dropped still reported healthy
+         * detector numbers. This is the emission side: `positional` climbing is
+         * the signal that an app needs annotating, and comparing it between a
+         * debug and a release build is the first real measurement of what
+         * minification costs the agent.
+         */
+        identity?: {
+            declared: number;
+            derived: number;
+            positional: number;
+        };
     };
 }
 /**
@@ -981,13 +1239,6 @@ declare function describeAction(action: AgentAction): BreadcrumbItem;
  */
 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;
@@ -1025,6 +1276,37 @@ interface AppilotsConfig {
      * @default true
      */
     fetchPersonalization?: boolean;
+    /**
+     * While running a destructive action the user already approved on the
+     * chat's confirm card, suppress the app's OWN `Alert.alert`
+     * confirmation once — otherwise they answer the same question twice
+     * and the second dialog is one the agent cannot press.
+     *
+     * Doing that means briefly replacing a global that belongs to your
+     * app, so it is opt-outable: set `false` to keep `Alert.alert`
+     * untouched at all times and show your own dialog instead. See
+     * `platform/confirmedDestructiveAlert.ts` for the exact window.
+     * @default true
+     */
+    suppressNativeConfirm?: boolean;
+    /**
+     * Record the app's own `Alert.alert` dialogs so the agent can SEE
+     * them.
+     *
+     * A native dialog renders outside React, so it is invisible to the
+     * tree walk — and because every press invokes the React handler
+     * directly, the agent otherwise keeps operating the app underneath a
+     * dialog that blocks every real finger. With tracking on, the
+     * observation reports the dialog, presses behind it fail honestly,
+     * and the agent can answer it.
+     *
+     * Like the suppression above, this replaces a global that belongs to
+     * your app, so it is opt-outable: set `false` to keep `Alert.alert`
+     * untouched — at the cost of the agent acting blind whenever one is
+     * up. See `platform/nativeDialogTracking.ts`.
+     * @default true
+     */
+    trackNativeDialogs?: boolean;
 }
 interface AppilotsProviderProps {
     /**
@@ -1049,8 +1331,26 @@ interface AppilotsContextValue {
      * and re-renders once this lands (accepted cold-start flash).
      */
     remotePersonalization: RemotePersonalization | null;
+    /**
+     * True when the provider crashed and the error boundary degraded it.
+     * The host app is still mounted and still has a context (so its
+     * `useAppilots()` calls don't throw), but nothing is wired: `client`
+     * rejects, `emit`/`subscribe` are inert, and `AppilotsChat` renders
+     * nothing. Consumers that show their own assistant affordance should
+     * branch on this.
+     */
+    degraded?: boolean;
 }
-declare function AppilotsProvider({ config: configProp, children, client: externalClient }: AppilotsProviderProps): React__default.JSX.Element;
+/**
+ * Public entry point. Its only job is to keep an exception thrown by
+ * anything Appilots renders from unmounting the host app's tree.
+ *
+ * The fallback deliberately re-renders `children` under a degraded
+ * context instead of a "something went wrong" screen: the children ARE
+ * the customer's app, and replacing them would be the same outage the
+ * boundary is here to prevent, just with nicer wording.
+ */
+declare function AppilotsProvider({ config, children, client }: AppilotsProviderProps): React__default.JSX.Element;
 declare function useAppilotsContext(): AppilotsContextValue;
 
 /**
@@ -1594,4 +1894,4 @@ interface UseSuggestedPromptsReturn {
  */
 declare function useSuggestedPrompts(options: UseSuggestedPromptsOptions): UseSuggestedPromptsReturn;
 
-export { componentRegistry as $, type AppilotsThemeTokens as A, type BreadcrumbItem as B, type ComponentRegistry as C, type RemotePersonalization as D, type EscalationState as E, type FieldEntry as F, SDK_VERSION as G, type SliderEntry as H, type InteractionElementSnapshot as I, type SuggestedPrompt as J, type ToggleEntry as K, type ListItemSnapshot as L, type MessageRole as M, type NavigationPayload as N, type ToggleSnapshot as O, type PartialThemeTokens as P, type UseAppilotsFieldOptions as Q, RateLimitedError as R, type ScreenSnapshot as S, type TargetEntry as T, type UIInteractionPayload as U, type UseAppilotsSliderOptions as V, type UseAppilotsTargetOptions as W, type UseAppilotsToggleOptions as X, type UseSuggestedPromptsOptions as Y, type UseSuggestedPromptsReturn as Z, clearAppilotsDebugTraces as _, type AppilotsLocale as a, createComponentRegistry as a0, defaultDarkTheme as a1, defaultLightTheme as a2, describeAction as a3, getAppilotsDebugTraces as a4, humanizeError as a5, mergeThemeTokens as a6, recordAppilotsDebugTrace as a7, subscribeAppilotsDebugTraces as a8, useAppilots as a9, useAppilotsActions as aa, useAppilotsChat as ab, useAppilotsContext as ac, useAppilotsField as ad, useAppilotsNavigation as ae, useAppilotsSlider as af, useAppilotsTarget as ag, useAppilotsToggle as ah, useSuggestedPrompts as ai, 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 };
+export { componentRegistry as $, type AppilotsThemeTokens as A, type BreadcrumbItem as B, type ComponentRegistry as C, type ListSnapshot as D, type EscalationState as E, type FieldEntry as F, type RemotePersonalization as G, type SliderEntry as H, type InteractionElementEntry as I, type SuggestedPrompt as J, type ToggleEntry as K, type ListItemSnapshot as L, type MessageRole as M, type NavigationPayload as N, type ToggleSnapshot as O, type PartialThemeTokens as P, type UseAppilotsFieldOptions as Q, RateLimitedError as R, type ScreenSnapshot as S, type TargetEntry as T, type UIInteractionPayload as U, type UseAppilotsSliderOptions as V, type UseAppilotsTargetOptions as W, type UseAppilotsToggleOptions as X, type UseSuggestedPromptsOptions as Y, type UseSuggestedPromptsReturn as Z, clearAppilotsDebugTraces as _, type AppilotsLocale as a, createComponentRegistry as a0, defaultDarkTheme as a1, defaultLightTheme as a2, describeAction as a3, getAppilotsDebugTraces as a4, humanizeError as a5, mergeThemeTokens as a6, recordAppilotsDebugTrace as a7, subscribeAppilotsDebugTraces as a8, useAppilots as a9, useAppilotsActions as aa, useAppilotsChat as ab, useAppilotsContext as ac, useAppilotsField as ad, useAppilotsNavigation as ae, useAppilotsSlider as af, useAppilotsTarget as ag, useAppilotsToggle as ah, useSuggestedPrompts as ai, 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 InteractionElementSnapshot as z };