Assert a JS expression against the current page. This is a HARD check: if it evaluates false the whole session is marked failed. Use it only for claims about the application under test. To wait for the page to become ready use ui_wait_for, and for a non-fatal observation use ui_check — do not call ui_assert in a retry loop, as the first false result permanently fails the run.

Check a JS expression against the current page WITHOUT failing the session if it is false. Use this for observations you want recorded in the report but which should not condemn the run. If the expression cannot run at all (no page open, or it throws) that is still a hard failure.

Click the single element matching the given selector. The selector may be a CSS selector or the selector value from ui_get_page_state, passed unchanged. Selectors containing "nth=" are positional: call ui_get_page_state again after the page changes before reusing them. Optional: button (right/middle), clickCount 2 for a double-click, modifiers for Shift/Control-click, position for an offset inside the element, force to click through an element covering it. If the click opens a native alert/confirm/prompt, the reply says the browser is waiting: answer it with ui_dialog.

Click just outside the single element matching the selector, the way a user closes a modal, drawer or popover by clicking its backdrop. Picks a point whose topmost element is not inside the target and not a control, and says what it hit. Pass the dialog panel, not the backdrop. Fails if no safe point exists (the element fills the viewport): use ui_press_key with Escape then. Selectors containing "nth=" are positional: call ui_get_page_state again after the page changes before reusing them.

Answer a native browser dialog (alert, confirm, prompt, beforeunload). When a tool call opens one, its reply says "Browser is waiting on a dialog" and every other tool is refused until you answer here. accept = OK / Leave; dismiss = Cancel / Stay; for a prompt add text. The reply also reports what the interrupted action did next. With no dialog waiting, this pre-sets the answer for the NEXT dialog, which is then answered at once (one answer, used once). An unanswered dialog is dismissed after a safety timeout.

Drag the single element matching from onto the single element matching to with real pointer events: reorders HTML5 drag-and-drop lists, kanban cards and pointer-based sortables. Use the selector values from ui_get_page_state. Selectors containing "nth=" are positional: call ui_get_page_state again after the page changes before reusing them.

End a session bracket: writes a JSON + HTML report and returns their paths. Pass session_id to choose which one; it can be omitted only when exactly one session is open.

Fill the single input element matching the given selector with a value. The selector may be a CSS selector or the selector value from ui_get_page_state, passed unchanged. Selectors containing "nth=" are positional: call ui_get_page_state again after the page changes before reusing them.

Read the browser problems captured in this session so far: console errors, uncaught page errors, failed requests and HTTP 4xx/5xx responses (method + URL, never bodies or headers). Use it when an action seemed to do nothing. since: last (default) returns only what is new since the previous call; start returns everything. Pass level: warning to include console warnings. Repeats are grouped (×N); at most 50 lines.

Return the current page's URL, title, visible interactive elements and visible alert/status messages. Each element is {role, name, selector, state?}: pass selector unchanged to ui_click/ui_fill (at most 200 elements); state lists only non-default fields (disabled, checked, value, expanded, selected, pressed, required, invalid; a password's value is never returned). Custom widgets (combobox, listbox, option, switch, slider, contenteditable, summary...) are listed too. overlays ({role, name, selector, modal}, topmost first) names each open dialog and is absent when none is open; focused ({role, name, selector}) names the element holding focus and is absent when focus is on the page body. To read page text use ui_get_text.

Read the trimmed visible text of the single element matching the selector, or of the whole page body when no selector is given (cut at 4000 characters with a note of the real length). Use it to check content: a table value, a heading, an error under a field, a total. Fails if the selector matches no element, more than one, or an element that is not visible. Selectors containing "nth=" are positional: call ui_get_page_state again after the page changes before reusing them.

Move the pointer over the single element matching the selector, to reveal :hover or mouseenter content such as dropdown menus. Use the selector from ui_get_page_state. Selectors containing "nth=" are positional: call ui_get_page_state again after the page changes before reusing them.

Navigate the browser to the given URL and report the result.

Go back or forward in the browser history, or reload the current page, and report the resulting URL and title. Unlike ui_navigate this keeps the history, so it can check that state survives a reload. Going back or forward with no such history entry is an error that says so.

