pursr 0.7.3 → 0.8.1

package/README.md

@@ -33,8 +33,8 @@
 Most teams need **five separate tools** to do visual QA: a screenshot CLI, a regression diff runner, an accessibility auditor, a way to share captures with an AI assistant, and a way to **turn all of that into a PDF report** for stakeholders. **pursr is all five** - built as a single Node.js package with:
 
 - **A unified CLI** (`pursr`) for every capture, diff, sweep, and audit.
-- **An MCP stdio server** (`pursr-mcp`) so Claude Code, Cursor, and Continue can take screenshots, run sweeps, and inspect prior captures as MCP resources.
-- **A library** with 34 named exports and 18 subpath modules, so you can embed it in your own tooling.
+- **An agent-grade MCP stdio server** (`pursr-mcp`) built on the official Model Context Protocol SDK, with persistent tabs, direct image responses, rendered-state inspection, actions, diagnostics, screenshots, sweeps, and resources.
+- **A library API** with 23 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.
@@ -96,7 +96,7 @@ pursr sweep ./plan.json   # see plans/ for an example
 | HAR capture | HAR 1.2 spec, written next to your shot | `--har ./req.har.json` |
 | Auth state | Playwright storageState, reuse logged-in sessions | `--auth-state admin` |
 | Plugins | custom viewports, sweep ops, before/after hooks | `pursr-plugin-*` |
-| MCP server | 7 tools + resources/list & resources/read for Claude/Cursor | `npx pursr-mcp` |
+| MCP server | Official MCP SDK transport, 16 tools, and resources for Claude/Cursor/Codex | `npx pursr-mcp` |
 | PDF report | render sweep.json to a styled, embedded-PNG A4 PDF | `pursr report --sweep ./sweep.json` |
 | AI diff summary | vision LLM describes the diff in plain language | `pursr diff ... --ai` |
 
@@ -184,17 +184,51 @@ npx pursr-mcp
 npx pursr-mcp --verbose
 ```
 
-### Exposed Tools
-
-| Tool | Description |
-| --- | --- |
-| `pursr_shoot` | Rich screenshot capture (viewport, grid, layer, cursor, camera, animation freeze, HAR) |
+### Exposed Tools
+
+| Tool | Description |
+| --- | --- |
+| `pursr_session_open` | Open a persistent browser tab for iterative agent work |
+| `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_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 |
+| `pursr_session_close` | Close the tab and release its browser process |
+| `pursr_shoot` | Rich screenshot capture (viewport, grid, layer, cursor, camera, animation freeze, HAR) |
 | `pursr_diff` | Pixel-diff a URL against a reference PNG |
 | `pursr_sweep` | Execute a batch sweep plan |
 | `pursr_frames` | Capture an N-frame animation timeline |
 | `pursr_probe` | Health-check a URL |
 | `pursr_audit` | axe-core WCAG audit + highlighted screenshot |
-| `pursr_dom_snapshot` | Full DOM + selector map snapshot |
+| `pursr_dom_snapshot` | Full DOM + selector map snapshot |
+| `pursr_check` | CI visual regression check against a stable baseline |
+
+### Agent workflow
+
+Use persistent sessions for the same inspect-act-verify loop as an interactive browser agent:
+
+1. Call `pursr_session_open` once with a stable `sessionId`.
+2. Call `pursr_snapshot` to understand the rendered page before acting.
+3. Use `pursr_act` for a small, ordered interaction sequence.
+4. Call `pursr_screenshot` when visual judgment matters; the model receives the PNG directly.
+5. Use `pursr_inspect` for layout, clipping, typography, or stacking problems.
+6. Read `pursr_diagnostics`, then reload and verify after source changes.
+7. Call `pursr_session_close` when the review is complete.
+
+Example action arguments:
+
+```json
+{
+  "sessionId": "farm",
+  "actions": [
+    { "type": "hover", "selector": "role=button|Build" },
+    { "type": "click", "selector": "text=Barn" },
+    { "type": "wait", "selector": "role=dialog" }
+  ]
+}
+```
 
 ### Exposed Resources
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pursr",
-  "version": "0.7.3",
+  "version": "0.8.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",
@@ -12,8 +12,8 @@
   "funding": "https://github.com/sponsors/0xheycat",
   "type": "module",
   "bin": {
-    "pursr": "./bin/pursr.mjs",
-    "pursr-mcp": "./bin/pursr-mcp.mjs"
+    "pursr": "bin/pursr.mjs",
+    "pursr-mcp": "bin/pursr-mcp.mjs"
   },
   "main": "./src/index.js",
   "exports": {
@@ -38,7 +38,8 @@
     "./watch": "./src/watch.js",
     "./snap": "./src/snap.js",
     "./report": "./src/report.js",
-    "./ai-diff": "./src/ai-diff.js"
+    "./ai-diff": "./src/ai-diff.js",
+    "./session": "./src/session.js"
   },
   "files": [
     "bin",
@@ -76,10 +77,12 @@
   ],
   "license": "MIT",
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "axe-core": "^4.12.1",
     "pdfkit": "^0.19.1",
     "pixelmatch": "^5.3.0",
