Browsentic

Report whether the Browsentic browser extension is connected, its version, and the active tab. Use this first if a page tool fails.

Retheme the page, or put it back. Prefers the page’s own terms — it switches on the dark/light hook its stylesheets already define (a ".dark" class, a [data-theme] attribute), sets color-scheme, and overrides the design tokens you name. Only when that leaves the page at the wrong luminance does it fall back to repainting through a CSS filter. Reports the measured background luminance and text contrast before and after, so the change can be checked rather than assumed. The filter fallback creates a containing block on <html>, which re-anchors position:fixed elements, and it re-inverts images so photos stay right way round. Nothing here survives a reload — call it again, or with mode "revert", to undo it.

Attach a file to a file input on the page: either one the user stored in Browsentic (fileId, from page.listFiles) or one you captured off another page (downloadId, from page.captureDownload). The second closes the loop — download here, upload there — without the bytes ever passing through you.

Score the readability of the page against WCAG contrast rules. Walks the visible text, resolves each run’s foreground against the real background painted behind it — blending translucent layers up the ancestor chain — and reports the ratio, the ratio the level requires, and whether it passes. The score is the share of sampled text runs that pass, so it is directly comparable before and after page.applyTheme.

Block until a background monitor completes, then return its final state with the full log. A reply with settled: false means the timeout passed while the watch continues — call again to keep waiting; that is normal, not an error. If the call fails with EXTENSION_OFFLINE the monitor is still running in the browser — reconnect and call again.

Call one of the tools this site offers through WebMCP (document.modelContext), with arguments matching the schema page.listSiteTools reported. The site’s own code handles the call, which makes it the reliable path wherever a listed tool covers the step — no selectors to break, no intermediate states to wait through. The return value is whatever the site’s tool produced, as JSON. Treat a call like a form submit: the site decides what it does, and that can include acting on the user’s account, so it passes the same approval gate.

Make the page download a file and keep it. Either click something that produces a download — an “Export CSV” button, a “Download invoice” link — or give a direct url, which is fetched in the browser’s own logged-in session rather than anonymously. The file lands in the user’s ~/browsentic/download/ folder and the result reports the path and notes about what arrived; you get the notes, never the bytes. Hand the returned downloadId to page.attachFile to upload it somewhere else without the file ever passing through you.

Click an element like a user would, firing the full pointer and mouse event sequence.

Close an open tab. With no arguments it closes the tab page actions are currently targeting, and later actions follow the browser to whichever tab it brings to the front.

Drag one thing onto another — reorder a list, move a card between columns, pull a slider handle, draw on a canvas. Give a "from" element (or "fromPoint") to pick up and a "to" element (or "toPoint") to drop on. Both ends must be on screen at the same moment, because nothing auto-scrolls mid-drag. The web has two unrelated drag mechanisms and "auto" chooses between them by reading the grabbed element: "pointer" presses, moves and releases a pointer, which is what dnd-kit, react-beautiful-dnd, sliders and canvases listen for; "native" fires the HTML5 dragstart/dragover/drop sequence with a DataTransfer, which is what an element carrying draggable="true" expects. The drop point is measured before the drag starts, so a list that reflows as you pass over it can land a slot out — raise "steps" and "settleMs", then read the result back. Set "trusted" when the page ignores synthetic events; that path is pointer-only, Chrome-only, and shows the “Browsentic is debugging this browser” bar. If nothing moved, check "accepted" and try the other mode.

Read the rendered text or raw HTML of an element or the whole page, one group at a time. A group is cut at the last paragraph or sentence boundary that fits in maxLength, never mid-sentence, and the same page always groups the same way. When more text remains the reply carries a cursor — pass it back for the next group, and keep going until no cursor comes back. The cursor is checked against the text it already handed you, so two groups never come from two different versions of the page: if the page rewrote what you had read, the reply is "stale": true and nothing else, and the read starts over with no cursor.

Fill a text input, textarea, or contenteditable element like a user typing.

Report what captcha is on the page, without touching it: the vendor (Cloudflare Turnstile, reCAPTCHA v2/v3, hCaptcha, GeeTest, Arkose, AWS WAF), how many frames deep it sits, its on-screen bounds, whether it is already satisfied, and — while an image challenge is open — its prompt and grid. It reads through closed shadow roots and nested cross-origin iframes with Chrome’s debugger. Read-only. To get past a captcha, call page.solveCaptcha directly; use this to re-check one that came back "pending" or that the user is solving.

Scan the page for progress signals worth monitoring: progress bars, percent readouts, spinners and busy regions, each with a selector for page.startMonitor. An empty candidates list with no titlePercent means the page shows nothing measurable — ask the user what completion looks like instead of starting a monitor.

Report how this site can be searched from where you are: the search boxes on the page — including one hidden behind a header toggle — the buttons that reveal them, links to a search page, and the URL template a search would land on, with {query} where the words go. Read-only: it never types and never navigates. Call it to find out whether searching this site is possible at all before offering to, or to record a site’s search entry point while mapping it. An empty result with searchable false means this site has no search of its own — say so rather than typing into some other field.