Press a key (Playwright key name such as Enter, Tab, Escape, ArrowDown, or a combo like Control+a). With selector it presses on that element; without, on whatever has focus. Enter in a text input submits its form. Selectors containing "nth=" are positional: call ui_get_page_state again after the page changes before reusing them.

Scroll one step. With selector, bring that element into view. Otherwise scroll by one viewport height (or width) in direction (down, up, left, right, or jump to top / bottom, default down): the page, or with container the scroll area matching that selector (a chat panel, a virtual table, a carousel). The result says when the end was reached (nothing more to scroll that way): stop looping then. A page or panel with nothing to scroll is not an error. Selectors containing "nth=" are positional: call ui_get_page_state again after the page changes before reusing them.

Choose an option of the single matching the selector, by option value or visible label. For a this selects exactly that one option. Use the selector from ui_get_page_state. Selectors containing "nth=" are positional: call ui_get_page_state again after the page changes before reusing them.

Set the single checkbox or radio button matching the selector to checked or unchecked. Idempotent: already in that state is fine. A radio cannot be unchecked directly. Use the selector from ui_get_page_state. Selectors containing "nth=" are positional: call ui_get_page_state again after the page changes before reusing them.

Resize the current page's viewport (320-3840 x 320-2160 CSS pixels), e.g. 375x812 for a phone or 768x1024 for a tablet. Layouts can change when the page is resized, so call ui_get_page_state again afterwards.

Start a session bracket: opens a fresh browser context and begins logging subsequent primitive tool calls into a report. A connection can hold several sessions at once (up to MAX_SESSIONS_PER_CONNECTION, default 3): pass the returned session id as session_id to every other tool to choose which session it acts on. A session left unused for 10 minutes is closed automatically and its report is written with status timed_out. Optionally test at the sizes and settings real users have: device (a Playwright device name such as "iPhone 13": mobile user agent, touch, pixel ratio and size), viewport (overrides the device size), colorScheme, locale, timezoneId. With none of them the browser is a 1280x720 desktop. These apply to this session only; use ui_set_viewport to resize mid-flow.

Label what you are about to do, in plain language. Every following action is grouped under this label in the report until the next ui_step. Call it before each meaningful part of the flow (e.g. "Log in as jcarlin", "Toggle Manual Invoice access on", "Reload and confirm it persisted") — this label is the only human-readable description the report has, so write it for the person who will read the result, not for yourself.

Manage browser tabs of this session (numbered from 1). A link with target=_blank or window.open opens a new tab, announced on the next tool response but not switched to. list: index, url, title, current. switch: make that tab the one every tool acts on. close: close that tab (default: the current one) and fall back to the previous one; the last tab cannot be closed.

Capture the current viewport and save it as a PNG to the reports output. With selector, capture just that element; with fullPage, the whole scrollable page (cut at 16000 device pixels tall and 3840px wide). With inline: true the image itself is also returned (scaled to fit 1280x8000px; the file on disk stays full size) so you can look at it. Selectors containing "nth=" are positional: call ui_get_page_state again after the page changes before reusing them.

Type text into the single editable element matching the selector one key at a time, like a user (keydown, input and keyup per character), appending to what is already there. Use it instead of ui_fill for autocomplete, search-as-you-type, masked inputs (phone, card) and OTP boxes. Use the selector from ui_get_page_state. Text typed into a password, one-time-code or card-number field is never stored in the report. Selectors containing "nth=" are positional: call ui_get_page_state again after the page changes before reusing them.

Upload the built-in test file default_draft.png (a tiny PNG) to the single element matching the selector: an input[type=file] (hidden ones work), or a button/label whose click opens the file chooser. Takes no path: this is the only file it can ever upload. If the input's accept excludes images the response says so. Selectors containing "nth=" are positional: call ui_get_page_state again after the page changes before reusing them.

Poll a JS expression until it becomes true or the timeout elapses. Use this to wait for the page to render instead of retrying ui_assert. Returning true is recorded as one action; timing out fails the session.