-    "pngjs": "^7.0.0"
+    "pngjs": "^7.0.0",
+    "zod": "^4.4.3"
   },
   "peerDependencies": {
     "playwright-core": "*"

package/src/dom-snapshot.js

@@ -95,7 +95,7 @@ const SNAPSHOT_PAGE_SCRIPT = `(() => {
     const href = el.getAttribute('href');
     const src = el.getAttribute('src');
 
-    const entry = {
+    const entry = {
       tag,
       id,
       css: getCSSSelector(el),
@@ -108,8 +108,29 @@ const SNAPSHOT_PAGE_SCRIPT = `(() => {
       href: href || null,
       src: src || null,
       rect: visible ? { x: round(rect.x), y: round(rect.y), w: round(rect.width), h: round(rect.height) } : null,
-      visible,
-    };
+      visible,
+    };
+
+    if (visible) {
+      const computed = getComputedStyle(el);
+      entry.computedStyle = {
+        display: computed.display,
+        position: computed.position,
+        zIndex: computed.zIndex,
+        overflowX: computed.overflowX,
+        overflowY: computed.overflowY,
+        opacity: computed.opacity,
+        visibility: computed.visibility,
+        color: computed.color,
+        backgroundColor: computed.backgroundColor,
+        fontFamily: computed.fontFamily,
+        fontSize: computed.fontSize,
+        fontWeight: computed.fontWeight,
+        lineHeight: computed.lineHeight,
+        transform: computed.transform,
+        boxShadow: computed.boxShadow,
+      };
+    }
 
     // get computed role from accessibility tree
     try { entry.ariaRole = el.computedRole || el.getAttribute('role') || null; } catch {}

package/src/index.js

@@ -43,7 +43,8 @@ import { startWatch, matchGlob, shouldFire } from "./watch.js";
 import { runSnap, approveSnapsAsBaselines } from "./snap.js";
 import { runCheck } from "./check.js";
 import { renderSweepPdf } from "./report.js";
-import { aiDiffSummary, aiDiffSidecar } from "./ai-diff.js";
+import { aiDiffSummary, aiDiffSidecar } from "./ai-diff.js";
+import { BrowserSessionManager } from "./session.js";
 
 
 // Derive VERSION from package.json to prevent drift
@@ -85,8 +86,9 @@ export {
   // v6: PDF report, AI diff summary
   runDiffWithAi,
   renderSweepPdf,
-  aiDiffSummary, aiDiffSidecar,
-  VERSION,
+  aiDiffSummary, aiDiffSidecar,
+  BrowserSessionManager,
+  VERSION,
 };
 
 export default {
@@ -106,6 +108,7 @@ export default {
   validateSweepPlan, registerSweepOp,
   listResources, readResource, recordResource,
   // v6: PDF report, AI diff summary
-  runDiffWithAi, renderSweepPdf, aiDiffSummary, aiDiffSidecar,
-  VERSION,
-};
+  runDiffWithAi, renderSweepPdf, aiDiffSummary, aiDiffSidecar,
+  BrowserSessionManager,
+  VERSION,
+};

package/src/mcp.js

@@ -1,8 +1,7 @@
 //  pursr — MCP stdio server (Model Context Protocol).
 //
-// Implements JSON-RPC 2.0 over stdio with Content-Length framing.
-// Exposes every pursr capability as an MCP tool for use by
-// Claude Code, Cursor, Continue, and any other MCP host.
+// Uses the official Model Context Protocol SDK over stdio and exposes every
+// pursr capability to Claude Code, Cursor, Codex, and other MCP hosts.
 //
 // Config via PURSR_MCP_CONFIG env or ~/./mcp-config.json:
 //   { "plugins": ["./my-plugin.js"], "defaultOutDir": "./mcp-output" }
@@ -23,13 +22,22 @@ import { runAudit } from "./plugin-audit.js";
 import { loadPlugins, listPlugins } from "./plugin.js";
 import { makeOut, nowIso } from "./util.js";
 import { listResources, readResource, recordResource } from "./mcp-resources.js";
-import { createRequire } from "node:module";
+import { createRequire } from "node:module";
+import { BrowserSessionManager } from "./session.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
 
 const __require = createRequire(import.meta.url);
 let _pkg = { version: "0.1.0" };
 try { _pkg = __require("../package.json"); } catch {}
 
-const MCP_VERSION = "0.1.0";
+const MCP_VERSION = _pkg.version || "0.1.0";
 
 // ─── Config ──────────────────────────────────────────────────────────────
 
@@ -59,138 +67,68 @@ class McpError extends Error {
 
 // ─── Server ──────────────────────────────────────────────────────────────
 
-class PursrMCPServer {
-  constructor(config = {}) {
-    this.config = config;
-    this._buffer = Buffer.alloc(0);
-    this._contentLength = -1;
-    this._initialized = false;
-    this._verbose = !!config.verbose;
-  }
+class PursrMCPServer {
+  constructor(config = {}) {
+    this.config = config;
+    this._verbose = !!config.verbose;
+    this.sessions = new BrowserSessionManager({ outputDir: config.defaultOutDir || process.cwd() });
+    this.sdk = new McpServer(
+      { name: "pursr", version: MCP_VERSION },
+      {
+        capabilities: { tools: {}, resources: {} },
+        instructions: "Use a persistent pursr session for iterative visual work: open, snapshot, act, screenshot, inspect, diagnose, then close.",
+      },
+    );
+    this.server = this.sdk.server;
+    this.transport = null;
+    this._registerSdkHandlers();
+  }
 
   log(...args) {
     if (this._verbose) console.error("[pursr-mcp]", ...args);
   }
 
-  async start() {
+  async start() {
     if (this.config.plugins?.length) {
       await loadPlugins(this.config.plugins);
     }
-    this.log("server started, plugins:", listPlugins());
-
-    process.stdin.on("data", (chunk) => {
-      this._buffer = Buffer.concat([this._buffer, chunk]);
-      this._processBuffer();
-    });
-    process.stdin.on("end", () => {
-      this.log("stdin closed");
-    });
-
-    process.on("uncaughtException", (err) => {
-      console.error("[pursr-mcp] uncaught:", err.message);
-    });
-  }
-
-  // ── Buffer framing ──────────────────────────────────────────────────
-
-  _processBuffer() {
-    while (true) {
-      if (this._contentLength < 0) {
-        const idx = this._buffer.indexOf(Buffer.from("\r\n\r\n"));
-        if (idx === -1) break;
-        const header = this._buffer.slice(0, idx).toString("utf8");
-        const m = header.match(/Content-Length:\s*(\d+)/i);
-        if (m) this._contentLength = parseInt(m[1], 10);
-        this._buffer = this._buffer.slice(idx + 4);
-      }
-      if (this._contentLength > 0 && this._buffer.length >= this._contentLength) {
-        const raw = this._buffer.slice(0, this._contentLength).toString("utf8");
-        this._buffer = this._buffer.slice(this._contentLength);
-        this._contentLength = -1;
-        try {
-          const msg = JSON.parse(raw);
-          this._handleMessage(msg);
-        } catch (e) {
-          console.error("[pursr-mcp] invalid JSON:", e.message);
-        }
-      } else break;
-    }
-  }
-
-  _send(msg) {
-    const json = JSON.stringify(msg);
-    const bytes = Buffer.from(json, "utf8");
-    const header = `Content-Length: ${bytes.length}\r\n\r\n`;
-    process.stdout.write(header);
-    process.stdout.write(bytes);
-  }
-
-  // ── JSON-RPC dispatcher ─────────────────────────────────────────────
-
-  async _handleMessage(msg) {
-    if (!msg || msg.jsonrpc !== "2.0" || !msg.method) {
-      console.error("[pursr-mcp] skipping non-JSON-RPC message");
-      return;
-    }
-    const { method, id } = msg;
-
-    // Notifications — no id → no response
-    if (method === "notifications/initialized" || method === "notifications/cancelled") {
-      if (method === "notifications/initialized") this._initialized = true;
-      return;
-    }
-    if (id === undefined || id === null) return; // unnamed notification
-
-    try {
-      switch (method) {
-        case "initialize":
-          this._initialized = true;
-          this._send({
-            jsonrpc: "2.0", id,
-            result: {
-              protocolVersion: msg.params?.protocolVersion || "2024-11-05",
-              capabilities: { tools: {} },
-              serverInfo: { name: "pursr", version: MCP_VERSION },
-            },
-          });
-          break;
-
-        case "tools/list":
-          this._send({ jsonrpc: "2.0", id, result: { tools: this._toolDefs() } });
-          break;
-
-        case "resources/list":
-          this._send({ jsonrpc: "2.0", id, result: { resources: listResources().map(this._toMcpResource, this) } });
-          break;
-
-        case "resources/read":
-          if (!msg.params?.uri) throw new McpError(-32602, "Missing uri");
-          const data = readResource(msg.params.uri);
-          if (!data) throw new McpError(-32602, "Resource not found: " + msg.params.uri);
-          this._send({ jsonrpc: "2.0", id, result: { contents: [data] } });
-          break;
-
-        case "tools/call":
-          if (!msg.params?.name) throw new McpError(-32602, "Missing tool name");
-          const result = await this._callTool(msg.params.name, msg.params.arguments || {});
-          this._send({ jsonrpc: "2.0", id, result: { content: result } });
-          break;
-
-        default:
-          this._send({
-            jsonrpc: "2.0", id,
-            error: { code: -32601, message: `Unknown method: ${method}` },
-          });
-      }
-    } catch (e) {
-      if (e instanceof McpError) {
-        this._send({ jsonrpc: "2.0", id, error: { code: e.code, message: e.message } });
-      } else {
-        console.error("[pursr-mcp] handler error:", e.stack || e.message);
-        this._send({ jsonrpc: "2.0", id, error: { code: -32603, message: e.message } });
-      }
-    }
-  }
+    this.transport = new StdioServerTransport();
+    this.transport.onclose = () => {
+      this.log("stdio transport closed");
+      this.sessions.closeAll().catch(() => {});
+    };
+    await this.sdk.connect(this.transport);
+    this.log("server started with official MCP SDK, plugins:", listPlugins());
+  }
+
+  async close() {
+    await this.sessions.closeAll();
+    await this.sdk.close();
+  }
+
+  _registerSdkHandlers() {
+    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: this._toolDefs() }));
+    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
+      try {
+        const content = await this._callTool(request.params.name, request.params.arguments || {});
+        return { content };
+      } catch (error) {
+        this.log("tool error:", error.stack || error.message);
+        return {
+          isError: true,
+          content: [{ type: "text", text: JSON.stringify({ error: error.message, code: error.code || -32603 }, null, 2) }],
+        };
+      }
+    });
+    this.server.setRequestHandler(ListResourcesRequestSchema, async () => ({
+      resources: listResources().map(this._toMcpResource, this),
+    }));
+    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const data = readResource(request.params.uri);
+      if (!data) throw new Error("Resource not found: " + request.params.uri);
+      return { contents: [data] };
+    });
+  }
 
   // ── Resource shape adapter ─────────────────────────────────────────
 
