pursr 0.8.0 → 0.9.0

package/README.md

@@ -33,8 +33,9 @@
 Most teams need **five separate tools** to do visual QA: a screenshot CLI, a regression diff runner, an accessibility auditor, a way to share captures with an AI assistant, and a way to **turn all of that into a PDF report** for stakeholders. **pursr is all five** - built as a single Node.js package with:
 
 - **A unified CLI** (`pursr`) for every capture, diff, sweep, and audit.
-- **An agent-grade MCP stdio server** (`pursr-mcp`) with persistent tabs, direct image responses, rendered-state inspection, actions, diagnostics, screenshots, sweeps, and resources.
-- **A library API** with 23 subpath modules, so you can embed the browser and QA primitives in your own tooling.
+- **An agent-grade MCP stdio server** (`pursr-mcp`) built on the official Model Context Protocol SDK, with persistent tabs, direct image responses, rendered-state inspection, actions, diagnostics, screenshots, sweeps, and resources.
+- **Visual Operator** sessions with a rendered cursor, target labels, click markers, visible Chrome windows, and authenticated Chrome attachment over CDP.
+- **A library API** with 24 subpath modules, so you can embed the browser and QA primitives in your own tooling.
 - **A plugin system** for custom viewports, sweep ops, and capture hooks.
 - **PDF reports + AI diff summaries** built in - render a sweep to a styled PDF or ask a vision LLM to describe the regression in plain language.
 - **Zero browser bundled** - drives your system Chrome via Playwright. No 200 MB Chromium download.
@@ -79,7 +80,8 @@ pursr sweep ./plan.json   # see plans/ for an example
 | Multi-viewport capture | 10+ presets (mobile, tablet, desktop, ultrawide) | `--preset mobile-375` |
 | Layered states | entity / terrain / hud / ui isolation | `--layer entity` |
 | Animation freeze | pause CSS/JS animations for stable frames | `--no-animation` |
-| Cursor overlay | pointer / grab / grabbing / crosshair | `--cursor crosshair` |
+| Cursor overlay | pointer / grab / grabbing / crosshair | `--cursor crosshair` |
+| Visual Operator | rendered cursor, target labels, click markers, headed and CDP sessions | MCP session tools |
 | Grid overlay | spacing guides, custom color + tile size | `--grid --grid-tile 64` |
 | Camera control | zoom + pan via mouse wheel/drag | `--zoom 1.5 --panX 200` |
 | Frame timeline | N captures at intervalMs for animations | `pursr frames <url> 8 200` |
@@ -96,7 +98,7 @@ pursr sweep ./plan.json   # see plans/ for an example
 | HAR capture | HAR 1.2 spec, written next to your shot | `--har ./req.har.json` |
 | Auth state | Playwright storageState, reuse logged-in sessions | `--auth-state admin` |
 | Plugins | custom viewports, sweep ops, before/after hooks | `pursr-plugin-*` |
-| MCP server | 16 tools + resources/list & resources/read for Claude/Cursor | `npx pursr-mcp` |
+| MCP server | Official MCP SDK transport, 16 tools, and resources for Claude/Cursor/Codex | `npx pursr-mcp` |
 | PDF report | render sweep.json to a styled, embedded-PNG A4 PDF | `pursr report --sweep ./sweep.json` |
 | AI diff summary | vision LLM describes the diff in plain language | `pursr diff ... --ai` |
 
@@ -188,10 +190,10 @@ npx pursr-mcp --verbose
 
 | Tool | Description |
 | --- | --- |
-| `pursr_session_open` | Open a persistent browser tab for iterative agent work |
+| `pursr_session_open` | Open a headless, visible, or CDP browser session with optional Visual Operator |
 | `pursr_sessions` | List active browser sessions |
 | `pursr_snapshot` | Visible rendered nodes, geometry, semantics, and computed styles |
-| `pursr_act` | Click, hover, fill, type, scroll, navigate, reload, and more |
+| `pursr_act` | Interact plus move cursor, annotate targets, and clear visual feedback |
 | `pursr_screenshot` | Return the current PNG directly to the vision model |
 | `pursr_inspect` | Inspect exact geometry, computed styles, and stacking ancestors |
 | `pursr_diagnostics` | Read console, page errors, failed requests, and HTTP failures |
