pursr 0.9.0 → 0.10.0

package/README.md

@@ -35,7 +35,7 @@ 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.
 - **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 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.
@@ -81,7 +81,7 @@ pursr sweep ./plan.json   # see plans/ for an example
 | 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` |
-| Visual Operator | rendered cursor, target labels, click markers, headed and CDP sessions | MCP session tools |
+| 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` |
@@ -161,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) |
@@ -236,6 +237,45 @@ Example action arguments:
 
 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",
@@ -246,6 +286,8 @@ Set `visual: true` to render the agent cursor and interaction feedback into scre
 }
 ```
 
+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

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.9.0",
+  "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",
@@ -40,6 +40,7 @@
     "./report": "./src/report.js",
     "./ai-diff": "./src/ai-diff.js",
     "./session": "./src/session.js",
+    "./operator": "./src/operator.js",
     "./visual-operator": "./src/visual-operator.js"
   },
   "files": [

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

@@ -45,6 +45,7 @@ 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,
@@ -92,6 +93,7 @@ export {
   renderSweepPdf,
   aiDiffSummary, aiDiffSidecar,
   BrowserSessionManager,
+  runOperator,
   installVisualOperator, moveVisualCursor, highlightVisualTarget,
   markVisualClick, clearVisualAnnotations, visualPointForLocator,
   VERSION,
@@ -116,6 +118,7 @@ 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

@@ -161,6 +161,7 @@ class PursrMCPServer {
             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" },
           },
@@ -187,7 +188,7 @@ class PursrMCPServer {
       },
       {
         name: "pursr_act",
-        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.",
+        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: {
@@ -416,6 +417,7 @@ class PursrMCPServer {
       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

@@ -70,6 +70,10 @@ export async function newPage(browser, viewport, opts = {}) {
       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(() => {});

package/src/session.js

@@ -71,6 +71,9 @@ export class BrowserSessionManager {
     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 })
@@ -79,14 +82,18 @@ export class BrowserSessionManager {
       const viewport = resolveViewport(flags);
       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 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);
       if (visual) await installVisualOperator(page, operatorOptions);
-      const session = { id, browser, page, context: page._pursrContext, viewport, mode, visual, operatorOptions, diagnostics, createdAt: new Date().toISOString() };
+      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, mode, visual, status: nav.status, createdAt: session.createdAt };
     } catch (error) {
@@ -158,7 +165,7 @@ export class BrowserSessionManager {
       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;
@@ -169,14 +176,42 @@ export class BrowserSessionManager {
             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 && op === "click" && point) await markVisualClick(page, point.x, point.y, { ...operatorOptions, color: action.color });
+          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));
@@ -242,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() {