surf-codebase_skill

Overview

This skill lets you navigate and modify the surf-cli codebase that powers AI-driven Chrome automation via a CLI, a native host, and a browser extension. It focuses on implementing and debugging features around Chrome DevTools Protocol (CDP), accessibility-based DOM interactions, network/console capture, and CLI tooling. Use it to add commands, CDP operations, or content-script behaviors and to reason about architecture and message flow.

How this skill works

The codebase routes CLI commands through a native host into a service worker which dispatches either CDP operations or content-script messages to the page. Key components include a CDP controller for browser control, a content-script that generates accessibility trees and stable element refs, and a CLI layer that maps tools to extension messages. Screenshot caching, tab registry, and network/console tracking are implemented centrally in the service worker and CDP controller.

When to use it

• Adding a new surf-cli command that triggers browser actions from the CLI.
• Implementing a new CDP operation such as emulation, network manipulation, or custom screenshot capture.
• Building DOM interactions or accessibility-based selectors that need stable element references.
• Debugging message flow, CDP attach latency, or native-extension IPC issues.
• Extending network/console capture and storage or adding formatters for captured data.

Best practices

• Add CLI entries in the native/cli TOOLS map and create matching handlers in the service worker’s message router.
• Keep CDP methods on the CDPController and call this.send(tabId, 'Domain.method', params) to maintain consistent wiring.
• Use accessibility tree handlers and window.__piRefs for stable element references instead of brittle selectors.
• Handle CDP events in handleCDPEvent when operations require asynchronous event tracking (network, loading, console).
• Account for CDP attach latency (100–500ms) and chrome:// restrictions; document when refresh is needed for content scripts.

Example use cases

• Add a 'click-and-screenshot' CLI tool: register in TOOLS, route to EXECUTE_CLICK, then call captureScreenshot in CDPController.
• Implement network throttling: add emulateNetwork in CDPController and expose a CLI flag to trigger it via the host.
• Create a form autofill command: use GENERATE_ACCESSIBILITY_TREE to locate fields, then FORM_INPUT via the content script.
• Extend request logging: subscribeToNetwork in CDPController, format entries using native formatters, and write to /tmp/surf/requests.jsonl.