Skip to content

v2.26.0

Latest

Choose a tag to compare

@nicobailon nicobailon released this 06 Nov 06:08
· 59 commits to main since this release

Surf now tells you when something didn't work. Clicks, typing, dropdown choices and locate actions used to print OK even when nothing happened. Now they fail with the reason, for example a disabled button, a cookie banner in the way, or text longer than the field allows. Keeping Surf current takes one command, surf update, and setup no longer needs an extension ID copied from Chrome. surf read also shows more of real pages, including forms built from custom components, styled checkboxes, and what each field currently holds.

Highlights

  • Clicks and typing fail honestly. Surf says why an action didn't work (e5 is disabled, e2 is covered by dialog "Cookie consent") instead of printing OK. Clicks wait for the element to be ready and use a real mouse click, and locate no longer clicks "Save draft" when you asked for "Save".
  • One command to update. surf update updates the CLI, the browser connection and the agent skill, then reloads the extension. When the parts get out of step, every command warns you.
  • read sees more of the page. It now lists form fields inside custom components (such as SmartRecruiters job forms) and styled checkboxes, along with what each text field holds. Passwords are never shown. It also counts the controls further down the page.
  • New commands. surf check and surf uncheck set a checkbox to the state you want. surf page.text --ref prints a field's whole value. surf type --escapes types real newlines and tabs.

Need to know

Who What to do
Existing Surf users Surf's extension ID changes once. Run surf install, then reload Surf in chrome://extensions. Settings saved in the old copy, such as Debug Mode, don't carry over.
Scripts that relied on OK Actions that used to print OK without working now exit with an error. These include clicking a disabled or covered element, an ambiguous locate --action, text too long for its field, and a dropdown value with no matching option.

Highlights

  • When a click, typed text, dropdown choice or locate action doesn't work, Surf now fails and says why (e5 is disabled, e2 is covered by dialog "Cookie consent") instead of printing OK. Clicks also wait for the element to be ready and use a real mouse click.
  • surf update updates the CLI, the browser connection and the agent skill, then reloads the extension, all in one command. surf install no longer asks for an extension ID.
  • surf read sees more of the page: form fields inside custom components, styled checkboxes, what each text field holds (never passwords), and a count of controls further down the page.
  • New surf check and surf uncheck set a checkbox to the state you want, and surf page.text --ref prints a field's whole value.
  • If you already use Surf, its extension ID changes once: rerun surf install, then reload Surf in chrome://extensions.

Added

  • surf check and surf uncheck set a checkbox to the state you want - Clicking a checkbox toggles it, so an agent had to read its state first or risk unticking a box that was already ticked by default. surf check <ref> and surf uncheck <ref> leave a checkbox, switch or radio alone when it is already in that state (e6 was already checked; nothing clicked.), and otherwise click it like a real mouse would, so pages that keep their own state in click handlers (such as React apps) see the change. If the control still isn't in the requested state after the click, the command fails. uncheck on a radio button fails and says to pick another option in its group. Thanks to @morgan55555 for #436.
  • Surf can start your browser for you - Set "browser": { "autostart": true } in surf.json and a command run while the browser (or its Surf host) isn't running starts it, waits up to 30 seconds for Surf to connect, then runs. surf go <url> opens the browser on that page instead of a blank new tab. Pick the browser with "app" (chrome, chromium, brave, edge, arc or helium) or give the exact command with "command"; "timeoutMs" changes the wait. Thanks to @morgan55555 for #424.
  • surf doctor shows the CLI, native host and extension versions - The CLI, native host and loaded extension come from one package but pick up a new version at different times, so they can run different versions. surf doctor now reports all three versions and fails with a version-skew check, naming the fix (surf update), when they differ.
  • Every command warns when the CLI, native host and extension versions differ - The native host now sends its own version and the extension's with each response, and when either differs from the CLI's, the command prints one line on stderr, such as surf: version mismatch (cli 2.26.0, host 2.25.0, extension 2.25.0). Run `surf update`. The command's output and exit code stay the same, and a host too old to send its version prints no line.
  • surf update updates surf and reloads the extension in one step - Updating used to mean reinstalling with npm, rerunning surf install, and clicking Reload in chrome://extensions, and a missed step left the CLI, native host and extension on different versions. surf update reinstalls with the npm that installed this surf (not whichever npm is first on PATH), or runs npm ci && npm run build in a linked repo checkout, refreshes the native host for the browsers that already have it and the agent skill links, asks the extension to reload itself, and prints the versions before and after (--json for {before, after, steps}). It changes nothing for an install it doesn't recognize. The first time, the running extension is too old to reload itself, so surf update asks you to reload it once in chrome://extensions.
  • surf install links the agent skill to the installed package - The Surf skill for Claude Code and pi was copied by hand, so it fell behind the CLI. surf install now links ~/.claude/skills/surf and ~/.pi/agent/skills/surf to the skills/surf folder of the surf-cli you ran it with, so the skill updates with surf. It only links where that agent's skills folder already exists, repoints an existing link, and never touches a skill folder you made yourself: it says it kept it and that you can remove it and rerun surf install to switch. It skips pi when pi already loads surf-cli as a package, so the skill isn't loaded twice.
  • surf install no longer needs an extension ID - Chrome gave each unpacked Surf an ID based on the folder it was loaded from, so you had to copy it from chrome://extensions into surf install <extension-id>. The extension now carries a fixed public key, so every Surf build has the ID oaclimdkkglbnpekeignmjenkodkaaka. surf install <extension-id> still works for a fork or a build with a different ID. If you already use Surf, its extension ID changes once: rerun surf install, then reload Surf in chrome://extensions. Until you reload, the old copy keeps working; afterwards a disabled copy under the old ID stays listed until the browser restarts. Settings the old extension stored, such as Debug Mode, don't carry over to the new ID.
  • surf page.text --ref prints one field's whole value or one element's text - To check a long note or cover letter before sending it, you had only surf read, which cuts a field's value at 80 characters and joins its lines, or a surf js call with a CSS selector. surf page.text --ref <ref> now prints a text field's, textarea's or editable area's whole current value, newlines included, and any other element's rendered text. A secret field (the same ones read shows as [value hidden]) fails with e4 is a secret field, so its value is not shown and its value is never sent. Thanks to @morgan55555 for #449.
  • surf type --escapes types newlines and tabs - Putting a real newline or tab into a shell argument is awkward, and smaller models often can't, so surf type "line1\nline2" typed a backslash and an n. With --escapes, \n, \t, \r and \\ in the text become a newline, tab, carriage return and one backslash before typing, on every type path (--ref, --into and at the cursor). Any other backslash sequence is typed as written. Without the flag, surf type types the text literally as before. Thanks to @morgan55555 for #451.