@@ -229,6 +231,52 @@ Example action arguments:
   ]
 }
 ```
+
+### Visual Operator
+
+Set `visual: true` to render the agent cursor and interaction feedback into screenshots. `mode: "visible"` enables it automatically and opens a Chrome window that a developer can watch.
+
+```json
+{
+  "url": "http://localhost:3000",
+  "sessionId": "visual-review",
+  "mode": "visible",
+  "operatorColor": "#ff2ea6",
+  "slowMo": 80
+}
+```
+
+Visual actions use the regular `pursr_act` tool:
+
+```json
+{
+  "sessionId": "visual-review",
+  "actions": [
+    { "type": "move", "x": 640, "y": 360, "durationMs": 300 },
+    { "type": "annotate", "selector": "role=button|Publish", "label": "Primary CTA" },
+    { "type": "click", "selector": "role=button|Publish" },
+    { "type": "clearAnnotations", "keepCursor": true }
+  ]
+}
+```
+
+To use an existing authenticated Chrome profile, start Chrome with a dedicated remote-debugging profile and attach using CDP. Do not expose the debugging port beyond localhost.
+
+```bash
+chrome --remote-debugging-port=9222 --user-data-dir=/tmp/pursr-chrome
+```
+
+```json
+{
+  "url": "https://app.example.com",
+  "sessionId": "signed-in-review",
+  "mode": "cdp",
+  "cdpUrl": "http://127.0.0.1:9222",
+  "visual": true
+}
+```
+
+Pursr opens a new tab in Chrome's default context, preserving that profile's cookies and login state. Closing the Pursr session disconnects without terminating the owner browser.
 
 ### Exposed Resources
 
@@ -364,7 +412,8 @@ import {
   saveBaseline, diffKey,
   startHarCapture, stopHarCapture, writeHar,
   loadAuthState,
-  PursrMCPServer, loadMcpConfig,
+  PursrMCPServer, loadMcpConfig, BrowserSessionManager,
+  installVisualOperator, moveVisualCursor, highlightVisualTarget,
   validateSweepPlan,
   listResources, readResource,
   listViewports, resolveViewport, VIEWPORTS,
@@ -389,7 +438,9 @@ import { validateSweepPlan } from "pursr/sweep-schema";
 import { startHarCapture, stopHarCapture } from "pursr/har";
 import { saveAuthState, loadAuthState } from "pursr/auth";
 import { listResources, readResource } from "pursr/mcp-resources";
-import { PursrMCPServer } from "pursr/mcp";
+import { PursrMCPServer } from "pursr/mcp";
+import { BrowserSessionManager } from "pursr/session";
+import { moveVisualCursor, highlightVisualTarget } from "pursr/visual-operator";
 ```
 
 ## Plugins
