pursr 0.8.1 → 0.10.0

package/README.md

@@ -34,7 +34,8 @@ Most teams need **five separate tools** to do visual QA: a screenshot CLI, a reg
 
 - **A unified CLI** (`pursr`) for every capture, diff, sweep, and audit.
 - **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.
-- **A library API** with 23 subpath modules, so you can embed the browser and QA primitives in your own tooling.
+- **Visual Operator** sessions with a rendered cursor, target labels, click markers, visible Chrome windows, and authenticated Chrome attachment over CDP.
+- **A library API** with 25 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, WebM recording, headed and CDP sessions | `operator` CLI + 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` |
@@ -159,7 +161,8 @@ pursr validate ./plan.json
 | `probe` | Health check (HTTP status, page title) |
 | `shot` / `full` | Viewport / full-page screenshot |
 | `eval` | Execute JS in the page, return result |
-| `click` / `type` / `wait` / `seq` | Interaction primitives |
+| `click` / `type` / `wait` / `seq` | Interaction primitives |
+| `operator` | Run a visible action plan with cursor feedback, screenshot, trace, diagnostics, and optional WebM video |
 | `diff` | Pixel-level diff vs a reference PNG |
 | `viewports` | List all registered viewport presets |
 | `shoot` | Rich capture (overlays, freeze, camera, plugins) |
@@ -188,10 +191,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 +232,93 @@ 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.
+
+#### CLI: scripted tutorials and repeatable recordings
+
+Use the CLI when the steps are already known. It needs no MCP host and produces a final screenshot, JSON trace, diagnostics, and an optional WebM recording.
+
+```bash
+pursr operator http://localhost:3000 @plans/operator-tutorial.json \
+  --visible \
+  --start-delay 3000 \
+  --slow-mo 100 \
+  --video ./recordings \
+  --out ./recordings/final.png
+```
+
+The action plan is a JSON array. The same action objects work through `pursr_act` in MCP:
+
+```json
+[
+  { "type": "annotate", "selector": "role=button|Build", "label": "Open build menu" },
+  { "type": "click", "selector": "role=button|Build", "durationMs": 350, "settleMs": 500 },
+  { "type": "click", "x": 640, "y": 420, "durationMs": 250 },
+  { "type": "drag", "fromX": 520, "fromY": 400, "toX": 760, "toY": 520, "steps": 30 },
+  { "type": "keyDown", "key": "Shift" },
+  { "type": "keyUp", "key": "Shift" },
+  { "type": "press", "key": "Escape" },
+  { "type": "sleep", "ms": 800 },
+  { "type": "clearAnnotations", "keepCursor": true }
+]
+```
+
+Chrome records the browser viewport as silent WebM video. Add narration or system audio in your editor, and convert to MP4 when needed:
+
+```bash
+ffmpeg -i recording.webm -c:v libx264 -pix_fmt yuv420p tutorial.mp4
+```
+
+#### MCP: adaptive agent operation
+
+Use MCP when the agent must inspect the current page, decide the next action, verify visual results, or pause for human approval. MCP is not required for CLI recording. Both interfaces use the same session and Visual Operator engine.
+
+```json
+{
+  "url": "http://localhost:3000",
+  "sessionId": "visual-review",
+  "mode": "visible",
+  "operatorColor": "#ff2ea6",
+  "slowMo": 80
+}
+```
+
+Add `recordVideoDir` to record an MCP session in headless or visible mode. The final video path is returned by `pursr_session_close`. CDP sessions preserve an existing browser profile but cannot record video because Chrome owns that context.
+
+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 +454,8 @@ import {
   saveBaseline, diffKey,
   startHarCapture, stopHarCapture, writeHar,
   loadAuthState,
-  PursrMCPServer, loadMcpConfig,
+  PursrMCPServer, loadMcpConfig, BrowserSessionManager,
+  installVisualOperator, moveVisualCursor, highlightVisualTarget,
   validateSweepPlan,
   listResources, readResource,
   listViewports, resolveViewport, VIEWPORTS,
@@ -389,7 +480,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 +510,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/bin/pursr.mjs

@@ -2,7 +2,8 @@
 // pursr CLI. Thin wrapper around src/* that mirrors the npm bin.
 
 import { VERSION } from "../src/index.js";
-import { runClick, runType, runWait, runSeq } from "../src/interact.js";
+import { runClick, runType, runWait, runSeq } from "../src/interact.js";
+import { runOperator } from "../src/operator.js";
 import { runEval } from "../src/eval.js";
 import { runProbe } from "../src/probe.js";
 import { runShot } from "../src/shot.js";
@@ -24,7 +25,8 @@ import { loadPlugins, listPlugins, getFlagHelp } from "../src/plugin.js";
 
 const USAGE = `usage:
   v1: pursr {probe|shot|full|eval|click|type|wait|diff|seq} <url> [...]
