docs: add Browser Use callback demo

Author: aaronlab

docs/browser-use-debugging.html

@@ -216,7 +216,7 @@ <h2>Try it before wiring Browser Use</h2>
       <pre><code>pip install "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.6"
 browsertrace demo
 browsertrace</code></pre>
-      <p>Open <code>http://127.0.0.1:3000</code>, then inspect <code>demo: checkout agent fails on disabled button</code>.</p>
+      <p>Open <code>http://127.0.0.1:3000</code>, then inspect <code>demo: checkout agent fails on disabled button</code>. From a source checkout, <code>python examples/browser_use_callback_demo.py</code> records Browser Use-shaped callback steps without installing Browser Use.</p>
     </section>
 
     <section>

docs/launch/metrics-log.md

@@ -59,3 +59,4 @@ uv run --python 3.11 python scripts/launch_metrics.py --json
 | 2026-05-09T10:47:56+00:00 | 3 | 998 | 0 | 0 | 7 | 0 | 0 | after Playwright LLM debugging landing page added |
 | 2026-05-09T10:49:38+00:00 | 3 | 998 | 0 | 0 | 7 | 0 | 0 | after owner launch checklist issues updated with stack landing pages |
 | 2026-05-09T10:52:41+00:00 | 3 | 998 | 0 | 0 | 7 | 0 | 0 | after comparison landing page added |
+| 2026-05-09T10:55:33+00:00 | 3 | 998 | 0 | 0 | 7 | 0 | 0 | after Browser Use no-dependency callback demo added |

examples/README.md

@@ -21,6 +21,7 @@ Open `http://127.0.0.1:3000` and inspect
 | Example | Use when | Extra services | Command |
 |---|---|---:|---|
 | `no_api_failure_demo.py` | You want the fastest failing trace | None | `python examples/no_api_failure_demo.py` |
+| `browser_use_callback_demo.py` | You want to see Browser Use-shaped step callbacks recorded | None | `python examples/browser_use_callback_demo.py` |
 | `stagehand_wrapper_example.py` | You want to see Stagehand-style `act` and `extract` calls recorded | None | `python examples/stagehand_wrapper_example.py` |
 | `skyvern_wrapper_example.py` | You want to see Skyvern-style task calls recorded | None | `python examples/skyvern_wrapper_example.py` |
 | `basic_example.py` | You want the smallest manual SDK example | None | `python examples/basic_example.py` |

examples/browser_use_callback_demo.py

@@ -0,0 +1,92 @@
+"""Run the Browser Use adapter without installing Browser Use.
+
+This uses a fake Browser Use-shaped agent so the example is deterministic:
+
+    python examples/browser_use_callback_demo.py
+
+Then open the BrowserTrace UI:
+
+    browsertrace
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import os
+
+from browsertrace import Tracer
+from browsertrace.integrations.browser_use import attach_tracer
+
+
+PNG_BYTES = b"\x89PNG\r\n\x1a\n" + b"\x00" * 16
+
+
+class DemoBrowserState:
+    def __init__(self, url: str):
+        self.url = url
+        self.screenshot = base64.b64encode(PNG_BYTES).decode("ascii")
+
+
+class DemoAction:
+    def __init__(self, payload: dict):
+        self._payload = payload
+
+    def model_dump(self, exclude_none: bool = True) -> dict:
+        return self._payload
+
+
+class DemoCurrentState:
+    def __init__(self, thought: str):
+        self.thought = thought
+
+
+class DemoAgentOutput:
+    def __init__(self, thought: str, action: dict):
+        self.current_state = DemoCurrentState(thought)
+        self.action = [DemoAction(action)]
+
+
+class DemoBrowserUseAgent:
+    def __init__(self):
+        self._new_step_callback = None
+
+    def register_new_step_callback(self, callback):
+        self._new_step_callback = callback
+
+    async def run(self) -> None:
+        if self._new_step_callback is None:
+            raise RuntimeError("step callback was not registered")
+
+        await self._new_step_callback(
+            DemoBrowserState("https://example.com/search"),
+            DemoAgentOutput(
+                "search for the project",
+                {"search_google": {"query": "BrowserTrace"}},
+            ),
+            0,
+        )
+        await self._new_step_callback(
+            DemoBrowserState("https://example.com/results"),
+            DemoAgentOutput(
+                "open the first useful result",
+                {"click": {"selector": "#result-1"}},
+            ),
+            1,
+        )
+
+
+async def main() -> None:
+    tracer = Tracer(home=os.environ.get("BROWSERTRACE_HOME"))
+    agent = DemoBrowserUseAgent()
+
+    with attach_tracer(agent, tracer, name="demo: browser-use callback flow") as bt_run:
+        await agent.run()
+
+    print(f"BrowserTrace run id: {bt_run.run.id}")
+    print("Recorded Browser Use-shaped callback steps: search_google, click")
+    print("Open the local UI with: browsertrace")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

tests/test_examples.py

@@ -83,3 +83,30 @@ def test_stagehand_wrapper_example_creates_completed_trace(tmp_path, monkeypatch
     assert steps[0][2] == "ok"
     assert json.loads(steps[0][3])["method"] == "act"
     assert steps[0][4].endswith(".png")
+
+
+def test_browser_use_callback_demo_creates_completed_trace(tmp_path, monkeypatch):
+    monkeypatch.setenv("BROWSERTRACE_HOME", str(tmp_path))
+
+    runpy.run_path("examples/browser_use_callback_demo.py", run_name="__main__")
+
+    with sqlite3.connect(tmp_path / "db.sqlite") as c:
+        run = c.execute(
+            "SELECT id, name, status, error FROM runs ORDER BY started_at DESC LIMIT 1"
+        ).fetchone()
+        steps = c.execute(
+            "SELECT action, url, status, model_output "
+            "FROM steps WHERE run_id=? ORDER BY step_index",
+            (run[0],),
+        ).fetchall()
+
+    assert run[1] == "demo: browser-use callback flow"
+    assert run[2] == "completed"
+    assert run[3] is None
+    assert [step[0] for step in steps] == [
+        "search_google(query=BrowserTrace)",
+        "click(selector=#result-1)",
+    ]
+    assert steps[0][1] == "https://example.com/search"
+    assert steps[1][2] == "ok"
+    assert json.loads(steps[1][3])["thought"] == "open the first useful result"