pursr 0.10.1 → 0.10.2

package/README.md

@@ -36,23 +36,40 @@ Most teams need **five separate tools** to do visual QA: a screenshot CLI, a reg
 - **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 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.
+- **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, Edge, Brave, or Chromium via Playwright. No surprise browser download during install.
+- **First-run doctor + update notices** - diagnose missing browser/runtime pieces and get lightweight release notifications without breaking CI or JSON output.
 
 ## Install
 
 ```bash
-npm install pursr
-npm install --save-dev playwright-core   # peer dep - bring your own Chrome
-```
-
-Then verify:
-
-```bash
-pursr viewports         # list 10+ registered viewport presets
-pursr probe https://example.com   # health check
-```
+npm install pursr
+npm install --save-dev playwright-core   # peer dep - bring your own Chrome
+```
+
+Then verify:
+
+```bash
+pursr doctor                    # check Node, playwright-core, browser, and SKILL.md
+pursr setup                     # print next steps if anything is missing
+pursr viewports                 # list 10+ registered viewport presets
+pursr probe https://example.com # health check
+```
+
+Pursr intentionally does **not** download browsers during `npm install`. Install Chrome, Edge, Brave, or Chromium yourself, or point Pursr at a Chrome-compatible executable:
+
+```bash
+# Windows
+setx PURSR_BROWSER_PATH "C:\Program Files\Google\Chrome\Application\chrome.exe"
+
+# macOS/Linux
+export PURSR_BROWSER_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"
+```
+
+Browser discovery checks standard global installs, user installs, Dev/Beta/Canary/Nightly channels, and executable names found in `PATH` across Windows, macOS, and Linux. Current target is Chromium-family browsers; Firefox/WebKit are planned, but not claimed as stable targets yet.
+
+CLI update notifications are cached for 24 hours, written to stderr, and disabled automatically in CI/non-interactive runs. Disable them manually with `PURSR_NO_UPDATE_NOTIFIER=1`.
 
 ## 30 seconds
 
@@ -165,10 +182,12 @@ 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 |
+| Subcommand | Purpose |
+| --- | --- |
+| `doctor` | Diagnose Node, `playwright-core`, browser discovery, and packaged skill availability |
+| `setup` | Print first-run setup guidance without auto-installing browsers |
+| `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 |
 | `operator` | Run a visible action plan with cursor feedback, screenshot, trace, diagnostics, and optional WebM video |

package/SKILL.md

@@ -1,21 +1,90 @@
 ---
 name: pursr
-description: Use Pursr for browser screenshots, scripted visual operation, visual regression, accessibility audits, DOM inspection, and MCP-driven browser sessions.
+description: Use Pursr for browser screenshots, scripted visual operation, visual regression, accessibility audits, DOM inspection, and MCP-driven browser sessions. Use when a user asks an agent to inspect a site, operate an existing browser session, fill or draft UI content, record a tutorial, compare visuals, debug layout, or behave like a careful browser operator that observes, acts, verifies, and pauses before external side effects.
 ---
 
 # Pursr
 
 Use this skill when a user asks an agent to inspect, operate, record, test, or compare a browser interface.
 
+## Operator Mindset
+
+Act like a careful visual browser operator, not a command runner.
+
+- Infer the user's practical goal from the page and request, then state the first step briefly.
+- Prefer the smallest useful action: observe, act once, verify, then continue.
+- Use the current authenticated browser session when the task depends on login state, open tabs, cookies, or a dashboard the user already opened.
+- Use a fresh session for repeatable tests, visual regression, tutorial recordings, or unauthenticated pages.
+- Draft or prepare external communication, but pause before publishing, sending, buying, deleting, or changing permissions.
+- Report what changed, what was verified, and what still needs user approval.
+
+Examples:
+
+- If the user says "help me make a first post on the Twitter tab I opened", find the open tab, inspect the composer, write a polished draft, then ask before clicking `Post`.
+- If the user says "check why this dashboard looks wrong", open a session, capture a screenshot, inspect geometry/styles for the suspect element, make a small diagnosis, and propose or apply the fix if the repo is available.
+- If the user says "make a tutorial video", use `pursr operator` or MCP actions with visible cursor, labels, slow motion, screenshots, and WebM recording.
+
 ## 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 doctor` before first-run debugging or when browser/runtime setup is uncertain.
