pursor 0.2.0

package/src/overlays.js

@@ -0,0 +1,170 @@
+// Shared capture-side helpers: page-side CSS overlays, camera control,
+// frame stability wait.
+
+export const NAV_TIMEOUT_MS = 90_000;
+export const SETTLE_MS = 1200;
+export const CLICK_TIMEOUT_MS = 15_000;
+export const WAIT_DEFAULT_TIMEOUT_MS = 30_000;
+
+export async function gotoOrThrow(page, url, opts = {}) {
+  const timeout = opts.timeoutMs || NAV_TIMEOUT_MS;
+  const resp = await page.goto(url, { waitUntil: "domcontentloaded", timeout });
+  if (!resp) throw new Error(`No response for ${url}`);
+  const status = resp.status();
+  if (status >= 400) throw new Error(`HTTP ${status} for ${url}`);
+  return { status, title: await page.title() };
+}
+
+export async function settle(page) {
+  await page.waitForTimeout(SETTLE_MS);
+}
+
+// --- overlays ---
+
+export async function overlayCursor(page, kind) {
+  if (!kind || kind === "default" || kind === "none") return async () => {};
+  const map = { pointer: "pointer", grab: "grab", grabbing: "grabbing", crosshair: "crosshair" };
+  const css = map[kind] || "pointer";
+  const marker = `/*purr_visual_cursor_${css}*/`;
+  await page.addStyleTag({ content: `${marker}\n*, *::before, *::after { cursor: ${css} !important; }` });
+  return async () => {
+    await page.evaluate((m) => document.querySelectorAll("style").forEach(s => { if (s.textContent && s.textContent.includes(m)) s.remove(); }), marker).catch(() => {});
+  };
+}
+
+export async function overlayGrid(page, opts = {}) {
+  const tile = Math.max(8, Math.min(512, Number(opts.tileSize) || 64));
+  // Sanitize color: allow only CSS-safe color tokens (hex, rgba, named)
+  const raw = (opts.color || "rgba(255, 0, 255, 0.35)").trim();
+  // Reject anything with braces, semicolons, quotes, or HTML — CSS injection guard
+  const color = /^[a-zA-Z#()\d\s,%.]+$/.test(raw) ? raw : "rgba(255, 0, 255, 0.35)";
+  await page.evaluate(({ tile, color }) => {
+    let s = document.getElementById("__purr_visual_grid__");
+    if (s) s.remove();
+    s = document.createElement("style");
+    s.id = "__purr_visual_grid__";
+    s.textContent = `body::before { content: ""; position: fixed; inset: 0; pointer-events: none; z-index: 99999; background-image: linear-gradient(to right, ${color} 1px, transparent 1px), linear-gradient(to bottom, ${color} 1px, transparent 1px); background-size: ${tile}px ${tile}px, ${tile}px ${tile}px; }`;
+    document.documentElement.appendChild(s);
+  }, { tile, color });
+  return async () => {
+    await page.evaluate(() => document.getElementById("__purr_visual_grid__")?.remove()).catch(() => {});
+  };
+}
+
+export async function hideHud(page) {
+  const marker = "/*purr_visual_hide_hud*/";
+  const css = marker + "\n" + [
+    "header, footer, nav { display: none !important; }",
+    ".hud-topbar, .bottom-nav { display: none !important; }",
+    "[data-pursor-hud=\"hide\"] { display: none !important; }",
+  ].join("\n");
+  await page.addStyleTag({ content: css });
+  return async () => {
+    await page.evaluate((m) => document.querySelectorAll("style").forEach(s => { if (s.textContent && s.textContent.includes(m)) s.remove(); }), marker).catch(() => {});
+  };
+}
+
+export async function isolateLayer(page, layer) {
+  if (!layer || layer === "all" || layer === "none") return async () => {};
+  let css = "";
+  // entity = canvas only (game worlds typically render into <canvas>)
+  if (layer === "entity") css = "[class*=\"bottom\"], [class*=\"hud\"], [class*=\"nav\"], [class*=\"bar\"], [class*=\"companion\"] { display: none !important; }";
+  else if (layer === "terrain") css = "canvas { display: none !important; }";
+  else if (layer === "hud") css = "[class*=\"hud\"], [class*=\"nav\"], [class*=\"bar\"] { display: none !important; }";
+  else if (layer === "ui") css = "canvas, header, footer, main > nav { display: none !important; }";
+  else throw new Error("unknown layer: " + layer);
+  const marker = `/*purr_visual_layer_${layer}*/`;
+  await page.addStyleTag({ content: `${marker}\n${css}` });
+  return async () => {
+    await page.evaluate((m) => document.querySelectorAll("style").forEach(s => { if (s.textContent && s.textContent.includes(m)) s.remove(); }), marker).catch(() => {});
+  };
+}
+
+export async function freezeAnimation(page, freeze) {
+  if (!freeze) return async () => {};
+  const marker = "/*purr_visual_freeze*/";
+  await page.addStyleTag({ content: `${marker}\n*, *::before, *::after { animation-play-state: paused !important; animation-delay: 0s !important; transition: none !important; }` });
+  return async () => {
+    await page.evaluate((m) => document.querySelectorAll("style").forEach(s => { if (s.textContent && s.textContent.includes(m)) s.remove(); }), marker).catch(() => {});
+  };
+}
+
+export async function waitForStableFrame(page, ms) {
+  if (!ms || ms <= 0) return;
+  const hard = 8000;
+  const t0 = Date.now();
+  let lastHash = null, lastChange = Date.now();
+  while (Date.now() - t0 < hard) {
+    let h;
+    try {
+      h = await page.evaluate(() => {
+        const c = document.querySelector("canvas");
+        if (!c) return null;
+        // Prefer WebGL context (common in game canvases), fall back to 2D
+        let ctx, type;
+        try {
+          ctx = c.getContext("webgl2", { willReadFrequently: false }) || c.getContext("webgl");
+          if (ctx) type = "webgl";
+        } catch {}
+        if (!ctx) {
+          try { ctx = c.getContext("2d", { willReadFrequently: true }); type = "2d"; } catch {}
+        }
+        if (!ctx) return null;
+        if (type === "webgl") {
+          // Create a small readback for WebGL with complete framebuffer
+          const fb = ctx.createFramebuffer();
+          ctx.bindFramebuffer(ctx.FRAMEBUFFER, fb);
+          const rb = ctx.createRenderbuffer();
+          ctx.bindRenderbuffer(ctx.RENDERBUFFER, rb);
+          ctx.renderbufferStorage(ctx.RENDERBUFFER, ctx.RGBA4, 4, 4);
+          ctx.framebufferRenderbuffer(ctx.FRAMEBUFFER, ctx.COLOR_ATTACHMENT0, ctx.RENDERBUFFER, rb);
+          const d = new Uint8Array(64);
+          ctx.readPixels(0, 0, 4, 4, ctx.RGBA, ctx.UNSIGNED_BYTE, d);
+          let acc = 0; for (let i = 0; i < d.length; i += 4) acc = (acc * 31 + d[i]) | 0;
+          return acc.toString(36);
+        } else {
+          const d = ctx.getImageData(Math.floor(c.width / 2), Math.floor(c.height / 2), 32, 32).data;
+          let acc = 0; for (let i = 0; i < d.length; i += 64) acc = (acc * 31 + d[i]) | 0;
+          return acc.toString(36);
+        }
+      });
+    } catch {
+      // page detached mid-poll — give up
+      return;
+    }
+    if (h && h === lastHash) { if (Date.now() - lastChange >= ms) return; }
+    else { lastHash = h; lastChange = Date.now(); }
+    await page.waitForTimeout(120);
+  }
+}
+
+// --- camera ---
+
+export async function applyCamera(page, opts = {}) {
+  if (!opts) return;
+  const zoom = Number(opts.zoom) || 1;
+  const panX = Number(opts.panX) || 0;
+  const panY = Number(opts.panY) || 0;
+  const center = await page.evaluate(() => {
+    const c = document.querySelector("canvas");
+    if (!c) return null;
+    const r = c.getBoundingClientRect();
+    return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
+  });
+  if (!center) return;
+  if (zoom !== 1) {
+    const factor = Math.log2(zoom) * 8;
+    const delta = -120 * (factor > 0 ? 1 : -1);
+    for (let i = 0; i < Math.max(1, Math.abs(Math.round(factor))); i++) {
+      await page.mouse.move(center.x, center.y);
+      await page.mouse.wheel(0, delta);
+      await page.waitForTimeout(50);
+    }
+  }
+  if (panX || panY) {
+    await page.mouse.move(center.x, center.y);
+    await page.mouse.down();
+    await page.mouse.move(center.x + panX, center.y + panY, { steps: 10 });
+    await page.mouse.up();
+  }
+}

package/src/plugin-audit.js

@@ -0,0 +1,260 @@
+// pursor — axe-core accessibility audit.
+//
+// Injects axe-core into the page, runs a WCAG audit, returns violations.
+// Optionally highlights violated elements with a red overlay and
+// generates a full audit report.
+//
+// Used internally via runAudit() and also exposed as a sweep-op
+// so it works in batch plans.
+//
+// Dependencies: axe-core (npm i axe-core)
+
+import { launch, newPage } from "./runway.js";
+import { resolveViewport } from "./viewport.js";
+import { gotoOrThrow, settle } from "./overlays.js";
+import { writeFileSync, mkdirSync, readFileSync, existsSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { asNum, nowIso } from "./util.js";
+
+// ─── Injected audit runner ──────────────────────────────────────────────
+
+const AUDIT_RUNNER = (axeSource) => `
+${axeSource}
+(function() {
+  return new Promise((resolve, reject) => {
+    const config = typeof window.__PURR_AUDIT_CONFIG__ !== 'undefined' ? window.__PURR_AUDIT_CONFIG__ : {};
+    var tags = config.tags || ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice'];
+    axe.run(
+      { runOnly: { type: 'tag', values: tags } },
+      function(err, results) {
+        if (err) { reject(err.message); return; }
+        // Also collect element references for highlighting
+        resolve(JSON.parse(JSON.stringify(results)));
+      }
+    );
+  });
+})()
+`;
+
+// ─── Highlight overlay script ──────────────────────────────────────────
+
+const HIGHLIGHT_VIOLATIONS = (violationsJson) => `
+(function() {
+  var violations = ${violationsJson};
+  if (!violations || !violations.length) return;
+  var style = document.createElement('style');
+  style.id = '__purr_audit_highlight__';
+  style.textContent = \`
+    [data-purr-audit-violation] {
+      outline: 3px solid rgba(255, 0, 0, 0.85) !important;
+      background: rgba(255, 0, 0, 0.12) !important;
+      position: relative !important;
+    }
+    [data-purr-audit-violation]::after {
+      content: attr(data-purr-audit-violation);
+      position: absolute;
+      top: -20px;
+      left: 0;
+      background: #d00;
+      color: #fff;
+      font: 10px/14px monospace;
+      padding: 1px 5px;
+      border-radius: 3px;
+      z-index: 999999;
+      white-space: nowrap;
+    }
+  \`;
+  document.documentElement.appendChild(style);
+  for (var v of violations) {
+    for (var n of v.nodes || []) {
+      for (var t of n.target || []) {
+        try {
+          var sel = Array.isArray(t) ? t.join(' ') : t;
+          var els = document.querySelectorAll(sel);
+          for (var e of els) {
+            e.setAttribute('data-purr-audit-violation', v.id + ': ' + v.impact);
+          }
+        } catch(e) {}
+      }
+    }
+  }
+})()
+`;
+
+// ─── Load axe-core ──────────────────────────────────────────────────────
+
+let _axeSource = null;
+async function getAxeSource() {
+  if (_axeSource) return _axeSource;
+  // Try node_modules/axe-core
+  const paths = [
+    join(process.cwd(), "node_modules", "axe-core", "axe.min.js"),
+    join(process.cwd(), "node_modules", "axe-core", "axe.js"),
+    new URL("..", import.meta.url).pathname && join(dirname(new URL(import.meta.url).pathname), "node_modules", "axe-core", "axe.min.js"),
+    join(dirname(process.execPath), "node_modules", "axe-core", "axe.min.js"),
+  ];
+  for (const p of paths) {
+    if (p && existsSync(p)) {
+      _axeSource = readFileSync(p, "utf8");
+      return _axeSource;
+    }
+  }
+  throw new Error("axe-core not found. Install: npm i axe-core");
+}
+
+// ─── Group helper ───────────────────────────────────────────────────────
+
+/** Count violations by WCAG impact level */
+function summarizeViolations(violations) {
+  const byImpact = { critical: 0, serious: 0, moderate: 0, minor: 0 };
+  const byTag = {};
+  for (const v of violations) {
+    byImpact[v.impact] = (byImpact[v.impact] || 0) + v.nodes.length;
+    for (const t of v.tags || []) {
+      if (!byTag[t]) byTag[t] = 0;
+      byTag[t] += v.nodes.length;
+    }
+  }
+  return { total: violations.length, totalNodes: violations.reduce((s, v) => s + v.nodes.length, 0), byImpact, byTag };
+}
+
+// ─── Public API ─────────────────────────────────────────────────────────
+
+/**
+ * Run axe-core audit on a URL.
+ *
+ * @param {object} opts
+ * @param {string} opts.url        - Target URL
+ * @param {string[]} [opts.tags]   - WCAG tags (default: wcag2a, wcag2aa, wcag21a, wcag21aa, best-practice)
+ * @param {string}  [opts.outDir]  - Output directory
+ * @param {boolean} [opts.screenshot=true] - Capture highlighted screenshot
+ * @param {object}  [opts.flags]   - Extra capture flags
+ * @returns {Promise<object>} Audit result
+ */
+export async function runAudit({ url, tags, outDir, screenshot = true, flags = {} }) {
+  const dir = outDir || join(process.cwd(), `audit-${Date.now()}`);
+  mkdirSync(dir, { recursive: true });
+
+  const viewport = resolveViewport(flags);
+  const browser = await launch();
+  const axeSource = await getAxeSource();
+
+  try {
+    const page = await newPage(browser, viewport);
+    const r = await gotoOrThrow(page, url);
+    await settle(page);
+    // Give dynamic content time to fully render
+    await page.waitForTimeout(800);
+
+    // Inject axe config
+    await page.evaluate((t) => {
+      window.__PURR_AUDIT_CONFIG__ = { tags: t || ['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'best-practice'] };
+    }, tags || undefined);
+
+    // Inject and run axe
+    const rawResults = await page.evaluate(AUDIT_RUNNER, axeSource);
+
+    const result = {
+      url,
+      title: r.title,
+      ts: nowIso(),
+      viewport: { width: viewport.width, height: viewport.height, dpr: viewport.dpr },
+      violationSummary: summarizeViolations(rawResults.violations || []),
+      passes: (rawResults.passes || []).length,
+      incomplete: (rawResults.incomplete || []).length,
+      inapplicable: (rawResults.inapplicable || []).length,
+      violations: rawResults.violations || [],
+    };
+
+    // Write audit report
+    const auditPath = join(dir, "audit.json");
+    writeFileSync(auditPath, JSON.stringify(result, null, 2));
+
+    // Write summary Markdown
+    const mdPath = join(dir, "audit-summary.md");
+    writeFileSync(mdPath, renderAuditMarkdown(result));
+
+    // Highlighted screenshot
+    if (screenshot && result.violations.length > 0) {
+      const violationsJson = JSON.stringify(result.violations.map(v => ({
+        id: v.id,
+        impact: v.impact,
+        nodes: (v.nodes || []).map(n => ({ target: n.target })),
+      })));
+      await page.evaluate(HIGHLIGHT_VIOLATIONS, violationsJson);
+      await page.waitForTimeout(200);
+      const shotPath = join(dir, "audit-highlighted.png");
+      await page.screenshot({ path: shotPath, fullPage: true });
+      result.highlightedScreenshot = shotPath;
+    } else if (screenshot) {
+      const shotPath = join(dir, "audit-clean.png");
+      await page.screenshot({ path: shotPath, fullPage: true });
+      result.cleanScreenshot = shotPath;
+    }
+
+    return result;
+  } finally {
+    try { await browser.close(); } catch {}
+  }
+}
+
+// ─── Markdown report ────────────────────────────────────────────────────
+
+function renderAuditMarkdown(result) {
+  const s = result.violationSummary || {};
+  const lines = [
+    `# Accessibility Audit: ${result.url}`,
+    ``,
+    `**Date:** ${result.ts}`,
+    `**Viewport:** ${result.viewport.width}x${result.viewport.height} @${result.viewport.dpr}x`,
+    ``,
+    `## Summary`,
+    ``,
+    `| Severity | Count |`,
+    `|----------|-------|`,
+    `| 🔴 Critical | ${s.byImpact?.critical || 0} nodes`,
+    `| 🟠 Serious | ${s.byImpact?.serious || 0} nodes`,
+    `| 🟡 Moderate | ${s.byImpact?.moderate || 0} nodes`,
+    `| ⚪ Minor | ${s.byImpact?.minor || 0} nodes`,
+    `| **Total violations** | **${s.total} rules, ${s.totalNodes} nodes** |`,
+    ``,
+    `| Check | Count |`,
+    `|-------|-------|`,
+    `| Passes | ${result.passes || 0} |`,
+    `| Incomplete | ${result.incomplete || 0} |`,
+    `| Inapplicable | ${result.inapplicable || 0} |`,
+    ``,
+  ];
+
+  if (result.violations.length) {
+    lines.push(`## Violations`);
+    lines.push(``);
+    for (const v of result.violations) {
+      lines.push(`### ${v.id} — ${v.impact}`);
+      lines.push(``);
+      lines.push(`**Help:** ${v.helpUrl || v.help || 'N/A'}`);
+      lines.push(``);
+      lines.push(`**Tags:** ${(v.tags || []).join(', ')}`);
+      lines.push(``);
+      lines.push(`**Affected nodes:** ${(v.nodes || []).length}`);
+      lines.push(``);
+      for (const n of (v.nodes || []).slice(0, 10)) { // top 10 per violation
+        const target = (n.target || []).join(', ');
+        const snippet = (n.html || '').slice(0, 200);
+        const failureSummary = n.failureSummary || '';
+        lines.push(`- \`${target}\``);
+        if (snippet) lines.push(`  - \`${snippet.replace(/`/g, '')}\``);
+        if (failureSummary) lines.push(`  - ${failureSummary.split('\\n')[0]}`);
+      }
+      if ((v.nodes || []).length > 10) lines.push(`  - … and ${v.nodes.length - 10} more nodes`);
+      lines.push(``);
+    }
+  }
+
+  if (result.highlightedScreenshot) lines.push(`![Highlighted screenshot](${result.highlightedScreenshot})`);
+  if (result.cleanScreenshot) lines.push(`![Clean screenshot](${result.cleanScreenshot})`);
+
+  lines.push(``);
+  lines.push(`_Generated by pursor audit_`);
+  return lines.join('\n');
+}

package/src/plugin.js

@@ -0,0 +1,121 @@
+// pursor — plugin API.
+//
+// A plugin is a plain ES module that exports a default object with one
+// or more hook handlers. The host loads plugins from:
+//   1. The built-in `plugins/` directory (shipped with the package).
+//   2. A path passed to `loadPlugins([...paths])`.
+//   3. Any package named `pursor-plugin-*` in node_modules.
+//
+// Hook reference:
+//
+//   name:        "my-plugin"  // optional, for logs
+//   viewport:    { <presetName>: { width, height, dpr, label } }
+//   sweepOp:     { <opName>: async (ctx, opts) => Result }
+//   beforeShoot: async (ctx) => void   // mutate ctx.flags / ctx.viewport
+//   afterShoot:  async (ctx, meta) => void  // augment sidecar
+//   flagHelp:    { "my-flag": "what it does" }
+//
+// ctx fields available to hooks:
+//   url, out, viewport, flags, browser, page
+//
+// Example plugin (plugins/my-plugin.js):
+//
+//   export default {
+//     name: "my-plugin",
+//     viewport: {
+//       "my-laptop": { width: 1440, height: 900, dpr: 2, label: "MBP 14" },
+//     },
+//     sweepOp: {
+//       "lighthouse": async (ctx, opts) => {
+//         // ... run lighthouse, return { out, meta }
+//       },
+//     },
+//     beforeShoot: async (ctx) => {
+//       // e.g. set extra cookies, click a button, etc.
+//     },
+//   };
+
+const plugins = [];
+const registeredRefs = new Set();
+const sweepOps = new Map();
+const viewportPresets = new Map();
+const flagHelp = new Map();
+
+export function registerPlugin(p) {
+  if (!p || typeof p !== "object") return;
+  if (registeredRefs.has(p)) return;
+  registeredRefs.add(p);
+  plugins.push(p);
+  if (p.name) console.error(`[pursor] loaded plugin: ${p.name}`);
+  if (p.viewport) {
+    for (const [k, v] of Object.entries(p.viewport)) viewportPresets.set(k, v);
+  }
+  if (p.sweepOp) {
+    for (const [k, v] of Object.entries(p.sweepOp)) sweepOps.set(k, v);
+  }
+  if (p.flagHelp) {
+    for (const [k, v] of Object.entries(p.flagHelp)) flagHelp.set(k, v);
+  }
+}
+
+export async function loadPlugins(paths = []) {
+  if (typeof paths === "string") paths = [paths];
+  const loadedPaths = new Set();
+  // auto-load built-in plugins from plugins/ directory
+  const { readdirSync, existsSync } = await import("node:fs");
+  const { join, dirname } = await import("node:path");
+  const { fileURLToPath, pathToFileURL } = await import("node:url");
+  const selfDir = dirname(fileURLToPath(import.meta.url));
+  const pluginDir = join(selfDir, "..", "plugins");
+  if (existsSync(pluginDir)) {
+    for (const f of readdirSync(pluginDir)) {
+      if (f.endsWith(".js")) {
+        const fullPath = pathToFileURL(join(pluginDir, f)).href;
+        if (loadedPaths.has(fullPath)) continue;
+        loadedPaths.add(fullPath);
+        try {
+          const mod = await import(/* @vite-ignore */ fullPath);
+          registerPlugin(mod.default || mod);
+        } catch (e) {
+          console.error(`[pursor] failed to load built-in plugin ${f}: ${e.message}`);
+        }
+      }
+    }
+  }
+  // user-supplied plugins — resolve relative to cwd
+  for (const p of paths) {
+    if (loadedPaths.has(p)) continue;
+    loadedPaths.add(p);
+    try {
+      const resolved = pathToFileURL(join(process.cwd(), p)).href;
+      const mod = await import(/* @vite-ignore */ resolved);
+      registerPlugin(mod.default || mod);
+    } catch (e) {
+      console.error(`[pursor] failed to load plugin ${p}: ${e.message}`);
+    }
+  }
+  return plugins.length;
+}
+
+export function listPlugins() { return plugins.map(p => p?.name || "(unnamed)"); }
+
+export function getSweepOp(name) { return sweepOps.get(name); }
+export function getViewportPreset(name) { return viewportPresets.get(name); }
+export function listViewportPresets() { return Object.fromEntries(viewportPresets); }
+export function getFlagHelp() { return Object.fromEntries(flagHelp); }
+
+export async function runBeforeShoot(ctx) {
+  for (const p of plugins) {
+    if (typeof p.beforeShoot === "function") {
+      try { await p.beforeShoot(ctx); } catch (e) { console.error(`[plugin ${p.name}] beforeShoot: ${e.message}`); }
+    }
+  }
+}
+
+export async function runAfterShoot(ctx, meta) {
+  for (const p of plugins) {
+    if (typeof p.afterShoot === "function") {
+      try { await p.afterShoot(ctx, meta); } catch (e) { console.error(`[plugin ${p.name}] afterShoot: ${e.message}`); }
+    }
+  }
+}

package/src/probe.js

@@ -0,0 +1,20 @@
+// Probe: open a viewport, navigate, return basic info. No screenshot.
+
+import { launch, newPage } from "./runway.js";
+import { DEFAULT_VIEWPORT } from "./viewport.js";
+import { gotoOrThrow } from "./overlays.js";
+import { requireArg } from "./util.js";
+
+export async function runProbe(url) {
+  requireArg("url", url, "string");
+  const browser = await launch();
+  try {
+    const page = await newPage(browser, DEFAULT_VIEWPORT);
+    let navError = null, status = null, title = null;
+    try {
+      const r = await gotoOrThrow(page, url);
+      status = r.status; title = r.title;
+    } catch (e) { navError = e.message; }
+    return { url, status, title, navError, viewport: DEFAULT_VIEWPORT };
+  } finally { try { await browser.close(); } catch {} }
+}

package/src/runway.js

@@ -0,0 +1,63 @@
+// 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.
+  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"]);
+
+export async function launch() {
+  const chromium = await getChromium();
+  const exec = findChrome();
+  if (!exec) throw new Error("system Chrome not found in standard paths");
+  return await chromium.launch({ headless: true, executablePath: exec, args: BROWSER_ARGS });
+}
+
+export async function newPage(browser, viewport) {
+  const ctx = await browser.newContext({
+    viewport: { width: viewport.width, height: viewport.height },
+    deviceScaleFactor: viewport.dpr || 1,
+    reducedMotion: "no-preference",
+    colorScheme: "light",
+    hasTouch: !!(viewport.name && viewport.name.startsWith("mobile")),
+    isMobile: !!(viewport.name && viewport.name.startsWith("mobile")),
+  });
+  return await ctx.newPage();
+}