> ## Documentation Index
> Fetch the complete documentation index at: https://piyushvyas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Shared Types

> Core type definitions shared across BAP SDKs: selectors, interactive elements, execution steps, and results.

This page documents the core types used across the BAP protocol, TypeScript SDK, and Python SDK. All types are defined as Zod schemas in `@browseragentprotocol/protocol` and as Pydantic models in the Python SDK.

## BAPSelector

A union type representing one of the 10 selector types. Used in all action and observation methods.

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    type BAPSelector =
      | { type: "css"; value: string }
      | { type: "xpath"; value: string }
      | { type: "role"; role: string; name?: string }
      | { type: "text"; value: string }
      | { type: "label"; value: string }
      | { type: "placeholder"; value: string }
      | { type: "testId"; value: string }
      | { type: "semantic"; description: string }
      | { type: "coordinates"; x: number; y: number }
      | { type: "ref"; value: string };
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from browseragentprotocol.types import BAPSelector

    # Factory functions
    role("button", "Submit")   # {"type": "role", "role": "button", "name": "Submit"}
    text("Sign in")            # {"type": "text", "value": "Sign in"}
    label("Email")             # {"type": "label", "value": "Email"}
    test_id("submit-btn")      # {"type": "testId", "value": "submit-btn"}
    ref("@e1")                 # {"type": "ref", "value": "@e1"}
    css("#login-btn")          # {"type": "css", "value": "#login-btn"}
    xpath("//button")          # {"type": "xpath", "value": "//button"}
    ```
  </Tab>
</Tabs>

## InteractiveElement

Returned by `agent/observe`. Represents a single interactive element on the page with a stable reference, selector, and metadata.

<ResponseField name="ref" type="string" required>
  Stable element reference ID (e.g., `"@e1"` or `"@submitBtn"`). Persists across observations for
  the same element.
</ResponseField>

<ResponseField name="selector" type="BAPSelector" required>
  Pre-computed selector that uniquely targets this element. Use this directly in action methods.
</ResponseField>

<ResponseField name="role" type="string" required>
  ARIA role (e.g., `"button"`, `"textbox"`, `"link"`, `"checkbox"`).
</ResponseField>

<ResponseField name="name" type="string">
  Accessible name of the element.
</ResponseField>

<ResponseField name="value" type="string">
  Current value (for input elements).
</ResponseField>

<ResponseField name="actionHints" type="string[]" required>
  What actions can be performed: `"clickable"`, `"editable"`, `"selectable"`, `"checkable"`,
  `"expandable"`, `"draggable"`, `"scrollable"`, `"submittable"`.
</ResponseField>

<ResponseField name="tagName" type="string" required>
  HTML tag name (e.g., `"button"`, `"input"`, `"a"`).
</ResponseField>

<ResponseField name="bounds" type="ElementBounds">
  Bounding box `{ x, y, width, height }` if `includeBounds` was requested.
</ResponseField>

<ResponseField name="focused" type="boolean">
  Whether the element currently has focus.
</ResponseField>

<ResponseField name="disabled" type="boolean">
  Whether the element is disabled.
</ResponseField>

<ResponseField name="stability" type="RefStability">
  Ref stability indicator: `"stable"` (same element, same ref), `"new"` (newly discovered),
  `"moved"` (element found but ref changed).
</ResponseField>

<ResponseField name="alternativeSelectors" type="BAPSelector[]">
  Alternative selectors ordered by reliability: testId, role+name, css #id, text, css path.
</ResponseField>

## ExecutionStep

Defines a single step in an `agent/act` sequence.

<ResponseField name="action" type="string" required>
  The BAP method to execute (e.g., `"action/click"`, `"action/fill"`, `"page/navigate"`).
</ResponseField>

<ResponseField name="params" type="Record<string, unknown>" required>
  Parameters for the action.
</ResponseField>

<ResponseField name="label" type="string">
  Human-readable label for logging and debugging.
</ResponseField>

<ResponseField name="condition" type="StepCondition">
  Pre-condition that must be met before execution. Object with `selector`, `state` (`"visible"` |
  `"enabled"` | `"exists"` | `"hidden"` | `"disabled"`), and optional `timeout`.
</ResponseField>

<ResponseField name="onError" type="string">
  Error handling strategy: `"stop"` (default), `"skip"`, or `"retry"`.
</ResponseField>

<ResponseField name="maxRetries" type="number">
  Max retries if `onError` is `"retry"` (1-5).
</ResponseField>

### Building Steps

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    import { BAPClient } from "@browseragentprotocol/client";

    const steps = [
      BAPClient.step("action/fill", {
        selector: { type: "label", value: "Email" },
        value: "user@example.com"
      }),
      BAPClient.step("action/click", {
        selector: { type: "role", role: "button", name: "Submit" }
      }),
    ];
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from browseragentprotocol import BAPClient, label, role

    steps = [
        BAPClient.step("action/fill", {"selector": label("Email"), "value": "user@example.com"}),
        BAPClient.step("action/click", {"selector": role("button", "Submit")}),
    ]
    ```
  </Tab>
