lexmount:browser
Manage cloud browser sessions, navigate, interact, wait, capture screenshots, and export PDFs.
lexmount:browser creates or attaches to cloud browsers for collecting pages, working with forms, and saving documents. It uses the project identity of the current task submission. Code does not supply an API key and receives neither credentials nor CDP URLs.
import browser from 'lexmount:browser';
const session = await browser.create({ browserMode: 'normal' });
try {
const page = await session.openUrl('https://example.com');
console.log(page.title);
} finally {
await session.destroy();
}The default export and named browser export reference the same read-only manager; import { browser } from 'lexmount:browser' also works. Parameters use camelCase; service metadata uses snake_case.
Shared options
Options objects are optional. Unsupported fields cause TypeError. Each field below applies only to methods that explicitly accept it.
| Type / field | Type | Default and description |
|---|---|---|
TimeoutOptions.timeoutMs | number | Integer milliseconds, 1–86400000; creation defaults to 600000, confirmed closure to 180000, other ordinary operations to 30000 |
SessionOptions.regionId | string | Management region; defaults to the current execution's region |
ActionOptions.targetId | string | Page ID; defaults to the first page, creating a blank page if none exists |
SessionOptions and ActionOptions also include timeoutMs. An explicit targetId must identify an open page in that session. For consecutive actions on one page, obtain its ID with targets() and reuse it. Session handles retain the region selected when attaching.
Session management
browser.create(options?)
Function: creates a cloud browser and waits until it is available.
Parameters: optional CreateOptions, containing SessionOptions and the fields below. Unless a default is stated, omitted fields use the browser service's defaults.
| Field | Type | Description |
|---|---|---|
browserMode | 'normal' / 'light' | Browser mode; defaults to normal |
contextId | string | Attach an existing persistent Context |
contextMode | 'read_write' / 'read_only' | Requires contextId; defaults to read_write |
contextDescription | string | Context description |
weakLock | boolean | Context weak-lock option |
officialProxy | boolean | Use the official proxy |
localProxyTunnelId | string | Use a running local proxy tunnel; requires normal mode, the tunnel's region, and no official proxy |
customImageId | string | Custom image ID |
windowSize | string | ACE window dimensions as width,height, for example 1920,1080 |
downloads | boolean | Enable download storage |
recording | boolean | Enable persistent replay; unsupported by Moli |
extensionIds | string[] | Extension IDs to load |
Return value: Promise<BrowserSession>, resolving once the browser is available. Features depend on project entitlements and browser type. Creation failure or timeout rejects without automatic retry.
browser.get(sessionId, options?)
Function: attaches to an existing session.
Parameters: required sessionId: string; optional options?: SessionOptions selects region and timeout.
Return value: Promise<BrowserSession>. Attachment does not transfer ownership or make the existing session eligible for automatic destruction when the task ends.
browser.list(options?)
Function: queries session metadata for the current project.
Parameters: optional SessionOptions, plus status?: 'active' | 'closed' to filter status. This interface exposes no page-number or page-size parameters.
Return value: Promise<SessionList>, containing sessions: SessionInfo[]. Optional pagination contains numeric fields currentPage, pageSize, totalCount, totalPages, activeCount, and closedCount. This method does not return actionable BrowserSession handles.
browser.destroy(sessionId, options?)
Function: closes a session and waits for backend confirmation.
Parameters: required sessionId: string; optional options?: SessionOptions selects region and timeout.
Return value: Promise<void>. The default confirmation timeout is 180000 milliseconds.
SessionInfo
Items returned by browser.list() and the result of session.getInfo() use this metadata structure:
| Field | Type | Description |
|---|---|---|
session_id | string | Session ID |
status | string | Backend-reported status |
project_id | Optional string | Owning project |
browser_mode | Optional string | Browser mode |
region_id | Optional string / null | Region |
context_id | Optional string / null | Context ID |
context_description | Optional string / null | Context description |
context_display_name | Optional string / null | Context display name |
created_at, closed_at | Optional Json | Creation and closure time values from the service |
create_error | Optional string / null | Creation error message |
Json means null, a boolean, number, string, an array of these values, or an object with string keys.
BrowserSession
A session handle has a read-only sessionId: string property and the following methods.
session.getInfo(options?)
Function: reads the session's current status and metadata.
Parameters: options?: TimeoutOptions.
Return value: Promise<SessionInfo>; see SessionInfo.
session.targets(options?)
Function: lists session page targets for choosing a targetId.
Parameters: options?: TimeoutOptions.
Return value: Promise<{ session_id: string; targets: Target[] }>. Each Target contains string fields id, type, title, and url.
session.keepalive(options?)
Function: polls session status over a period and retains the resulting snapshots.
| Parameter | Type | Default and description |
|---|---|---|
options.intervalMs | number | 5000; polling interval, 1–86400000 milliseconds |
options.durationMs | number | 60000; duration, 0–86400000 milliseconds; 0 still performs one check |
options.stopOnInactive | boolean | false; stop early when the session is no longer active |
options.timeoutMs | number | Defaults to durationMs + 60000 for the complete operation; explicit values follow the shared option range |
Return value: Promise<{ session_id: string; checks: number; snapshots: SessionInfo[] }>, containing the session ID, check count, and status snapshots.
session.destroy(options?)
Function: closes this session and waits for backend confirmation.
Parameters: options?: TimeoutOptions; confirmation timeout defaults to 180000 milliseconds.
Return value: Promise<void>. Repeated calls on a handle reuse an in-progress or successful close. A failed close can be retried.
Page actions
The options argument of each method below accepts ActionOptions; extra fields are listed per method. The default timeout is 30000 milliseconds.
session.openUrl(url, options?)
Function: navigates the selected page.
Parameters: required url: string; options?: ActionOptions.
Return value: Promise<{ navigation: Json; url: string; title: string }>, containing navigation output, final URL, and page title.
session.eval(expression, options?)
Function: evaluates a JavaScript expression in the page and reads its result.
Parameters: required expression: string; options?: ActionOptions.
Return value: Promise<Json>. Results are JSON values, without remote object handles.
session.waitSelector(selector, options?)
Function: waits for a CSS selector to match an element.
Parameters: required nonempty selector: string; options?: ActionOptions.
Return value: Promise<{ found: true; selector: string }>. Timeout rejects.
session.waitText(text, options?)
Function: polls page text until it appears or disappears.
Parameters: required text: string, which can be empty; options accepts ActionOptions plus:
| Field | Type | Default and description |
|---|---|---|
selector | string | Optional matching scope |
state | 'present' / 'absent' | present; wait for appearance or disappearance |
exact | boolean | false; require an exact match |
caseSensitive | boolean | false; distinguish letter case |
includeHidden | boolean | false; include hidden elements |
pollMs | number | 250; polling interval, 0–86400000 milliseconds, with an effective minimum of 25 milliseconds |
Return value: Promise<WaitTextResult>. An unmet condition resolves with timed_out: true; connection and protocol errors still reject.
| Result field | Type | Description |
|---|---|---|
found, matched | boolean | Whether matching text was found; both fields have the same value |
state | 'present' / 'absent' | Requested condition |
text | string | Query text |
selector | string / null | Matching scope |
exact, case_sensitive, include_hidden | boolean | Effective matching options |
waited_ms, timeout_ms, poll_ms | number | Wait duration, timeout, and polling interval |
candidate_count | number | Number of candidate elements |
element | Json | Matched element information |
timed_out | boolean | Whether waiting timed out |
Use !result.timed_out to test whether the requested condition was met. Successful waiting for absent returns false for both found and matched.
session.click(selector, options?)
Function: clicks an element selected by CSS.
Parameters: required nonempty selector: string; options?: ActionOptions.
Return value: Promise<true>; failures reject.
session.fill(selector, value, options?)
Function: fills an input element selected by CSS.
Parameters: required nonempty selector: string; required value: string, which can be empty; options?: ActionOptions.
Return value: Promise<true>; failures reject.
session.screenshot(options?)
Function: captures a PNG image of the page.
Parameters: optional ActionOptions, plus fullPage?: boolean, default false; set it to true to capture the full page.
Return value: Promise<Uint8Array> containing original PNG bytes.
session.pdf(options?)
Function: exports the page as a PDF.
Parameters: optional ActionOptions, plus printBackground?: boolean, default false, to include backgrounds.
Return value: Promise<Uint8Array> containing original PDF bytes.
session.snapshot(options?)
Function: reads a page snapshot.
Parameters: options?: ActionOptions.
Return value: Promise<Json> containing string fields url, title, text, and html, plus an interactive array. Interactive contains at most 200 elements, each with index: number, tag: string, text: string (up to 240 characters), and nullable string fields id, name, and role.
session.raw(method, params?, options?)
Function: calls an underlying browser protocol method on the selected page.
Parameters: required nonempty method: string; params?: Record<string, Json>, default {}; options?: ActionOptions. For example, raw('Page.getLayoutMetrics').
Return value: Promise<Json> containing the method result. Unsupported protocol methods or invalid parameters reject.
Errors and cleanup
Browser operation errors are Error objects with name: 'BrowserError' and a string code. BrowserError is a type declaration, not an exported runtime constructor. Branch on error.code; argument validation can also throw TypeError directly.
The runtime attempts to reclaim sessions created by create() when the task ends. Still use finally and explicitly await session.destroy(). A session alone does not keep the task active, and local task completion does not confirm cloud closure. The caller arranges closure for sessions attached with get().
See the cloud browser example and browser.d.ts.