Show agent pointer over Browserbase Live View

COOKBOOK_AUTHORED.json

@@ -3,14 +3,49 @@
   "files": [
     {
       "path": "examples/README.md",
-      "sha256": "d4b80442ca66ab0f2c3a4d9666ff6b16bdfeed6aa4396ee76ebef5f3253ea63c",
+      "sha256": "92f2c66626bc21a74f9641616fdfe8395de6b788fb2d248cf8cf56db55d70405",
       "reason": "Cookbook-authored migration, test, configuration, or collection metadata outside the pinned upstream tree."
     },
     {
       "path": "examples/go/hackernews/.env.example",
       "sha256": "f2397eaef401700a0baed905b587b31320715da4655b6edb876906f476d1e351",
       "reason": "Cookbook-authored migration, test, configuration, or collection metadata outside the pinned upstream tree."
     },
+    {
+      "path": "examples/javascript/live-view-cursor-ui/.env.example",
+      "sha256": "42b43bad0fa9275b332ccc4eb93bd4f05cc674ad8f219e0e410271d32ba32039",
+      "reason": "Cookbook-authored migration, test, configuration, or collection metadata outside the pinned upstream tree."
+    },
+    {
+      "path": "examples/javascript/live-view-cursor-ui/README.md",
+      "sha256": "71fcc1931cdf76cb93fa874b426b6e6d069fb8b1ea64c31379800830bd84d8b2",
+      "reason": "Cookbook-authored migration, test, configuration, or collection metadata outside the pinned upstream tree."
+    },
+    {
+      "path": "examples/javascript/live-view-cursor-ui/package.json",
+      "sha256": "2dd68b36eab0409135d534fa1d9b6f2b157450c50f656258c0b4d85fd546b2d7",
+      "reason": "Cookbook-authored migration, test, configuration, or collection metadata outside the pinned upstream tree."
+    },
+    {
+      "path": "examples/javascript/live-view-cursor-ui/server.mjs",
+      "sha256": "1fc37d1f1247b19adf3db6a9b7a4697c104f51e300302d1878b126b0eaacbf05",
+      "reason": "Cookbook-authored migration, test, configuration, or collection metadata outside the pinned upstream tree."
+    },
+    {
+      "path": "examples/javascript/live-view-cursor-ui/ui/app.js",
+      "sha256": "4c68b8e8ac26912a809742b83296a56a25e52d48661dc78505a13d7cf11701ab",
+      "reason": "Cookbook-authored migration, test, configuration, or collection metadata outside the pinned upstream tree."
+    },
+    {
+      "path": "examples/javascript/live-view-cursor-ui/ui/index.html",
+      "sha256": "ce1202bba1719ec1f2665da875bab354b0becfa2c7eb923ebabab5abb110626c",
+      "reason": "Cookbook-authored migration, test, configuration, or collection metadata outside the pinned upstream tree."
+    },
+    {
+      "path": "examples/javascript/live-view-cursor-ui/ui/styles.css",
+      "sha256": "999fc836f8b0a64c7e79f9dbd8058c8039740103c7a3edfa4fedb92a64b0e81a",
+      "reason": "Cookbook-authored migration, test, configuration, or collection metadata outside the pinned upstream tree."
+    },
     {
       "path": "examples/python/agentic-kyb/.env.example",
       "sha256": "f2397eaef401700a0baed905b587b31320715da4655b6edb876906f476d1e351",

README.md

@@ -33,6 +33,7 @@ This cookbook brings together Browserbase's public templates, complete projects,
 | Extract structured product data with Stagehand        | [Python](examples/python/amazon-product-scraping/) or [TypeScript](examples/typescript/amazon-product-scraping/)                   |
 | Save a login and handle MFA                           | [Authentication recipes](docs/topics/authentication.md)                                                                            |
 | Pause an agent for a person                           | [Human-in-the-loop app](examples/typescript/agent-with-human-in-loop/)                                                             |
+| Style Live View pointers for people and agents        | [JavaScript pointer UI](examples/javascript/live-view-cursor-ui/)                                                                  |
 | Add Browserbase to an agent framework                 | [Integrations](integrations/README.md)                                                                                             |
 | Study a complete consumer browser agent               | [Browsie](projects/browsie/)                                                                                                       |
 

catalog.json

@@ -332,6 +332,126 @@
       "verification": "source-inspected",
       "working_directory": "examples/go/hackernews"
     },
+    {
+      "access": "public",
+      "caveats": [
+        "The agent pointer styling appears in the wrapper, not in a direct Browserbase Live View URL.",
+        "The sample tracks agent pointer events in the main browser tab only; new remote tabs and frames need their own pointer listener.",
+        "The local server gives its signed Live View URL to its own page; protect the page and API routes before deployment."
+      ],
+      "collection": "examples",
+      "dependencies": {
+        "@browserbasehq/sdk": "2.18.0",
+        "@browserbasehq/stagehand": "4.0.2",
+        "dotenv": "^16.4.5",
+        "playwright-core": "1.55.0"
+      },
+      "entrypoints": [
+        "examples/javascript/live-view-cursor-ui/server.mjs",
+        "examples/javascript/live-view-cursor-ui/ui/app.js"
+      ],
+      "environment_setup_command": "test -f .env || cp .env.example .env",
+      "environment_template": "examples/javascript/live-view-cursor-ui/.env.example",
+      "environment_variables": [
+        {
+          "default": null,
+          "name": "BROWSERBASE_API_KEY",
+          "provider": "Browserbase",
+          "purpose": "Creates and connects to the cloud browser session.",
+          "requirement": "required",
+          "safe_example": "<set-locally>",
+          "secret": true,
+          "setup_url": "https://www.browserbase.com/settings",
+          "validation": "Must be a valid Browserbase API key"
+        },
+        {
+          "default": "4790",
+          "name": "LIVE_VIEW_UI_PORT",
+          "provider": "Recipe configuration",
+          "purpose": "Sets the localhost port for the pointer UI.",
+          "requirement": "optional",
+          "safe_example": "4790",
+          "secret": false,
+          "setup_url": null,
+          "validation": "Must be an available TCP port"
+        }
+      ],
+      "frameworks": [
+        "Browserbase SDK",
+        "Stagehand",
+        "Playwright"
+      ],
+      "id": "examples-javascript-live-view-cursor-ui",
+      "languages": [
+        "javascript"
+      ],
+      "lifecycle": "current",
+      "manifests": [
+        "examples/javascript/live-view-cursor-ui/package.json"
+      ],
+      "path": "examples/javascript/live-view-cursor-ui",
+      "readme": "docs/recipes/examples-javascript-live-view-cursor-ui.md",
+      "run_commands": [
+        "npm start"
+      ],
+      "search_aliases": [
+        "live view cursor",
+        "agent pointer",
+        "playwright cursor",
+        "stagehand cursor"
+      ],
+      "setup_commands": [
+        "npm install"
+      ],
+      "source": {
+        "kind": "cookbook-authored",
+        "path": "examples/javascript/live-view-cursor-ui"
+      },
+      "summary": "Embed Browserbase Live View with a custom agent pointer while human input uses the native Live View.",
+      "tags": [],
+      "title": "Live View agent pointer (JavaScript)",
+      "topics": [
+        "agents-and-human-handoff",
+        "testing-and-observability"
+      ],
+      "upstream_readme": "examples/javascript/live-view-cursor-ui/README.md",
+      "verification": "live-tested",
+      "verification_evidence": [
+        {
+          "command": "npm install --ignore-scripts --no-audit --no-fund --package-lock=false",
+          "date": "2026-10-08",
+          "kind": "install-verified",
+          "limits": "Installed inside a new recipe directory without a shared dependency tree. This did not run a browser session.",
+          "result": "passed",
+          "runtime": "Node.js 25.9.0 and npm on macOS arm64"
+        },
+        {
+          "command": "LIVE_VIEW_UI_PORT=4792 npm start; node /private/tmp/live-view-cursor-smoke.mjs playwright; node /private/tmp/live-view-cursor-smoke.mjs stagehand",
+          "date": "2026-10-08",
+          "kind": "live-tested",
+          "limits": "One Browserbase SauceDemo session. Playwright emitted 6 pointer events and 3 clicks; Stagehand emitted 8 pointer events and 4 clicks. Both ended with the backpack in the cart. Human UI input and other browser clients were not retested in this checkout. The session was closed.",
+          "result": "passed",
+          "runtime": "Node.js 25.9.0 on macOS arm64; Browserbase SDK 2.18.0, Stagehand 4.0.2, Playwright Core 1.55.0"
+        },
+        {
+          "command": "env -u BROWSERBASE_PROJECT_ID LIVE_VIEW_UI_PORT=4793 npm start",
+          "date": "2026-10-08",
+          "kind": "live-tested",
+          "limits": "The Browserbase and Stagehand session initialized with no project ID in the environment or launch options and was closed. This check did not rerun the Playwright or Stagehand cart actions.",
+          "result": "passed",
+          "runtime": "Node.js 25.9.0 on macOS arm64; Browserbase SDK 2.18.0 and Stagehand 4.0.2"
+        },
+        {
+          "command": "LIVE_VIEW_UI_PORT=4804 node server.mjs; node /private/tmp/live-view-independent-test.mjs http://127.0.0.1:4804 cookbook; node /private/tmp/cookbook-agent-only-test.mjs",
+          "date": "2026-10-08",
+          "kind": "live-tested",
+          "limits": "Agent-only version: a human click through the iframe showed the SauceDemo username error with no /api/input request. Playwright showed the custom agent pointer and added the backpack to the cart. Stagehand was not rerun for this version. The session was reset after testing.",
+          "result": "passed",
+          "runtime": "Node.js 25.9.0 on macOS arm64; Browserbase SDK 2.18.0, Stagehand 4.0.2, Playwright Core 1.55.0"
+        }
+      ],
+      "working_directory": "examples/javascript/live-view-cursor-ui"
+    },
     {
       "access": "public",
       "caveats": [],

docs/catalog.md

@@ -12,9 +12,9 @@ Search locally with `python3 scripts/catalog.py search "persistent login" --lang
 - [Files and documents](topics/downloads-and-documents.md) (21). Upload files, retrieve downloads, capture PDFs, and parse documents.
 - [Extraction and research](topics/extraction-and-research.md) (54). Find pages and extract structured information from them.
 - [Forms and transactions](topics/forms-and-transactions.md) (28). Fill forms and prepare application, booking, and payment workflows.
-- [Agents and human handoff](topics/agents-and-human-handoff.md) (27). Build browser agents and pause work for human input.
+- [Agents and human handoff](topics/agents-and-human-handoff.md) (28). Build browser agents and pause work for human input.
 - [Integrations and orchestration](topics/integrations-and-orchestration.md) (32). Connect Browserbase to agent frameworks, services, and workflow engines.
-- [Testing and observability](topics/testing-and-observability.md) (7). Test sites and inspect browser behavior, reliability, and performance.
+- [Testing and observability](topics/testing-and-observability.md) (8). Test sites and inspect browser behavior, reliability, and performance.
 - [Commerce and travel](topics/commerce-and-travel.md) (14). Compare products, research travel, and inspect booking workflows.
 - [Business operations](topics/business-operations.md) (11). Automate research and operations across business domains.
 
@@ -23,6 +23,7 @@ Search locally with `python3 scripts/catalog.py search "persistent login" --lang
 | Recipe | Language | Type | Status | Collection |
 | --- | --- | --- | --- | --- |
 | [Hackernews (Go)](recipes/examples-go-hackernews.md) | go | runnable example | current / public | examples |
+| [Live View agent pointer (JavaScript)](recipes/examples-javascript-live-view-cursor-ui.md) | javascript | runnable example | current / public | examples |
 | [Agentic KYB registry research (Python, Stagehand v4)](recipes/examples-python-agentic-kyb.md) | python | runnable example | current / public | examples |
 | [Amazon global price comparison (Python)](recipes/examples-python-amazon-global-price-comparison.md) | python | runnable example | current / public | examples |
 | [Amazon product scraping (Python)](recipes/examples-python-amazon-product-scraping.md) | python | runnable example | current / public | examples |

docs/recipes/examples-javascript-live-view-cursor-ui.md

@@ -0,0 +1,86 @@
+# Live View agent pointer (JavaScript)
+
+Embed Browserbase Live View with a custom agent pointer while human input uses the native Live View.
+
+> [!CAUTION]
+> Demo and reference code only. This recipe is not a vetted production implementation. Independently review it, obtain authorization, and validate security, privacy, compliance, cost, and site-term requirements before use. Use at your own risk.
+
+**Status:** current · public · live workflow tested.
+
+**Recipe type:** runnable example.
+**LLM requirement:** required (derived from the inspected framework and configuration metadata).
+
+## Code and prerequisites
+
+- Working directory from the cookbook root: `examples/javascript/live-view-cursor-ui`.
+- Languages: javascript.
+- Frameworks: Browserbase SDK, Stagehand, Playwright.
+- [Upstream setup and behavior](../../examples/javascript/live-view-cursor-ui/README.md).
+- [Dependency manifest `examples/javascript/live-view-cursor-ui/package.json`](../../examples/javascript/live-view-cursor-ui/package.json).
+- [Source `examples/javascript/live-view-cursor-ui/server.mjs`](../../examples/javascript/live-view-cursor-ui/server.mjs).
+- [Source `examples/javascript/live-view-cursor-ui/ui/app.js`](../../examples/javascript/live-view-cursor-ui/ui/app.js).
+
+## Setup and run
+
+Run from this directory. Commands come from the package manifest, upstream setup guide, or inspected entrypoint. Configure credentials before starting.
+
+```sh
+cd examples/javascript/live-view-cursor-ui
+npm install
+test -f .env || cp .env.example .env
+```
+
+Available launch commands are listed below. For applications with separate workers or servers, read the upstream guide for process order. A production `start` command may require a build first.
+
+```sh
+npm start
+```
+
+## Environment
+
+[Environment template](../../examples/javascript/live-view-cursor-ui/.env.example) lists example configuration. Fill in your own values locally.
+
+### Required
+
+| Variable | Provider and purpose | Safe example | Validation and default |
+| --- | --- | --- | --- |
+| `BROWSERBASE_API_KEY` | [Browserbase](https://www.browserbase.com/settings). Creates and connects to the cloud browser session. Secret. | `<set-locally>` | Must be a valid Browserbase API key. No default. |
+
+### Optional
+
+| Variable | Provider and purpose | Safe example | Validation and default |
+| --- | --- | --- | --- |
+| `LIVE_VIEW_UI_PORT` | Recipe configuration. Sets the localhost port for the pointer UI. Non-secret. | `4790` | Must be an available TCP port. Default: `4790`. |
+
+
+## Dependencies
+
+Declared runtime dependencies from [examples/javascript/live-view-cursor-ui/package.json](../../examples/javascript/live-view-cursor-ui/package.json). Alternate manifests may differ; use the documented setup path.
+
+| Package | Declared version |
+| --- | --- |
+| `@browserbasehq/sdk` | `2.18.0` |
+| `@browserbasehq/stagehand` | `4.0.2` |
+| `dotenv` | `^16.4.5` |
+| `playwright-core` | `1.55.0` |
+
+## Caveats and verification
+
+Source and setup metadata were inspected. A scoped live workflow check is recorded below; only its stated command, date, result, and limits are verified. Other websites, accounts, permissions, costs, and configurations remain unverified.
+
+| Check | Date | Runtime | Command | Result and limits |
+| --- | --- | --- | --- | --- |
+| Clean install verified | 2026-10-08 | `Node.js 25.9.0 and npm on macOS arm64` | `npm install --ignore-scripts --no-audit --no-fund --package-lock=false` | passed. Installed inside a new recipe directory without a shared dependency tree. This did not run a browser session. |
+| Live workflow tested | 2026-10-08 | `Node.js 25.9.0 on macOS arm64; Browserbase SDK 2.18.0, Stagehand 4.0.2, Playwright Core 1.55.0` | `LIVE_VIEW_UI_PORT=4792 npm start; node /private/tmp/live-view-cursor-smoke.mjs playwright; node /private/tmp/live-view-cursor-smoke.mjs stagehand` | passed. One Browserbase SauceDemo session. Playwright emitted 6 pointer events and 3 clicks; Stagehand emitted 8 pointer events and 4 clicks. Both ended with the backpack in the cart. Human UI input and other browser clients were not retested in this checkout. The session was closed. |
+| Live workflow tested | 2026-10-08 | `Node.js 25.9.0 on macOS arm64; Browserbase SDK 2.18.0 and Stagehand 4.0.2` | `env -u BROWSERBASE_PROJECT_ID LIVE_VIEW_UI_PORT=4793 npm start` | passed. The Browserbase and Stagehand session initialized with no project ID in the environment or launch options and was closed. This check did not rerun the Playwright or Stagehand cart actions. |
+| Live workflow tested | 2026-10-08 | `Node.js 25.9.0 on macOS arm64; Browserbase SDK 2.18.0, Stagehand 4.0.2, Playwright Core 1.55.0` | `LIVE_VIEW_UI_PORT=4804 node server.mjs; node /private/tmp/live-view-independent-test.mjs http://127.0.0.1:4804 cookbook; node /private/tmp/cookbook-agent-only-test.mjs` | passed. Agent-only version: a human click through the iframe showed the SauceDemo username error with no /api/input request. Playwright showed the custom agent pointer and added the backpack to the cart. Stagehand was not rerun for this version. The session was reset after testing. |
+
+- The agent pointer styling appears in the wrapper, not in a direct Browserbase Live View URL.
+- The sample tracks agent pointer events in the main browser tab only; new remote tabs and frames need their own pointer listener.
+- The local server gives its signed Live View URL to its own page; protect the page and API routes before deployment.
+
+## Provenance
+
+Cookbook-authored example. Its reviewed source is included at the local paths above.
+
+Related topics: [Agents and human handoff](../topics/agents-and-human-handoff.md), [Testing and observability](../topics/testing-and-observability.md).

docs/topics/agents-and-human-handoff.md

@@ -6,6 +6,7 @@ Open a recipe guide for its working directory, commands, environment references,
 
 | Recipe | Language | Type | Status | Collection |
 | --- | --- | --- | --- | --- |
+| [Live View agent pointer (JavaScript)](../recipes/examples-javascript-live-view-cursor-ui.md) | javascript | runnable example | current / public | examples |
 | [Anthropic Claude browser agent (Python)](../recipes/examples-python-anthropic-cua.md) | python | runnable example | current / public | examples |
 | [Business lookup (Python)](../recipes/examples-python-business-lookup.md) | python | runnable example | current / public | examples |
 | [Cartesia form filling (Python)](../recipes/examples-python-cartesia-form-filling.md) | python | runnable example | current / public | examples |

docs/topics/testing-and-observability.md

@@ -6,6 +6,7 @@ Open a recipe guide for its working directory, commands, environment references,
 
 | Recipe | Language | Type | Status | Collection |
 | --- | --- | --- | --- | --- |
+| [Live View agent pointer (JavaScript)](../recipes/examples-javascript-live-view-cursor-ui.md) | javascript | runnable example | current / public | examples |
 | [Agentic KYB registry research (Python, Stagehand v4)](../recipes/examples-python-agentic-kyb.md) | python | runnable example | current / public | examples |
 | [Cerebras docs checker (Python)](../recipes/examples-python-cerebras-docs-checker.md) | python | runnable example | current / public | examples |
 | [Smart fetch scraper (Python)](../recipes/examples-python-smart-fetch-scraper.md) | python | runnable example | current / public | examples |