Fixed

  • surf read says how many controls it left out for being off-screen - surf read lists only the controls on screen unless you pass --all, and gave no sign that more were further down the page, so agents read a page, missed the controls below the fold, and sometimes decided the page was broken. When controls are left out for being off-screen, surf read now ends with a line such as +142 elements off-screen: surf read --all. There's no such line when nothing was left out, or with --all or --ref. Thanks to @morgan55555 for #452.
  • locate no longer acts on the wrong element - surf locate.role, locate.text and locate.label with --action used to act on the first element whose name contained your words, and printed OK, so surf locate.role button --name "Save" --action click could click "Save draft", and --name "Delete" on a list clicked the first row's Delete button. Now an element whose name is exactly what you asked for wins over partial matches, and when more than one element still matches, nothing is clicked or filled: the command fails and lists each match with its ref, so you can act on the one you mean with surf click <ref>.
  • Typing into a field that can't take the text fails instead of saying OK - surf type "<text>" --ref <ref>, surf type "<text>" --into <selector> and surf form.fill used to write past a field's character limit, overwrite a read-only field, and print OK when the page threw the text away. Now a read-only or disabled field, or text longer than the field allows, fails with the reason, such as e1 accepts at most 4 characters, but 8 were given, and nothing is written. If the field still holds its old value after typing, or the page empties it, the command fails with did not keep the typed text. A field that reformats what you typed, such as a phone number mask, still counts as success. A form.fill that fills some fields but not others now fails too, says how many it filled, and names each field it couldn't fill.
  • Errors say what went wrong instead of "Try refreshing the page" - When a page command such as read, click, type, locate.* or wait.element failed for any reason, Surf said Content script not loaded. Try refreshing the page., even when Surf was working on the page and something else went wrong. Refreshing then threw away what was typed into the page. Surf now says this only when its script really isn't answering on the page. A command cut short because the page navigated or closed says so, and any other failure shows its real error.
  • Clicking by ref only clicks what a user could click - surf click <ref> and surf locate.* --action click used to fire the element directly and print OK for a disabled button, click straight through a cookie banner or dialog covering it, and do nothing on buttons that ignore script-made clicks. Now Surf waits up to 5 seconds for the element to be visible, enabled and not covered, scrolling it into view if it is hidden inside a scroll box, then clicks it with a real mouse event. If it never becomes clickable, the command fails with the reason, such as e5 is disabled or e2 is covered by dialog "Cookie consent", and nothing is clicked.
  • A ref from an earlier page no longer clicks something on the current one - Every page used to number its elements from e1, so after a navigation or reload an old ref such as e2 named a different element on the new page, and surf click e2 acted on it and printed OK. Within a tab, a new page now numbers its elements after the ones earlier pages used, so refs never repeat. Using a ref from an earlier page fails and names that page, such as e2 is from an earlier page in this tab (https://example.com/plan). Run surf read to get current refs. A page you go back to from the browser's back/forward cache keeps its own refs.
  • Custom buttons, links, tabs and menu items show their names - A control built from a <div> or <span> with a role such as button, link, tab, menuitem or option got an empty name when its text sat inside a child element or was shorter than 3 characters, so surf read listed <div role="button"><span>Save</span></div> as button "", and surf locate.role button --name "Save" --action click refused because it couldn't tell such buttons apart. These controls now take their name from their text, as <button> already did, so surf read shows button "Save" and locate picks the exact one. Table cells and headers are named from their text too. See #430.
  • A click that can't be a real mouse click says so - When surf click <ref> or locate.* --action click couldn't send a real mouse click, it fell back to clicking the element inside the page and still printed only OK, so you couldn't tell why a site ignored it. Now the output adds a line such as Clicked e3 inside the page, not with the mouse, because its tab is hidden (a background tab, or a window behind other windows). If nothing happened, switch to the tab (surf tab.switch <id>) or bring its window to the front and retry. Clicks in hidden tabs, inside frames, or when Surf can't attach its debugger still go in the page after the same checks, and now say why. After you click Cancel on Chrome's "is debugging this browser" bar, the next ref click attaches again and sends a real mouse click instead of quietly falling back.
  • Form fields inside custom components are now visible - Pages that build their forms from custom elements with open shadow roots, such as job application forms on SmartRecruiters, showed none of their fields in surf read, and surf locate.label "First name" found nothing. Surf now reads through open shadow roots, so those fields and buttons appear with their names (taken from the label inside the component), you can click and type into them by ref as usual, and locate.label, locate.role and locate.text find them too, acting on the field inside the component rather than on the component that shares its id. Closed shadow roots stay unreachable. Thanks to @morgan55555 for #437.
  • Selecting an option that doesn't exist fails instead of saying OK - surf select <ref> <value> printed a warning but exited 0 when no option matched, and surf form.fill quietly emptied a dropdown it couldn't match. Both now fail and change nothing, for example e5 has no option matching "nowhere" (by value), so nothing was selected. form.fill matches a dropdown option by its value or its visible text.
  • read shows what a field holds, and never a password - surf read listed a text field by its label or placeholder but not its contents, so checking what surf type or the user entered took a surf js call. Text inputs, textareas and editable areas now show their current value, such as textbox "hello@example.com" [e85] type="email" placeholder="hello@example.com" value="hello22", cut at 80 characters with .... Secret fields show [value hidden] instead: type="password" fields, fields whose autocomplete is current-password, new-password, one-time-code or a cc- card token, and fields the page masks on screen with -webkit-text-security. The page-change report after surf type now hides masked fields' values too. read also no longer prints a password as the field's name: a password field Surf couldn't otherwise name, such as one inside a <label> without for, used to appear as textbox "<the password>". Thanks to @morgan55555 for #434.
  • On Android, surf doctor says why it can't work and what to do instead - In Termux, surf doctor and a failed command told you to make sure the browser was running with the Surf extension, but no Android browser can run the extension's native host. Now surf doctor fails with that reason and both point to running the browser on a desktop machine and connecting with surf --remote <host>:<port> --remote-credential <file>. Thanks to @shankarkrupa for #417.
  • surf install sets up the host from the surf you ran it with - With two surf-cli installs on PATH (for example one from a Node version manager and one from Homebrew), surf install pointed the browser's native host at whichever copy npm root -g named, so the browser could run a different, older host than your surf command. It now always uses the host from the same install as the surf you ran. SURF_HOST_PATH still overrides it.
  • Page text no longer fills up with CSS rules - surf page.text and the --- Page Text --- part of surf read took every bit of text in the page's markup, so on sites that put their styles and scripts inside the page body (such as Tilda sites) the output was mostly CSS and JavaScript. They now return the text the page actually shows. Styles, scripts and hidden content such as collapsed sections or display:none blocks are left out. Thanks to @morgan55555 for #435.
  • page.html and page.save work without --selector - surf page.html and surf page.save --output <file> failed with Value is unserializable unless you passed --selector, because Chrome refuses an empty argument in the script it runs. They now return the whole document with its <!doctype> line. Thanks to @doctorguile for #423.
  • surf read lists form fields the page draws over with a transparent input - Styled checkboxes, radios and other fields often leave the real <input> at opacity: 0 and draw their own box beneath it, so surf read left the field out unless you passed --include-hidden, and surf check or surf click on it reported no visible change. Now an input, select or textarea that is transparent but otherwise shown appears in surf read and its YAML output, surf check reports its change (e3 checkbox "I agree" now checked), and an old ref to it still finds it after the page re-renders. Other transparent elements, such as faded-out menus and buttons, stay hidden. Thanks to @morgan55555 for #450.