+- Use `pursr setup` to give the user safe install guidance without downloading browsers automatically.
 - 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.
 
+## Capability Check
+
+Before operating a browser, pick the strongest available path:
+
+1. Existing browser-control plugin or app: use it for logged-in tabs and user-opened pages.
+2. Pursr MCP session: use it for inspect-act-verify loops, visual debugging, and agent-driven browser work.
+3. Pursr CLI: use it for screenshots, scripted operator plans, regression checks, and recordings.
+4. No browser tools: provide the draft, action plan JSON, or exact command for the user to run.
+
+Do not pretend to control the user's live browser if only the CLI is available. Use CDP attach only when the user intentionally starts Chrome with a local debugging port.
+
+## First Run And Setup
+
+Do not auto-install browsers during package installation. Pursr is intentionally lightweight at install time.
+
+Run:
+
+```bash
+pursr doctor
+pursr setup
+```
+
+Expected support target:
+
+- Chrome-compatible browsers first: Google Chrome, Microsoft Edge, Brave, and Chromium.
+- Discovery should cover global installs, user installs, Dev/Beta/Canary/Nightly channels, and executables found in `PATH` across Windows, macOS, and Linux.
+- Use `PURSR_BROWSER_PATH` when discovery misses the executable.
+- Firefox and WebKit are not the primary supported target yet; do not claim full all-browser support unless the implementation has been added and verified.
+- Update notifications are informational only, cached, written to stderr, and disabled by `PURSR_NO_UPDATE_NOTIFIER=1`.
+
+## Autonomous Browser Workflow
+
+For open-ended browser tasks:
+
+1. Discover context: list or open the relevant tab, read URL/title, and snapshot the visible page.
+2. Build intent: identify the user's real goal, the current page state, and the next safe action.
+3. Act narrowly: click, type, scroll, or run an action plan only after the target is visible or identified from a snapshot.
+4. Verify immediately: take a new snapshot, screenshot, URL check, or diagnostics read after meaningful actions.
+5. Stop at side effects: ask for confirmation immediately before final publish/send/delete/purchase/permission actions.
+6. Leave a handoff: keep important tabs or artifacts available and summarize the exact state.
+
+Use this loop for social posts, dashboard setup, design QA, local app testing, checkout-like flows, account settings, and tutorial recording.
+
+Default short progress pattern:
+
+- "I will inspect the current page first."
+- "I found the relevant tab/page and I am preparing the smallest safe action."
+- "Draft/action is ready; I am stopping before the final external side effect."
+- "Verified: [state]. Remaining approval/action: [item]."
+
 ## CLI Argument Contract
 
 Flags may appear before or after positional arguments.
@@ -67,6 +136,24 @@ Common actions:
 6. Read `pursr_diagnostics` after failures.
 7. Close with `pursr_session_close`; this finalizes any video recording.
 
+Recommended MCP behavior:
+
+- Keep one persistent session per task.
+- Prefer snapshots for target discovery and screenshots for visual judgment.
+- Use `pursr_inspect` when the issue is position, z-index, clipping, opacity, transform, or layout.
+- Use `pursr_act` for small verified action batches, not long blind scripts.
+- When recording, add visible cursor movement, target labels, and short pauses so the output is understandable.
+
+## Communication Drafting
+
+When operating social media, email, forms, comments, or public dashboards:
+
+1. Draft text in the UI or provide it to the user.
+2. Verify the account/page context before filling anything.
+3. Keep tone natural and specific to the product; avoid generic AI-marketing language.
+4. Ask for final approval before clicking the button that transmits the content.
+5. After approval and posting, verify the success state or resulting URL.
+
 ## Safety
 
 - Inspect before acting on unfamiliar pages.

package/bin/pursr.mjs

@@ -13,12 +13,13 @@ import { runFrames } from "../src/frames.js";
 import { runDiff, runDiffWithAi } from "../src/diff.js";
 import { runSweep } from "../src/sweep.js";
 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 { runAudit } from "../src/plugin-audit.js";
