diff (#510)

* diff * fixes * fixes * fixes * fixes * fixes * better docs
2026-02-19 23:51:09 -06:00
parent 9732031087
commit d5a667ea2d
21 changed files with 2446 additions and 88 deletions
@@ -3,7 +3,7 @@
  "version": "0.1.0",
  "private": true,
  "scripts": {
-    "dev": "next dev",
+    "dev": "portless agent-browser next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint"
@@ -70,25 +70,30 @@ This enables control of:

 ## Global options

-| Option | Description |
-| --- | --- |
-| `--session <name>` | Use isolated session |
-| `--profile <path>` | Persistent browser profile directory |
-| `-p <provider>` | Cloud browser provider (`browserbase`, `browseruse`, `kernel`) |
-| `--headers <json>` | HTTP headers scoped to origin |
-| `--executable-path` | Custom browser executable |
-| `--args <args>` | Browser launch args (comma-separated) |
-| `--user-agent <ua>` | Custom User-Agent string |
-| `--proxy <url>` | Proxy server URL |
-| `--proxy-bypass <hosts>` | Hosts to bypass proxy |
-| `--json` | JSON output for scripts |
-| `--full, -f` | Full page screenshot |
-| `--name, -n` | Locator name filter |
-| `--exact` | Exact text match |
-| `--headed` | Show browser window |
-| `--cdp <port\|url>` | CDP connection (port or WebSocket URL) |
-| `--auto-connect` | Auto-discover and connect to running Chrome |
-| `--debug` | Debug output |
+<table>
+  <thead>
+    <tr><th>Option</th><th>Description</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>--session &lt;name&gt;</code></td><td>Use isolated session</td></tr>
+    <tr><td><code>--profile &lt;path&gt;</code></td><td>Persistent browser profile directory</td></tr>
+    <tr><td><code>-p &lt;provider&gt;</code></td><td>Cloud browser provider (<code>browserbase</code>, <code>browseruse</code>, <code>kernel</code>)</td></tr>
+    <tr><td><code>--headers &lt;json&gt;</code></td><td>HTTP headers scoped to origin</td></tr>
+    <tr><td><code>--executable-path</code></td><td>Custom browser executable</td></tr>
+    <tr><td><code>--args &lt;args&gt;</code></td><td>Browser launch args (comma-separated)</td></tr>
+    <tr><td><code>--user-agent &lt;ua&gt;</code></td><td>Custom User-Agent string</td></tr>
+    <tr><td><code>--proxy &lt;url&gt;</code></td><td>Proxy server URL</td></tr>
+    <tr><td><code>--proxy-bypass &lt;hosts&gt;</code></td><td>Hosts to bypass proxy</td></tr>
+    <tr><td><code>--json</code></td><td>JSON output for scripts</td></tr>
+    <tr><td><code>--full, -f</code></td><td>Full page screenshot</td></tr>
+    <tr><td><code>--name, -n</code></td><td>Locator name filter</td></tr>
+    <tr><td><code>--exact</code></td><td>Exact text match</td></tr>
+    <tr><td><code>--headed</code></td><td>Show browser window</td></tr>
+    <tr><td><code>{"--cdp <port|url>"}</code></td><td>CDP connection (port or WebSocket URL)</td></tr>
+    <tr><td><code>--auto-connect</code></td><td>Auto-discover and connect to running Chrome</td></tr>
+    <tr><td><code>--debug</code></td><td>Debug output</td></tr>
+  </tbody>
+</table>

 ## Cloud providers

@@ -8,12 +8,17 @@ Create an `agent-browser.json` file to set persistent defaults instead of repeat

 agent-browser checks two locations, merged in priority order:

-| Priority | Location | Scope |
-|----------|----------|-------|
-| 1 (lowest) | `~/.agent-browser/config.json` | User-level defaults |
-| 2 | `./agent-browser.json` | Project-level overrides |
-| 3 | `AGENT_BROWSER_*` env vars | Override config values |
-| 4 (highest) | CLI flags | Override everything |
+<table>
+  <thead>
+    <tr><th>Priority</th><th>Location</th><th>Scope</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>1 (lowest)</td><td><code>~/.agent-browser/config.json</code></td><td>User-level defaults</td></tr>
+    <tr><td>2</td><td><code>./agent-browser.json</code></td><td>Project-level overrides</td></tr>
+    <tr><td>3</td><td><code>AGENT_BROWSER_*</code> env vars</td><td>Override config values</td></tr>
+    <tr><td>4 (highest)</td><td>CLI flags</td><td>Override everything</td></tr>
+  </tbody>
+</table>

 Project-level values override user-level values. Environment variables override both. CLI flags always win.

@@ -40,29 +45,34 @@ AGENT_BROWSER_CONFIG=./ci-config.json agent-browser open example.com

 Every CLI flag can be set in the config file using its camelCase equivalent:

-| Config Key | CLI Flag | Type |
-|------------|----------|------|
-| `headed` | `--headed` | boolean |
-| `json` | `--json` | boolean |
-| `full` | `--full, -f` | boolean |
-| `debug` | `--debug` | boolean |
-| `session` | `--session` | string |
-| `sessionName` | `--session-name` | string |
-| `executablePath` | `--executable-path` | string |
-| `extensions` | `--extension` | string[] |
-| `profile` | `--profile` | string |
-| `state` | `--state` | string |
-| `proxy` | `--proxy` | string |
-| `proxyBypass` | `--proxy-bypass` | string |
-| `args` | `--args` | string |
-| `userAgent` | `--user-agent` | string |
-| `provider` | `-p, --provider` | string |
-| `device` | `--device` | string |
-| `ignoreHttpsErrors` | `--ignore-https-errors` | boolean |
-| `allowFileAccess` | `--allow-file-access` | boolean |
-| `cdp` | `--cdp` | string |
-| `autoConnect` | `--auto-connect` | boolean |
-| `headers` | `--headers` | string (JSON) |
+<table>
+  <thead>
+    <tr><th>Config Key</th><th>CLI Flag</th><th>Type</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>headed</code></td><td><code>--headed</code></td><td>boolean</td></tr>
+    <tr><td><code>json</code></td><td><code>--json</code></td><td>boolean</td></tr>
+    <tr><td><code>full</code></td><td><code>--full, -f</code></td><td>boolean</td></tr>
+    <tr><td><code>debug</code></td><td><code>--debug</code></td><td>boolean</td></tr>
+    <tr><td><code>session</code></td><td><code>--session</code></td><td>string</td></tr>
+    <tr><td><code>sessionName</code></td><td><code>--session-name</code></td><td>string</td></tr>
+    <tr><td><code>executablePath</code></td><td><code>--executable-path</code></td><td>string</td></tr>
+    <tr><td><code>extensions</code></td><td><code>--extension</code></td><td>string[]</td></tr>
+    <tr><td><code>profile</code></td><td><code>--profile</code></td><td>string</td></tr>
+    <tr><td><code>state</code></td><td><code>--state</code></td><td>string</td></tr>
+    <tr><td><code>proxy</code></td><td><code>--proxy</code></td><td>string</td></tr>
+    <tr><td><code>proxyBypass</code></td><td><code>--proxy-bypass</code></td><td>string</td></tr>
+    <tr><td><code>args</code></td><td><code>--args</code></td><td>string</td></tr>
+    <tr><td><code>userAgent</code></td><td><code>--user-agent</code></td><td>string</td></tr>
+    <tr><td><code>provider</code></td><td><code>-p, --provider</code></td><td>string</td></tr>
+    <tr><td><code>device</code></td><td><code>--device</code></td><td>string</td></tr>
+    <tr><td><code>ignoreHttpsErrors</code></td><td><code>--ignore-https-errors</code></td><td>boolean</td></tr>
+    <tr><td><code>allowFileAccess</code></td><td><code>--allow-file-access</code></td><td>boolean</td></tr>
+    <tr><td><code>cdp</code></td><td><code>--cdp</code></td><td>string</td></tr>
+    <tr><td><code>autoConnect</code></td><td><code>--auto-connect</code></td><td>boolean</td></tr>
+    <tr><td><code>headers</code></td><td><code>--headers</code></td><td>string (JSON)</td></tr>
+  </tbody>
+</table>

 ## Common Configurations

@@ -0,0 +1,177 @@
+export const metadata = { title: "Diffing" }
+
+import { DiffDemo } from "@/components/diff-demo"
+
+# Diffing
+
+Compare page states to detect changes -- structurally via accessibility tree snapshots, visually via pixel comparison, or across two different URLs.
+
+<DiffDemo />
+
+## Commands
+
+<table>
+  <thead>
+    <tr><th>Command</th><th>Description</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>diff snapshot</code></td><td>Compare current snapshot to last snapshot in session</td></tr>
+    <tr><td><code>diff snapshot --baseline &lt;file&gt;</code></td><td>Compare current snapshot to a saved file</td></tr>
+    <tr><td><code>diff screenshot --baseline &lt;file&gt;</code></td><td>Visual pixel diff against a baseline image</td></tr>
+    <tr><td><code>diff url &lt;url1&gt; &lt;url2&gt;</code></td><td>Compare two pages (snapshot + optional screenshot)</td></tr>
+  </tbody>
+</table>
+
+## Snapshot diff
+
+Compares the accessibility tree between two points in time using a line-level text diff.
+
+```bash
+# Compare against the last snapshot taken in this session
+agent-browser diff snapshot
+
+# Compare against a saved baseline file
+agent-browser diff snapshot --baseline before.txt
+
+# Scope to a specific part of the page
+agent-browser diff snapshot --selector "#main" --compact
+```
+
+Without `--baseline`, the command automatically compares against the most recent snapshot taken in the current session. This is the primary use case for agents verifying that an action had the intended effect.
+
+### Options
+
+<table>
+  <thead>
+    <tr><th>Flag</th><th>Description</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>-b, --baseline &lt;file&gt;</code></td><td>Path to a saved snapshot file to compare against</td></tr>
+    <tr><td><code>-s, --selector &lt;sel&gt;</code></td><td>Scope the current snapshot to a CSS selector or @ref</td></tr>
+    <tr><td><code>-c, --compact</code></td><td>Use compact snapshot format</td></tr>
+    <tr><td><code>-d, --depth &lt;n&gt;</code></td><td>Limit snapshot tree depth</td></tr>
+  </tbody>
+</table>
+
+### Output
+
+The diff uses `+` for added lines and `-` for removed lines, similar to unified diff format. A summary line shows the count of additions, removals, and unchanged lines.
+
+```
+- button "Submit" [ref=e2]
+ button "Submit" [ref=e2] [disabled]
+  3 additions, 2 removals, 41 unchanged
+```
+
+## Screenshot diff
+
+Compares the current page screenshot against a baseline image at the pixel level. Produces a diff image with changed pixels highlighted in red.
+
+```bash
+# Basic visual diff
+agent-browser diff screenshot --baseline before.png
+
+# Save diff image to a specific path
+agent-browser diff screenshot --baseline before.png --output diff.png
+
+# Adjust threshold and scope to element
+agent-browser diff screenshot --baseline before.png --threshold 0.2 --selector "#hero"
+```
+
+### Options
+
+<table>
+  <thead>
+    <tr><th>Flag</th><th>Description</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>-b, --baseline &lt;file&gt;</code></td><td>Baseline PNG/JPEG image to compare against (required)</td></tr>
+    <tr><td><code>-o, --output &lt;file&gt;</code></td><td>Path for the generated diff image (default: temp dir)</td></tr>
+    <tr><td><code>-t, --threshold &lt;0-1&gt;</code></td><td>Color distance threshold (default: 0.1). Higher = more tolerant</td></tr>
+    <tr><td><code>-s, --selector &lt;sel&gt;</code></td><td>Scope the current screenshot to an element</td></tr>
+    <tr><td><code>--full</code></td><td>Take a full-page screenshot</td></tr>
+  </tbody>
+</table>
+
+### Output
+
+Reports the diff image path, number of different pixels, and mismatch percentage. The diff image shows unchanged pixels dimmed with changed pixels in red.
+
+If the baseline and current images have different dimensions, the command reports a dimension mismatch instead of attempting pixel comparison.
+
+## URL diff
+
+Compares two pages by navigating to each in sequence and diffing the results.
+
+```bash
+# Compare two URLs (snapshot diff)
+agent-browser diff url https://staging.example.com https://prod.example.com
+
+# Include visual comparison
+agent-browser diff url https://v1.example.com https://v2.example.com --screenshot
+
+# Full-page screenshot comparison
+agent-browser diff url https://v1.example.com https://v2.example.com --screenshot --full
+```
+
+The command navigates to the first URL, captures state, then navigates to the second URL and captures again. Snapshot diff is always included. Screenshot diff requires the `--screenshot` flag.
+
+After completion, the browser remains on the second URL.
+
+### Options
+
+<table>
+  <thead>
+    <tr><th>Flag</th><th>Description</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>--screenshot</code></td><td>Also perform visual screenshot comparison</td></tr>
+    <tr><td><code>--full</code></td><td>Use full-page screenshots</td></tr>
+    <tr><td><code>--wait-until &lt;strategy&gt;</code></td><td>Navigation wait strategy: <code>load</code>, <code>domcontentloaded</code>, <code>networkidle</code> (default: <code>load</code>)</td></tr>
+    <tr><td><code>-s, --selector &lt;sel&gt;</code></td><td>Scope snapshots to a CSS selector or @ref</td></tr>
+    <tr><td><code>-c, --compact</code></td><td>Use compact snapshot format</td></tr>
+    <tr><td><code>-d, --depth &lt;n&gt;</code></td><td>Limit snapshot tree depth</td></tr>
+  </tbody>
+</table>
+
+## Use cases
+
+### Verifying agent actions
+
+The most common use case: confirm that an action (click, fill, submit) changed the page as expected.
+
+```bash
+agent-browser snapshot -i          # Take interactive-only snapshot (baseline)
+agent-browser fill @e3 "test@example.com"
+agent-browser diff snapshot        # Compare current snapshot to the baseline
+```
+
+### Monitoring for changes
+
+Periodically compare a page against a saved baseline to detect updates.
+
+```bash
+# Save baseline
+agent-browser open https://example.com && agent-browser snapshot > baseline.txt
+
+# Later, check for changes
+agent-browser open https://example.com && agent-browser diff snapshot --baseline baseline.txt
+```
+
+### Visual regression testing
+
+Compare screenshots before and after a deploy to catch unintended visual changes.
+
+```bash
+agent-browser open https://staging.example.com && agent-browser screenshot baseline.png
+# ... deploy happens ...
+agent-browser open https://staging.example.com && agent-browser diff screenshot --baseline baseline.png
+```
+
+### Comparing environments
+
+Diff staging against production to verify parity.
+
+```bash
+agent-browser diff url https://staging.example.com https://prod.example.com --screenshot
+```
@@ -93,11 +93,16 @@ agent-browser snapshot -i
 agent-browser tap @e1
 ```

-| Variable | Description |
-| --- | --- |
-| `AGENT_BROWSER_PROVIDER` | Set to `ios` to enable iOS mode |
-| `AGENT_BROWSER_IOS_DEVICE` | Device name (e.g., "iPhone 16 Pro") |
-| `AGENT_BROWSER_IOS_UDID` | Device UDID (alternative to device name) |
+<table>
+  <thead>
+    <tr><th>Variable</th><th>Description</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>AGENT_BROWSER_PROVIDER</code></td><td>Set to <code>ios</code> to enable iOS mode</td></tr>
+    <tr><td><code>AGENT_BROWSER_IOS_DEVICE</code></td><td>Device name (e.g., "iPhone 16 Pro")</td></tr>
+    <tr><td><code>AGENT_BROWSER_IOS_UDID</code></td><td>Device UDID (alternative to device name)</td></tr>
+  </tbody>
+</table>

 ## Supported devices

@@ -168,13 +173,18 @@ agent-browser -p ios --device "John's iPhone" open https://example.com

 ## Differences from desktop

-| Feature | Desktop | iOS |
-| --- | --- | --- |
-| Browser | Chromium/Firefox/WebKit | Safari only |
-| Tabs | Supported | Single tab only |
-| PDF export | Supported | Not supported |
-| Screencast | Supported | Not supported |
-| Swipe gestures | Not native | Native support |
+<table>
+  <thead>
+    <tr><th>Feature</th><th>Desktop</th><th>iOS</th></tr>
+  </thead>
+  <tbody>
+    <tr><td>Browser</td><td>Chromium/Firefox/WebKit</td><td>Safari only</td></tr>
+    <tr><td>Tabs</td><td>Supported</td><td>Single tab only</td></tr>
+    <tr><td>PDF export</td><td>Supported</td><td>Not supported</td></tr>
+    <tr><td>Screencast</td><td>Supported</td><td>Not supported</td></tr>
+    <tr><td>Swipe gestures</td><td>Not native</td><td>Native support</td></tr>
+  </tbody>
+</table>

 ## Troubleshooting

@@ -25,11 +25,16 @@ 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 |
+<table>
+  <thead>
+    <tr><th>Command</th><th>Description</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>profiler start</code></td><td>Start recording a performance profile</td></tr>
+    <tr><td><code>profiler start --categories &lt;list&gt;</code></td><td>Start with custom trace categories</td></tr>
+    <tr><td><code>profiler stop [path]</code></td><td>Stop profiling and save to file</td></tr>
+  </tbody>
+</table>

 ## Trace categories

@@ -46,14 +51,19 @@ 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 |
+<table>
+  <thead>
+    <tr><th>Category</th><th>What it captures</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>devtools.timeline</code></td><td>Standard DevTools performance events</td></tr>
+    <tr><td><code>v8.execute</code></td><td>Time spent running JavaScript</td></tr>
+    <tr><td><code>blink</code></td><td>Renderer events (layout, paint, style)</td></tr>
+    <tr><td><code>blink.user_timing</code></td><td><code>performance.mark()</code> and <code>performance.measure()</code> calls</td></tr>
+    <tr><td><code>latencyInfo</code></td><td>Input-to-display latency</td></tr>
+    <tr><td><code>disabled-by-default-v8.cpu_profiler</code></td><td>Sampling-based JS CPU profiling</td></tr>
+  </tbody>
+</table>

 ## Output format

@@ -181,9 +181,14 @@ agent-browser set headers '{"X-Custom-Header": "value"}'

 ## Environment variables

-| Variable | Description |
-|----------|-------------|
-| `AGENT_BROWSER_SESSION` | Browser session ID (default: "default") |
-| `AGENT_BROWSER_SESSION_NAME` | Auto-save/load state persistence name |
-| `AGENT_BROWSER_ENCRYPTION_KEY` | 64-char hex key for AES-256-GCM encryption |
-| `AGENT_BROWSER_STATE_EXPIRE_DAYS` | Auto-delete states older than N days (default: 30) |
+<table>
+  <thead>
+    <tr><th>Variable</th><th>Description</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>AGENT_BROWSER_SESSION</code></td><td>Browser session ID (default: "default")</td></tr>
+    <tr><td><code>AGENT_BROWSER_SESSION_NAME</code></td><td>Auto-save/load state persistence name</td></tr>
+    <tr><td><code>AGENT_BROWSER_ENCRYPTION_KEY</code></td><td>64-char hex key for AES-256-GCM encryption</td></tr>
+    <tr><td><code>AGENT_BROWSER_STATE_EXPIRE_DAYS</code></td><td>Auto-delete states older than N days (default: 30)</td></tr>
+  </tbody>
+</table>
@@ -18,13 +18,18 @@ agent-browser snapshot -s "#main"         # Scope to CSS selector
 agent-browser snapshot -i -c -d 5         # Combine options
 ```

-| Option | Description |
-| --- | --- |
-| `-i, --interactive` | Only interactive elements (buttons, links, inputs) |
-| `-C, --cursor` | Include cursor-interactive elements (cursor:pointer, onclick, tabindex) |
-| `-c, --compact` | Remove empty structural elements |
-| `-d, --depth` | Limit tree depth |
-| `-s, --selector` | Scope to CSS selector |
+<table>
+  <thead>
+    <tr><th>Option</th><th>Description</th></tr>
+  </thead>
+  <tbody>
+    <tr><td><code>-i, --interactive</code></td><td>Only interactive elements (buttons, links, inputs)</td></tr>
+    <tr><td><code>-C, --cursor</code></td><td>Include cursor-interactive elements (cursor:pointer, onclick, tabindex)</td></tr>
+    <tr><td><code>-c, --compact</code></td><td>Remove empty structural elements</td></tr>
+    <tr><td><code>-d, --depth</code></td><td>Limit tree depth</td></tr>
+    <tr><td><code>-s, --selector</code></td><td>Scope to CSS selector</td></tr>
+  </tbody>
+</table>

 ## Cursor-interactive elements

@@ -0,0 +1,282 @@
+"use client";
+
+function DiffLine({ line }: { line: string }) {
+  if (line.startsWith("+ ")) {
+    return <div className="text-green-400">{line}</div>;
+  }
+  if (line.startsWith("- ")) {
+    return <div className="text-red-400">{line}</div>;
+  }
+  return <div className="opacity-50">{line}</div>;
+}
+
+function CommandLine({ children }: { children: string }) {
+  return (
+    <div>
+      <span className="opacity-40">$ </span>
+      {children}
+    </div>
+  );
+}
+
+function Terminal({ children }: { children: React.ReactNode }) {
+  return (
+    <div
+      className="rounded border font-mono text-[0.8125rem] leading-[1.7] overflow-x-auto"
+      style={{
+        background: "var(--card)",
+        borderColor: "var(--border)",
+        padding: "0.875rem",
+      }}
+    >
+      {children}
+    </div>
+  );
+}
+
+function PageMockup({
+  label,
+  buttonColor,
+  diffMode,
+}: {
+  label: string;
+  buttonColor: string;
+  diffMode?: boolean;
+}) {
+  const dimOpacity = diffMode ? 0.15 : 1;
+  return (
+    <div className="flex-1 min-w-0">
+      <div
+        className="text-[0.6875rem] font-medium mb-1.5 text-center"
+        style={{ color: "var(--muted-foreground)" }}
+      >
+        {label}
+      </div>
+      <svg
+        viewBox="0 0 160 120"
+        className="w-full rounded border"
+        style={{ borderColor: "var(--border)" }}
+      >
+        <rect width="160" height="120" fill={diffMode ? "#1a1a1a" : "#111"} />
+
+        {/* Nav bar */}
+        <rect
+          x="0"
+          y="0"
+          width="160"
+          height="16"
+          fill="#222"
+          opacity={dimOpacity}
+        />
+        <rect
+          x="8"
+          y="5"
+          width="24"
+          height="6"
+          rx="1"
+          fill="#555"
+          opacity={dimOpacity}
+        />
+        <rect
+          x="120"
+          y="5"
+          width="12"
+          height="6"
+          rx="1"
+          fill="#444"
+          opacity={dimOpacity}
+        />
+        <rect
+          x="136"
+          y="5"
+          width="12"
+          height="6"
+          rx="1"
+          fill="#444"
+          opacity={dimOpacity}
+        />
+
+        {/* Heading */}
+        <rect
+          x="20"
+          y="26"
+          width="80"
+          height="6"
+          rx="1"
+          fill="#666"
+          opacity={dimOpacity}
+        />
+
+        {/* Subtext */}
+        <rect
+          x="30"
+          y="38"
+          width="60"
+          height="4"
+          rx="1"
+          fill="#444"
+          opacity={dimOpacity}
+        />
+
+        {/* Input field */}
+        <rect
+          x="30"
+          y="52"
+          width="100"
+          height="14"
+          rx="2"
+          fill="#1a1a1a"
+          stroke="#333"
+          strokeWidth="0.5"
+          opacity={dimOpacity}
+        />
+
+        {/* Button -- this is what changes */}
+        {diffMode ? (
+          <>
+            <rect
+              x="55"
+              y="76"
+              width="50"
+              height="14"
+              rx="2"
+              fill="#ef4444"
+              opacity="0.85"
+            />
+            <rect
+              x="55"
+              y="76"
+              width="50"
+              height="14"
+              rx="2"
+              fill="none"
+              stroke="#ef4444"
+              strokeWidth="1.5"
+              strokeDasharray="3 2"
+            />
+          </>
+        ) : (
+          <rect
+            x="55"
+            y="76"
+            width="50"
+            height="14"
+            rx="2"
+            fill={buttonColor}
+          />
+        )}
+        <text
+          x="80"
+          y="85.5"
+          textAnchor="middle"
+          fill="white"
+          fontSize="6"
+          fontFamily="system-ui, sans-serif"
+          opacity={diffMode ? 0.9 : 1}
+        >
+          Submit
+        </text>
+
+        {/* Footer line */}
+        <rect
+          x="40"
+          y="102"
+          width="80"
+          height="3"
+          rx="1"
+          fill="#333"
+          opacity={dimOpacity}
+        />
+      </svg>
+    </div>
+  );
+}
+
+const snapshotDiffLines = [
+  "  heading \"Sign Up\" [ref=e1]",
+  "  text \"Create your account\" [ref=e2]",
+  "- textbox \"Email\" [ref=e3]",
+  "+ textbox \"Email\" [ref=e3]: \"test@example.com\"",
+  "- button \"Submit\" [ref=e4]",
+  "+ button \"Submit\" [ref=e4] [disabled]",
+  "+ status \"Sending...\" [ref=e7]",
+  "  link \"Already have an account?\" [ref=e5]",
+];
+
+export function DiffDemo() {
+  return (
+    <div className="grid gap-8 my-8">
+      {/* Panel 1: Snapshot diff */}
+      <div>
+        <div
+          className="text-xs font-medium uppercase tracking-wider mb-3"
+          style={{ color: "var(--muted-foreground)" }}
+        >
+          Verify an action changed the page
+        </div>
+        <Terminal>
+          <div className="opacity-60 mb-2">
+            <CommandLine>agent-browser snapshot -i</CommandLine>
+            <CommandLine>
+              agent-browser fill @e3 &quot;test@example.com&quot;
+            </CommandLine>
+            <CommandLine>agent-browser click @e4</CommandLine>
+          </div>
+          <div className="mb-3">
+            <CommandLine>agent-browser diff snapshot</CommandLine>
+          </div>
+          <div
+            className="border-t pt-3"
+            style={{ borderColor: "var(--border)" }}
+          >
+            {snapshotDiffLines.map((line, i) => (
+              <DiffLine key={i} line={line} />
+            ))}
+            <div className="mt-2 opacity-60">
+              <span className="text-green-400">3</span> additions,{" "}
+              <span className="text-red-400">2</span> removals,{" "}
+              <span>3</span> unchanged
+            </div>
+          </div>
+        </Terminal>
+      </div>
+
+      {/* Panel 2: Screenshot diff */}
+      <div>
+        <div
+          className="text-xs font-medium uppercase tracking-wider mb-3"
+          style={{ color: "var(--muted-foreground)" }}
+        >
+          Catch a visual regression
+        </div>
+        <Terminal>
+          <div className="mb-3">
+            <CommandLine>
+              agent-browser diff screenshot --baseline before-deploy.png
+            </CommandLine>
+          </div>
+          <div
+            className="border-t pt-3"
+            style={{ borderColor: "var(--border)" }}
+          >
+            <div className="text-red-400">
+              &#x2717; 2.37% pixels differ
+            </div>
+            <div className="opacity-50">
+              Diff image: ~/.agent-browser/tmp/diffs/diff-1708473621.png
+            </div>
+            <div className="opacity-50">
+              <span className="text-red-400">1,137</span> different /{" "}
+              48,000 total pixels
+            </div>
+          </div>
+        </Terminal>
+        <div className="flex gap-2 mt-3">
+          <PageMockup label="Baseline" buttonColor="#3b82f6" />
+          <PageMockup label="Current" buttonColor="#22c55e" />
+          <PageMockup label="Diff" buttonColor="#ef4444" diffMode />
+        </div>
+      </div>
+    </div>
+  );
+}
@@ -30,6 +30,7 @@ export const navigation: NavSection[] = [
    title: "Features",
    items: [
      { name: "Sessions", href: "/sessions" },
+      { name: "Diffing", href: "/diffing" },
      { name: "CDP Mode", href: "/cdp-mode" },
      { name: "Streaming", href: "/streaming" },
      { name: "Profiler", href: "/profiler" },