-  v2: pursr {viewports|shoot|layer|frames|hover|sweep} <...>
+  v2: pursr {viewports|shoot|layer|frames|hover|sweep} <...>
+  operator: pursr operator <url> <actions.json|@file> [--visible] [--start-delay 3000] [--video <dir>] [--out <final.png>]
   flags: --preset <name> --width N --height N --dpr N
          --zoom 1.5 --panX 200 --panY -100
          --cursor pointer|grab|grabbing|crosshair|none
@@ -90,7 +92,41 @@ await loadPlugins(pluginPaths);
           : await runDiff(url, ref, out, threshold, flags);
         console.log(JSON.stringify(r, null, 2)); break;
       }
-      case "seq": { if (!url) die("missing url"); const actions = readArg(b); if (!actions) die("seq: missing <actions.json> (or @file)"); const out = c || makeOut("seq.png"); const r = await runSeq(url, actions, out); console.log(JSON.stringify(r, null, 2)); break; }
+      case "seq": { if (!url) die("missing url"); const actions = readArg(b); if (!actions) die("seq: missing <actions.json> (or @file)"); const out = c || makeOut("seq.png"); const r = await runSeq(url, actions, out); console.log(JSON.stringify(r, null, 2)); break; }
+      case "operator": {
+        if (!url) die("operator: missing <url>");
+        const actions = readArg(b); if (!actions) die("operator: missing <actions.json> (or @file)");
+        const flags = parseFlags(argv.slice(5));
+        const out = flags.out || makeOut("operator.png");
+        const videoValue = flags.video ?? flags["record-video"];
+        const recordVideoDir = videoValue
+          ? (videoValue === true ? dirname(out) : String(videoValue))
+          : null;
+        const r = await runOperator({
+          url,
+          actions,
+          out,
+          outputDir: dirname(out),
+          sessionId: flags.session || undefined,
+          flags: {
+            mode: flags.mode || (flags.cdp ? "cdp" : flags.visible ? "visible" : "headless"),
+            visual: !flags["no-visual"],
+            cdpUrl: flags.cdp || flags["cdp-url"],
+            slowMo: asNum(flags["slow-mo"] ?? flags.slowMo, 0),
+            startDelayMs: asNum(flags["start-delay"] ?? flags.startDelayMs, 0),
+            operatorColor: flags["operator-color"] || flags.operatorColor,
+            recordVideoDir,
+            width: flags.width,
+            height: flags.height,
+            dpr: flags.dpr,
+            preset: flags.preset,
+            full: !!flags.full,
+          },
+        });
+        console.log(JSON.stringify(r, null, 2));
+        if (!r.ok) process.exitCode = 1;
+        break;
+      }
       case "viewports": { console.log(JSON.stringify(listViewports(), null, 2)); break; }
       case "shoot": {
         if (!url) die("missing url");
@@ -342,4 +378,4 @@ await loadPlugins(pluginPaths);
     console.error(JSON.stringify({ error: e.message, stack: e.stack?.split("\n").slice(0, 3).join("\n") }, null, 2));
     process.exit(1);
   }
-})();
+})();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pursr",
-  "version": "0.8.1",
+  "version": "0.10.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",
@@ -39,7 +39,9 @@
     "./snap": "./src/snap.js",
     "./report": "./src/report.js",
     "./ai-diff": "./src/ai-diff.js",
