feat: Enable capture of profiling data (#290)

* feat: Enable capture of profiling data

Adding a new set of commands:
```
agent-browser profiler start

agent-browser profiler stop trace.json
```

With this, agents can start a profiling trace, perform a set of actions, and then extract the profiling data for analysis.

**Note:** I was originally going to call it `agent-browser profile` but I realized that might cause confusion with the `--profile` flag

CDP supports a couple commands for starting/stopping a trace.
When a trace is running, it emits events that need to be picked up.
We store these locally in the daemon until the trace is completed.
When the final event is received, we dump all of them into an output file.

That file can be loaded directly into chrome devtools or another analysis tool to visualize what happened during the agentic run.

Added some basic rust tests for parsing the commands (since they have some optional / required args)

TS daemon adds ~6 tests to make sure the profiling lifecycle (including saving the output file) works as intended

* add docs

* fixes

* fixes

---------

Co-authored-by: Chris Tate <chris@ctate.dev>

docs/src/app/commands/page.mdx

@@ -176,6 +176,8 @@ agent-browser dialog dismiss          # Dismiss dialog
 ```bash
 agent-browser trace start [path]      # Start trace
 agent-browser trace stop [path]       # Stop and save trace
+agent-browser profiler start          # Start Chrome DevTools profiling
+agent-browser profiler stop [path]    # Stop and save profile (.json)
 agent-browser record start <path>     # Start video recording (WebM)
 agent-browser record stop             # Stop and save video
 agent-browser record restart <path>   # Stop current and start new recording

docs/src/app/profiler/page.mdx

@@ -0,0 +1,102 @@
+export const metadata = { title: "Profiler" }
+
+# Profiler
+
+Capture Chrome DevTools performance profiles during browser automation.
+Use profiles to diagnose slow page loads, expensive JavaScript, layout thrashing,
+and other performance bottlenecks in agentic workflows.
+
+## Basic usage
+
+```bash
+# Start profiling
+agent-browser profiler start
+
+# Perform actions
+agent-browser navigate https://example.com
+agent-browser click "#button"
+
+# Stop and save profile
+agent-browser profiler stop ./trace.json
+```
+
+The output JSON file can be loaded into Chrome DevTools, Perfetto UI, or any
+tool that accepts Chrome Trace Event format.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `profiler start` | Start recording a performance profile |
+| `profiler start --categories <list>` | Start with custom trace categories |
+| `profiler stop [path]` | Stop profiling and save to file |
+
+## Trace categories
+
+The `--categories` flag accepts a comma-separated list of Chrome trace categories.
+
+```bash
+agent-browser profiler start --categories "devtools.timeline,v8.execute,blink.user_timing"
+```
+
+Default categories include `devtools.timeline`, `v8.execute`, `blink`,
+`blink.user_timing`, `latencyInfo`, `renderer.scheduler`, `toplevel`, and
+several `disabled-by-default-*` categories for detailed CPU profiling and
+call stack analysis.
+
+### Common categories
+
+| Category | What it captures |
+|----------|-----------------|
+| `devtools.timeline` | Standard DevTools performance events |
+| `v8.execute` | Time spent running JavaScript |
+| `blink` | Renderer events (layout, paint, style) |
+| `blink.user_timing` | `performance.mark()` and `performance.measure()` calls |
+| `latencyInfo` | Input-to-display latency |
+| `disabled-by-default-v8.cpu_profiler` | Sampling-based JS CPU profiling |
+
+## Output format
+
+The output is a JSON file in Chrome Trace Event format:
+
+```json
+{
+  "traceEvents": [
+    {
+      "cat": "devtools.timeline",
+      "name": "RunTask",
+      "ph": "X",
+      "ts": 12345,
+      "dur": 100,
+      "pid": 1,
+      "tid": 1
+    }
+  ],
+  "metadata": {
+    "clock-domain": "LINUX_CLOCK_MONOTONIC"
+  }
+}
+```
+
+The `metadata.clock-domain` field reflects the host platform (Linux or macOS).
+On Windows it is omitted.
+
+## Viewing profiles
+
+- **Chrome DevTools** -- Performance panel > Load profile
+- **Perfetto** -- https://ui.perfetto.dev/ (drag and drop the JSON file)
+- **Trace Viewer** -- `chrome://tracing` in any Chromium browser
+
+## Use cases
+
+- **Page load analysis** -- Profile navigation to identify slow resources, long tasks, or layout shifts
+- **Interaction profiling** -- Measure the cost of clicks, form fills, and other user interactions
+- **CI regression checks** -- Capture profiles per build and compare trace data over time
+- **Agent workflow optimization** -- Find which steps in an agentic flow are most expensive
+
+## Limitations
+
+- Only works with Chromium-based browsers (Chrome, Edge). Not supported on Firefox or WebKit.
+- Trace data accumulates in memory while profiling is active (capped at 5 million events). Stop profiling promptly after the area of interest.
+- Data collection on stop has a 30-second timeout. If the browser is unresponsive, the stop command may fail.
+- When no output path is provided, the profile is saved to an auto-generated path under the agent-browser temp directory.

docs/src/lib/docs-navigation.ts

@@ -32,6 +32,7 @@ export const navigation: NavSection[] = [
       { name: "Sessions", href: "/sessions" },
       { name: "CDP Mode", href: "/cdp-mode" },
       { name: "Streaming", href: "/streaming" },
+      { name: "Profiler", href: "/profiler" },
       { name: "iOS Simulator", href: "/ios" },
     ],
   },