Methods on browser.* operate on a browser pane. Most take { surfaceId: string, … } — omit surfaceId to target the focused browser surface (or HT_SURFACE).
| Method | Params | Result |
|---|
browser.list | {} | { browsers: Array<{ surfaceId, url, title, … }> } |
browser.open | { url: string, surfaceId?: string } | { surfaceId } |
browser.open_split | { url: string, direction?: "left"|"right"|"up"|"down" } | { surfaceId } |
browser.close | { surfaceId?: string } | { ok: true } |
browser.identify | { surfaceId?: string } | { surfaceId, url, title } |
| Method | Params | Result |
|---|
browser.navigate | { surfaceId?: string, url: string } | { ok: true } |
browser.back | { surfaceId?: string } | { ok: true } |
browser.forward | { surfaceId?: string } | { ok: true } |
browser.reload | { surfaceId?: string } | { ok: true } |
browser.url | { surfaceId?: string } | { url } |
browser.navigate accepts http:// / https:// (including localhost / LAN dev servers), about: (e.g. about:blank), data:, and chrome-extension:// URLs. file:// URLs are intentionally rejected for security — they would let a browser pane read arbitrary local files over the socket.
| Method | Params | Result |
|---|
browser.wait | { surfaceId?: string, selector?: string, text?: string, loadState?: "domcontentloaded"|"load"|"complete", timeoutMs?: number } | { ok: true } |
Supply at most one of selector, text, loadState. Default timeout 30 000 ms.
| Method | Params | Result |
|---|
browser.click | { surfaceId?: string, selector: string } | { ok: true } |
browser.dblclick | { surfaceId?: string, selector: string } | { ok: true } |
browser.hover | { surfaceId?: string, selector: string } | { ok: true } |
browser.focus | { surfaceId?: string, selector: string } | { ok: true } |
browser.check / browser.uncheck | { surfaceId?: string, selector: string } | { ok: true } |
browser.scroll_into_view | { surfaceId?: string, selector: string } | { ok: true } |
browser.type | { surfaceId?: string, selector: string, text: string } | { ok: true } |
browser.fill | { surfaceId?: string, selector: string, value: string } | { ok: true } |
browser.press | { surfaceId?: string, key: string } | { ok: true } |
browser.select | { surfaceId?: string, selector: string, value: string } | { ok: true } |
browser.scroll | { surfaceId?: string, x?: number, y?: number } | { ok: true } |
browser.highlight | { surfaceId?: string, selector: string, durationMs?: number } | { ok: true } |
| Method | Params | Result |
|---|
browser.snapshot | { surfaceId?: string } | { accessibilityTree: object } |
browser.get | { surfaceId?: string, what: "title"|"url"|"text"|"value"|"html", selector?: string } | { value: string } |
browser.is | { surfaceId?: string, what: "visible"|"enabled"|"checked"|"focused", selector: string } | { value: boolean } |
browser.eval | { surfaceId?: string, expression: string } | { result: any } |
| Method | Params | Result |
|---|
browser.addscript | { surfaceId?: string, source: string } | { ok: true } |
browser.addstyle | { surfaceId?: string, source: string } | { ok: true } |
browser.eval, browser.addscript, and browser.addstyle reject payloads larger than 256 KiB — this only affects pathologically large scripts or stylesheets.
| Method | Params | Result |
|---|
browser.find | { surfaceId?: string, query: string } | { ok: true } |
browser.stop_find | { surfaceId?: string } | { ok: true } |
browser.devtools | { surfaceId?: string } | { ok: true } |
| Method | Params | Result |
|---|
browser.console_list | { surfaceId?: string, follow?: boolean } | { entries: Array<{ level, text, ts }> } |
browser.console_clear | { surfaceId?: string } | { ok: true } |
browser.errors_list | { surfaceId?: string, follow?: boolean } | { entries: Array<{ message, source, ts }> } |
browser.errors_clear | { surfaceId?: string } | { ok: true } |
browser.history | { search?: string, limit?: number } | { entries: Array<{ url, title, visits, lastAt }> } |
browser.clear_history | {} | { ok: true } |
follow: true opens a stream — additional events arrive as { id, event: { … } } frames until cancelled.
Mapped 1:1 by ht browser.
A persistent cookie jar shared with browser panes (partitioned per
browserPartitionMode).
| Method | Params | Result |
|---|
browser.cookie_list | { domain? } | stored cookies, optionally filtered by domain |
browser.cookie_get | { url } | cookies that would be sent for this URL |
browser.cookie_set | { name, value, domain, path?, secure?, http_only?, expires? } | "OK" |
browser.cookie_delete | { domain, name } | "OK" |
browser.cookie_clear | { domain? } | "OK" — all cookies, or one domain |
browser.cookie_import | { path, format? } | count imported (json or netscape) |
browser.cookie_export | { format? } | serialised jar (json default, or netscape) |
browser.cookie_capture | { surface_id? } | cookies harvested from the pane’s current page |
Cookies are credentials — treat an exported jar like a password file. See
ht browser-cookie-*.