-    "./session": "./src/session.js"
+    "./session": "./src/session.js",
+    "./operator": "./src/operator.js",
+    "./visual-operator": "./src/visual-operator.js"
   },
   "files": [
     "bin",

package/plans/operator-tutorial.json

@@ -0,0 +1,16 @@
+[
+  {
+    "type": "annotate",
+    "selector": "body",
+    "label": "Visual Operator session",
+    "durationMs": 300
+  },
+  {
+    "type": "sleep",
+    "ms": 700
+  },
+  {
+    "type": "clearAnnotations",
+    "keepCursor": true
+  }
+]

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,11 @@ import { runCheck } from "./check.js";
 import { renderSweepPdf } from "./report.js";
 import { aiDiffSummary, aiDiffSidecar } from "./ai-diff.js";
 import { BrowserSessionManager } from "./session.js";
+import { runOperator } from "./operator.js";
+import {
+  installVisualOperator, moveVisualCursor, highlightVisualTarget,
+  markVisualClick, clearVisualAnnotations, visualPointForLocator,
+} from "./visual-operator.js";
 
 
 // Derive VERSION from package.json to prevent drift
@@ -64,7 +69,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 +93,9 @@ export {
   renderSweepPdf,
   aiDiffSummary, aiDiffSidecar,
   BrowserSessionManager,
+  runOperator,
+  installVisualOperator, moveVisualCursor, highlightVisualTarget,
+  markVisualClick, clearVisualAnnotations, visualPointForLocator,
   VERSION,
 };
 
@@ -98,7 +106,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 +118,8 @@ export default {
   // v6: PDF report, AI diff summary
   runDiffWithAi, renderSweepPdf, aiDiffSummary, aiDiffSidecar,
   BrowserSessionManager,
+  runOperator,
+  installVisualOperator, moveVisualCursor, highlightVisualTarget,
+  markVisualClick, clearVisualAnnotations, visualPointForLocator,
   VERSION,
 };

package/src/mcp.js

@@ -147,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: {
@@ -155,6 +155,14 @@ 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" },
+            recordVideoDir: { type: "string", description: "Directory for a WebM recording (headless or visible mode only)" },
+            timeoutMs: { type: "number", description: "Navigation/CDP connection timeout" },
             storageState: { description: "Playwright storageState object or file path" },
           },
           required: ["url"],
@@ -180,7 +188,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 selector or coordinate click/doubleClick, drag, hover, fill, type, check, select, press, keyDown, keyUp, scroll, wait, sleep, navigate, reload, eval, move, annotate, and clearAnnotations.",
         inputSchema: {
           type: "object",
           properties: {
@@ -405,7 +413,12 @@ 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,
+      recordVideoDir: args.recordVideoDir,
+    };
     const result = await this.sessions.open({ sessionId: args.sessionId, url: args.url, flags, storageState: args.storageState });
     return this._text(result);
   }

package/src/operator.js

@@ -0,0 +1,61 @@
+// One-shot Visual Operator workflow for CLI and library consumers.
+
+import { dirname, join, resolve } from "node:path";
+import { mkdirSync } from "node:fs";
+import { BrowserSessionManager } from "./session.js";
+
+function normalizeActions(actions) {
+  if (typeof actions === "string") actions = JSON.parse(actions);
+  if (!Array.isArray(actions) || !actions.length) throw new Error("operator actions must be a non-empty JSON array");
+  return actions;
+}
+
+export async function runOperator({
+  url,
+  actions,
+  out,
+  outputDir = process.cwd(),
+  sessionId = `operator-${Date.now().toString(36)}`,
+  flags = {},
+} = {}) {
+  if (!url) throw new Error("operator url is required");
+  const steps = normalizeActions(actions);
+  const screenshotOut = resolve(out || join(outputDir, `${sessionId}.png`));
+  mkdirSync(dirname(screenshotOut), { recursive: true });
+
+  const manager = new BrowserSessionManager({ outputDir });
+  let opened = null;
+  let acted = null;
+  let shot = null;
+  let diagnostics = null;
+  let closed = null;
+  try {
+    opened = await manager.open({
+      sessionId,
+      url,
+      storageState: flags.storageState,
+      flags: { ...flags, visual: flags.visual !== false },
+    });
+    if (Number(flags.startDelayMs) > 0) {
+      await manager.get(sessionId).page.waitForTimeout(Number(flags.startDelayMs));
+    }
+    acted = await manager.act(sessionId, steps);
+    shot = await manager.screenshot(sessionId, { out: screenshotOut, full: !!flags.full });
+    diagnostics = manager.diagnostics(sessionId);
+  } finally {
+    closed = await manager.close(sessionId).catch(() => ({ sessionId, closed: false, video: null }));
+  }
+
+  return {
+    ok: !acted?.failed,
+    sessionId,
+    mode: opened?.mode,
+    visual: opened?.visual,
+    url: acted?.url || opened?.url || url,
+    title: acted?.title || opened?.title || null,
+    trace: acted?.trace || [],
+    screenshot: shot?.out || null,
+    video: closed?.video || null,
+    diagnostics,
+  };
+}

package/src/runway.js

@@ -43,24 +43,40 @@ 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,
+      recordVideo: opts.recordVideoDir ? {
+        dir: opts.recordVideoDir,
+        size: { width: viewport.width, height: viewport.height },
+      } : 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,41 @@ 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 recordVideoDir = flags.recordVideoDir || null;
+    if (recordVideoDir && mode === "cdp") throw new Error("video recording is not available in CDP mode; use visible or headless mode");
+    if (recordVideoDir) mkdirSync(recordVideoDir, { recursive: true });
+    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, recordVideoDir });
       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, video: page.video?.() || null,
