JavaScript pages

You rarely need to ask for a browser. When plain HTTP returns an app shell, an unrendered template or almost no text, Frankensurf reports VISUAL_REQUIRED and moves on to a browser by itself.

• Force a browser with render=True when you already know the page needs one.
• Wait for a specific element before capture.
• Browsers: local Chromium, Steel, Crawl4AI, stealth browsers and hosted ones.

Usage

Python

page = await web.read("https://app.example.com/dashboard", policy_overrides={
    "render": True,
    "wait_selector": "[data-testid=results]",
    "settle_ms": 800,
})

CLI

frankensurf read https://app.example.com/dashboard --render --wait-selector '[data-testid=results]'

MCP

{ "tool": "read", "arguments": { "url": "https://app.example.com/dashboard", "render": true,
  "acquisition_policy": { "wait_selector": "[data-testid=results]", "settle_ms": 800 } } }

Here is what automatic escalation looks like on a page plain HTTP can’t use:

receipt.attempts

[
  { "provider": "http", "status": "failed", "failure": "VISUAL_REQUIRED", "latency_ms": 88 },
  { "provider": "local", "status": "observed", "latency_ms": 1310 }
]

Options

Option	Default	Description
render	false	Use a browser from the start.
wait_selector	none	Wait for this CSS selector.
wait_state	"attached"	attached or visible.
content_ready_selector	none	Wait for this selector, but capture anyway when it times out.
settle_ms	400	Extra wait after the page is ready.
allow_local_browser	true	Set false to use only remote browsers.