@@ -205,10 +143,88 @@ class PursrMCPServer {
 
   // ── Tool definitions ────────────────────────────────────────────────
 
-  _toolDefs() {
-    return [
-      {
-        name: "pursr_shoot",
+  _toolDefs() {
+    return [
+      {
+        name: "pursr_session_open",
+        description: "Open a persistent browser tab for iterative agent work. State, hover, scroll, dialogs, and navigation persist until closed.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            url: { type: "string", description: "Initial URL" },
+            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" },
+            storageState: { description: "Playwright storageState object or file path" },
+          },
+          required: ["url"],
+        },
+      },
+      {
+        name: "pursr_sessions",
+        description: "List active persistent browser sessions.",
+        inputSchema: { type: "object", properties: {} },
+      },
+      {
+        name: "pursr_snapshot",
+        description: "Read the current rendered state from a persistent session as concise visible nodes, geometry, semantics, and computed visual styles.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            sessionId: { type: "string" }, selector: { type: "string", description: "CSS root selector (default body)" },
+            maxNodes: { type: "number", description: "Maximum returned nodes, 1-1000" },
+            includeStyles: { type: "boolean", description: "Include compact computed styles (default true)" },
+          },
+          required: ["sessionId"],
+        },
+      },
+      {
+        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.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            sessionId: { type: "string" },
+            actions: { type: "array", minItems: 1, maxItems: 50, items: { type: "object" } },
+          },
+          required: ["sessionId", "actions"],
+        },
+      },
+      {
+        name: "pursr_screenshot",
+        description: "Capture the current persistent session and return the PNG directly to the model as image content.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            sessionId: { type: "string" }, out: { type: "string" }, full: { type: "boolean" },
+            selector: { type: "string", description: "Capture only the first matching element" },
+          },
+          required: ["sessionId"],
+        },
+      },
+      {
+        name: "pursr_inspect",
+        description: "Inspect one rendered element: HTML, exact geometry, computed style, and clipping/stacking ancestors.",
+        inputSchema: {
+          type: "object", properties: { sessionId: { type: "string" }, selector: { type: "string" } }, required: ["sessionId", "selector"],
+        },
+      },
+      {
+        name: "pursr_diagnostics",
+        description: "Read console messages, page errors, failed requests, and HTTP 4xx/5xx responses accumulated during a persistent session.",
+        inputSchema: {
+          type: "object", properties: { sessionId: { type: "string" }, clear: { type: "boolean" } }, required: ["sessionId"],
+        },
+      },
+      {
+        name: "pursr_session_close",
+        description: "Close a persistent browser session and release its browser process.",
+        inputSchema: {
+          type: "object", properties: { sessionId: { type: "string" } }, required: ["sessionId"],
+        },
+      },
+      {
+        name: "pursr_shoot",
         description: "Capture a screenshot of a URL with full feature control (viewport, grid, layer, cursor, camera, animation freeze). Returns PNG path and sidecar metadata.",
         inputSchema: {
           type: "object",
@@ -354,9 +370,17 @@ class PursrMCPServer {
 
   // ── Tool dispatcher ─────────────────────────────────────────────────
 
-  async _callTool(name, args) {
-    switch (name) {
-      case "pursr_shoot":        return await this._shoot(args);
+  async _callTool(name, args) {
+    switch (name) {
+      case "pursr_session_open":  return await this._sessionOpen(args);
+      case "pursr_sessions":      return this._text(this.sessions.list());
+      case "pursr_snapshot":      return await this._sessionSnapshot(args);
+      case "pursr_act":           return await this._sessionAct(args);
+      case "pursr_screenshot":    return await this._sessionScreenshot(args);
+      case "pursr_inspect":       return await this._sessionInspect(args);
+      case "pursr_diagnostics":   return this._sessionDiagnostics(args);
+      case "pursr_session_close": return await this._sessionClose(args);
+      case "pursr_shoot":        return await this._shoot(args);
       case "pursr_diff":         return await this._diff(args);
       case "pursr_sweep":        return await this._sweep(args);
       case "pursr_frames":       return await this._frames(args);
@@ -368,9 +392,61 @@ class PursrMCPServer {
     }
   }
 
-  // ── Tool implementations ────────────────────────────────────────────
-
-  async _shoot(args) {
+  // ── Tool implementations ────────────────────────────────────────────
+
+  _text(value) {
+    return [{ type: "text", text: JSON.stringify(value, null, 2) }];
+  }
+
+  _requireSessionId(args) {
+    if (!args.sessionId) throw new McpError(-32602, "Missing required: sessionId");
+    return args.sessionId;
+  }
+
+  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 result = await this.sessions.open({ sessionId: args.sessionId, url: args.url, flags, storageState: args.storageState });
+    return this._text(result);
+  }
+
+  async _sessionSnapshot(args) {
+    const result = await this.sessions.snapshot(this._requireSessionId(args), args);
+    return this._text(result);
+  }
+
+  async _sessionAct(args) {
+    const result = await this.sessions.act(this._requireSessionId(args), args.actions);
+    return this._text(result);
+  }
+
+  async _sessionScreenshot(args) {
+    const result = await this.sessions.screenshot(this._requireSessionId(args), args);
+    recordResource({
+      kind: "session", id: args.sessionId, name: `session screenshot: ${args.sessionId}`,
+      description: result.url, uri: `pursr://session/${encodeURIComponent(args.sessionId)}`,
+      mimeType: result.mimeType, file: result.out, meta: { url: result.url, ts: nowIso() },
+    });
+    return [
+      { type: "text", text: JSON.stringify({ sessionId: result.sessionId, out: result.out, url: result.url }, null, 2) },
+      { type: "image", data: result.data, mimeType: result.mimeType },
+    ];
+  }
+
+  async _sessionInspect(args) {
+    const result = await this.sessions.inspect(this._requireSessionId(args), args.selector);
+    return this._text(result);
+  }
+
+  _sessionDiagnostics(args) {
+    return this._text(this.sessions.diagnostics(this._requireSessionId(args), { clear: !!args.clear }));
+  }
+
+  async _sessionClose(args) {
+    return this._text(await this.sessions.close(this._requireSessionId(args)));
+  }
+
+  async _shoot(args) {
     const url = args.url;
     if (!url) throw new McpError(-32602, "Missing required: url");
 
@@ -397,7 +473,9 @@ class PursrMCPServer {
       file: out, meta: { url, flags, ts: sidecar?.ts },
     });
 
-    return [{ type: "text", text: JSON.stringify({ out, meta: sidecar }, null, 2) }];
+    const content = [{ type: "text", text: JSON.stringify({ out, meta: sidecar }, null, 2) }];
+    if (existsSync(out)) content.push({ type: "image", data: readFileSync(out).toString("base64"), mimeType: "image/png" });
+    return content;
   }
 
   async _diff(args) {
@@ -414,7 +492,9 @@ class PursrMCPServer {
       if (k !== "url" && k !== "ref" && k !== "out" && k !== "threshold") flags[k] = v;
     }
     const result = await runDiff(url, ref, out, threshold, flags);
-    return [{ type: "text", text: JSON.stringify(result, null, 2) }];
+    const content = [{ type: "text", text: JSON.stringify(result, null, 2) }];
+    if (existsSync(out)) content.push({ type: "image", data: readFileSync(out).toString("base64"), mimeType: "image/png" });
+    return content;
   }
 
   async _sweep(args) {

package/src/session.js

@@ -0,0 +1,204 @@
+// Persistent browser sessions for agent-driven visual QA.
+
+import { mkdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { 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";
+
+const MAX_DIAGNOSTICS = 250;
+const MAX_ACTIONS = 50;
+
+function cleanId(value) {
+  const id = String(value || "").trim();
+  if (!id) return `session-${Date.now().toString(36)}`;
+  if (!/^[a-zA-Z0-9._-]{1,80}$/.test(id)) throw new Error("sessionId must use only letters, numbers, dot, underscore, or dash");
+  return id;
+}
+
+function pushCapped(list, value) {
+  list.push(value);
+  if (list.length > MAX_DIAGNOSTICS) list.splice(0, list.length - MAX_DIAGNOSTICS);
+}
+
+function attachDiagnostics(page, diagnostics) {
+  page.on("console", (msg) => pushCapped(diagnostics.console, { type: msg.type(), text: msg.text(), ts: new Date().toISOString() }));
+  page.on("pageerror", (error) => pushCapped(diagnostics.errors, { message: error.message, stack: error.stack || null, ts: new Date().toISOString() }));
+  page.on("requestfailed", (request) => pushCapped(diagnostics.requests, {
+    method: request.method(), url: request.url(), failure: request.failure()?.errorText || "failed", ts: new Date().toISOString(),
+  }));
+  page.on("response", (response) => {
+    if (response.status() < 400) return;
+    pushCapped(diagnostics.responses, {
+      status: response.status(), method: response.request().method(), url: response.url(), ts: new Date().toISOString(),
+    });
+  });
+}
+
+export class BrowserSessionManager {
+  constructor({ launchBrowser = launch, outputDir = process.cwd() } = {}) {
+    this.launchBrowser = launchBrowser;
+    this.outputDir = outputDir;
+    this.sessions = new Map();
+  }
+
+  get size() { return this.sessions.size; }
+
+  get(sessionId) {
+    const session = this.sessions.get(String(sessionId || ""));
+    if (!session) throw new Error(`unknown session: ${sessionId}`);
+    return session;
+  }
+
+  list() {
+    return [...this.sessions.values()].map(({ id, page, viewport, createdAt }) => ({ sessionId: id, url: page.url(), viewport, 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();
+    try {
+      const viewport = resolveViewport(flags);
+      const page = await newPage(browser, viewport, { storageState });
+      const diagnostics = { console: [], errors: [], requests: [], responses: [] };
+      attachDiagnostics(page, diagnostics);
+      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() };
+      this.sessions.set(id, session);
+      return { sessionId: id, url: page.url(), title: await page.title(), viewport, status: nav.status, createdAt: session.createdAt };
+    } catch (error) {
+      try { await browser.close(); } catch {}
+      throw error;
+    }
+  }
+
+  async snapshot(sessionId, { selector = "body", maxNodes = 250, includeStyles = true } = {}) {
+    const { page } = this.get(sessionId);
+    const limit = Math.max(1, Math.min(1000, Number(maxNodes) || 250));
+    return await page.evaluate(({ selector, limit, includeStyles }) => {
+      const roots = [...document.querySelectorAll(selector)];
+      const elements = roots.flatMap((root) => [root, ...root.querySelectorAll("*")]);
+      const nodes = [];
+      for (const el of elements) {
+        if (nodes.length >= limit) break;
+        const rect = el.getBoundingClientRect();
+        const style = getComputedStyle(el);
+        if (rect.width <= 0 || rect.height <= 0 || style.visibility === "hidden" || style.display === "none") continue;
+        const text = (el.innerText || el.textContent || "").replace(/\s+/g, " ").trim().slice(0, 160) || null;
+        const item = {
+          node: nodes.length + 1, tag: el.tagName.toLowerCase(), id: el.id || null,
+          role: el.getAttribute("role") || null,
+          name: el.getAttribute("aria-label") || el.getAttribute("alt") || el.getAttribute("title") || text,
+          text, rect: { x: Math.round(rect.x), y: Math.round(rect.y), width: Math.round(rect.width), height: Math.round(rect.height) },
+          state: { disabled: "disabled" in el ? !!el.disabled : undefined, checked: "checked" in el ? !!el.checked : undefined, expanded: el.getAttribute("aria-expanded") },
+        };
+        if (includeStyles) item.style = {
+          display: style.display, position: style.position, zIndex: style.zIndex,
+          overflow: `${style.overflowX} ${style.overflowY}`, opacity: style.opacity,
+          color: style.color, backgroundColor: style.backgroundColor,
+          font: `${style.fontWeight} ${style.fontSize}/${style.lineHeight} ${style.fontFamily}`,
+          transform: style.transform, boxShadow: style.boxShadow,
+        };
+        nodes.push(item);
+      }
+      return { url: location.href, title: document.title, selector, truncated: elements.length > limit, nodes };
+    }, { selector, limit, includeStyles: includeStyles !== false });
+  }
+
+  async inspect(sessionId, selector) {
+    if (!selector) throw new Error("selector is required");
+    const { page } = this.get(sessionId);
+    const locator = await resolveLocator(page, selector);
+    await locator.first().waitFor({ state: "attached", timeout: CLICK_TIMEOUT_MS });
+    return await locator.first().evaluate((el) => {
+      const rect = el.getBoundingClientRect();
+      const style = getComputedStyle(el);
+      const ancestors = [];
+      for (let node = el.parentElement; node && ancestors.length < 6; node = node.parentElement) {
+        const s = getComputedStyle(node);
+        ancestors.push({ tag: node.tagName.toLowerCase(), id: node.id || null, position: s.position, overflow: `${s.overflowX} ${s.overflowY}`, zIndex: s.zIndex, transform: s.transform });
+      }
+      const computedStyle = {};
+      for (const key of ["display","position","inset","width","height","margin","padding","gap","overflow","opacity","visibility","zIndex","transform","transformOrigin","color","background","border","borderRadius","boxShadow","fontFamily","fontSize","fontWeight","lineHeight","textAlign","objectFit","pointerEvents"]) computedStyle[key] = style[key];
+      return { tag: el.tagName.toLowerCase(), html: el.outerHTML.slice(0, 2000), rect: { x: rect.x, y: rect.y, width: rect.width, height: rect.height }, computedStyle, ancestors };
+    });
+  }
+
+  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 trace = [];
+    for (let i = 0; i < actions.length; i++) {
+      const action = actions[i] || {};
+      const op = action.type || action.op;
+      const step = { index: i, type: op };
+      try {
+        if (["click", "hover", "fill", "type", "check", "select"].includes(op)) {
+          const locator = await resolveLocator(page, action.selector);
+          await locator.first().waitFor({ state: "visible", timeout: action.timeoutMs || CLICK_TIMEOUT_MS });
+          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);
+          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 === "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));
+        step.ok = true;
+      } catch (error) {
+        step.ok = false; step.error = error.message; trace.push(step); break;
+      }
+      trace.push(step);
+    }
+    return { sessionId, url: page.url(), title: await page.title(), trace, failed: trace.some((step) => !step.ok) };
+  }
+
+  async screenshot(sessionId, { out, full = false, selector } = {}) {
+    const { page } = this.get(sessionId);
+    const file = out || join(this.outputDir, `pursr-${sessionId}-${Date.now()}.png`);
+    mkdirSync(dirname(file), { recursive: true });
+    if (selector) {
+      const locator = await resolveLocator(page, selector);
+      await locator.first().screenshot({ path: file });
+    } else await page.screenshot({ path: file, fullPage: !!full });
+    return { sessionId, out: file, url: page.url(), data: readFileSync(file).toString("base64"), mimeType: "image/png" };
+  }
+
+  diagnostics(sessionId, { clear = false } = {}) {
+    const session = this.get(sessionId);
+    const result = JSON.parse(JSON.stringify(session.diagnostics));
+    if (clear) {
+      session.diagnostics.console.length = 0;
+      session.diagnostics.errors.length = 0;
+      session.diagnostics.requests.length = 0;
+      session.diagnostics.responses.length = 0;
+    }
+    return { sessionId, ...result };
+  }
+
+  async close(sessionId) {
+    const id = String(sessionId || "");
+    const session = this.sessions.get(id);
+    if (!session) return { sessionId: id, closed: false };
+    this.sessions.delete(id);
+    try { await session.browser.close(); } catch {}
+    return { sessionId: id, closed: true };
+  }
+
+  async closeAll() {
+    await Promise.all([...this.sessions.keys()].map((id) => this.close(id)));
+  }
+}