+        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,29 +157,86 @@ 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] || {};
       const op = action.type || action.op;
       const step = { index: i, type: op };
       try {
-        if (["click", "hover", "fill", "type", "check", "select"].includes(op)) {
+        if (["click", "doubleClick", "hover", "fill", "type", "check", "select"].includes(op) && action.selector) {
           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 === "doubleClick") await locator.first().dblclick();
           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 && ["click", "doubleClick"].includes(op) && point) await markVisualClick(page, point.x, point.y, { ...operatorOptions, color: action.color });
           step.selector = action.selector;
+        } else if (["click", "doubleClick"].includes(op) && Number.isFinite(Number(action.x)) && Number.isFinite(Number(action.y))) {
+          const x = Number(action.x), y = Number(action.y);
+          if (visual) await moveVisualCursor(page, x, y, { ...operatorOptions, durationMs: action.durationMs });
+          await page.mouse[op === "doubleClick" ? "dblclick" : "click"](x, y, { button: action.button || "left" });
+          if (visual) await markVisualClick(page, x, y, { ...operatorOptions, color: action.color });
+          step.cursor = { x: Math.round(x), y: Math.round(y) };
+        } else if (op === "drag") {
+          const start = action.fromSelector
+            ? await visualPointForLocator((await resolveLocator(page, action.fromSelector)).first())
+            : { x: Number(action.fromX), y: Number(action.fromY) };
+          const end = action.toSelector
+            ? await visualPointForLocator((await resolveLocator(page, action.toSelector)).first())
+            : { x: Number(action.toX), y: Number(action.toY) };
+          if (![start.x, start.y, end.x, end.y].every(Number.isFinite)) throw new Error("drag requires from/to coordinates or selectors");
+          if (visual) await moveVisualCursor(page, start.x, start.y, { ...operatorOptions, durationMs: action.durationMs });
+          await page.mouse.move(start.x, start.y);
+          await page.mouse.down({ button: action.button || "left" });
+          const steps = Math.max(1, Math.min(100, Number(action.steps) || 20));
+          await page.mouse.move(end.x, end.y, { steps });
+          await page.mouse.up({ button: action.button || "left" });
+          if (visual) {
+            await moveVisualCursor(page, end.x, end.y, { ...operatorOptions, durationMs: 0 });
+            await markVisualClick(page, end.x, end.y, { ...operatorOptions, color: action.color });
+          }
+          step.cursor = { x: Math.round(end.x), y: Math.round(end.y) };
         } else if (op === "press") await page.keyboard.press(String(action.key));
+        else if (op === "keyDown") await page.keyboard.down(String(action.key));
+        else if (op === "keyUp") await page.keyboard.up(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));
@@ -194,8 +277,16 @@ export class BrowserSessionManager {
     const session = this.sessions.get(id);
     if (!session) return { sessionId: id, closed: false };
     this.sessions.delete(id);
+    let video = null;
+    try {
+      if (session.mode === "cdp") await session.page.close();
+      else await session.context.close();
+    } catch {}
     try { await session.browser.close(); } catch {}
-    return { sessionId: id, closed: true };
+    if (session.video) {
+      try { video = await session.video.path(); } catch {}
+    }
+    return { sessionId: id, closed: true, video };
   }
 
   async closeAll() {

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 };
+}