Page control

The page as a tree of roles, names and states, with a ref on everything you can act on. Start here: it is a few hundred lines where the HTML is tens of thousands, and every acting route takes the refs it mints. A ref belongs to the snapshot that minted it — navigate or re-snapshot and the old ones are refused by name, naming the generation, rather than silently resolving to whatever now sits in that position.

Finds elements by CSS selector, visible text, ARIA role, accessible name, or any combination, and mints a ref for each. Text matching returns the innermost match, so searching for "Sign in" gives the button rather than the <body> that also contains it. At least one filter is required; an unfiltered search would return the first twenty elements on the page, which answers nothing.

The page’s markup, whole or one subtree by ref or selector. Use it when you need the markup itself — an attribute, a data- value, a hidden input. For deciding what to click, the snapshot is smaller and more useful. Reports truncated and totalChars rather than silently cutting.

A PNG of the viewport, the full page, or one element by ref or selector, base64.

Clicks an element by ref, selector or visible text. Scrolls to it with a real wheel first, then moves the pointer along a human trajectory and presses. The target’s own width is fed to the motion model, because a move to a small target genuinely takes a person longer than one of the same distance to a big one. Returns forced: true on the rare element only a programmatic scroll could reach — inside an overflow container, say — so a transcript shows the one action that was not a person’s. Targeting by text refuses an ambiguous match unless you pass first.

Moves the pointer onto an element and leaves it there, for menus and tooltips that open on hover.

Types text as a person types it: real keydown, keypress, input and keyup per character, human inter-key timing, occasional typos corrected with a backspace. With a ref or selector it clicks the field first; with neither it types into whatever already has focus. Never a paste — a field that goes from empty to forty characters in one event fires no keydown at all, which is among the cheapest bot signals a site can collect.

Clears a field and types a value into it, with the same human timing. The clear uses the select-all shortcut for the platform the page believes it is on, read through navigator.platform rather than the host — so a profile presenting as Windows sends Control+A even on a Mac, and the keystroke agrees with the rest of its fingerprint. Refuses anything that is not an input, a textarea or a contenteditable, naming what it found instead.

Presses one named key, optionally with modifiers held. An unknown key is a 400 listing the keys that exist, because "unknown key" with no list sends the caller to the source. For ordinary characters use the type route.

Chooses options in a native <select>, by value or by visible label. A native dropdown is drawn by the operating system and is not in the page, so there is nothing to click: this sets the selection and fires the input and change events a browser would, both bubbling, because a change that does not bubble is why this looks like it worked and changes nothing. No matching option is a 400 listing the options the select offers. For a custom dropdown, click it and then click the option.

Scrolls the page with a real wheel, or brings an element into view. The wheel deltas match the pointing device this profile was assigned — a trackpad and a notched mouse produce different event streams, and mixing them inside one session describes two different computers.

Drags from one element to another as a press, a human-shaped move and a release.

Attaches files to a file input by absolute path on this machine. Point it at the <input type="file"> itself, which is often hidden behind a styled button — find it with a selector rather than by clicking the button. Anything else is a 400 naming the element it found.

Navigates the controlled tab and waits for load. Returns the URL it ended on, which is not always the one you asked for. A page that never fires load because one tracker is hanging still returns rather than failing — it is a page you can read.

Reloads the controlled tab and waits for load.

Steps through the tab’s real history rather than calling history.go(), so it crosses an origin boundary the way the back button does instead of being refused by the page’s same-origin scope. Nothing to step to is a 400 saying which end it is at.

Waits for a selector to appear or disappear, for text to show up, or for the network to go quiet. Returns met: false on a timeout rather than failing, because "it never appeared" is frequently the answer you wanted and an exception makes it indistinguishable from a broken call; why says which it was. Waiting on network idle needs the request log running — without it there are no events to be idle between, and that is a 400 rather than a wait that can never end.

Runs JavaScript against the page. world: "isolated" is the default and the page cannot see it — it is also where refs resolve, so passing a ref hands the expression that element as element. world: "page" runs in the page’s own realm, which is the only way to reach a framework’s globals and is the one mode the page could notice. A ref cannot be passed to page-world code, and asking is a 400 saying so rather than a silent undefined.

What the page has logged, from two sources with two different costs. Free and invisible, always on: the browser’s own entries through the CDP Log domain — failed requests, CSP and mixed-content violations, deprecations, DOM warnings — which arrive with a browser:<source> kind. Page-visible, and off by default: the page’s own console.log calls and its uncaught errors and unhandled rejections, which need the wrapper that POST /profiles/:id/page/console-mode installs. That split is measured, not assumed. An earlier version captured uncaught errors from an isolated world and captured nothing at all — Blink reports an uncaught exception only to the world it was thrown in — and Log.enable does not carry them either, because they ride Runtime.exceptionThrown, which needs the one domain that makes a profile detectable. note always says which sources you are getting. Timestamps on page entries are stamped on read rather than in the page, and ordering between the sources is approximate; that is stated rather than implied, because a timestamp that looks precise and is not is worse than none.

Turns on capture of everything that happens in the page’s own world: its console.log calls, its uncaught errors and its unhandled rejections. This is the one page-control feature a page could detect, and it is off by default for that reason — seeing a console.log call means being the function that gets called, so console is wrapped in the page’s own realm and the error listeners are registered there too. The wrapper’s toString reports a native body, but a page holding a reference from before it ran can still tell. There is no invisible alternative for these three, and that is measured rather than assumed: isolated-world listeners receive no uncaught exceptions, and the Log domain does not carry them. Turning it off restores the original console functions exactly. The reply carries detectable and a sentence saying so, because a switch that costs something and does not say so has misled the caller by omission.

Starts recording every request this tab makes, and keeps recording across navigations until you stop it. Unlike the fixed-window tab route, this runs in the background, so you can act and then read. Requests from before you started are not in it — reload if you need the ones that built the page. A recording left running stops itself after thirty minutes, and the next read says that it did.

The recorded requests with their method, type, status and failure reason. Carries total, how many were dropped when the buffer filled, and stoppedBecause when the log simply ends — a truncated list that reports itself as complete is the same lie as a count over eight failures.

Stops recording. What has already been recorded stays readable.

The response body of one recorded request, by URL. Fetched on demand rather than buffered, so recording a busy page does not hold every response in memory — which also means the recording has to still be running, and a 400 says so.

What alert, confirm and prompt have asked, and how they are being answered.

Sets how JavaScript dialogs are answered. This exists because attaching at all makes it necessary: Chromium dismisses a dialog itself when nothing is attached to the page, but the moment page control attaches, the page blocks until this client answers — so a default of doing nothing would hang any page that calls alert(), the automation causing the fault it was sent to observe. Dismiss is the default, every dialog is recorded, and the log is readable.

Every tab page control currently holds open, with whether it is recording and how long it has been idle. Attachments are made on first use and dropped when the profile stops or after ten idle minutes; this exists so one that outlives its usefulness is visible rather than merely forgotten — a leaked DevTools attachment leaves the page marked as inspected.

Releases the attachment for a tab, or for every tab of a profile when tabId is omitted. Rarely needed — they expire on their own and a stopped profile drops all of its own — but it is here for when you want the page left with nothing attached. Refs from previous snapshots die with it. Releasing something already released is detached: false, not a 404.