docs: add Stagehand wrapper example

Author: aaronlab

README.md

@@ -162,6 +162,9 @@ await page.extract("get the headline")      # auto-recorded
 page.bt_run.close()
 ```
 
+For a no-network wrapper demo that does not require a Stagehand install, run
+`python examples/stagehand_wrapper_example.py`.
+
 ### Skyvern integration
 
 Wrap a Skyvern-shaped client to record high-level task and workflow calls.

examples/stagehand_wrapper_example.py

@@ -0,0 +1,58 @@
+"""Run the Stagehand wrapper without installing Stagehand.
+
+This uses a fake Stagehand-shaped page so the example is deterministic:
+
+    python examples/stagehand_wrapper_example.py
+
+Then open the BrowserTrace UI:
+
+    browsertrace
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+
+from browsertrace import Tracer
+from browsertrace.integrations.stagehand import wrap_stagehand
+
+
+class DemoStagehandPage:
+    url = "https://shop.example.test/cart"
+
+    async def screenshot(self) -> bytes:
+        return b"\x89PNG\r\n\x1a\n" + b"\x00" * 16
+
+    async def act(self, instruction: str) -> dict[str, str]:
+        await asyncio.sleep(0)
+        return {"status": "completed", "instruction": instruction}
+
+    async def extract(self, instruction: str) -> dict[str, str]:
+        await asyncio.sleep(0)
+        return {
+            "status": "completed",
+            "instruction": instruction,
+            "order_total": "$42.00",
+        }
+
+
+async def main() -> None:
+    tracer = Tracer(home=os.environ.get("BROWSERTRACE_HOME"))
+    page = wrap_stagehand(
+        DemoStagehandPage(),
+        tracer,
+        name="demo: stagehand checkout flow",
+    )
+
+    await page.act("click the checkout button")
+    await page.extract("extract the order total")
+    page.bt_run.close()
+
+    print(f"BrowserTrace run id: {page.bt_run.id}")
+    print("Recorded Stagehand calls: act, extract")
+    print("Open the local UI with: browsertrace")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

tests/test_examples.py

@@ -55,3 +55,31 @@ def test_skyvern_wrapper_example_creates_completed_trace(tmp_path, monkeypatch):
     assert json.loads(step[2])["kwargs"]["url"] == "https://example.com/invoice"
     assert json.loads(step[3])["task_run_id"] == "tsk_demo_001"
     assert json.loads(step[4])["skyvern_run_id"] == "tsk_demo_001"
+
+
+def test_stagehand_wrapper_example_creates_completed_trace(tmp_path, monkeypatch):
+    monkeypatch.setenv("BROWSERTRACE_HOME", str(tmp_path))
+
+    runpy.run_path("examples/stagehand_wrapper_example.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_input, screenshot_path "
+            "FROM steps WHERE run_id=? ORDER BY step_index",
+            (run[0],),
+        ).fetchall()
+
+    assert run[1] == "demo: stagehand checkout flow"
+    assert run[2] == "completed"
+    assert run[3] is None
+    assert [step[0] for step in steps] == [
+        "act: click the checkout button",
+        "extract: extract the order total",
+    ]
+    assert steps[0][1] == "https://shop.example.test/cart"
+    assert steps[0][2] == "ok"
+    assert json.loads(steps[0][3])["method"] == "act"
+    assert steps[0][4].endswith(".png")