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

# BrowserResource: Open and Control Browser Sessions

> Use the Figranium JavaScript SDK to open browser sessions, inspect headful instances, highlight selectors, and stream live selector events from the server.

The `BrowserResource` in the Figranium JavaScript SDK gives you programmatic control over browser sessions. You can open headless or headful sessions, inspect the current headful state, highlight candidate selectors on a page, and stream live selector events during an active headful session.

```ts theme={null}
import { Figranium } from "@figranium/sdk";

const figranium = new Figranium({ apiKey: process.env.FIGRANIUM_API_KEY! });
```

## Methods

<AccordionGroup>
  <Accordion title="open">
    Opens a browser session. You can run in headless mode, headful mode, scrape mode, or agent mode.

    * **HTTP endpoint:** `POST /api/browser/open`
    * **Signature:** `open(input: { url?: string; mode?: "headful" | "scrape" | "agent"; devTools?: boolean; headless?: boolean } = {}, options?: RequestOptions): Promise<BrowserSession>`
    * **Returns:** [`BrowserSession`](/docs/sdk/js/resources/browser) with `sessionId`, `status`, and optionally `wsEndpoint`.

    ```ts open-session.ts theme={null}
    const session = await figranium.browser.open({
      url: "https://example.com",
      mode: "headful",
      devTools: true,
    });

    console.log(session.sessionId, session.status);
    ```
  </Accordion>

  <Accordion title="highlight">
    Highlights candidate selectors on a page and returns a DOM snapshot. Useful for building or debugging selector-based tasks.

    * **HTTP endpoint:** `POST /api/inspector/highlight`
    * **Signature:** `highlight(input: { sessionId?: string; url?: string; targetHint?: string }, options?: RequestOptions): Promise<{ success: boolean; selectors: SelectorCandidate[]; snapshot: string | null }>`
    * **Returns:** An object with `success`, an array of [`SelectorCandidate`](/docs/sdk/js/resources/browser) objects (`css`, optional `xpath` and `confidence`), and a `snapshot` string.

    ```ts highlight.ts theme={null}
    const result = await figranium.browser.highlight({
      url: "https://example.com",
      targetHint: "search input",
    });

    for (const candidate of result.selectors) {
      console.log(candidate.css, candidate.confidence);
    }
    ```
  </Accordion>

  <Accordion title="stopHeadful">
    Stops the active headful browser session.

    * **HTTP endpoint:** `POST /headful/stop`
    * **Signature:** `stopHeadful(options?: RequestOptions): Promise<UnknownRecord>`
    * **Returns:** `UnknownRecord`

    ```ts stop-headful.ts theme={null}
    await figranium.browser.stopHeadful();
    ```
  </Accordion>

  <Accordion title="headfulStatus">
    Checks whether the headful session is configured to use noVNC.

    * **HTTP endpoint:** `GET /api/headful/status`
    * **Signature:** `headfulStatus(options?: RequestOptions): Promise<{ useNovnc: boolean }>`
    * **Returns:** `{ useNovnc: boolean }`

    ```ts headful-status.ts theme={null}
    const status = await figranium.browser.headfulStatus();
    console.log(status.useNovnc);
    ```
  </Accordion>

  <Accordion title="inspect">
    Inspects the current headful session and returns diagnostic information.

    * **HTTP endpoint:** `POST /api/headful/inspect`
    * **Signature:** `inspect(options?: RequestOptions): Promise<UnknownRecord>`
    * **Returns:** `UnknownRecord`

    ```ts inspect.ts theme={null}
    const info = await figranium.browser.inspect();
    console.log(info);
    ```
  </Accordion>

  <Accordion title="vncPassword">
    Retrieves the VNC password for the current headful session.

    * **HTTP endpoint:** `GET /api/headful/vnc-password`
    * **Signature:** `vncPassword(options?: RequestOptions): Promise<{ password: string }>`
    * **Returns:** `{ password: string }`

    ```ts vnc-password.ts theme={null}
    const { password } = await figranium.browser.vncPassword();
    ```
  </Accordion>

  <Accordion title="selectorStream">
    Streams live selector events from the headful session as an async iterable.

    * **HTTP endpoint:** `GET /api/headful/selector_stream`
    * **Signature:** `selectorStream<T = UnknownRecord>(options?: RequestOptions): AsyncIterable<StreamEvent<T>>`
    * **Returns:** `AsyncIterable<StreamEvent<T>>`

    <Note>
      This is a server-sent event stream. For details on aborting and iterating streams, see [Streaming](/docs/sdk/js/streaming).
    </Note>

    ```ts selector-stream.ts theme={null}
    const controller = new AbortController();

    for await (const event of figranium.browser.selectorStream({
      signal: controller.signal,
    })) {
      console.log(event.event, event.data);
    }
    ```
  </Accordion>
</AccordionGroup>

## Headful debugging workflow

A typical headful debugging session combines several `BrowserResource` methods to open a browser, inspect state, stream selector events, and clean up when finished.

```ts headful-workflow.ts theme={null}
// 1. Open a headful session
const session = await figranium.browser.open({
  url: "https://example.com",
  mode: "headful",
});

// 2. Check headful status and VNC access
const status = await figranium.browser.headfulStatus();
const { password } = await figranium.browser.vncPassword();

// 3. Stream selector events while interacting with the page
const controller = new AbortController();
const stream = figranium.browser.selectorStream({ signal: controller.signal });

for await (const event of stream) {
  console.log("selector event:", event.data);
}

// 4. Stop the session when done
await figranium.browser.stopHeadful();
```

## Related resources

<CardGroup cols={2}>
  <Card title="Streaming" icon="signal-stream" href="/docs/sdk/js/streaming">
    Details on `AsyncIterable<StreamEvent<T>>` and abort controllers.
  </Card>

  <Card title="Request options" icon="sliders" href="/docs/sdk/js/request-options">
    Pass `signal`, `timeoutMs`, and custom `headers`.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/docs/sdk/js/errors">
    Handle `FigraniumError` responses.
  </Card>
</CardGroup>