</Tabs>

## AgentActResult

Returned by `agent/act`. Contains results for each step and optional fused observations.

<ResponseField name="completed" type="number" required>
  Number of steps completed successfully.
</ResponseField>

<ResponseField name="total" type="number" required>
  Total number of steps in the sequence.
</ResponseField>

<ResponseField name="success" type="boolean" required>
  Whether all steps succeeded.
</ResponseField>

<ResponseField name="results" type="StepResult[]" required>
  Results for each step in order. Each contains `step` (index), `success`, `duration`, optional
  `result` data, and optional `error`.
</ResponseField>

<ResponseField name="duration" type="number" required>
  Total execution time in milliseconds.
</ResponseField>

<ResponseField name="failedAt" type="number">
  Index of the first failed step (if any).
</ResponseField>

<ResponseField name="preObservation" type="AgentObserveResult">
  Pre-execution observation result (if `preObserve` was set).
</ResponseField>

<ResponseField name="postObservation" type="AgentObserveResult">
  Post-execution observation result (if `postObserve` was set).
</ResponseField>

## AgentObserveResult

Returned by `agent/observe`. Contains the page snapshot.

<ResponseField name="metadata" type="ObserveMetadata">
  Page metadata: `url`, `title`, `viewport` `{ width, height }`.
</ResponseField>

<ResponseField name="interactiveElements" type="InteractiveElement[]">
  List of interactive elements with stable refs and selectors.
</ResponseField>

<ResponseField name="totalInteractiveElements" type="number">
  Total count on the page (may exceed the returned list if `maxElements` was set).
</ResponseField>

<ResponseField name="accessibility" type="{ tree: AccessibilityNode[] }">
  Full accessibility tree (if `includeAccessibility` was set).
</ResponseField>

<ResponseField name="screenshot" type="ObserveScreenshot">
  Screenshot data with `data` (base64), `format`, `width`, `height`, `annotated`.
</ResponseField>

<ResponseField name="annotationMap" type="AnnotationMapping[]">
  Mapping from annotation labels to element refs and positions (if screenshot annotation was used).
</ResponseField>

<ResponseField name="changes" type="ObserveChanges">
  Incremental changes: `added`, `updated`, `removed` (if `incremental: true`).
</ResponseField>

<ResponseField name="webmcpTools" type="WebMCPTool[]">
  WebMCP tools discovered on the page (if `includeWebMCPTools: true`).
</ResponseField>

## AgentExtractResult

Returned by `agent/extract`.

<ResponseField name="success" type="boolean" required>
  Whether extraction succeeded.
</ResponseField>

<ResponseField name="data" type="unknown" required>
  Extracted data matching the provided schema.
</ResponseField>

<ResponseField name="sources" type="ExtractionSourceRef[]">
  Source element references for extracted data (if `includeSourceRefs` was set).
</ResponseField>

<ResponseField name="confidence" type="number">
  Confidence score (0-1) for the extraction.
</ResponseField>

<ResponseField name="error" type="string">
  Error message if extraction failed.
</ResponseField>

## ExtractionSchema

Simplified JSON Schema subset (max 2 levels deep) used by `agent/extract`:

```typescript theme={null}
{
  type: "object" | "array" | "string" | "number" | "boolean",
  properties?: Record<string, {
    type: string;
    description?: string;
    properties?: Record<string, { type: string; description?: string }>;
    items?: { type: string; description?: string; properties?: Record<...> };
  }>,
  required?: string[],
  items?: { type: string; description?: string; properties?: Record<...> },
  description?: string,
}
```

## Allowed Act Actions

These method names are permitted in `ExecutionStep.action`:

| Action            | Description                 |
| ----------------- | --------------------------- |
| `action/click`    | Click element               |
| `action/dblclick` | Double-click                |
| `action/fill`     | Fill input                  |
| `action/type`     | Type character by character |
| `action/press`    | Press key                   |
| `action/hover`    | Hover                       |
| `action/scroll`   | Scroll                      |
| `action/select`   | Select option               |
| `action/check`    | Check checkbox              |
| `action/uncheck`  | Uncheck checkbox            |
| `action/clear`    | Clear input                 |
| `action/upload`   | Upload file                 |
| `action/drag`     | Drag element                |
| `page/navigate`   | Navigate to URL             |
| `page/reload`     | Reload page                 |
| `page/goBack`     | Go back                     |
| `page/goForward`  | Go forward                  |