API: extraction/browser

better-web-search-mcp / extraction/browser

extraction/browser#

Classes#

BrowserPool#

Defined in: src/extraction/browser.ts:151

A pool of reusable browser contexts backed by a single chromium instance.

The browser is launched lazily on first use and reused for every render. Contexts are created on demand up to DEFAULT_POOL_SIZE and then reused round-robin, so no render launches a browser per request.

Constructors#

Constructor#

new BrowserPool(size?): BrowserPool

Defined in: src/extraction/browser.ts:158

Parameters#

Parameter	Type	Default value
`size`	`number`	`DEFAULT_POOL_SIZE`

Returns#

BrowserPool

Methods#

close()#

close(): Promise<void>

Defined in: src/extraction/browser.ts:251

Close every context and the shared browser, resetting the pool.

Returns#

Promise<void>

renderWithBrowser()#

renderWithBrowser(url, opts?): Promise<RenderResult>

Defined in: src/extraction/browser.ts:223

Render a URL in a pooled context and return its HTML plus captured JSON API responses.

A navigation timeout does not throw: whatever rendered is extracted and returned as partial HTML. The page is always closed and the capture listener removed, even on error.

Parameters#

Parameter	Type
`url`	`string`
`opts`	`RenderOptions`

Returns#

Promise<RenderResult>

PlaywrightMissingError#

Defined in: src/extraction/browser.ts:66

Thrown when the Playwright browser binary is not installed.

Extends#

Error

Constructors#

Constructor#

new PlaywrightMissingError(): PlaywrightMissingError

Defined in: src/extraction/browser.ts:67

Returns#

PlaywrightMissingError

Overrides#

Error.constructor

Properties#

Property	Modifier	Type	Description	Inherited from	Defined in
`cause?`	`public`	`unknown`	-	`Error.cause`	node_modules/typescript/lib/lib.es2022.error.d.ts:26
`message`	`public`	`string`	-	`Error.message`	node_modules/typescript/lib/lib.es5.d.ts:1077
`name`	`public`	`string`	-	`Error.name`	node_modules/typescript/lib/lib.es5.d.ts:1076
`stack?`	`public`	`string`	-	`Error.stack`	node_modules/typescript/lib/lib.es5.d.ts:1078
`stackTraceLimit`	`static`	`number`	The `Error.stackTraceLimit` property specifies the number of stack frames collected by a stack trace (whether generated by `new Error().stack` or `Error.captureStackTrace(obj)`). The default value is `10` but may be set to any valid JavaScript number. Changes will affect any stack trace captured after the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames.	`Error.stackTraceLimit`	node_modules/@types/node/globals.d.ts:68

Methods#

captureStackTrace()#

static captureStackTrace(targetObject, constructorOpt?): void

Defined in: node_modules/@types/node/globals.d.ts:52

Creates a .stack property on targetObject, which when accessed returns a string representing the location in the code at which Error.captureStackTrace() was called.

const myObject = {};
Error.captureStackTrace(myObject);
myObject.stack;  // Similar to `new Error().stack`

The first line of the trace will be prefixed with ${myObject.name}: ${myObject.message}.

The optional constructorOpt argument accepts a function. If given, all frames above constructorOpt, including constructorOpt, will be omitted from the generated stack trace.

The constructorOpt argument is useful for hiding implementation details of error generation from the user. For instance:

function a() {
  b();
}

function b() {
  c();
}

function c() {
  // Create an error without stack trace to avoid calculating the stack trace twice.
  const { stackTraceLimit } = Error;
  Error.stackTraceLimit = 0;
  const error = new Error();
  Error.stackTraceLimit = stackTraceLimit;

  // Capture the stack trace above function b
  Error.captureStackTrace(error, b); // Neither function c, nor b is included in the stack trace
  throw error;
}

a();

Parameters#

Parameter	Type
`targetObject`	`object`
`constructorOpt?`	`Function`

Returns#

void

Inherited from#

Error.captureStackTrace

prepareStackTrace()#

static prepareStackTrace(err, stackTraces): any

Defined in: node_modules/@types/node/globals.d.ts:56

Parameters#

Parameter	Type
`err`	`Error`
`stackTraces`	`CallSite`[]

Returns#

any

See#

https://v8.dev/docs/stack-trace-api#customizing-stack-traces

Inherited from#