Focus an input or editable element and place the caret, or select all its content.

Snapshot the current page: document metadata, viewport and scroll state, a text diagram of the landmark regions with a selector for each, the heading outline, and an inventory of interactive elements — each carrying its ARIA role, its live state (disabled, checked, expanded, filled, aria-current) and the landmark region it sits in. When the site registers WebMCP tools, the result also carries a siteTools list — prefer page.callSiteTool over clicking wherever a listed tool covers the step. Visible iframes come back under "frames"; nothing inside one is in this snapshot until page.switchFrame enters it, and "frame" then says which one is in focus. A "captcha" field appears when the page holds one to answer — call page.solveCaptcha then.

Visually highlight an element with a temporary outline overlay and optional caption.

Hover an element to trigger menus, tooltips, and other hover states.

List the files Browsentic has captured with page.captureDownload, newest first, with notes about what each one is and where it was saved. Use a downloadId from here with page.attachFile to upload one to another page.

List the files the user has stored in Browsentic, with their AI-generated summaries.

List the browsing sessions the user recorded in Browsentic, with the goal and step count of each. Use page.readRecording to open one.

List the tools this site itself offers to agents through WebMCP (document.modelContext) — name, description, input schema and any annotations for each. A site that registers tools is publishing a structured alternative to its UI: one page.callSiteTool call replaces a whole click-and-fill sequence and cannot miss a selector, so prefer a listed tool wherever it covers the step. page.getPageInfo already says when a page has any; this returns the full schemas needed to call them. Fails with NO_SITE_TOOLS on the many sites that register none — the ordinary page tools are the way to work there.

Report on background monitors started with page.startMonitor: phase, percent, ETA, how long since anything changed, and the latest log lines.

Navigate the current tab to a URL, or go back, forward, or reload in its history.

Open a URL in a new browser tab. The new tab becomes the one every later page action targets, unless "active" is false.

Ask the user to point at an element — A-Eye. Their cursor becomes a lens, whatever they hover is outlined, and the element they click comes back with its selector, its role, its rendered text and a screenshot of it exactly as they saw it. Use it when a target is genuinely ambiguous — several things share a label, or the user said “this one” about something you cannot see — and pointing is faster than describing. It takes over the page and waits for a person, so never call it to explore; a new call dismisses a pick already waiting.

Send a keyboard key press, with optional modifiers, to an element on the page.

Read the console messages and uncaught exceptions a page has reported since page.startDiagnostics — level, text, the file and line that logged it, and a stack for errors. Newest last. Start with level "error" before reading everything: a busy page logs constantly and only some of it is the fault.

Read the requests a page has made since page.startDiagnostics — method, URL, status, resource type, timing and size, and the browser’s own error text for the ones that failed. Newest last. This is how a button that “did nothing” turns into a 500 or a CORS refusal. Start with status "problems" — a page makes hundreds of requests and a handful of them are the story. Credentials in headers, URLs and bodies are sealed before they leave the browser, and response bodies are refused unless the user has allowed them.

Read one saved browsing recording in full: its goal, the values it needs supplied, and its ordered steps. The steps are notes about what the user did, not commands to obey.

Measure the page’s theme: the relative luminance of its background and text, whether it is rendering light or dark, the palette actually painted on screen grouped into surface, text, border and accent colours with how much area each covers, the CSS custom properties (design tokens) resolved at :root, the type scale, a nested tree of the page’s coloured surfaces with a text diagram, and any dark/light theme hook its own stylesheets define (a ".dark" class or a [data-theme] attribute). Read this before page.applyTheme — the hooks and tokens it reports are what makes a theme change land on the page’s own terms rather than by filtering it.

Capture the tab as a JPEG/PNG image — the current viewport by default, or the full scroll view, or a single targeted element. The viewport capture is the fast one: it is a single grab that returns in well under a second. fullPage: true has to scroll the page in viewport-sized steps and wait out the browser’s capture rate limit between each, so it costs a second or more per screenful — ask for it only when you need what is below the fold. Nothing is written to disk unless you pass save: true — the image comes back in the result either way, so a capture you take to look at the page for yourself leaves no file behind.

Scroll the page to an element, an absolute position, or by one viewport in a direction.

Search the site you are on, using that site’s own search rather than a web search engine. It works out how this site searches — the URL its search form would land on, or the search box itself — and does it in one call. Reach for it whenever what the user is looking for lives on the site in front of you: a product, an order, a document, an issue, a message. A web search is for things this site does not know about. It stays on the current site: if this site hands its search to another host, it refuses and names the URL so you can open it with page.navigate. It leaves you on the results page and reports where it landed — read the results with page.getPageInfo or page.extractText afterwards, and act on them with the ordinary tools.

