pursr 0.9.0 → 0.10.1

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` |
@@ -154,14 +154,24 @@ pursr baseline approve myapp ./new.png home --url https://example.com
 pursr validate ./plan.json
 ```
 
-### Subcommands
+### Subcommands
+
+Flags are order-independent. Both commands below are valid, and explicit output paths override Pursr's default output directory:
+
+```bash
+pursr shot --preset desktop-1280 https://example.com --out ./captures/home.png
+pursr full https://example.com --preset desktop-1280 --out-dir ./captures
+```
+
+`--out` is a complete file path. `--out-dir` is a directory where Pursr writes the command's standard filename.
 
 | Subcommand | Purpose |
 | --- | --- |
 | `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) |
@@ -174,7 +184,11 @@ pursr validate ./plan.json
 | `every-viewport` | Capture once per preset in parallel (3-wide pool) |
 | `baseline` | save / list / approve / show visual baselines |
 | `auth` | save / load / list / delete Playwright storageState |
-| `validate` | Validate a sweep plan JSON without running it |
+| `validate` | Validate a sweep plan JSON without running it |
+
+### Agent Skill
+
+The npm package includes [`SKILL.md`](./SKILL.md), a compact operating guide for coding agents. Point an agent at `node_modules/pursr/SKILL.md`, or copy it into the skill directory used by your agent host. It explains when to use CLI versus MCP, correct argument order, action plans, visual verification, and safety boundaries.
 
 ## MCP Server
 
@@ -236,6 +250,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 +299,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/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: pursr
+description: Use Pursr for browser screenshots, scripted visual operation, visual regression, accessibility audits, DOM inspection, and MCP-driven browser sessions.
+---
+
+# Pursr
+
+Use this skill when a user asks an agent to inspect, operate, record, test, or compare a browser interface.
+
+## Choose The Right Surface
+
+- Use the CLI for repeatable commands and prewritten action plans.
+- Use MCP when the agent must inspect the current page, choose the next action, verify it, or pause for human approval.
+- Use `pursr operator` for a visible scripted walkthrough or silent WebM recording.
+- Use `pursr shoot` for a rich screenshot with viewport, layer, camera, grid, or animation controls.
+- Use `pursr check` for CI regression against an approved baseline.
+- Use `pursr sweep` only with a local JSON plan path. A URL is not a sweep plan.
+
+## CLI Argument Contract
+
+Flags may appear before or after positional arguments.
+
+```bash
+pursr shot --preset desktop-1280 https://example.com --out ./out/page.png
+pursr full https://example.com --out-dir ./out
+pursr eval --preset desktop-1280 https://example.com "document.title" --out ./out/eval.png
+pursr click https://example.com "role=button|Continue" --out ./out/click.png
+pursr type https://example.com "#email" "hello@example.com" --out ./out/type.png
+pursr hover https://example.com "text=Pricing" --out ./out/hover.png
+pursr seq https://example.com ./actions.json --out ./out/final.png
+pursr sweep ./sweep-plan.json --out-dir ./out/sweep
+```
+
+`--out` is a complete file path. `--out-dir` is a directory; Pursr chooses the command's standard filename inside it.
+
+For `seq` and `operator`, actions may be inline JSON, a plain `.json` path, or an `@file.json` reference.
+
+## Visual Operator
+
+```bash
+pursr operator https://example.com ./actions.json \
+  --visible --start-delay 1500 --slow-mo 80 \
+  --video ./recordings --out ./recordings/final.png
+```
+
+The result includes the action trace, final screenshot, diagnostics, and WebM path. Browser video is silent.
+
+Common actions:
+
+```json
+[
+  { "type": "annotate", "selector": "role=button|Continue", "label": "Continue" },
+  { "type": "click", "selector": "role=button|Continue" },
+  { "type": "fill", "selector": "#email", "text": "hello@example.com" },
+  { "type": "drag", "fromX": 200, "fromY": 300, "toX": 600, "toY": 300 },
+  { "type": "press", "key": "Escape" }
+]
+```
+
+## MCP Agent Loop
+
+1. Open one stable session with `pursr_session_open`.
+2. Read rendered state with `pursr_snapshot`.
+3. Perform a small action sequence with `pursr_act`.
+4. Use `pursr_screenshot` when visual judgment is needed.
+5. Use `pursr_inspect` for geometry, clipping, style, or stacking issues.
+6. Read `pursr_diagnostics` after failures.
+7. Close with `pursr_session_close`; this finalizes any video recording.
+
+## Safety
+
+- Inspect before acting on unfamiliar pages.
+- Ask for human confirmation immediately before publishing, sending, purchasing, deleting, or changing permissions.
+- Keep CDP endpoints on localhost. CDP preserves the browser profile but cannot record video.
+- Do not claim a visual result passed until the produced screenshot or video has been checked.
+
+## Avoid
+
+- Do not pass a URL to `sweep`; pass a JSON plan file.
+- Do not treat `viewports` as a capture command; it only lists presets.
+- Do not use `probe` as visual evidence; it only returns HTTP and page metadata.
+- Do not invent selectors. Snapshot or inspect the page first when using MCP.

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";
@@ -15,16 +16,18 @@ import { runEveryViewport } from "../src/every-viewport.js";
 import { runAudit } from "../src/plugin-audit.js";
 import { captureDomSnapshot } from "../src/dom-snapshot.js";
 import { listViewports } from "../src/viewport.js";
-import { parseFlags, asNum, readArg, makeOut, pickOutPath, __PURSR_GET } from "../src/util.js";
+import { asNum, readArg, makeOut, __PURSR_GET } from "../src/util.js";
+import { filePathArg, parseCommandArgs } from "../src/cli-args.js";
 import { writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { dirname } from "node:path";
+import { dirname, join } from "node:path";
 import { readFileSync as _readFileSync } from "node:fs";
 const readFile = _readFileSync;
 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
@@ -42,19 +45,24 @@ function die(msg, code = 2) {
   process.exit(code);
 }
 
-const argv = process.argv;
-const [, , cmd, a, b, c, d] = argv;
-const url = __PURSR_GET("PURSR_URL") || a;
-// Top-level --plan / --out parsing for subcommands that need it before dispatch
-function _topOpts() {
-  const o = {};
-  for (let i = 2; i < argv.length; i++) {
-    if (argv[i] === "--plan" && i + 1 < argv.length) o.plan = argv[++i];
-    if (argv[i] === "--out" && i + 1 < argv.length) o.out = argv[++i];
-  }
-  return o;
-}
-const opts = _topOpts();
+const argv = process.argv;
+const [, , cmd] = argv;
+const { flags: cliFlags, positionals } = parseCommandArgs(argv.slice(3));
+const [a, b, c, d] = positionals;
+const url = __PURSR_GET("PURSR_URL") || a;
+const opts = { plan: cliFlags.plan, out: cliFlags.out };
+
+function outputPath(positional, filename) {
+  if (cliFlags.out) return String(cliFlags.out);
+  if (positional) return positional;
+  if (cliFlags["out-dir"]) return join(String(cliFlags["out-dir"]), filename);
+  return makeOut(filename);
+}
+
+function dataArg(value) {
+  if (value && !value.startsWith("@") && existsSync(value)) return readFile(value, "utf8").replace(/\r?\n$/, "");
+  return readArg(value);
+}
 
 // Plugin loading: scan for --plugin <path> and built-in plugins/
 const pluginPaths = [];
@@ -62,48 +70,83 @@ for (let i = 0; i < argv.length; i++) if (argv[i] === "--plugin" && i + 1 < argv
 await loadPlugins(pluginPaths);
 
 (async () => {
-  try {
-    switch (cmd) {
+  try {
+    if (cliFlags.help) { console.log(JSON.stringify({ usage: USAGE }, null, 2)); return; }
+    switch (cmd) {
       case undefined: case "help": case "--help": case "-h": { console.log(JSON.stringify({ usage: USAGE }, null, 2)); break; }
       case "version": case "--version": case "-v": {
         console.log(JSON.stringify({ name: "pursr", version: VERSION, plugins: listPlugins() }, null, 2));
         break;
       }
       case "probe": { if (!url) die("missing url"); const r = await runProbe(url); console.log(JSON.stringify(r, null, 2)); break; }
-      case "shot": { if (!url) die("missing url"); const out = b || makeOut("shot.png"); const r = await runShot(url, out, { fullPage: false }); console.log(JSON.stringify(r, null, 2)); break; }
-      case "full": { if (!url) die("missing url"); const out = b || makeOut("full.png"); const r = await runShot(url, out, { fullPage: true }); console.log(JSON.stringify(r, null, 2)); break; }
-      case "eval": { if (!url) die("missing url"); const js = readArg(b); if (!js) die("eval: missing <js> (or @file)"); const out = c || makeOut("eval.png"); const r = await runEval(url, js, out); console.log(JSON.stringify(r, null, 2)); break; }
-      case "click": { if (!url) die("missing url"); const sel = b; if (!sel) die("click: missing <selector>"); const out = c || makeOut(`click-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runClick(url, sel, out); console.log(JSON.stringify(r, null, 2)); break; }
-      case "type": { if (!url) die("missing url"); const sel = b; const text = readArg(c); if (!sel || text === undefined) die("type: missing <selector> or <text> (text can be @file)"); const out = d || makeOut(`type-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runType(url, sel, text, out); console.log(JSON.stringify(r, null, 2)); break; }
-      case "wait": { if (!url) die("missing url"); const sel = b; if (!sel) die("wait: missing <selector>"); const t = c !== undefined ? asNum(c, 30000) : 30000; const r = await runWait(url, sel, t); console.log(JSON.stringify(r, null, 2)); break; }
+      case "shot": { if (!url) die("missing url"); const out = outputPath(b, "shot.png"); const r = await runShot(url, out, { ...cliFlags, fullPage: false }); console.log(JSON.stringify(r, null, 2)); break; }
+      case "full": { if (!url) die("missing url"); const out = outputPath(b, "full.png"); const r = await runShot(url, out, { ...cliFlags, fullPage: true }); console.log(JSON.stringify(r, null, 2)); break; }
+      case "eval": { if (!url) die("missing url"); const js = dataArg(b); if (!js) die("eval: missing <js> (or @file)"); const out = outputPath(c, "eval.png"); const r = await runEval(url, js, out, cliFlags); console.log(JSON.stringify(r, null, 2)); break; }
+      case "click": { if (!url) die("missing url"); const sel = b; if (!sel) die("click: missing <selector>"); const out = outputPath(c, `click-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runClick(url, sel, out, cliFlags); console.log(JSON.stringify(r, null, 2)); break; }
+      case "type": { if (!url) die("missing url"); const sel = b; const text = dataArg(c); if (!sel || text === undefined) die("type: missing <selector> or <text> (text can be @file)"); const out = outputPath(d, `type-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`); const r = await runType(url, sel, text, out, cliFlags); console.log(JSON.stringify(r, null, 2)); break; }
+      case "wait": { if (!url) die("missing url"); const sel = b; if (!sel) die("wait: missing <selector>"); const t = c !== undefined ? asNum(c, 30000) : 30000; const r = await runWait(url, sel, t, cliFlags); console.log(JSON.stringify(r, null, 2)); break; }
       case "diff": {
         if (!url) die("missing url"); const ref = b; if (!ref) die("diff: missing <ref.png>");
-        const out = c || makeOut("diff.png"); const threshold = d !== undefined ? Number(d) : 0.1;
-        const flags = parseFlags(argv.slice(5));
+        const out = outputPath(c, "diff.png"); const threshold = cliFlags.threshold !== undefined ? Number(cliFlags.threshold) : d !== undefined ? Number(d) : 0.1;
+        const flags = { ...cliFlags };
         // --ai / --ai-model / --ai-base-url / --ai-api-key
         const useAi = argv.includes("--ai");
-        const aiModel = (() => { const i = argv.indexOf("--ai-model"); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined; })();
-        const aiBaseUrl = (() => { const i = argv.indexOf("--ai-base-url"); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined; })();
-        const aiApiKey = (() => { const i = argv.indexOf("--ai-api-key"); return i >= 0 && i + 1 < argv.length ? argv[i + 1] : undefined; })();
+        const aiModel = cliFlags["ai-model"];
+        const aiBaseUrl = cliFlags["ai-base-url"];
+        const aiApiKey = cliFlags["ai-api-key"];
         const r = useAi
           ? await runDiffWithAi(url, ref, out, threshold, flags, { model: aiModel, baseUrl: aiBaseUrl, apiKey: aiApiKey })
           : 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 = dataArg(b); if (!actions) die("seq: missing <actions.json> (or @file)"); const out = outputPath(c, "seq.png"); const r = await runSeq(url, actions, out, cliFlags); console.log(JSON.stringify(r, null, 2)); break; }
+      case "operator": {
+        if (!url) die("operator: missing <url>");
+        const actions = dataArg(b); if (!actions) die("operator: missing <actions.json> (or @file)");
+        const flags = { ...cliFlags };
+        const out = outputPath(null, "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");
-        const out = (b && !b.startsWith("--")) ? b : pickOutPath(argv.slice(5)) || makeOut("shoot.png");
-        const r = await runShootWithSidecar({ url, out, flags: parseFlags(argv.slice(5)) });
+        const out = outputPath(b, "shoot.png");
+        const r = await runShootWithSidecar({ url, out, flags: { ...cliFlags } });
         console.log(JSON.stringify(r, null, 2));
         break;
       }
       case "layer": {
         if (!url) die("missing url");
         const layerName = b; if (!layerName) die("layer: missing <name>");
-        const out = (c && !c.startsWith("--")) ? c : pickOutPath(argv.slice(6)) || makeOut(`layer-${layerName}.png`);
-        const flags = parseFlags(argv.slice(7)); flags.layer = layerName;
+        const out = outputPath(c, `layer-${layerName}.png`);
+        const flags = { ...cliFlags, layer: layerName };
         const r = await runShootWithSidecar({ url, out, flags });
         console.log(JSON.stringify(r, null, 2));
         break;
@@ -112,71 +155,70 @@ await loadPlugins(pluginPaths);
         if (!url) die("missing url");
         const count = asNum(b, 8);
         const stepMs = asNum(c, 250);
-        const outDir = (d && !d.startsWith("--")) ? d : makeOut(`frames-${count}x${stepMs}ms`);
-        const r = await runFrames({ url, count, intervalMs: stepMs, outDir, flags: parseFlags(argv.slice(7)) });
+        const outDir = cliFlags["out-dir"] || cliFlags.out || d || makeOut(`frames-${count}x${stepMs}ms`);
+        const r = await runFrames({ url, count, intervalMs: stepMs, outDir, flags: { ...cliFlags } });
         console.log(JSON.stringify(r, null, 2));
         break;
       }
       case "hover": {
         if (!url) die("missing url");
         const sel = b; if (!sel) die("hover: missing <selector>");
-        const out = (c && !c.startsWith("--")) ? c : pickOutPath(argv.slice(6)) || makeOut(`hover-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`);
-        const r = await runHover({ url, selector: sel, out, flags: parseFlags(argv.slice(6)) });
+        const out = outputPath(c, `hover-${(sel||"").replace(/[^a-z0-9]+/gi, "_").slice(0, 32)}.png`);
+        const r = await runHover({ url, selector: sel, out, flags: { ...cliFlags } });
         console.log(JSON.stringify(r, null, 2));
         break;
       }
       case "sweep": {
-        const planPath = readArg(a);
-        if (!planPath) die("sweep: missing <plan.json> (or @file)");
-        const outDirArg = (b && !b.startsWith("--")) ? b : undefined;
+        const planPath = filePathArg(a);
+        if (!planPath) die("sweep: missing <plan.json>");
+        if (/^https?:\/\//i.test(planPath)) die("sweep: expected a local JSON plan path, not a URL");
+        const outDirArg = cliFlags["out-dir"] || cliFlags.out || b;
         const r = await runSweep(planPath, outDirArg);
         console.log(JSON.stringify(r, null, 2));
         break;
       }
       case "report": {
         // pursr report --sweep <sweep.json> [--out report.pdf] [--title "..."]
-        const sweepIdx = argv.indexOf("--sweep");
-        const sweepPath = sweepIdx >= 0 && sweepIdx + 1 < argv.length ? argv[sweepIdx + 1] : a;
+        const sweepPath = cliFlags.sweep || a;
         if (!sweepPath) die("report: missing --sweep <sweep.json>");
         if (!existsSync(sweepPath)) die("report: sweep not found: " + sweepPath);
-        const outIdx = argv.indexOf("--out");
-        const outPath = outIdx >= 0 && outIdx + 1 < argv.length ? argv[outIdx + 1] : (opts.out || makeOut("report.pdf").replace(/pursr-[^-]+-shot.png$/, "report.pdf"));
+        const outPath = cliFlags.out || makeOut("report.pdf").replace(/pursr-[^-]+-shot.png$/, "report.pdf");
         if (outPath && outPath !== "-") mkdirSync(dirname(outPath), { recursive: true });
-        const titleIdx = argv.indexOf("--title");
-        const title = titleIdx >= 0 && titleIdx + 1 < argv.length ? argv[titleIdx + 1] : undefined;
-        const noEmbed = argv.includes("--no-embed");
+        const title = cliFlags.title;
+        const noEmbed = !!cliFlags["no-embed"];
         const summary = JSON.parse(readFile(sweepPath, "utf8"));
         const { renderSweepPdf } = await import("../src/report.js");
         const buf = await renderSweepPdf(summary, { out: outPath === "-" ? undefined : outPath, title, embedImages: !noEmbed });
         console.log(JSON.stringify({ ok: true, sweep: sweepPath, out: outPath, bytes: buf.length }, null, 2));
         break;
       }
-      case "every-viewport": {
-        if (!url) die("missing url");
-        const outDir = (b && !b.startsWith("--")) ? b : undefined;
-        const viewports = c?.startsWith("--") ? undefined : c?.split(",");
+      case "every-viewport": {
+        if (!url) die("missing url");
+        const outDir = cliFlags["out-dir"] || cliFlags.out || b;
+        const viewports = c?.split(",");
         const r = await runEveryViewport({ url, outDir, viewports });
         console.log(JSON.stringify(r, null, 2));
         break;
       }
-      case "audit": {
-        if (!url) die("missing url");
-        const tags = (b && !b.startsWith("--")) ? b : undefined;
-        const outDir = (c && !c.startsWith("--")) ? c : undefined;
+      case "audit": {
+        if (!url) die("missing url");
+        const tags = cliFlags.tags || b;
+        const outDir = cliFlags["out-dir"] || cliFlags.out || c;
         const r = await runAudit({ url, tags: tags?.split(",").map(t => t.trim()), outDir });
         console.log(JSON.stringify(r, null, 2));
         break;
       }
-      case "dom-snapshot": case "dom": {
-        if (!url) die("missing url");
-        const out = (b && !b.startsWith("--")) ? b : undefined;
+      case "dom-snapshot": case "dom": {
+        if (!url) die("missing url");
+        const out = cliFlags.out || b;
         const r = await captureDomSnapshot({ url, out });
         console.log(JSON.stringify({ url: r.url, title: r.title, elements: r.selectorMap?.length, domSize: r.dom?.length, out: r.url?.replace(/[^/]+$/, "") + "dom.json" }, null, 2));
         break;
       }
-      case "validate": {
-        const planPath = readArg(a);
-        if (!planPath) die("validate: missing <plan.json> (or @file)");
+      case "validate": {
+        const planPath = filePathArg(a);
+        if (!planPath) die("validate: missing <plan.json>");
+        if (/^https?:\/\//i.test(planPath)) die("validate: expected a local JSON plan path, not a URL");
         let plan;
         try { plan = JSON.parse(readFile(planPath, "utf8")); }
         catch (e) { die("validate: " + e.message); }
@@ -201,7 +243,7 @@ await loadPlugins(pluginPaths);
         } else if (sub === "save") {
           if (!b || !c || !d) die("baseline save: <project> <png> <step> [--id <id>] [--url <u>] [--meta-json <file>]");
           const project = b, png = c, step = d;
-          const flags = parseFlags(argv.slice(7));
+          const flags = { ...cliFlags };
           let meta = null;
           if (flags["meta-json"]) meta = JSON.parse(readFile(flags["meta-json"], "utf8"));
           else if (flags.url) meta = { url: flags.url };
@@ -217,14 +259,14 @@ await loadPlugins(pluginPaths);
         } else if (sub === "approve") {
           if (!b || !c || !d) die("baseline approve: <project> <png> <step> [--id <id>] [--url <u>]");
           const project = b, png = c, step = d;
-          const flags = parseFlags(argv.slice(7));
+          const flags = { ...cliFlags };
           const id = flags.id || diffKey({ url: flags.url || "", flags: {} });
           const result = approveBaseline({ project, id, step, fromPng: png });
           console.log(JSON.stringify({ approved: true, ...result }, null, 2));
         } else if (sub === "show") {
           if (!b || !c) die("baseline show: <project> <step> [--id <id>] [--url <u>]");
           const project = b, step = c;
-          const flags = parseFlags(argv.slice(5));
+          const flags = { ...cliFlags };
           const id = flags.id || diffKey({ url: flags.url || "", flags: {} });
           const r = loadBaseline({ project, id, step });
           console.log(JSON.stringify(r, null, 2));
@@ -246,14 +288,14 @@ await loadPlugins(pluginPaths);
                 console.log(JSON.stringify(listAuthStates(project), null, 2));
               } else if (sub === "save") {
                 if (!b || !c) die("auth save: <project> <name> --from <state.json>");
-                const fromFile = argv[argv.indexOf("--from") + 1];
+                const fromFile = cliFlags.from;
                 if (!fromFile) die("auth save: missing --from <state.json>");
                 const state = JSON.parse(readFile(fromFile, "utf8"));
                 const r = saveAuthState({ project: b, name: c, state });
                 console.log(JSON.stringify({ saved: true, ...r }, null, 2));
               } else if (sub === "load") {
                 if (!b || !c) die("auth load: <project> <name> --out <state.json>");
-                const outFile = argv[argv.indexOf("--out") + 1];
+                const outFile = cliFlags.out;
                 if (!outFile) die("auth load: missing --out <state.json>");
                 const state = loadAuthState({ project: b, name: c });
                 if (!state) { console.error("not found"); process.exit(2); }
@@ -276,9 +318,9 @@ await loadPlugins(pluginPaths);
                 die("watch: missing <url> (or use --plan <plan.json>)");
               }
               const { startWatch } = await import("../src/watch.js");
-              const out = (b && !b.startsWith("--")) ? b : (opts.out || makeOut("watch.png"));
+              const out = opts.out || b || makeOut("watch.png");
               if (out && out !== "--plan") mkdirSync(dirname(out), { recursive: true });
-              const flags = parseFlags(argv.slice(3));
+              const flags = { ...cliFlags };
               const onGlobs = [];
               for (let i = 0; i < argv.length; i++) {
                 if (argv[i] === "--on" && i + 1 < argv.length) onGlobs.push(argv[++i]);
@@ -305,9 +347,9 @@ await loadPlugins(pluginPaths);
               // pursr snap <url> <selector> [--out <dir>] [--name <slug>] [--max N] [--baseline <project>]
               if (!url) die("snap: missing <url>");
               const sel = b; if (!sel) die("snap: missing <selector>");
-              const flags = parseFlags(argv.slice(4));
+              const flags = { ...cliFlags };
               const { runSnap, approveSnapsAsBaselines } = await import("../src/snap.js");
-              const outDir = flags.out || makeOut("snaps").replace(/pursr-[^-]+-snap\.png$/, "snaps");
+              const outDir = flags["out-dir"] || flags.out || makeOut("snaps").replace(/pursr-[^-]+-snap\.png$/, "snaps");
               const snap = await runSnap({ url, selector: sel, outDir, name: flags.name, max: flags.max, flags });
               console.log(JSON.stringify({
                 url: snap.url,
@@ -327,7 +369,7 @@ await loadPlugins(pluginPaths);
             case "check": {
               // pursr check <url> [--preset <name>] [--update] [--json] [--threshold 0.1] [--out <diff.png>]
               if (!url) die("check: missing <url>");
-              const flags = parseFlags(argv.slice(4));
+              const flags = { ...cliFlags };
               const update = !!flags.update;
               const threshold = flags.threshold !== undefined ? Number(flags.threshold) : 0.1;
               const { runCheck } = await import("../src/check.js");
@@ -342,4 +384,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.1",
   "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": [
@@ -48,6 +49,7 @@
     "plugins",
     "plans",
     "assets",
+    "SKILL.md",
     "README.md",
     "LICENSE"
   ],

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/cli-args.js

@@ -0,0 +1,33 @@
+// Order-independent CLI argument parsing for pursr subcommands.
+
+const DEFAULT_BOOLEAN_FLAGS = new Set([
+  "ai", "full", "grid", "help", "json", "no-animation", "no-embed",
+  "no-hud", "no-visual", "update", "visible",
+]);
+
+export function parseCommandArgs(args = [], { booleanFlags = DEFAULT_BOOLEAN_FLAGS } = {}) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < args.length; i++) {
+    const token = args[i];
+    if (!token?.startsWith("--")) {
+      positionals.push(token);
+      continue;
+    }
+
+    const eq = token.indexOf("=");
+    const key = token.slice(2, eq >= 0 ? eq : undefined);
+    let value;
+    if (eq >= 0) value = token.slice(eq + 1);
+    else if (booleanFlags.has(key)) value = true;
+    else if (i + 1 < args.length && !args[i + 1].startsWith("--")) value = args[++i];
+    else value = true;
+    flags[key] = value;
+  }
+  return { flags, positionals };
+}
+
+export function filePathArg(value) {
+  if (typeof value !== "string") return value;
+  return value.startsWith("@") ? value.slice(1) : value;
+}

package/src/diff.js

@@ -1,6 +1,6 @@
 // Pixelmatch diff against a reference PNG.
 
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { launch, newPage } from "./runway.js";
 import { resolveViewport } from "./viewport.js";
@@ -24,7 +24,8 @@ export async function runDiff(url, refPath, out, threshold, flags = {}, browser)
   requireArg("url", url, "string");
   requireArg("refPath", refPath, "string");
   const t = threshold !== undefined ? Number(threshold) : DIFF_DEFAULT_THRESHOLD;
-  if (!existsSync(refPath)) return { url, refPath, error: "reference file not found" };
+  if (!existsSync(refPath)) return { url, refPath, error: "reference file not found" };
+  if (out) mkdirSync(dirname(out), { recursive: true });
   const PNG = await loadPngjs();
   const pixelmatch = await loadPixelmatch();
   const ownBrowser = !browser;

package/src/eval.js

@@ -1,18 +1,24 @@
 // Evaluate a JS string in the page, optionally screenshot after.
 
 import { launch, newPage } from "./runway.js";
-import { DEFAULT_VIEWPORT } from "./viewport.js";
+import { resolveViewport } from "./viewport.js";
 import { gotoOrThrow } from "./overlays.js";
-import { requireArg } from "./util.js";
+import { requireArg } from "./util.js";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 
-export async function runEval(url, js, out) {
-  requireArg("url", url, "string");
-  const browser = await launch();
-  try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
+export async function runEval(url, js, out, flags = {}) {
+  requireArg("url", url, "string");
+  const viewport = resolveViewport(flags);
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, viewport);
     const r = await gotoOrThrow(page, url);
     const result = await page.evaluate(js);
-    if (out) await page.screenshot({ path: out, fullPage: false });
-    return { ...r, url, out, result };
+    if (out) {
+      mkdirSync(dirname(out), { recursive: true });
+      await page.screenshot({ path: out, fullPage: false });
+    }
+    return { ...r, url, out, viewport, result };
   } finally { try { await browser.close(); } catch {} }
-}
+}

package/src/hover.js

@@ -4,7 +4,9 @@ import { launch, newPage } from "./runway.js";
 import { resolveViewport } from "./viewport.js";
 import { gotoOrThrow, settle, CLICK_TIMEOUT_MS } from "./overlays.js";
 import { resolveLocator } from "./selector.js";
-import { asNum, asBool, nowIso, writeSidecar, requireArg } from "./util.js";
+import { asNum, asBool, nowIso, writeSidecar, requireArg } from "./util.js";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 
 export async function runHover({ url, selector, out, flags = {} }) {
   requireArg("url", url, "string");
@@ -18,9 +20,12 @@ export async function runHover({ url, selector, out, flags = {} }) {
     await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
     await loc.first().hover({ timeout: CLICK_TIMEOUT_MS });
     await page.waitForTimeout(asNum(flags["hover-ms"], 250));
-    if (out) await page.screenshot({ path: out, fullPage: asBool(flags.full, false) });
+    if (out) {
+      mkdirSync(dirname(out), { recursive: true });
+      await page.screenshot({ path: out, fullPage: asBool(flags.full, false) });
+    }
     const meta = { ...r, url, out, selector, viewport, ts: nowIso() };
     if (out) await writeSidecar(meta);
     return meta;
   } finally { try { await browser.close(); } catch {} }
-}
+}

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/interact.js

@@ -1,50 +1,56 @@
 // click, type, wait, seq — interaction primitives.
 
 import { launch, newPage } from "./runway.js";
-import { DEFAULT_VIEWPORT } from "./viewport.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 { requireArg } from "./util.js";
+import { requireArg } from "./util.js";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+function ensureScreenshotDir(out) {
+  if (out) mkdirSync(dirname(out), { recursive: true });
+}
 
-export async function runClick(url, selector, out) {
+export async function runClick(url, selector, out, flags = {}) {
   requireArg("url", url, "string");
   requireArg("selector", selector, "string");
   const browser = await launch();
   try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const page = await newPage(browser, resolveViewport(flags));
     const r = await gotoOrThrow(page, url); await settle(page);
     const loc = await resolveLocator(page, selector);
     await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
     await loc.first().click({ timeout: CLICK_TIMEOUT_MS });
     await settle(page);
-    if (out) await page.screenshot({ path: out, fullPage: false });
+    if (out) { ensureScreenshotDir(out); await page.screenshot({ path: out, fullPage: false }); }
     return { ...r, url, out, selector, clicked: true };
   } finally { try { await browser.close(); } catch {} }
 }
 
-export async function runType(url, selector, text, out) {
+export async function runType(url, selector, text, out, flags = {}) {
   requireArg("url", url, "string");
   requireArg("selector", selector, "string");
   const browser = await launch();
   try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const page = await newPage(browser, resolveViewport(flags));
     const r = await gotoOrThrow(page, url); await settle(page);
     const loc = await resolveLocator(page, selector);
     await loc.first().waitFor({ state: "visible", timeout: CLICK_TIMEOUT_MS });
     await loc.first().click({ timeout: CLICK_TIMEOUT_MS });
     await page.keyboard.type(String(text ?? ""), { delay: 10 });
     await settle(page);
-    if (out) await page.screenshot({ path: out, fullPage: false });
+    if (out) { ensureScreenshotDir(out); await page.screenshot({ path: out, fullPage: false }); }
     return { ...r, url, out, selector, text, typed: true };
   } finally { try { await browser.close(); } catch {} }
 }
 
-export async function runWait(url, selector, timeoutMs) {
+export async function runWait(url, selector, timeoutMs, flags = {}) {
   requireArg("url", url, "string");
   requireArg("selector", selector, "string");
   const browser = await launch();
   try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const page = await newPage(browser, resolveViewport(flags));
     const r = await gotoOrThrow(page, url);
     const loc = await resolveLocator(page, selector);
     const t = timeoutMs || WAIT_DEFAULT_TIMEOUT_MS;
@@ -57,7 +63,7 @@ export async function runWait(url, selector, timeoutMs) {
   } finally { try { await browser.close(); } catch {} }
 }
 
-export async function runSeq(url, actionsJson, out) {
+export async function runSeq(url, actionsJson, out, flags = {}) {
   requireArg("url", url, "string");
   let actions;
   try { actions = JSON.parse(actionsJson); }
@@ -66,7 +72,7 @@ export async function runSeq(url, actionsJson, out) {
   if (!actions.length) throw new Error("actions array is empty");
   const browser = await launch();
   try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    const page = await newPage(browser, resolveViewport(flags));
     const r = await gotoOrThrow(page, url); await settle(page);
     const trace = [];
     let failed = false;
@@ -132,7 +138,7 @@ export async function runSeq(url, actionsJson, out) {
       trace.push(step);
       if (failed) break;
     }
-    if (out) await page.screenshot({ path: out, fullPage: false });
+    if (out) { ensureScreenshotDir(out); await page.screenshot({ path: out, fullPage: false }); }
     return { ...r, url, out, steps: trace, failed };
   } finally { try { await browser.close(); } catch {} }
-}
+}

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() {

package/src/shoot.js

@@ -10,10 +10,13 @@ import {
 import { asNum, asBool, nowIso, writeSidecar, requireArg } from "./util.js";
 import { runBeforeShoot, runAfterShoot } from "./plugin.js";
 import { startHarCapture, stopHarCapture, writeHar } from "./har.js";
-import { loadAuthState } from "./auth.js";
+import { loadAuthState } from "./auth.js";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 
-export async function runShoot({ url, out, flags = {}, prepare, browser: extBrowser }) {
-  requireArg("url", url, "string");
+export async function runShoot({ url, out, flags = {}, prepare, browser: extBrowser }) {
+  requireArg("url", url, "string");
+  if (out) mkdirSync(dirname(out), { recursive: true });
   const viewport = resolveViewport(flags);
   const ownBrowser = !extBrowser;
   const browser = extBrowser || await launch();
@@ -71,4 +74,4 @@ export async function runShootWithSidecar(args) {
   const meta = await runShoot(args);
   await writeSidecar(meta);
   return meta;
-}
+}

package/src/shot.js

@@ -1,18 +1,22 @@
 // Simple screenshot (no flags / overlays).
 
 import { launch, newPage } from "./runway.js";
-import { DEFAULT_VIEWPORT } from "./viewport.js";
+import { resolveViewport } from "./viewport.js";
 import { gotoOrThrow, settle } from "./overlays.js";
-import { requireArg } from "./util.js";
+import { requireArg } from "./util.js";
+import { mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 
-export async function runShot(url, out, opts = {}) {
-  requireArg("url", url, "string");
-  const browser = await launch();
-  try {
-    const page = await newPage(browser, DEFAULT_VIEWPORT);
+export async function runShot(url, out, opts = {}) {
+  requireArg("url", url, "string");
+  const viewport = resolveViewport(opts);
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, viewport);
     const r = await gotoOrThrow(page, url);
     await settle(page);
-    await page.screenshot({ path: out, fullPage: !!opts.fullPage });
-    return { ...r, url, out, fullPage: !!opts.fullPage };
+    if (out) mkdirSync(dirname(out), { recursive: true });
+    await page.screenshot({ path: out, fullPage: !!opts.fullPage });
+    return { ...r, url, out, viewport, fullPage: !!opts.fullPage };
   } finally { try { await browser.close(); } catch {} }
-}
+}