pursr 0.8.1 → 0.9.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 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` |
@@ -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.1",
+  "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",
@@ -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",

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

@@ -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,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"],
@@ -180,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: {
@@ -405,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 };
+}