+import { captureDomSnapshot } from "../src/dom-snapshot.js";
+import { listViewports } from "../src/viewport.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 { notifyUpdate } from "../src/update-notifier.js";
+import { writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { readFileSync as _readFileSync } from "node:fs";
 const readFile = _readFileSync;
@@ -28,15 +29,16 @@ const USAGE = `usage:
   v1: pursr {probe|shot|full|eval|click|type|wait|diff|seq} <url> [...]
   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
+  flags: --preset <name> --width N --height N --dpr N
          --zoom 1.5 --panX 200 --panY -100
          --cursor pointer|grab|grabbing|crosshair|none
          --layer entity|terrain|hud|ui
          --grid --grid-tile 64 --grid-color rgba(255,0,255,0.35)
          --no-animation --wait-frame 600 --full
   @file prefix reads argv contents from file (UTF-8, newline trimmed).
-  report: pursr report --sweep <sweep.json> [--out <report.pdf>] [--title "..."] [--no-embed]
-         diff extras: --ai [--ai-model M] [--ai-base-url U] [--ai-api-key K]
+  report: pursr report --sweep <sweep.json> [--out <report.pdf>] [--title "..."] [--no-embed]
+  setup: pursr doctor [--json] | pursr setup [--json]
+         diff extras: --ai [--ai-model M] [--ai-base-url U] [--ai-api-key K]
   plugins: pursr automatically loads built-in plugins from plugins/.
   You can also pass --plugin <path> to load custom plugins (repeatable).`;
 
@@ -67,10 +69,11 @@ function dataArg(value) {
 // Plugin loading: scan for --plugin <path> and built-in plugins/
 const pluginPaths = [];
 for (let i = 0; i < argv.length; i++) if (argv[i] === "--plugin" && i + 1 < argv.length) pluginPaths.push(argv[++i]);
-await loadPlugins(pluginPaths);
-
-(async () => {
+await loadPlugins(pluginPaths);
+
+(async () => {
   try {
+    await notifyUpdate({ currentVersion: VERSION, stdout: process.stdout, stderr: process.stderr });
     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; }
@@ -134,8 +137,24 @@ await loadPlugins(pluginPaths);
         if (!r.ok) process.exitCode = 1;
         break;
       }
-      case "viewports": { console.log(JSON.stringify(listViewports(), null, 2)); break; }
-      case "shoot": {
+      case "viewports": { console.log(JSON.stringify(listViewports(), null, 2)); break; }
+      case "doctor": {
+        const { runDoctor, renderDoctorText } = await import("../src/doctor.js");
+        const r = await runDoctor();
+        if (cliFlags.json) console.log(JSON.stringify(r, null, 2));
+        else console.log(renderDoctorText(r));
+        process.exitCode = r.ok ? 0 : 1;
+        break;
+      }
+      case "setup": {
+        const { runSetup, renderSetupText } = await import("../src/doctor.js");
+        const r = await runSetup();
+        if (cliFlags.json) console.log(JSON.stringify(r, null, 2));
+        else console.log(renderSetupText(r));
+        process.exitCode = r.ok ? 0 : 1;
+        break;
+      }
+      case "shoot": {
         if (!url) die("missing url");
         const out = outputPath(b, "shoot.png");
         const r = await runShootWithSidecar({ url, out, flags: { ...cliFlags } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pursr",
-  "version": "0.10.1",
+  "version": "0.10.2",
   "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",
@@ -35,6 +35,9 @@
     "./mcp-resources": "./src/mcp-resources.js",
     "./har": "./src/har.js",
     "./auth": "./src/auth.js",
+    "./browser-discovery": "./src/browser-discovery.js",
+    "./doctor": "./src/doctor.js",
+    "./update-notifier": "./src/update-notifier.js",
     "./watch": "./src/watch.js",
     "./snap": "./src/snap.js",
     "./report": "./src/report.js",

package/src/browser-discovery.js

@@ -0,0 +1,196 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { posix, win32 } from "node:path";
+
+function uniq(list) {
+  return [...new Set(list.filter(Boolean).map(String))];
+}
+
+function envPath(env, key) {
+  return env && env[key] ? String(env[key]) : "";
+}
+
+function pathJoin(platform, ...parts) {
+  return platform === "win32" ? win32.join(...parts) : posix.join(...parts);
+}
+
+function joinIf(platform, base, ...parts) {
+  return base ? pathJoin(platform, base, ...parts) : "";
+}
+
+function pathExecutableCandidates(env, names, platform) {
+  const pathValue = envPath(env, "PATH");
+  if (!pathValue) return [];
+  const dirs = pathValue.split(platform === "win32" ? ";" : ":").filter(Boolean);
+  const exts = platform === "win32"
+    ? (envPath(env, "PATHEXT") || ".EXE;.CMD;.BAT").split(";").filter(Boolean)
+    : [""];
+  const out = [];
+  for (const dir of dirs) {
+    for (const name of names) {
+      if (platform === "win32" && /\.[a-z0-9]+$/i.test(name)) out.push(pathJoin(platform, dir, name));
+      else for (const ext of exts) out.push(pathJoin(platform, dir, name + ext.toLowerCase()));
+    }
+  }
+  return out;
+}
+
+export function browserCandidates(options = {}) {
+  const platform = options.platform || process.platform;
+  const env = options.env || process.env;
+  const home = options.homeDir || homedir();
+  const localAppData = envPath(env, "LOCALAPPDATA");
+  const programFiles = envPath(env, "ProgramFiles") || "C:\\Program Files";
+  const programFilesX86 = envPath(env, "ProgramFiles(x86)") || "C:\\Program Files (x86)";
+
+  const explicit = [
+    envPath(env, "PURSR_BROWSER_PATH"),
+    envPath(env, "CHROME_PATH"),
+    envPath(env, "PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH"),
+  ];
+
+  if (platform === "win32") {
+    const pathNames = [
+      "chrome.exe", "msedge.exe", "brave.exe", "chromium.exe",
+    ];
+    return uniq([
+      ...explicit,
+      pathJoin(platform, programFiles, "Google", "Chrome", "Application", "chrome.exe"),
+      pathJoin(platform, programFilesX86, "Google", "Chrome", "Application", "chrome.exe"),
+      joinIf(platform, localAppData, "Google", "Chrome", "Application", "chrome.exe"),
+      pathJoin(platform, programFiles, "Google", "Chrome Beta", "Application", "chrome.exe"),
+      pathJoin(platform, programFilesX86, "Google", "Chrome Beta", "Application", "chrome.exe"),
+      joinIf(platform, localAppData, "Google", "Chrome Beta", "Application", "chrome.exe"),
+      pathJoin(platform, programFiles, "Google", "Chrome Dev", "Application", "chrome.exe"),
+      pathJoin(platform, programFilesX86, "Google", "Chrome Dev", "Application", "chrome.exe"),
+      joinIf(platform, localAppData, "Google", "Chrome Dev", "Application", "chrome.exe"),
+      joinIf(platform, localAppData, "Google", "Chrome SxS", "Application", "chrome.exe"),
+      pathJoin(platform, programFiles, "Microsoft", "Edge", "Application", "msedge.exe"),
+      pathJoin(platform, programFilesX86, "Microsoft", "Edge", "Application", "msedge.exe"),
+      joinIf(platform, localAppData, "Microsoft", "Edge", "Application", "msedge.exe"),
+      pathJoin(platform, programFiles, "Microsoft", "Edge Beta", "Application", "msedge.exe"),
+      pathJoin(platform, programFilesX86, "Microsoft", "Edge Beta", "Application", "msedge.exe"),
+      joinIf(platform, localAppData, "Microsoft", "Edge Beta", "Application", "msedge.exe"),
+      pathJoin(platform, programFiles, "Microsoft", "Edge Dev", "Application", "msedge.exe"),
+      pathJoin(platform, programFilesX86, "Microsoft", "Edge Dev", "Application", "msedge.exe"),
+      joinIf(platform, localAppData, "Microsoft", "Edge Dev", "Application", "msedge.exe"),
+      pathJoin(platform, programFiles, "Microsoft", "Edge SxS", "Application", "msedge.exe"),
+      pathJoin(platform, programFilesX86, "Microsoft", "Edge SxS", "Application", "msedge.exe"),
+      joinIf(platform, localAppData, "Microsoft", "Edge SxS", "Application", "msedge.exe"),
+      pathJoin(platform, programFiles, "BraveSoftware", "Brave-Browser", "Application", "brave.exe"),
+      pathJoin(platform, programFilesX86, "BraveSoftware", "Brave-Browser", "Application", "brave.exe"),
+      joinIf(platform, localAppData, "BraveSoftware", "Brave-Browser", "Application", "brave.exe"),
+      pathJoin(platform, programFiles, "BraveSoftware", "Brave-Browser-Beta", "Application", "brave.exe"),
+      pathJoin(platform, programFilesX86, "BraveSoftware", "Brave-Browser-Beta", "Application", "brave.exe"),
+      joinIf(platform, localAppData, "BraveSoftware", "Brave-Browser-Beta", "Application", "brave.exe"),
+      pathJoin(platform, programFiles, "BraveSoftware", "Brave-Browser-Nightly", "Application", "brave.exe"),
+      pathJoin(platform, programFilesX86, "BraveSoftware", "Brave-Browser-Nightly", "Application", "brave.exe"),
+      joinIf(platform, localAppData, "BraveSoftware", "Brave-Browser-Nightly", "Application", "brave.exe"),
+      pathJoin(platform, programFiles, "Chromium", "Application", "chrome.exe"),
+      pathJoin(platform, programFilesX86, "Chromium", "Application", "chrome.exe"),
+      ...pathExecutableCandidates(env, pathNames, platform),
+    ]);
+  }
+
+  if (platform === "darwin") {
+    return uniq([
+      ...explicit,
+      "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
+      pathJoin(platform, home, "Applications", "Google Chrome.app", "Contents", "MacOS", "Google Chrome"),
+      "/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta",
+      pathJoin(platform, home, "Applications", "Google Chrome Beta.app", "Contents", "MacOS", "Google Chrome Beta"),
+      "/Applications/Google Chrome Dev.app/Contents/MacOS/Google Chrome Dev",
+      pathJoin(platform, home, "Applications", "Google Chrome Dev.app", "Contents", "MacOS", "Google Chrome Dev"),
+      "/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary",
+      pathJoin(platform, home, "Applications", "Google Chrome Canary.app", "Contents", "MacOS", "Google Chrome Canary"),
+      "/Applications/Microsoft Edge.app/Contents/MacOS/Microsoft Edge",
+      "/Applications/Microsoft Edge Beta.app/Contents/MacOS/Microsoft Edge Beta",
+      "/Applications/Microsoft Edge Dev.app/Contents/MacOS/Microsoft Edge Dev",
+      "/Applications/Microsoft Edge Canary.app/Contents/MacOS/Microsoft Edge Canary",
+      "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
+      "/Applications/Brave Browser Beta.app/Contents/MacOS/Brave Browser Beta",
+      "/Applications/Brave Browser Nightly.app/Contents/MacOS/Brave Browser Nightly",
+      "/Applications/Chromium.app/Contents/MacOS/Chromium",
+      ...pathExecutableCandidates(env, [
+        "google-chrome", "google-chrome-stable", "google-chrome-beta", "google-chrome-unstable",
+        "chromium", "chromium-browser", "microsoft-edge", "microsoft-edge-beta",
+        "microsoft-edge-dev", "brave-browser", "brave-browser-beta", "brave-browser-nightly",
+      ], platform),
+    ]);
+  }
+
+  return uniq([
+    ...explicit,
+    "/usr/bin/google-chrome",
+    "/usr/bin/google-chrome-stable",
+    "/usr/bin/google-chrome-beta",
+    "/usr/bin/google-chrome-unstable",
+    "/usr/bin/chromium",
+    "/usr/bin/chromium-browser",
+    "/usr/bin/microsoft-edge",
+    "/usr/bin/microsoft-edge-stable",
+    "/usr/bin/microsoft-edge-beta",
+    "/usr/bin/microsoft-edge-dev",
+    "/usr/bin/brave-browser",
+    "/usr/bin/brave-browser-beta",
+    "/usr/bin/brave-browser-nightly",
+    "/snap/bin/chromium",
+    "/snap/bin/brave",
+    ...pathExecutableCandidates(env, [
+      "google-chrome", "google-chrome-stable", "google-chrome-beta", "google-chrome-unstable",
+      "chromium", "chromium-browser", "microsoft-edge", "microsoft-edge-stable",
+      "microsoft-edge-beta", "microsoft-edge-dev", "brave-browser", "brave-browser-beta",
+      "brave-browser-nightly",
+    ], platform),
+  ]);
+}
+
+export function discoverBrowsers(options = {}) {
+  const exists = options.exists || existsSync;
+  const candidates = browserCandidates(options);
+  const found = candidates.filter((path) => {
+    try { return exists(path); } catch { return false; }
+  });
+  return {
+    found,
+    preferred: found[0] || null,
+    candidates,
+    env: {
+      PURSR_BROWSER_PATH: !!(options.env || process.env).PURSR_BROWSER_PATH,
+      CHROME_PATH: !!(options.env || process.env).CHROME_PATH,
+    },
+  };
+}
+
+export function findBrowserExecutable(options = {}) {
+  return discoverBrowsers(options).preferred;
+}
+
+export function browserSetupHints(platform = process.platform) {
+  const common = [
+    "Set PURSR_BROWSER_PATH to a Chrome-compatible executable if auto-detection misses it.",
+    "Install playwright-core in the project when using pursr as a local dependency: npm i -D playwright-core",
+  ];
+  if (platform === "win32") {
+    return [
+      "Install Google Chrome, Microsoft Edge, Brave, or Chromium.",
+      "Dev/Beta/Canary channels and PATH-installed browser executables are also detected when available.",
+      "Windows example: setx PURSR_BROWSER_PATH \"C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe\"",
+      ...common,
+    ];
+  }
+  if (platform === "darwin") {
+    return [
+      "Install Google Chrome, Microsoft Edge, Brave, or Chromium.",
+      "Dev/Beta/Canary channels, user Applications, and PATH-installed browser executables are also detected when available.",
+      "macOS example: export PURSR_BROWSER_PATH=\"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome\"",
+      ...common,
+    ];
+  }
+  return [
+    "Install google-chrome-stable, chromium, microsoft-edge-stable, or brave-browser.",
+    "Dev/Beta/unstable channels and PATH-installed browser executables are also detected when available.",
+    "Linux example: export PURSR_BROWSER_PATH=/usr/bin/google-chrome",
+    ...common,
+  ];
+}

package/src/doctor.js

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { browserSetupHints, discoverBrowsers } from "./browser-discovery.js";
+import { resolvePlaywrightCore } from "./runway.js";
+
+function nodeMajor(version = process.version) {
+  const m = String(version).match(/^v?(\d+)/);
+  return m ? Number(m[1]) : 0;
+}
+
+function okCheck(name, ok, details = {}) {
+  return { name, ok: !!ok, ...details };
+}
+
+export async function runDoctor(options = {}) {
+  const version = options.version || process.version;
+  const browsers = discoverBrowsers(options);
+  let playwright = null;
+  try {
+    const resolved = await resolvePlaywrightCore();
+    playwright = okCheck("playwright-core", true, { source: resolved.source });
+  } catch (e) {
+    playwright = okCheck("playwright-core", false, { error: e.message });
+  }
+
+  const packageRoot = options.packageRoot || dirname(dirname(fileURLToPath(import.meta.url)));
+  const skillPath = join(packageRoot, "SKILL.md");
+  const checks = [
+    okCheck("node", nodeMajor(version) >= 18, { version, required: ">=18" }),
+    playwright,
+    okCheck("browser", !!browsers.preferred, { preferred: browsers.preferred, found: browsers.found }),
+    okCheck("skill", existsSync(skillPath), { path: skillPath }),
+  ];
+
+  const ok = checks.every((check) => check.ok);
+  return {
+    ok,
+    checks,
+    browsers,
+    hints: ok ? [] : browserSetupHints(options.platform || process.platform),
+  };
+}
+
+export function renderDoctorText(result) {
+  const lines = [];
+  lines.push(result.ok ? "pursr doctor: OK" : "pursr doctor: attention needed");
+  for (const check of result.checks) {
+    const mark = check.ok ? "ok" : "missing";
+    let detail = "";
+    if (check.name === "browser") detail = check.preferred ? ` (${check.preferred})` : "";
+    if (check.name === "playwright-core") detail = check.source ? ` (${check.source})` : check.error ? ` (${check.error})` : "";
+    if (check.name === "node") detail = ` (${check.version}, required ${check.required})`;
+    lines.push(`- ${mark}: ${check.name}${detail}`);
+  }
+  if (result.hints.length) {
+    lines.push("");
+    lines.push("Next steps:");
+    for (const hint of result.hints) lines.push(`- ${hint}`);
+  }
+  return lines.join("\n");
+}
+
+export async function runSetup(options = {}) {
+  const doctor = await runDoctor(options);
+  return {
+    ok: doctor.ok,
+    doctor,
+    recommended: doctor.ok ? [
+      "Run: pursr probe https://example.com",
+      "For agents, point them at node_modules/pursr/SKILL.md or enable the pursr MCP server.",
+    ] : [
+      ...doctor.hints,
+      "After fixing dependencies, run: pursr doctor",
+    ],
+  };
+}
+
+export function renderSetupText(result) {
+  const lines = [];
+  lines.push(result.ok ? "pursr setup: ready" : "pursr setup: manual steps required");
+  lines.push("");
+  lines.push(renderDoctorText(result.doctor));
+  lines.push("");
+  lines.push("Recommended:");
+  for (const item of result.recommended) lines.push(`- ${item}`);
+  return lines.join("\n");
+}

package/src/runway.js

@@ -1,55 +1,53 @@
-// Browser launcher: auto-detect Playwright + system Chrome.
-
-import { existsSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-let _chromium = null;
-async function getChromium() {
-  if (_chromium) return _chromium;
-  // Try local node_modules first
-  try { return _chromium = (await import("playwright-core")).chromium; } catch {}
-  // Try Codex cua_node runtime (current Codex Desktop bundles it).
-  // The cua_node folder has a hash subdir (e.g. 789504f803e82e2b), so we
-  // walk it to find the playwright-core entry.
+// Browser launcher: auto-detect Playwright + system Chrome.
+
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { findBrowserExecutable } from "./browser-discovery.js";
+
+let _chromium = null;
+export async function resolvePlaywrightCore() {
+  if (_chromium) return { chromium: _chromium, source: "cached" };
+  // Try local node_modules first
+  try {
+    _chromium = (await import("playwright-core")).chromium;
+    return { chromium: _chromium, source: "playwright-core" };
+  } catch {}
+  // Try Codex cua_node runtime (current Codex Desktop bundles it).
+  // The cua_node folder has a hash subdir (e.g. 789504f803e82e2b), so we
+  // walk it to find the playwright-core entry.
   const cuaRoot = join(homedir(), "AppData", "Local", "OpenAI", "Codex", "runtimes", "cua_node");
   if (existsSync(cuaRoot)) {
     const { readdirSync } = await import("node:fs");
     const subdirs = (() => { try { return readdirSync(cuaRoot); } catch { return []; } })();
     for (const sub of subdirs) {
       const cand = join(cuaRoot, sub, "bin", "node_modules", "playwright-core", "index.mjs");
-      if (existsSync(cand)) {
-        try {
-          const url = "file:///" + cand.replace(/\\/g, "/");
-          return _chromium = (await import(url)).chromium;
-        } catch {}
-      }
-    }
-  }
-  throw new Error("playwright-core not found. Install it: npm i -D playwright-core");
-}
-
-const CHROME_PATHS = [
-  "C:/Program Files/Google/Chrome/Application/chrome.exe",
-  "C:/Program Files (x86)/Google/Chrome/Application/chrome.exe",
-  "/usr/bin/google-chrome",
-  "/usr/bin/chromium-browser",
-  "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
-];
-function findChrome() {
-  for (const p of CHROME_PATHS) if (existsSync(p)) return p;
-  return null;
-}
-
-const BROWSER_ARGS = Object.freeze(["--no-sandbox", "--disable-gpu", "--disable-dev-shm-usage"]);
-
+      if (existsSync(cand)) {
+        try {
+          const url = "file:///" + cand.replace(/\\/g, "/");
+          _chromium = (await import(url)).chromium;
+          return { chromium: _chromium, source: "codex-cua-node" };
+        } catch {}
+      }
+    }
+  }
+  throw new Error("playwright-core not found. Install it: npm i -D playwright-core");
+}
+
+async function getChromium() {
+  const resolved = await resolvePlaywrightCore();
+  return resolved.chromium;
+}
+
+const BROWSER_ARGS = Object.freeze(["--no-sandbox", "--disable-gpu", "--disable-dev-shm-usage"]);
+
 export async function launch(options = {}) {
   const chromium = await getChromium();
-  const exec = findChrome();
-  if (!exec) throw new Error("system Chrome not found in standard paths");
+  const exec = options.executablePath || findBrowserExecutable();
+  if (!exec) throw new Error("Chrome-compatible browser not found. Run: pursr doctor");
   return await chromium.launch({
     headless: options.headless !== false,
-    executablePath: options.executablePath || exec,
+    executablePath: exec,
     slowMo: Math.max(0, Number(options.slowMo) || 0),
     args: [...BROWSER_ARGS, ...(Array.isArray(options.args) ? options.args : [])],
   });

package/src/update-notifier.js

@@ -0,0 +1,74 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { request as httpsRequest } from "node:https";
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+export function compareVersions(a, b) {
+  const pa = String(a || "0").split(".").map((x) => Number.parseInt(x, 10) || 0);
+  const pb = String(b || "0").split(".").map((x) => Number.parseInt(x, 10) || 0);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const da = pa[i] || 0;
+    const db = pb[i] || 0;
+    if (da > db) return 1;
+    if (da < db) return -1;
+  }
+  return 0;
+}
+
+export function updateCachePath(env = process.env) {
+  const root = env.PURSR_HOME || join(homedir(), ".pursr");
+  return join(root, "update-check.json");
+}
+
+export function shouldCheckForUpdate({ env = process.env, stdout = process.stdout, stderr = process.stderr, now = Date.now(), cachePath = updateCachePath(env) } = {}) {
+  if (env.PURSR_NO_UPDATE_NOTIFIER || env.NO_UPDATE_NOTIFIER || env.CI) return false;
+  if (!stderr?.isTTY || !stdout?.isTTY) return false;
+  try {
+    if (!existsSync(cachePath)) return true;
+    const cached = JSON.parse(readFileSync(cachePath, "utf8"));
+    return !cached.checkedAt || now - Date.parse(cached.checkedAt) > DAY_MS;
+  } catch {
+    return true;
+  }
+}
+
+function fetchLatestVersion({ registryUrl = "https://registry.npmjs.org/pursr/latest", timeoutMs = 800 } = {}) {
+  return new Promise((resolve) => {
+    const req = httpsRequest(registryUrl, { method: "GET", timeout: timeoutMs, headers: { accept: "application/json" } }, (res) => {
+      let body = "";
+      res.setEncoding("utf8");
+      res.on("data", (chunk) => { body += chunk; });
+      res.on("end", () => {
+        try {
+          const json = JSON.parse(body);
+          resolve(json.version || null);
+        } catch {
+          resolve(null);
+        }
+      });
+    });
+    req.on("timeout", () => { req.destroy(); resolve(null); });
+    req.on("error", () => resolve(null));
+    req.end();
+  });
+}
+
+export async function checkForUpdate({ currentVersion, env = process.env, stdout = process.stdout, stderr = process.stderr, now = Date.now(), cachePath = updateCachePath(env), fetchLatest = fetchLatestVersion } = {}) {
+  if (!shouldCheckForUpdate({ env, stdout, stderr, now, cachePath })) return null;
+  const latest = await fetchLatest();
+  try {
+    mkdirSync(dirname(cachePath), { recursive: true });
+    writeFileSync(cachePath, JSON.stringify({ checkedAt: new Date(now).toISOString(), latest }, null, 2), "utf8");
+  } catch {}
+  if (!latest || compareVersions(latest, currentVersion) <= 0) return null;
+  return { current: currentVersion, latest, command: "npm i -g pursr@latest" };
+}
+
+export async function notifyUpdate(options = {}) {
+  const result = await checkForUpdate(options);
+  if (!result) return null;
+  options.stderr?.write?.(`\npursr update available: ${result.current} -> ${result.latest}\nRun: ${result.command}\n\n`);
+  return result;
+}