Error.prepareStackTrace

Interfaces#

RenderOptions#

Defined in: src/extraction/browser.ts:53

Options controlling a single browser render.

Properties#

Property	Type	Description	Defined in
`navigationTimeoutMs?`	`number`	Timeout for the initial navigation, in ms. Default 15s.	src/extraction/browser.ts:55

RenderResult#

Defined in: src/extraction/browser.ts:45

The result of a browser render.

Properties#

Property	Type	Description	Defined in
`captured`	readonly `CapturedApiResponse`[]	JSON API responses captured during the render.	src/extraction/browser.ts:49
`html`	`string`	The rendered page HTML.	src/extraction/browser.ts:47

WaitPage#

Defined in: src/extraction/browser.ts:90

The minimal Page surface the wait helpers depend on.

Methods#

evaluate()#

evaluate(fn): Promise<string>

Defined in: src/extraction/browser.ts:97

Parameters#

Parameter	Type
`fn`	() => `string`

Returns#

Promise<string>

waitForFunction()#

waitForFunction(fn, opts): Promise<unknown>

Defined in: src/extraction/browser.ts:96

Parameters#

Parameter	Type
`fn`	() => `boolean`
`opts`	{ `timeout`: `number`; }
`opts.timeout`	`number`

Returns#

Promise<unknown>

waitForLoadState()#

waitForLoadState(state, opts): Promise<void>

Defined in: src/extraction/browser.ts:91

Parameters#

Parameter	Type
`state`	`"networkidle"`
`opts`	{ `timeout`: `number`; }
`opts.timeout`	`number`

Returns#

Promise<void>

waitForSelector()#

waitForSelector(selector, opts): Promise<unknown>

Defined in: src/extraction/browser.ts:95

Parameters#

Parameter	Type
`selector`	`string`
`opts`	{ `timeout`: `number`; }
`opts.timeout`	`number`

Returns#

Promise<unknown>

Variables#

DEFAULT_POOL_SIZE#

const DEFAULT_POOL_SIZE: 3 = 3

Defined in: src/extraction/browser.ts:24

Default number of contexts to keep open in the pool.

DOM_STABILITY_POLL_MS#

const DOM_STABILITY_POLL_MS: 200 = 200

Defined in: src/extraction/browser.ts:42

Delay between DOM-stability polls, in milliseconds.

DOM_STABILITY_TIMEOUT_MS#

const DOM_STABILITY_TIMEOUT_MS: 4000 = 4_000

Defined in: src/extraction/browser.ts:36

Timeout for the DOM-stability poll, in milliseconds.

MIN_CONTENT_LENGTH#

const MIN_CONTENT_LENGTH: 1000 = 1_000

Defined in: src/extraction/browser.ts:39

Minimum innerText length that signals meaningful content.

NAVIGATION_TIMEOUT_MS#

const NAVIGATION_TIMEOUT_MS: 15000 = 15_000

Defined in: src/extraction/browser.ts:30

Timeout for the initial navigation, in milliseconds.

WAIT_LEG_TIMEOUT_MS#

const WAIT_LEG_TIMEOUT_MS: 4000 = 4_000

Defined in: src/extraction/browser.ts:33

Timeout for each intelligent-wait race leg, in milliseconds.

Functions#

intelligentWait()#

intelligentWait(page): Promise<void>

Defined in: src/extraction/browser.ts:108

Wait intelligently for content to appear.

Races three signals — network idle, an <article> element, and innerText exceeding MIN_CONTENT_LENGTH — each with a bounded timeout. Whichever resolves first wins; every leg swallows its own timeout so a slow page never throws here.

Parameters#

Parameter	Type
`page`	`WaitPage`

Returns#

Promise<void>

shouldBlockResource()#

shouldBlockResource(resourceType): boolean

Defined in: src/extraction/browser.ts:76

Whether a resource type should be blocked (image/font/media).

Parameters#

Parameter	Type
`resourceType`	`string`

Returns#

boolean

waitForDomStability()#

waitForDomStability(page): Promise<void>

Defined in: src/extraction/browser.ts:131

Poll the DOM until innerText stops growing (content is stable).

Returns as soon as two consecutive polls report the same text, or when the DOM_STABILITY_TIMEOUT_MS budget is exhausted.

Parameters#

Parameter	Type
`page`	`WaitPage`

Returns#

Promise<void>