@appilots/web-sdk 0.2.0

package/dist/index.d.mts

@@ -0,0 +1,1010 @@
+import { C as ControlEvidence, A as AgentAction, a as AppilotsLocale, b as AgentPermissions, c as AppilotsEvent, W as WebNavigationAdapter, S as ScreenActionMetadataLike, d as ActionExecutionResult } from './AppilotsWebRuntime-DZF26UyU.mjs';
+export { e as ActionDiagnose, f as ActionQueueMachine, g as AgentActionType, h as AppilotsClient, i as AppilotsEventHandler, j as AppilotsWebRuntime, k as AppilotsWebRuntimeOptions, l as ChatMessage, m as ChatSessionMachine, n as ChatSessionOptions, o as ChatSessionState, E as EscalationState, p as EscalationStrings, R as RateLimitedError, q as WebNavigationAdapterOptions, r as WebNavigationState, s as WebRoute, t as WebScreenMetadata, u as buildPath, v as matchRoute } from './AppilotsWebRuntime-DZF26UyU.mjs';
+
+type ActionPresentationState = 'pending' | 'running' | 'success' | 'failed';
+
+/**
+ * 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`.
+ */
+/**
+ * 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) */
+    value?: string;
+    /** Placeholder text */
+    placeholder?: string;
+    /** Whether the input is editable */
+    editable?: boolean;
+    /** Whether the input is secure (password field) */
+    secure?: boolean;
+    /**
+     * Tipo do campo.
+     *
+     * Os cinco primeiros vêm da metadata de input da plataforma. Os quatro
+     * últimos vêm do registry: um select, um date picker, um toggle ou um
+     * controle custom registrado por `useAppilotsField` não é `TextInput`,
+     * então o walker não o coleta — e sem eles a observação não dizia o que
+     * estava preenchido num formulário que os exige. O schema de wire já
+     * aceitava (`type` é string livre lá); só o tipo local era estrito.
+     */
+    type?: 'text' | 'email' | 'number' | 'phone' | 'password' | 'select' | 'date' | 'toggle' | 'custom';
+    /**
+     * 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;
+    /**
+     * The app is asking for this field before the form can be submitted.
+     *
+     * ABSENT MEANS UNKNOWN, not optional: most apps never declare it, and
+     * reading absence as "not required" would let the agent submit a form
+     * it could have known was incomplete.
+     */
+    required?: boolean;
+    /**
+     * The app is currently rejecting this field's value.
+     *
+     * This is the fact the agent used to recover by READING — the error
+     * copy next to the input ("Campo obrigatório", "Formato inválido").
+     * Carrying the fact as a boolean is what lets a redacted observation
+     * still support recovery, and it is cheaper than the sentence even
+     * when nothing is redacted.
+     *
+     * Absent means the app declares no validity state — never that the
+     * field is valid.
+     */
+    invalid?: boolean;
+    /**
+     * Whether the field currently holds anything.
+     *
+     * Deliberately its own field rather than an inference over `value`.
+     * The value belongs to the user and is the first thing a privacy
+     * policy withholds; the EXISTENCE of a value belongs to the agent and
+     * is what stops it from filling the same field twice on a later hop.
+     * Separating them is what lets the second survive without the first.
+     */
+    filled?: boolean;
+    /**
+     * This input has keyboard focus right now.
+     *
+     * Tells apart "empty because nobody typed" from "empty because the
+     * user is typing in it at this moment" — the difference between
+     * completing a form and interrupting someone mid-sentence.
+     */
+    focused?: boolean;
+    /**
+     * 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 {
+    controlEvidence?: ControlEvidence;
+    /** 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 client can observe this button but cannot bind its id to an exact control. */
+    dispatchable?: boolean;
+    /**
+     * 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 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. */
+    inModal?: boolean;
+}
+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 */
+    value?: boolean;
+    /** True when this toggle lives inside a currently-visible modal. */
+    inModal?: boolean;
+}
+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 */
+    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 {
+    /** Whether this row intersects the list viewport, when geometry is available. */
+    onScreen?: boolean;
+    /** 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 {
+    /** Measured rows intersecting the list viewport; absent means unmeasurable. */
+    viewportItemCount?: number;
+    /** Mission-local exploration metadata; positions are 0-based, never action targets. */
+    exploration?: {
+        revision: number;
+        observedItemCount: number;
+        observedRanges: Array<{
+            start: number;
+            end: number;
+        }>;
+        rangesTruncated: boolean;
+        coverage: 'partial' | 'all-loaded';
+        pagination: 'possible' | 'not-declared';
+        scrollSteps: number;
+        remainingScrollSteps: number;
+        consecutiveNoProgress: number;
+        lastScroll?: 'moved' | 'no-progress' | 'boundary' | 'unverified';
+    };
+    /** 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';
+    /**
+     * How many items the list renders FROM — its `data.length`, which for
+     * a paginated list is the page and not the collection.
+     */
+    itemCount?: number;
+    /**
+     * Size of the whole collection when the app declared it.
+     *
+     * The three counts answer three different questions and a list that
+     * pages needs all three: `visibleItemCount` is what is mounted,
+     * `itemCount` is what is loaded, `totalItemCount` is what exists.
+     * Undefined means unknown — it is never a copy of `itemCount`.
+     */
+    totalItemCount?: 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;
+}
+/**
+ * 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;
+    /** 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 {
+    /** False means observation-only; absence preserves legacy client behavior. */
+    dispatchable?: boolean;
+    /** 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';
+    /**
+     * 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. */
+    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;
+}
+/**
+ * What changed between the previous observation and this one.
+ *
+ * The client holds both snapshots; the server only ever sees one. So the
+ * question the agent loop asks most often — "did the action I just took
+ * do anything?" — is one the client can answer as a FACT and the server
+ * can only guess at. Today it guesses: `effect: 'none'` on the turn trail
+ * is derived server-side from heuristics over a single snapshot.
+ *
+ * Everything here is shape, never content: counts, booleans, and field
+ * ids that the app declared itself. That is not an accident of design —
+ * it is what lets this survive a redacted or content-free observation
+ * intact, and it is why the most useful signal in the observation is also
+ * the cheapest one to send.
+ *
+ * ABSENT vs `unchanged: true` is the load-bearing distinction, and it is
+ * the same one `truncated` exists to make. Absent means there was no
+ * previous observation to compare against (the first capture of a
+ * mission). `unchanged: true` means we DID compare and nothing moved —
+ * which is the strongest evidence there is that an action did nothing.
+ */
+interface SnapshotDelta {
+    /** The active route is not the one the previous observation reported. */
+    routeChanged?: boolean;
+    /** A modal or native dialog is up now and was not before. */
+    modalOpened?: boolean;
+    /** A modal or native dialog was up before and is gone now. */
+    modalClosed?: boolean;
+    /** A loading indicator appeared. */
+    loadingStarted?: boolean;
+    /** A loading indicator that was showing is gone. */
+    loadingFinished?: boolean;
+    /** How many distinct visible texts are present now that were not before. */
+    textsAdded?: number;
+    /** How many distinct visible texts are gone. */
+    textsRemoved?: number;
+    /** Zero-based indexes of newly visible buttons in this snapshot, capped at 12.
+     * No derived ids or copy travel in the delta; render only from current buttons.
+     */
+    buttonsAddedIndices?: number[];
+    /** Number of previously visible button identities no longer visible. */
+    buttonsRemoved?: number;
+    /** Net change in mounted list rows, summed across every list. */
+    visibleRowsDelta?: number;
+    /**
+     * Net change in the lists' reported DATA totals, summed. This is the
+     * one that answers "did the record actually get created", because it
+     * moves even when virtualization keeps the new row unmounted.
+     */
+    totalRowsDelta?: number;
+    /**
+     * Fields that went from empty to filled. Declared ids only — a
+     * `derived` id is folded from visible copy, so publishing it here
+     * would smuggle content through a field that claims to carry none.
+     */
+    fieldsNewlyFilled?: string[];
+    /** Fields that went from filled to empty. Declared ids only. */
+    fieldsCleared?: string[];
+    /** Some field is reporting invalid that was not reporting it before. */
+    invalidAppeared?: boolean;
+    /**
+     * Nothing above fired: we compared two observations and the screen is
+     * structurally identical. Present only when every other field is
+     * absent, so a reader never has to check all of them to know.
+     */
+    unchanged?: 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;
+    /**
+     * 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
+     * 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[];
+    /**
+     * 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;
+    /**
+     * What moved since the previous observation. See {@link SnapshotDelta}
+     * — absent means there was nothing to compare against, which is a
+     * different statement from "nothing changed".
+     *
+     * Attached by the platform adapter rather than by the walker: the
+     * baseline has to be the last snapshot that was actually SENT, and
+     * `captureSnapshot` is also called for internal probes that never
+     * leave the device.
+     */
+    delta?: SnapshotDelta;
+    /** 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;
+        };
+    };
+}
+
+/** Customer action labels. Raw payloads remain in the action/debug records. */
+
+type BreadcrumbState = ActionPresentationState;
+interface BreadcrumbItem {
+    label: string;
+    state: BreadcrumbState;
+}
+declare function describeAction(action: AgentAction, locale?: AppilotsLocale): 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;
+
+/**
+ * walkDom — the DOM/ARIA equivalent of the RN SDK's Fiber walker.
+ *
+ * Same output shape (`ScreenSnapshot`), same semantic rules (an element
+ * is exactly one of text/input/slider/button/toggle; list containers are
+ * not descended in the main pass; the same dedup keys), different
+ * mechanics: this reads the document and its accessibility metadata
+ * instead of a framework's internal tree. That is deliberate — it means
+ * the walker works identically against React, Vue, Svelte, or plain
+ * HTML, and it cannot break when a framework changes its internals.
+ */
+
+interface WalkDomOptions {
+    /** Subtree to observe. Defaults to `document.body`. */
+    root?: Element;
+    /** Route name for the snapshot, when the caller knows it. */
+    route?: string | null;
+}
+/**
+ * Walk the DOM and produce a `ScreenSnapshot`. `elements` are NOT
+ * derived here — `captureSnapshot` adds them, mirroring how the RN SDK
+ * splits walking from interaction-graph derivation.
+ */
+declare function walkDom(options?: WalkDomOptions): ScreenSnapshot;
+
+/**
+ * captureSnapshot — walk the DOM, then derive the interaction graph.
+ *
+ * Split the same way the RN SDK splits it: `walkDom` produces the raw
+ * observation, `deriveInteractionElements` turns it into stable `el:`
+ * ids. Because that derivation lives in `@appilots/client-core` and
+ * reads only the snapshot, identical observed content yields identical
+ * element ids on web and React Native.
+ */
+
+declare function getRegisteredElement(id: string): InteractionElementSnapshot | undefined;
+declare function registeredElements(): InteractionElementSnapshot[];
+declare function captureSnapshot(options?: WalkDomOptions): ScreenSnapshot;
+/**
+ * Structural fingerprint of the current screen — ids and enabled/
+ * checked state only, never text or values. Two probes with the same
+ * fingerprint mean nothing actionable changed, which is how the settle
+ * loop decides the UI has stopped moving.
+ *
+ * Mirrors `probeLoadingState`'s fingerprint in the RN SDK, including
+ * the sort (so a DOM reorder alone is not a change).
+ */
+interface LoadingProbeResult {
+    loading: boolean;
+    pressedDisabled: boolean;
+    pressedFound: boolean;
+    modalOpen: boolean;
+    fingerprint: string;
+}
+declare function probeLoadingState(pressedComponentId?: string | null, route?: string | null, options?: WalkDomOptions): LoadingProbeResult;
+
+/**
+ * Locator resolution — how a DOM element gets the id and label the
+ * agent addresses it by.
+ *
+ * Deliberately DOM + accessibility metadata only: no framework
+ * internals (no React Fiber, no Vue instance), so the same walker works
+ * against React, Vue, Svelte, or hand-written HTML.
+ */
+/** Attribute checked first — the app's explicit opt-in agent id. */
+declare const APPILOTS_ID_ATTR = "data-appilots-id";
+/** Marks a subtree the walker must not descend into. */
+declare const APPILOTS_SKIP_ATTR = "data-appilots-skip";
+/** Marks a list container and carries its stable id. */
+declare const APPILOTS_LIST_ID_ATTR = "data-appilots-list-id";
+/** Marks a row inside a list container. */
+declare const APPILOTS_LIST_ITEM_ATTR = "data-appilots-list-item";
+/** Optional stable key for a row (the item's domain id). */
+declare const APPILOTS_ITEM_KEY_ATTR = "data-appilots-item-key";
+/** Optional 0-based index of a row in the list's backing data. */
+declare const APPILOTS_ITEM_INDEX_ATTR = "data-appilots-item-index";
+/** Optional total data-set size when the DOM only holds a page of it. */
+declare const APPILOTS_ITEM_COUNT_ATTR = "data-appilots-item-count";
+/** Marks the agent's own chat UI so it never observes itself. */
+declare const APPILOTS_CHAT_ATTR = "data-appilots-chat";
+/** Marks a field whose value must never leave the device. */
+declare const APPILOTS_SENSITIVE_ATTR = "data-appilots-sensitive";
+/**
+ * Turn a human label into an id, mirroring the RN walker's
+ * `normalizeLabel`: strip diacritics, drop non-alphanumerics, and
+ * camelCase-join the words ("Salvar veículo" → "salvarVeiculo").
+ */
+declare function normalizeLabelToId(label: string): string;
+/**
+ * The element's agent-facing id, in precedence order:
+ * `data-appilots-id` → `data-testid` → `id` → `name` → `aria-label`.
+ *
+ * `data-testid` sits high because it is the convention apps already use
+ * for e2e tests, so most apps get useful ids with zero extra markup.
+ */
+declare function bestId(el: Element): string | undefined;
+/**
+ * The element's accessible name, following the parts of the ARIA
+ * name computation that matter here: `aria-label`, `aria-labelledby`,
+ * an associated `<label>`, then `title`/`placeholder`/`alt`.
+ */
+declare function accessibleName(el: Element): string | undefined;
+/** The ARIA role: explicit `role` attribute, else the implicit one. */
+declare function elementRole(el: Element): string | undefined;
+/**
+ * Visible text directly owned by an element, used as a button's label.
+ * Mirrors the RN walker's `findChildText`: up to three text fragments
+ * containing at least one letter or digit, joined with ' · '.
+ */
+declare function readOwnText(el: Element, maxFragments?: number): string | undefined;
+
+/**
+ * Visibility — deciding whether the user can actually see and reach an
+ * element.
+ *
+ * Uses `Element.checkVisibility()` when the browser has it (it accounts
+ * for `content-visibility`, `display`, `visibility` and opacity in one
+ * call), and falls back to an explicit ancestor walk everywhere else.
+ * The fallback is what runs under jsdom/happy-dom in tests, where
+ * layout is not computed at all.
+ */
+/**
+ * True when this element hides itself and its subtree. Mirrors the RN
+ * walker's `shouldSkipSubtree` rules: an explicit opt-out marker, our
+ * own chat UI, `display: none`, and `opacity: 0` combined with
+ * `pointer-events: none` (both required — a fade-in animation mid-frame
+ * is still meant to be seen).
+ */
+declare function hidesSubtree(el: Element): boolean;
+/**
+ * True when the element is visible to the user, considering ancestors.
+ * Prefers the browser's own `checkVisibility()`; the manual walk is the
+ * fallback for test DOMs and older browsers.
+ */
+declare function isVisible(el: Element): boolean;
+interface ScrollMetrics {
+    offset: number;
+    visibleLength: number;
+    contentLength: number;
+}
+/**
+ * Read a scroll container's metrics. Returns undefined when the element
+ * reports no scrollable content — including test DOMs, where every
+ * layout number is zero and inventing scroll facts would be a lie.
+ */
+declare function readScrollMetrics(el: Element): ScrollMetrics | undefined;
+/**
+ * Nearest scrollable ancestor (or the element itself), used to answer
+ * "can this list scroll further up/down".
+ */
+declare function findScrollContainer(el: Element): Element | undefined;
+
+/**
+ * Settling — waiting for the UI to stop moving before observing it.
+ *
+ * Same contract as the RN SDK's `waitForScreenSettle` /
+ * `waitForLoadingSettle`, with DOM signals instead of Fiber ones: the
+ * URL for route transitions, and `aria-busy`/disabled-submit/structural
+ * fingerprint for async work.
+ */
+interface ScreenSettleOptions {
+    expectingChange?: boolean;
+    fromScreen?: string | null;
+    fromSignature?: string | null;
+    targetScreen?: string | null;
+    maxMs?: number;
+    pollMs?: number;
+    stableReads?: number;
+    mountFlushMs?: number;
+}
+interface ScreenSettleResult {
+    screen: string | null;
+    transitioned: boolean;
+    timedOut: boolean;
+    waitedMs: number;
+}
+interface LoadingSettleOptions {
+    pressedComponentId?: string | null;
+    fromScreen?: string | null;
+    maxMs?: number;
+    pollMs?: number;
+    backoffFactor?: number;
+    pollMaxMs?: number;
+    stableReads?: number;
+}
+interface LoadingSettleResult {
+    settled: boolean;
+    transitioned: boolean;
+    loadingPending: boolean;
+    screen: string | null;
+    waitedMs: number;
+    probeCount: number;
+}
+interface SettleProbes {
+    getCurrentScreen(): string | null;
+    getCurrentScreenSignature(): string | null;
+}
+declare const routesBelongToSameFeature: (a: string, b: string) => boolean;
+declare function screenDepartedBaseline(current: string | null, currentSignature: string | null, fromScreen: string | null, fromSignature: string | null): boolean;
+/**
+ * Wait for a route transition to land, then for the route to hold
+ * still for a few reads, then flush a frame so the new screen's effects
+ * have run before we observe it.
+ */
+declare function waitForScreenSettle(probes: SettleProbes, options?: ScreenSettleOptions): Promise<ScreenSettleResult>;
+/**
+ * Wait for async work kicked off by an interaction to finish. Fast path
+ * returns after ~one probe when nothing is busy, which is the common
+ * case; otherwise it polls with exponential backoff until the screen
+ * is quiescent (no loading indicator, the pressed control re-enabled,
+ * and a stable structural fingerprint).
+ */
+declare function waitForLoadingSettle(probes: SettleProbes, options?: LoadingSettleOptions): Promise<LoadingSettleResult>;
+
+/**
+ * Target resolution — turning an id the model emitted into a real DOM
+ * element.
+ *
+ * The model addresses controls by whatever id the snapshot showed it:
+ * a `data-testid`, an `el:` interaction-graph id, or a synthetic list
+ * ordinal (`list-0-item-3`). All three resolve here, with the same
+ * lenient-then-fuzzy ladder the RN executor uses, so a near-miss id
+ * still lands on the right control instead of failing the turn.
+ */
+interface ResolveOptions {
+    root?: Element | Document;
+    /** Restrict to controls that can be filled (inputs/selects/textareas). */
+    kind?: 'field' | 'target' | 'toggle' | 'any';
+}
+/**
+ * Strip the kind prefixes apps conventionally add, so `btn-submit`
+ * matches a control registered as `submit` (and vice versa). Mirrors
+ * the RN executor's `stripComponentPrefix`.
+ */
+declare function stripComponentPrefix(componentId: string): string | null;
+/** Rows of a list, in the order the walker saw them. */
+declare function findListItemElements(listIndex: number, options?: ResolveOptions): {
+    container: Element;
+    items: Element[];
+} | undefined;
+/** `list-0-item-3` → `{ listIndex: 0, itemIndex: 3 }` (1-based item). */
+declare function parseSyntheticListItemId(id: string): {
+    listIndex: number;
+    itemIndex: number;
+} | null;
+/** The row a synthetic ordinal points at. */
+declare function resolveListItem(syntheticId: string, options?: ResolveOptions): Element | undefined;
+/**
+ * The element a row's press should dispatch on.
+ *
+ * A row usually holds a primary control plus secondary ones — an "open"
+ * link next to a "delete" button. Two rules matter here:
+ *
+ *  - Never pick a destructive control. "Open the second vehicle" must
+ *    not delete it because delete happened to be the first button in
+ *    the DOM.
+ *  - Never fall back to the row itself when it holds controls. Clicking
+ *    a bare `<li>` does nothing, and the action would report success
+ *    while the user saw no change.
+ *
+ * Returns undefined when the row exposes only destructive controls, so
+ * the caller can fail with an ambiguous-target diagnose instead of
+ * guessing.
+ */
+declare function primaryControlOf(row: Element): Element | undefined;
+interface ResolvedTarget {
+    element: Element;
+    /** How we found it — useful in diagnostics when a match was fuzzy. */
+    via: 'element-registry' | 'list-ordinal' | 'exact-id' | 'prefix-id' | 'fuzzy-label';
+}
+/**
+ * Resolve an id to an element, trying (in order): the `el:` interaction
+ * registry, synthetic list ordinals, exact id attributes, prefix-
+ * stripped ids, then fuzzy label matching.
+ */
+declare function resolveTargetElement(rawId: string, options?: ResolveOptions): ResolvedTarget | undefined;
+/** Ids the model could have meant — attached to a not-found diagnose. */
+declare function candidateIds(options?: ResolveOptions, limit?: number): string[];
+/** True when a modal is up and the target is behind it. */
+declare function isOccludedByModal(el: Element, options?: ResolveOptions): boolean;
+/** Visible, enabled controls inside the open modal — recovery hints. */
+declare function modalCandidateLabels(options?: ResolveOptions, limit?: number): string[];
+
+/**
+ * ActionExecutor — executes the six agent actions against the DOM.
+ *
+ * Mirrors the RN executor's contract exactly: the same permission gate,
+ * the same validation errors, the same `ActionDiagnose` categories, and
+ * the same lifecycle events. What differs is the mechanics underneath
+ * (DOM events instead of registry handles) and navigation, which goes
+ * through the injected `WebNavigationAdapter` rather than React
+ * Navigation.
+ */
+
+interface WebExecutorContext {
+    signal?: AbortSignal;
+    /**
+     * PARTIAL: every flag left out takes its default. See
+     * `resolveAgentPermissions` in @appilots/client-core — a config that
+     * named some of the flags used to deny the rest in silence.
+     */
+    permissions?: Partial<AgentPermissions>;
+    emit: (event: AppilotsEvent) => void;
+    navigation: WebNavigationAdapter;
+    /** Subtree to act within. Defaults to the whole document. */
+    root?: Element | Document;
+    /**
+     * Actions the app declared for the current screen. Used to resolve
+     * the submit control by declaration rather than by guessing at copy.
+     */
+    screenActions?: Array<ScreenActionMetadataLike | string>;
+    /**
+     * True when the user already approved a destructive confirm for this
+     * action in chat — the app's own `window.confirm` is auto-accepted
+     * once so the user is not asked the same question twice.
+     */
+    confirmedDestructive?: boolean;
+}
+declare function executeAction(action: AgentAction, context: WebExecutorContext): Promise<ActionExecutionResult>;
+
+/**
+ * DOM event dispatch — the primitives every action handler builds on.
+ *
+ * Writing to a controlled React input is the subtle one: assigning
+ * `element.value` directly does not notify React, because React
+ * installs its own value setter on the element instance and tracks the
+ * last value it wrote. We call the *prototype's* native setter (which
+ * updates React's tracker) and then dispatch a bubbling `input` event,
+ * which is what React's synthetic `onChange` actually listens for. The
+ * same sequence works for Vue's `v-model` and for plain listeners.
+ */
+/** Focus an element, tolerating hosts where focus() is unavailable. */
+declare function focusElement(el: Element): void;
+/**
+ * Set a form control's value so the owning framework observes it.
+ * Returns false for a non-value control or an unavailable select option.
+ */
+declare function setControlValue(el: Element, value: string): boolean;
+/** Read a control's current value, whatever kind it is. */
+declare function readControlValue(el: Element): string;
+/** Flip a checkbox/switch and notify the framework. */
+declare function setToggleValue(el: Element, value: boolean): boolean;
+declare function readToggleValue(el: Element): boolean;
+/**
+ * Click an element the way a user would: pointer/mouse sequence first
+ * (so handlers bound to mousedown/pointerup fire), then `click()` so
+ * default behavior (form submission, link navigation) still happens.
+ */
+declare function clickElement(el: Element): void;
+/** Long-press: a click preceded by a held pointer, for context menus. */
+declare function longPressElement(el: Element): void;
+/** Scroll an element into view, tolerating hosts without the API. */
+declare function scrollIntoView(el: Element): void;
+/** Scroll a container to an absolute offset. */
+declare function scrollToOffset(container: Element, offset: number): boolean;
+
+/**
+ * GENERATED by scripts/release/sync-sdk-versions.mjs — do not edit.
+ *
+ * The version `@appilots/web-sdk` reports on the wire
+ * (`X-Appilots-Sdk-Version`). Kept identical to package.json by the
+ * release flow; `version.test.ts` fails if the two ever disagree.
+ */
+declare const SDK_VERSION = "0.2.0";
+
+export { APPILOTS_CHAT_ATTR, APPILOTS_ID_ATTR, APPILOTS_ITEM_COUNT_ATTR, APPILOTS_ITEM_INDEX_ATTR, APPILOTS_ITEM_KEY_ATTR, APPILOTS_LIST_ID_ATTR, APPILOTS_LIST_ITEM_ATTR, APPILOTS_SENSITIVE_ATTR, APPILOTS_SKIP_ATTR, ActionExecutionResult, AgentAction, AgentPermissions, AppilotsEvent, type LoadingProbeResult, type LoadingSettleOptions, type LoadingSettleResult, type ResolveOptions, type ResolvedTarget, SDK_VERSION, type ScreenSettleOptions, type ScreenSettleResult, type ScreenSnapshot, type ScrollMetrics, type SettleProbes, type WalkDomOptions, type WebExecutorContext, WebNavigationAdapter, accessibleName, bestId, candidateIds, captureSnapshot, clickElement, describeAction, elementRole, executeAction, findListItemElements, findScrollContainer, focusElement, getRegisteredElement, hidesSubtree, humanizeError, isOccludedByModal, isVisible, longPressElement, modalCandidateLabels, normalizeLabelToId, parseSyntheticListItemId, primaryControlOf, probeLoadingState, readControlValue, readOwnText, readScrollMetrics, readToggleValue, registeredElements, resolveListItem, resolveTargetElement, routesBelongToSameFeature, screenDepartedBaseline, scrollIntoView, scrollToOffset, setControlValue, setToggleValue, stripComponentPrefix, waitForLoadingSettle, waitForScreenSettle, walkDom };