Skip to main content
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.

​
Methods

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 with sessionId, status, and optionally wsEndpoint.
open-session.ts
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 objects (css, optional xpath and confidence), and a snapshot string.
highlight.ts
Stops the active headful browser session.
  • HTTP endpoint: POST /headful/stop
  • Signature: stopHeadful(options?: RequestOptions): Promise<UnknownRecord>
  • Returns: UnknownRecord
stop-headful.ts
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 }
headful-status.ts
Inspects the current headful session and returns diagnostic information.
  • HTTP endpoint: POST /api/headful/inspect
  • Signature: inspect(options?: RequestOptions): Promise<UnknownRecord>
  • Returns: UnknownRecord
inspect.ts
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 }
vnc-password.ts
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>>
This is a server-sent event stream. For details on aborting and iterating streams, see Streaming.
selector-stream.ts

​
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.
headful-workflow.ts

Streaming

Details on AsyncIterable<StreamEvent<T>> and abort controllers.

Request options

Pass signal, timeoutMs, and custom headers.

Errors

Handle FigraniumError responses.