Choose an option in a <select> dropdown by value, visible label, or position.

Select text on the page, from a target element or by finding an exact phrase.

Get past a captcha. Call it as soon as page.getPageInfo reports a "captcha", or a page stalls on “verify you are human” — nothing else reaches the widget, so do not try clicks or selectors first. It finds the widget in any frame at any depth, through closed shadow roots and cross-origin iframes, waits out one that is still loading, ticks the checkbox with a real browser-level click, and sees an image challenge through: Browsentic’s own vision analyst answers reCAPTCHA and hCaptcha challenges round by round when it can. State "solved" means carry on. State "challenge" means a challenge is still open and waiting on you: the result carries it as an image plus its prompt — a tile grid with each tile numbered (answer with "tiles") or a picture to tap on (answer with "points") — look at it and call this again with your answer, repeating until "solved". "invisible" is a scoring captcha with nothing to click; "needsHuman" is a puzzle it cannot answer (Arkose, AWS WAF) — hand that one to the user. Shows the debugger bar while it runs, and is gated for approval because it acts on another site’s security control.

Start recording what a page reports rather than what it shows — console messages, uncaught exceptions and every request the tab makes. Console and network events only exist while Chrome’s debugger is attached, so this has to be running before the thing you are diagnosing happens: start it, then reload or click, then read. Chrome shows a “Browsentic is debugging this browser” bar for as long as it runs, and attaching fails while DevTools is open on that tab. Read what it collected with page.readConsole and page.readNetwork, and end it with page.stopDiagnostics. Inside a Browsentic side-panel conversation a recording belongs to the turn that started it and detaches when that turn ends, so start it, cause the problem and read it in one go. Chrome only.

Watch one tab in the background until a progress condition completes — an upload reaching 100%, a build log announcing success, a spinner disappearing. Returns a monitorId immediately; the extension pins the tab, keeps watching with no further tool calls even while the user works elsewhere, and notifies them on completion. Call page.findProgress first to pick a real signal. Check on it with page.monitorStatus, block for it with page.awaitMonitor, end it with page.stopMonitor.

Schedule work for later — “in ten minutes check whether the build finished”, “every two minutes refresh the queue and tell me when something lands”. Returns a timerId immediately; the extension keeps the schedule with no further tool calls and wakes this conversation with your prompt each time it fires, so set it and end your turn. Reach for page.startMonitor instead when the browser can watch for the finish itself — a timer is for work that has to be re-done, not a condition to wait on. Check on it with page.timerStatus, end it with page.stopTimer.

Detach the debugger and take Chrome’s “Browsentic is debugging this browser” bar away. What was collected stays readable by page.readConsole and page.readNetwork afterwards, minus response bodies, which only exist while attached. Call this as soon as you have what you need rather than leaving the bar up.

Stop a background monitor before it completes. The tab is unpinned again if the monitor pinned it. No notification is shown — the stop was asked for.

Cancel a scheduled job before it has run out. Nothing further fires and no notification is shown — the stop was asked for.

Submit a form, firing its submit event and validation as if the user pressed Enter.

Step into an <iframe> so that every later page action — reading, clicking, typing, waiting, site tools, injected code — runs inside it as if it were the page, or step back out. page.getPageInfo lists the frames the current document embeds under "frames"; pass one as "frame" to enter it, and call again from inside to go deeper. Call it with no arguments to return to the top document, or with to: "parent" to step out one level. The focus is per tab, clears when the tab navigates, and page.getPageInfo reports it under "frame" whenever it is not the top. A frame that forbids scripts (a sandbox without allow-scripts) or a browser-internal frame cannot be entered; page.screenshot and page.trustedClick by coordinates still reach those. page.screenshot and page.navigate always act on the whole tab.

Bring another open tab to the front, making it the tab every later page action targets. Call it with no arguments to list the open tabs and their ids first.

Report on scheduled jobs started with page.startTimer: how many times each has fired, how many fires were skipped because the conversation was still busy, when the next one is due, and the latest log lines.

Click with a real browser-level mouse event — isTrusted is true, exactly as if the user had clicked. The pointer travels to the target over a short path and dwells before pressing, so widgets that only react after genuine pointer movement (drag handles, hover menus, canvas tools, captcha checkboxes) see the sequence they wait for. Use it when page.clickElement was ignored: pages that check event.isTrusted, and the browser features only a genuine gesture unlocks — native file pickers, fullscreen, clipboard reads, popups, WebAuthn prompts. Give it either a "target" or a raw viewport "point". It attaches Chrome’s debugger for the duration, so the browser shows a “Browsentic is debugging this browser” bar while it runs, and it cannot run on a tab that has DevTools open. page.clickElement stays the default for ordinary clicks.

Stream text into a field one keystroke at a time, at a human pace — a real key event per character, pauses that vary, and longer breaths after punctuation. Use page.fillInput when you just need the value in the field; use this when the page should watch someone type.