@@ -417,7 +468,9 @@ Plugins are auto-loaded from `plugins/` (built-in) or via `--plugin <path>`.
 ```
 src/
   index.js          - public library entry
-  mcp.js            - MCP stdio server (JSON-RPC 2.0)
+  mcp.js            - official MCP SDK stdio server
+  session.js        - persistent headless, visible, and CDP sessions
+  visual-operator.js - rendered cursor and interaction feedback
   shoot.js          - runShoot (overlays + camera + frame-stable)
   sweep.js          - runSweep (validated, parallel pool)
   diff.js           - pixelmatch wrapper

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pursr",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "private": false,
   "description": "pursr — Visual QA, audit, and MCP for the browser. One CLI + one MCP server for screenshots, sweeps, baselines, diffs, axe-core a11y audits, HAR capture, and auth state — with parallel sweep workers, auto-healing selectors, and a plugin system. Zero browser bundled: drives your system Chrome via Playwright.",
   "homepage": "https://github.com/0xheycat/pursr",
@@ -12,8 +12,8 @@
   "funding": "https://github.com/sponsors/0xheycat",
   "type": "module",
   "bin": {
-    "pursr": "./bin/pursr.mjs",
-    "pursr-mcp": "./bin/pursr-mcp.mjs"
+    "pursr": "bin/pursr.mjs",
+    "pursr-mcp": "bin/pursr-mcp.mjs"
   },
   "main": "./src/index.js",
   "exports": {
@@ -39,7 +39,8 @@
     "./snap": "./src/snap.js",
     "./report": "./src/report.js",
     "./ai-diff": "./src/ai-diff.js",
-    "./session": "./src/session.js"
+    "./session": "./src/session.js",
+    "./visual-operator": "./src/visual-operator.js"
   },
   "files": [
     "bin",
@@ -77,10 +78,12 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "axe-core": "^4.12.1",
     "pdfkit": "^0.19.1",
     "pixelmatch": "^5.3.0",
-    "pngjs": "^7.0.0"
+    "pngjs": "^7.0.0",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "playwright-core": "*"

package/src/index.js

@@ -25,7 +25,7 @@ import { runClick, runType, runWait, runSeq } from "./interact.js";
 import { listViewports, resolveViewport, VIEWPORTS } from "./viewport.js";
 import { applyCamera, waitForStableFrame } from "./overlays.js";
 import { loadPlugins, registerPlugin, listPlugins, getSweepOp, getViewportPreset, listViewportPresets, getFlagHelp } from "./plugin.js";
-import { launch, newPage } from "./runway.js";
+import { connectOverCDP, launch, newPage } from "./runway.js";
 import { parseFlags, asNum, asBool, nowIso, shortHash, escapeHtml, renderSweepHtml, renderEveryViewportHtml, findStepPng, readArg, makeOut } from "./util.js";
 import { resolveLocator, parseTextSelector } from "./selector.js";
 import { captureDomSnapshot, captureDomSnapshotSidecar } from "./dom-snapshot.js";
@@ -45,6 +45,10 @@ import { runCheck } from "./check.js";
 import { renderSweepPdf } from "./report.js";
 import { aiDiffSummary, aiDiffSidecar } from "./ai-diff.js";
 import { BrowserSessionManager } from "./session.js";
+import {
+  installVisualOperator, moveVisualCursor, highlightVisualTarget,
+  markVisualClick, clearVisualAnnotations, visualPointForLocator,
+} from "./visual-operator.js";
 
 
 // Derive VERSION from package.json to prevent drift
@@ -64,7 +68,7 @@ export {
   // plugin system
   loadPlugins, registerPlugin, listPlugins, getSweepOp, getViewportPreset, listViewportPresets, getFlagHelp,
   // low-level helpers (for plugin authors)
-  launch, newPage,
+  launch, connectOverCDP, newPage,
   parseFlags, asNum, asBool, nowIso, shortHash, escapeHtml, renderSweepHtml, renderEveryViewportHtml, findStepPng, readArg, makeOut,
   resolveLocator, parseTextSelector,
   // v3: selector healing, CI output, MCP server
@@ -88,6 +92,8 @@ export {
   renderSweepPdf,
   aiDiffSummary, aiDiffSidecar,
   BrowserSessionManager,
+  installVisualOperator, moveVisualCursor, highlightVisualTarget,
+  markVisualClick, clearVisualAnnotations, visualPointForLocator,
   VERSION,
 };
 
@@ -98,7 +104,7 @@ export default {
   listViewports, resolveViewport, VIEWPORTS,
   applyCamera, waitForStableFrame,
   loadPlugins, registerPlugin, listPlugins, getSweepOp, getViewportPreset, listViewportPresets, getFlagHelp,
-  launch, newPage,
+  launch, connectOverCDP, newPage,
   parseFlags, asNum, asBool, nowIso, shortHash, escapeHtml, renderSweepHtml, renderEveryViewportHtml, findStepPng, readArg, makeOut,
   resolveLocator, parseTextSelector,
   resolveHealedSelector, healStepAction,
@@ -110,5 +116,7 @@ export default {
   // v6: PDF report, AI diff summary
   runDiffWithAi, renderSweepPdf, aiDiffSummary, aiDiffSidecar,
   BrowserSessionManager,
+  installVisualOperator, moveVisualCursor, highlightVisualTarget,
+  markVisualClick, clearVisualAnnotations, visualPointForLocator,
   VERSION,
 };

package/src/mcp.js

@@ -1,8 +1,7 @@
 //  pursr — MCP stdio server (Model Context Protocol).
 //
-// Implements JSON-RPC 2.0 over stdio with Content-Length framing.
-// Exposes every pursr capability as an MCP tool for use by
-// Claude Code, Cursor, Continue, and any other MCP host.
+// Uses the official Model Context Protocol SDK over stdio and exposes every
+// pursr capability to Claude Code, Cursor, Codex, and other MCP hosts.
 //
 // Config via PURSR_MCP_CONFIG env or ~/./mcp-config.json:
 //   { "plugins": ["./my-plugin.js"], "defaultOutDir": "./mcp-output" }
@@ -25,12 +24,20 @@ import { makeOut, nowIso } from "./util.js";
 import { listResources, readResource, recordResource } from "./mcp-resources.js";
 import { createRequire } from "node:module";
 import { BrowserSessionManager } from "./session.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
 
 const __require = createRequire(import.meta.url);
 let _pkg = { version: "0.1.0" };
 try { _pkg = __require("../package.json"); } catch {}
 
-const MCP_VERSION = "0.1.0";
+const MCP_VERSION = _pkg.version || "0.1.0";
 
 // ─── Config ──────────────────────────────────────────────────────────────
 
@@ -60,140 +67,68 @@ class McpError extends Error {
 
 // ─── Server ──────────────────────────────────────────────────────────────
 
-class PursrMCPServer {
+class PursrMCPServer {
   constructor(config = {}) {
-    this.config = config;
-    this._buffer = Buffer.alloc(0);
-    this._contentLength = -1;
-    this._initialized = false;
+    this.config = config;
     this._verbose = !!config.verbose;
     this.sessions = new BrowserSessionManager({ outputDir: config.defaultOutDir || process.cwd() });
-  }
+    this.sdk = new McpServer(
+      { name: "pursr", version: MCP_VERSION },
+      {
+        capabilities: { tools: {}, resources: {} },
+        instructions: "Use a persistent pursr session for iterative visual work: open, snapshot, act, screenshot, inspect, diagnose, then close.",
+      },
+    );
+    this.server = this.sdk.server;
+    this.transport = null;
+    this._registerSdkHandlers();
+  }
 
   log(...args) {
     if (this._verbose) console.error("[pursr-mcp]", ...args);
   }
 
-  async start() {
+  async start() {
     if (this.config.plugins?.length) {
       await loadPlugins(this.config.plugins);
     }
-    this.log("server started, plugins:", listPlugins());
-
-    process.stdin.on("data", (chunk) => {
-      this._buffer = Buffer.concat([this._buffer, chunk]);
-      this._processBuffer();
-    });
-    process.stdin.on("end", () => {
-      this.log("stdin closed");
+    this.transport = new StdioServerTransport();
+    this.transport.onclose = () => {
+      this.log("stdio transport closed");
       this.sessions.closeAll().catch(() => {});
+    };
+    await this.sdk.connect(this.transport);
+    this.log("server started with official MCP SDK, plugins:", listPlugins());
+  }
+
+  async close() {
+    await this.sessions.closeAll();
+    await this.sdk.close();
+  }
+
+  _registerSdkHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: this._toolDefs() }));
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      try {
+        const content = await this._callTool(request.params.name, request.params.arguments || {});
+        return { content };
+      } catch (error) {
+        this.log("tool error:", error.stack || error.message);
+        return {
+          isError: true,
+          content: [{ type: "text", text: JSON.stringify({ error: error.message, code: error.code || -32603 }, null, 2) }],
+        };
+      }
     });
-
-    process.on("uncaughtException", (err) => {
-      console.error("[pursr-mcp] uncaught:", err.message);
-    });
-  }
-
-  // ── Buffer framing ──────────────────────────────────────────────────
-
-  _processBuffer() {
-    while (true) {
-      if (this._contentLength < 0) {
-        const idx = this._buffer.indexOf(Buffer.from("\r\n\r\n"));
-        if (idx === -1) break;
-        const header = this._buffer.slice(0, idx).toString("utf8");
-        const m = header.match(/Content-Length:\s*(\d+)/i);
-        if (m) this._contentLength = parseInt(m[1], 10);
-        this._buffer = this._buffer.slice(idx + 4);
-      }
-      if (this._contentLength > 0 && this._buffer.length >= this._contentLength) {
-        const raw = this._buffer.slice(0, this._contentLength).toString("utf8");
-        this._buffer = this._buffer.slice(this._contentLength);
-        this._contentLength = -1;
-        try {
-          const msg = JSON.parse(raw);
-          this._handleMessage(msg);
-        } catch (e) {
-          console.error("[pursr-mcp] invalid JSON:", e.message);
-        }
-      } else break;
-    }
-  }
-
-  _send(msg) {
-    const json = JSON.stringify(msg);
-    const bytes = Buffer.from(json, "utf8");
-    const header = `Content-Length: ${bytes.length}\r\n\r\n`;
-    process.stdout.write(header);
-    process.stdout.write(bytes);
-  }
-
-  // ── JSON-RPC dispatcher ─────────────────────────────────────────────
-
-  async _handleMessage(msg) {
-    if (!msg || msg.jsonrpc !== "2.0" || !msg.method) {
-      console.error("[pursr-mcp] skipping non-JSON-RPC message");
-      return;
-    }
-    const { method, id } = msg;
-
-    // Notifications — no id → no response
-    if (method === "notifications/initialized" || method === "notifications/cancelled") {
-      if (method === "notifications/initialized") this._initialized = true;
-      return;
-    }
-    if (id === undefined || id === null) return; // unnamed notification
-
-    try {
-      switch (method) {
-        case "initialize":
-          this._initialized = true;
-          this._send({
-            jsonrpc: "2.0", id,
-            result: {
-              protocolVersion: msg.params?.protocolVersion || "2024-11-05",
-              capabilities: { tools: {} },
-              serverInfo: { name: "pursr", version: MCP_VERSION },
-            },
-          });
-          break;
-
-        case "tools/list":
-          this._send({ jsonrpc: "2.0", id, result: { tools: this._toolDefs() } });
-          break;
-
-        case "resources/list":
-          this._send({ jsonrpc: "2.0", id, result: { resources: listResources().map(this._toMcpResource, this) } });
-          break;
-
-        case "resources/read":
-          if (!msg.params?.uri) throw new McpError(-32602, "Missing uri");
-          const data = readResource(msg.params.uri);
-          if (!data) throw new McpError(-32602, "Resource not found: " + msg.params.uri);
-          this._send({ jsonrpc: "2.0", id, result: { contents: [data] } });
-          break;
-
-        case "tools/call":
-          if (!msg.params?.name) throw new McpError(-32602, "Missing tool name");
-          const result = await this._callTool(msg.params.name, msg.params.arguments || {});
-          this._send({ jsonrpc: "2.0", id, result: { content: result } });
-          break;
-
-        default:
-          this._send({
-            jsonrpc: "2.0", id,
-            error: { code: -32601, message: `Unknown method: ${method}` },
-          });
-      }
-    } catch (e) {
-      if (e instanceof McpError) {
-        this._send({ jsonrpc: "2.0", id, error: { code: e.code, message: e.message } });
-      } else {
-        console.error("[pursr-mcp] handler error:", e.stack || e.message);
-        this._send({ jsonrpc: "2.0", id, error: { code: -32603, message: e.message } });
-      }
-    }
-  }
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+      resources: listResources().map(this._toMcpResource, this),
+    }));
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const data = readResource(request.params.uri);
+      if (!data) throw new Error("Resource not found: " + request.params.uri);
+      return { contents: [data] };
+    });
+  }
 
   // ── Resource shape adapter ─────────────────────────────────────────
 
@@ -212,7 +147,7 @@ class PursrMCPServer {
     return [
       {
         name: "pursr_session_open",
-        description: "Open a persistent browser tab for iterative agent work. State, hover, scroll, dialogs, and navigation persist until closed.",
+        description: "Open a persistent browser tab in headless, visible, or CDP mode. Visual sessions render cursor movement and interaction feedback into screenshots.",
         inputSchema: {
           type: "object",
           properties: {
@@ -220,6 +155,13 @@ class PursrMCPServer {
             sessionId: { type: "string", description: "Stable session name; generated when omitted" },
             preset: { type: "string", description: "Viewport preset" },
             width: { type: "number" }, height: { type: "number" }, dpr: { type: "number" },
+            mode: { type: "string", enum: ["headless", "visible", "cdp"], description: "Browser mode (default headless)" },
+            visible: { type: "boolean", description: "Alias for mode=visible" },
+            visual: { type: "boolean", description: "Enable rendered cursor and interaction overlays" },
+            cdpUrl: { type: "string", description: "Chrome DevTools endpoint for mode=cdp, e.g. http://127.0.0.1:9222" },
+            slowMo: { type: "number", description: "Delay Playwright operations in milliseconds" },
+            operatorColor: { type: "string", description: "Visual Operator accent color" },
+            timeoutMs: { type: "number", description: "Navigation/CDP connection timeout" },
             storageState: { description: "Playwright storageState object or file path" },
           },
           required: ["url"],
@@ -245,7 +187,7 @@ class PursrMCPServer {
       },
       {
         name: "pursr_act",
-        description: "Perform ordered actions in a persistent session. Supported types: click, hover, fill, type, check, select, press, scroll, wait, sleep, navigate, reload, eval.",
+        description: "Perform ordered actions in a persistent session. Supports click, hover, fill, type, check, select, press, scroll, wait, sleep, navigate, reload, eval, move, annotate, and clearAnnotations.",
         inputSchema: {
           type: "object",
           properties: {
@@ -470,7 +412,11 @@ class PursrMCPServer {
 
   async _sessionOpen(args) {
     if (!args.url) throw new McpError(-32602, "Missing required: url");
-    const flags = { preset: args.preset, width: args.width, height: args.height, dpr: args.dpr };
+    const flags = {
+      preset: args.preset, width: args.width, height: args.height, dpr: args.dpr,
+      mode: args.mode, visible: args.visible, visual: args.visual, cdpUrl: args.cdpUrl,
+      slowMo: args.slowMo, operatorColor: args.operatorColor, timeoutMs: args.timeoutMs,
+    };
     const result = await this.sessions.open({ sessionId: args.sessionId, url: args.url, flags, storageState: args.storageState });
     return this._text(result);
   }

package/src/runway.js

@@ -43,24 +43,36 @@ function findChrome() {
 
 const BROWSER_ARGS = Object.freeze(["--no-sandbox", "--disable-gpu", "--disable-dev-shm-usage"]);
 
-export async function launch() {
-  const chromium = await getChromium();
-  const exec = findChrome();
-  if (!exec) throw new Error("system Chrome not found in standard paths");
-  return await chromium.launch({ headless: true, executablePath: exec, args: BROWSER_ARGS });
-}
-
-export async function newPage(browser, viewport, opts = {}) {
-  const ctx = await browser.newContext({
-    viewport: { width: viewport.width, height: viewport.height },
-    deviceScaleFactor: viewport.dpr || 1,
-    reducedMotion: "no-preference",
-    colorScheme: "light",
-    hasTouch: !!(viewport.name && viewport.name.startsWith("mobile")),
-    isMobile: !!(viewport.name && viewport.name.startsWith("mobile")),
-    storageState: opts.storageState || undefined,
-  });
-  const page = await ctx.newPage();
-  page._pursrContext = ctx;
-  return page;
-}
+export async function launch(options = {}) {
+  const chromium = await getChromium();
+  const exec = findChrome();
+  if (!exec) throw new Error("system Chrome not found in standard paths");
+  return await chromium.launch({
+    headless: options.headless !== false,
+    executablePath: options.executablePath || exec,
+    slowMo: Math.max(0, Number(options.slowMo) || 0),
+    args: [...BROWSER_ARGS, ...(Array.isArray(options.args) ? options.args : [])],
+  });
+}
+
+export async function connectOverCDP(endpointURL, options = {}) {
+  if (!endpointURL || typeof endpointURL !== "string") throw new Error("cdpUrl is required for CDP mode");
+  const chromium = await getChromium();
+  return await chromium.connectOverCDP(endpointURL, { timeout: options.timeoutMs || 30_000 });
+}
+
+export async function newPage(browser, viewport, opts = {}) {
+  const ctx = opts.context || await browser.newContext({
+      viewport: { width: viewport.width, height: viewport.height },
+      deviceScaleFactor: viewport.dpr || 1,
+      reducedMotion: "no-preference",
+      colorScheme: "light",
+      hasTouch: !!(viewport.name && viewport.name.startsWith("mobile")),
+      isMobile: !!(viewport.name && viewport.name.startsWith("mobile")),
+      storageState: opts.storageState || undefined,
+    });
+  const page = await ctx.newPage();
+  if (opts.context) await page.setViewportSize({ width: viewport.width, height: viewport.height }).catch(() => {});
+  page._pursrContext = ctx;
+  return page;
+}

package/src/session.js

@@ -2,10 +2,18 @@
 
 import { mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { launch, newPage } from "./runway.js";
+import { connectOverCDP, launch, newPage } from "./runway.js";
 import { resolveViewport } from "./viewport.js";
 import { gotoOrThrow, settle, CLICK_TIMEOUT_MS, WAIT_DEFAULT_TIMEOUT_MS } from "./overlays.js";
 import { resolveLocator } from "./selector.js";
+import {
+  clearVisualAnnotations,
+  highlightVisualTarget,
+  installVisualOperator,
+  markVisualClick,
+  moveVisualCursor,
+  visualPointForLocator,
+} from "./visual-operator.js";
 
 const MAX_DIAGNOSTICS = 250;
 const MAX_ACTIONS = 50;
@@ -37,8 +45,9 @@ function attachDiagnostics(page, diagnostics) {
 }
 
 export class BrowserSessionManager {
-  constructor({ launchBrowser = launch, outputDir = process.cwd() } = {}) {
+  constructor({ launchBrowser = launch, connectBrowser = connectOverCDP, outputDir = process.cwd() } = {}) {
     this.launchBrowser = launchBrowser;
+    this.connectBrowser = connectBrowser;
     this.outputDir = outputDir;
     this.sessions = new Map();
   }
@@ -52,24 +61,34 @@ export class BrowserSessionManager {
   }
 
   list() {
-    return [...this.sessions.values()].map(({ id, page, viewport, createdAt }) => ({ sessionId: id, url: page.url(), viewport, createdAt }));
+    return [...this.sessions.values()].map(({ id, page, viewport, mode, visual, createdAt }) => ({ sessionId: id, url: page.url(), viewport, mode, visual, createdAt }));
   }
 
   async open({ sessionId, url, flags = {}, storageState } = {}) {
     if (!url) throw new Error("url is required");
     const id = cleanId(sessionId);
     if (this.sessions.has(id)) await this.close(id);
-    const browser = await this.launchBrowser();
+    const mode = flags.mode || (flags.cdpUrl ? "cdp" : flags.visible ? "visible" : "headless");
+    if (!new Set(["headless", "visible", "cdp"]).has(mode)) throw new Error("mode must be headless, visible, or cdp");
+    const visual = flags.visual === true || mode === "visible";
+    const operatorOptions = { color: flags.operatorColor || "#ff2ea6" };
+    const browser = mode === "cdp"
+      ? await this.connectBrowser(flags.cdpUrl, { timeoutMs: flags.timeoutMs })
+      : await this.launchBrowser({ headless: mode !== "visible", slowMo: flags.slowMo });
     try {
       const viewport = resolveViewport(flags);
-      const page = await newPage(browser, viewport, { storageState });
+      const context = mode === "cdp" ? browser.contexts()[0] : null;
+      if (mode === "cdp" && !context) throw new Error("CDP browser has no default context");
+      const page = await newPage(browser, viewport, { storageState, context });
       const diagnostics = { console: [], errors: [], requests: [], responses: [] };
       attachDiagnostics(page, diagnostics);
+      if (visual) page.on("domcontentloaded", () => installVisualOperator(page, operatorOptions).catch(() => {}));
       const nav = await gotoOrThrow(page, url, { timeoutMs: flags.timeoutMs });
       await settle(page);
-      const session = { id, browser, page, context: page._pursrContext, viewport, diagnostics, createdAt: new Date().toISOString() };
+      if (visual) await installVisualOperator(page, operatorOptions);
+      const session = { id, browser, page, context: page._pursrContext, viewport, mode, visual, operatorOptions, diagnostics, createdAt: new Date().toISOString() };
       this.sessions.set(id, session);
-      return { sessionId: id, url: page.url(), title: await page.title(), viewport, status: nav.status, createdAt: session.createdAt };
+      return { sessionId: id, url: page.url(), title: await page.title(), viewport, mode, visual, status: nav.status, createdAt: session.createdAt };
     } catch (error) {
       try { await browser.close(); } catch {}
       throw error;
@@ -131,7 +150,8 @@ export class BrowserSessionManager {
   async act(sessionId, actions = []) {
     if (!Array.isArray(actions) || !actions.length) throw new Error("actions must be a non-empty array");
     if (actions.length > MAX_ACTIONS) throw new Error(`actions cannot exceed ${MAX_ACTIONS}`);
-    const { page } = this.get(sessionId);
+    const session = this.get(sessionId);
+    const { page, visual, operatorOptions } = session;
     const trace = [];
     for (let i = 0; i < actions.length; i++) {
       const action = actions[i] || {};
@@ -141,19 +161,47 @@ export class BrowserSessionManager {
         if (["click", "hover", "fill", "type", "check", "select"].includes(op)) {
           const locator = await resolveLocator(page, action.selector);
           await locator.first().waitFor({ state: "visible", timeout: action.timeoutMs || CLICK_TIMEOUT_MS });
+          let point = null;
+          if (visual) {
+            point = await visualPointForLocator(locator.first());
+            await moveVisualCursor(page, point.x, point.y, { ...operatorOptions, durationMs: action.durationMs });
+            await highlightVisualTarget(page, point.rect, { ...operatorOptions, color: action.color, label: action.label || `${op}: ${action.selector}` });
+            step.cursor = { x: Math.round(point.x), y: Math.round(point.y) };
+          }
           if (op === "click") await locator.first().click();
           else if (op === "hover") await locator.first().hover();
           else if (op === "fill") await locator.first().fill(String(action.text ?? action.value ?? ""));
           else if (op === "type") await locator.first().pressSequentially(String(action.text ?? ""), { delay: action.delayMs || 10 });
           else if (op === "check") await locator.first().setChecked(action.checked !== false);
           else await locator.first().selectOption(action.value);
+          if (visual && op === "click" && point) await markVisualClick(page, point.x, point.y, { ...operatorOptions, color: action.color });
           step.selector = action.selector;
         } else if (op === "press") await page.keyboard.press(String(action.key));
         else if (op === "scroll") await page.mouse.wheel(Number(action.deltaX) || 0, Number(action.deltaY) || 0);
         else if (op === "wait") await (await resolveLocator(page, action.selector)).first().waitFor({ state: action.state || "visible", timeout: action.timeoutMs || WAIT_DEFAULT_TIMEOUT_MS });
         else if (op === "sleep") await page.waitForTimeout(Math.max(0, Number(action.ms) || 0));
-        else if (op === "navigate") await gotoOrThrow(page, action.url, { timeoutMs: action.timeoutMs });
-        else if (op === "reload") await page.reload({ waitUntil: "domcontentloaded" });
+        else if (op === "navigate") {
+          await gotoOrThrow(page, action.url, { timeoutMs: action.timeoutMs });
+          if (visual) await installVisualOperator(page, operatorOptions);
+        } else if (op === "reload") {
+          await page.reload({ waitUntil: "domcontentloaded" });
+          if (visual) await installVisualOperator(page, operatorOptions);
+        } else if (op === "move") {
+          if (!visual) throw new Error("move requires a visual session");
+          step.cursor = await moveVisualCursor(page, action.x, action.y, { ...operatorOptions, durationMs: action.durationMs });
+        } else if (op === "annotate") {
+          if (!visual) throw new Error("annotate requires a visual session");
+          const locator = await resolveLocator(page, action.selector);
+          await locator.first().waitFor({ state: "visible", timeout: action.timeoutMs || CLICK_TIMEOUT_MS });
+          const point = await visualPointForLocator(locator.first());
+          await moveVisualCursor(page, point.x, point.y, { ...operatorOptions, durationMs: action.durationMs });
+          await highlightVisualTarget(page, point.rect, { ...operatorOptions, color: action.color, label: action.label || action.selector });
+          step.selector = action.selector;
+          step.cursor = { x: Math.round(point.x), y: Math.round(point.y) };
+        } else if (op === "clearAnnotations") {
+          if (!visual) throw new Error("clearAnnotations requires a visual session");
+          await clearVisualAnnotations(page, { keepCursor: action.keepCursor !== false });
+        }
         else if (op === "eval") step.result = await page.evaluate(String(action.js || ""));
         else throw new Error(`unknown action type: ${op}`);
         if (action.settleMs) await page.waitForTimeout(Number(action.settleMs));

package/src/visual-operator.js

@@ -0,0 +1,124 @@
+// Visible cursor and interaction feedback for agent-driven browser sessions.
+
+const DEFAULT_COLOR = "#ff2ea6";
+
+function safeColor(value) {
+  const color = String(value || DEFAULT_COLOR).trim();
+  if (/^#[0-9a-f]{3,8}$/i.test(color)) return color;
+  if (/^(rgb|hsl)a?\([\d\s.,%+-]+\)$/i.test(color)) return color;
+  if (/^[a-z]{1,24}$/i.test(color)) return color;
+  return DEFAULT_COLOR;
+}
+
+export async function installVisualOperator(page, options = {}) {
+  const color = safeColor(options.color);
+  await page.evaluate(({ color }) => {
+    if (document.getElementById("__pursr_operator_style__")) return;
+    const style = document.createElement("style");
+    style.id = "__pursr_operator_style__";
+    style.textContent = `
+      #__pursr_cursor__ { position: fixed; left: 0; top: 0; width: 28px; height: 34px;
+        pointer-events: none; z-index: 2147483647; transform: translate(24px, 24px);
+        filter: drop-shadow(0 2px 2px rgba(0,0,0,.55)); transition: none; }
+      #__pursr_cursor__ svg { display: block; width: 100%; height: 100%; }
+      .__pursr_target__ { position: fixed; pointer-events: none; z-index: 2147483645;
+        border: 3px solid var(--pursr-color); border-radius: 7px;
+        box-shadow: 0 0 0 2px rgba(255,255,255,.92), 0 0 18px var(--pursr-color); }
+      .__pursr_label__ { position: absolute; left: -3px; bottom: calc(100% + 7px);
+        padding: 3px 7px; border-radius: 4px; background: var(--pursr-color); color: white;
+        font: 700 12px/1.3 ui-monospace, SFMono-Regular, Consolas, monospace;
+        white-space: nowrap; text-shadow: 0 1px 1px rgba(0,0,0,.35); }
+      .__pursr_click__ { position: fixed; width: 28px; height: 28px; margin: -14px 0 0 -14px;
+        pointer-events: none; z-index: 2147483646; border: 4px solid var(--pursr-color);
+        border-radius: 50%; box-shadow: 0 0 0 3px rgba(255,255,255,.9), 0 0 20px var(--pursr-color); }
+    `;
+    document.documentElement.appendChild(style);
+    const cursor = document.createElement("div");
+    cursor.id = "__pursr_cursor__";
+    cursor.dataset.x = "24";
+    cursor.dataset.y = "24";
+    cursor.style.setProperty("--pursr-color", color);
+    cursor.innerHTML = `<svg viewBox="0 0 28 34" aria-hidden="true"><path d="M3 2.5V27l6.8-6.2 4.7 10.2 5.2-2.5-4.7-9.8 9.4-.2z" fill="${color}" stroke="#fff" stroke-width="2.4" stroke-linejoin="round"/><path d="M3 2.5V27l6.8-6.2 4.7 10.2 5.2-2.5-4.7-9.8 9.4-.2z" fill="none" stroke="#16131a" stroke-width="1" stroke-linejoin="round"/></svg>`;
+    document.documentElement.appendChild(cursor);
+  }, { color });
+}
+
+export async function moveVisualCursor(page, x, y, options = {}) {
+  await installVisualOperator(page, options);
+  const durationMs = Math.max(0, Math.min(3000, Number(options.durationMs) || 220));
+  const point = { x: Math.round(Number(x) || 0), y: Math.round(Number(y) || 0) };
+  await page.evaluate(async ({ point, durationMs }) => {
+    const cursor = document.getElementById("__pursr_cursor__");
+    if (!cursor) return;
+    const startX = Number(cursor.dataset.x) || 0;
+    const startY = Number(cursor.dataset.y) || 0;
+    const started = performance.now();
+    await new Promise((resolve) => {
+      const frame = (now) => {
+        const progress = durationMs ? Math.min(1, (now - started) / durationMs) : 1;
+        const eased = 1 - Math.pow(1 - progress, 3);
+        const nextX = startX + (point.x - startX) * eased;
+        const nextY = startY + (point.y - startY) * eased;
+        cursor.style.transform = `translate(${nextX}px, ${nextY}px)`;
+        if (progress < 1) requestAnimationFrame(frame);
+        else resolve();
+      };
+      requestAnimationFrame(frame);
+    });
+    cursor.dataset.x = String(point.x);
+    cursor.dataset.y = String(point.y);
+  }, { point, durationMs });
+  await page.mouse.move(point.x, point.y, { steps: Math.max(1, Math.min(20, Math.ceil(durationMs / 20))) });
+  return point;
+}
+
+export async function highlightVisualTarget(page, rect, options = {}) {
+  await installVisualOperator(page, options);
+  const color = safeColor(options.color);
+  const label = String(options.label || "target").slice(0, 80);
+  await page.evaluate(({ rect, color, label }) => {
+    document.querySelectorAll(".__pursr_target__").forEach((node) => node.remove());
+    const target = document.createElement("div");
+    target.className = "__pursr_target__";
+    target.style.setProperty("--pursr-color", color);
+    target.style.left = `${Math.round(rect.x)}px`;
+    target.style.top = `${Math.round(rect.y)}px`;
+    target.style.width = `${Math.max(0, Math.round(rect.width))}px`;
+    target.style.height = `${Math.max(0, Math.round(rect.height))}px`;
+    const tag = document.createElement("span");
+    tag.className = "__pursr_label__";
+    tag.textContent = label;
+    target.appendChild(tag);
+    document.documentElement.appendChild(target);
+  }, { rect, color, label });
+}
+
+export async function markVisualClick(page, x, y, options = {}) {
+  await installVisualOperator(page, options);
+  const color = safeColor(options.color);
+  await page.evaluate(({ x, y, color }) => {
+    document.querySelectorAll(".__pursr_click__").forEach((node) => node.remove());
+    const marker = document.createElement("div");
+    marker.className = "__pursr_click__";
+    marker.style.setProperty("--pursr-color", color);
+    marker.style.left = `${Math.round(x)}px`;
+    marker.style.top = `${Math.round(y)}px`;
+    document.documentElement.appendChild(marker);
+  }, { x, y, color });
+}
+
+export async function clearVisualAnnotations(page, { keepCursor = true } = {}) {
+  await page.evaluate(({ keepCursor }) => {
+    document.querySelectorAll(".__pursr_target__, .__pursr_click__").forEach((node) => node.remove());
+    if (!keepCursor) {
+      document.getElementById("__pursr_cursor__")?.remove();
+      document.getElementById("__pursr_operator_style__")?.remove();
+    }
+  }, { keepCursor });
+}
+
+export async function visualPointForLocator(locator) {
+  const rect = await locator.boundingBox();
+  if (!rect) throw new Error("target has no visible bounding box");
+  return { rect, x: rect.x + rect.width / 2, y: rect.y + rect.height / 2 };
+}