v2.20.0

Surf 2.20.0 adds an optional way to find and interact with page elements by describing what you need. You can combine those actions into short workflows and adjust confidence thresholds for individual commands without changing the safer defaults. On dynamic pages, Surf is more careful about checking whether a change worked before it proceeds. Windows Chrome setup from WSL is more reliable and easier to diagnose, alongside several everyday CLI fixes.

Highlights

• Find and act on page elements with optional semantic browser commands, with explicit permission required for changes.
• Run short, repeatable browser workflows from a file, including form entry and checks.
• Set confidence thresholds per semantic command while keeping the safer defaults.
• Install Surf's Windows Chrome connection from WSL more reliably, with better diagnosis when it fails.

Full changelog

Highlights

• Find and act on page elements with optional semantic browser commands, with explicit permission required for changes.
• Run short, repeatable browser workflows from a file, including form entry and checks.
• Set confidence thresholds per semantic command while keeping the safer defaults.
• Install Surf's Windows Chrome connection from WSL more reliably, with better diagnosis when it fails.

Added

• Semantic browser commands - Use semantic.find, semantic.verify, and semantic.filter to locate and check elements, or semantic.act to work toward a goal. These optional commands use TypeSafe AI credentials; existing Surf commands do not need a provider. Changes to a page require --allow-write and can be limited with --allow-ref. Surf checks that the target has not changed before acting.
• Browser workflows - Run short workflows with find, same-origin open, ensureChecked, fill, click, and assert steps. Workflows require --allow-semantic; changes also require --allow-write. Use --inputs-stdin for private form values. Validation and dry runs work offline.
• Adjustable confidence - Set command-specific semantic confidence thresholds with repeatable --threshold name=value options. Defaults and write permissions remain in place, and structured output shows the thresholds used.

Changed

• Development dependencies - Updated Biome, Chrome and Node.js types, Pi Subagents, Puppeteer, TypeBox, Vitest, Vite, and Zod.

Fixed

• Dynamic pages - Semantic actions wait briefly for a page to update before checking the result, without repeating a change when its outcome is uncertain. They keep the action history when a later step fails and stop before changes when a requested option is unavailable. See #316.
• Semantic navigation - Equivalent navigation controls no longer appear as competing choices, while controls in different contexts remain separate.
• Connection troubleshooting - When socket or native-host checks fail, surf doctor explains how to enable extension Debug Mode and inspect the service-worker console.
• frame.diagnose help - Command-specific help now describes the diagnostic options and related frame commands without contacting Chrome. Thanks to @gimbo for #280.
• network.body output - surf network.body <id> prints the captured response exactly, including empty or JSON-shaped text; --json remains structured. Thanks to @Ananasiy for #291.
• npm extension files - Publishing rebuilds the extension so packages include current browser code. Thanks to @gimbo for #279 and @hongyuatcufe for confirming the issue.
• Windows Chrome from WSL - Installation now registers the native host for each Windows browser, even when Windows programs are absent from the WSL PATH. It tests the generated launcher before registration and checks that a fallback starts the intended distro. surf doctor checks the registration and tests only unmodified Surf launchers. Thanks to @airtonix for #290.