electron-verify-mcp 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dpraj007
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,155 @@
+# electron-verify-mcp
+
+Give your AI coding agent **eyes for Electron apps**: launch, drive, screenshot, and get a high-precision pass/fail verdict so it can verify its own UI in a loop.
+
+Signal **precision** is the product — a verdict that cries wolf once is worse than none. Hard-FAIL only on high-confidence signals (renderer crash, uncaught `pageerror`, main-process exit, blank screen). Bare `console.error` and `unhandledrejection` are **WARN** by default (opt into `strictConsole` for FAIL). Layout overflow, broken images, and readiness timeouts are WARN: the agent still gets the PNG to judge.
+
+## Install
+
+```bash
+npm install -g electron-verify-mcp
+# or one-shot
+npx -y electron-verify-mcp
+```
+
+Local / from source:
+
+```bash
+npm install
+npm run build   # emits dist/cli.js + dist/mcp.js + dist/core/index.js
+```
+
+## MCP setup (`.mcp.json`)
+
+**Published (npx):**
+
+```json
+{
+  "mcpServers": {
+    "electron-verify": {
+      "command": "npx",
+      "args": ["-y", "electron-verify-mcp"]
+    }
+  }
+}
+```
+
+**Local (dev):**
+
+```json
+{
+  "mcpServers": {
+    "electron-verify": {
+      "command": "node",
+      "args": ["C:/path/to/electron-verify-mcp/dist/mcp.js"]
+    }
+  }
+}
+```
+
+Or via tsx without building: `node --import tsx src/mcp.ts`.
+
+## Tools
+
+| Tool | Purpose |
+|------|---------|
+| `app_launch` | Open a single managed Electron session (closes any prior). Returns `{ windows, pid }`. URLs truncated (~120 chars). |
+| `app_screenshot` | Short readiness-gated PNG. Default `captureMode=window` (composited Electron chrome; falls back to content). Use `os-window` for the real OS caption bar. |
+| `app_click` | Click a CSS selector. |
+| `app_type` | Fill text into an input. |
+| `app_wait_for` | Wait for a CSS selector or visible text (single-word labels are text, not tags). Optional `by`. |
+| `app_evaluate` | Run a JS expression in the renderer (CSP-safe via CDP). |
+| `app_verify` | Signal pass + PNG + `structuredContent` verdict. Default human image is full-window; analysis uses content. `freshLoad` defaults true when no interaction since last verify. |
+| `app_close` | Dispose the session (graceful close with 5s timeout + force-kill). |
+
+Only **one** session at a time. Tool calls are serialized. Dead session → clean error (`no active session` / `session died — relaunch`), not a raw Playwright stack.
+
+## Verify loop (agent pattern)
+
+```text
+1. app_launch  { appPath, cwd?, buildCommand? }
+2. app_verify  { expect: "login screen shows" }
+3. Read the PNG + structuredContent.verdict (+ captureMode)
+4. If FAIL/WARN: fix code (or click into the right state with app_click / app_type)
+5. app_verify again (freshLoad stays false after interaction; true if you only re-check)
+6. app_close when done
+```
+
+## Capture modes
+
+| Mode | Human-facing image | Signal analysis |
+|------|--------------------|-----------------|
+| `window` (default) | Composited Electron window via `desktopCapturer` **window** sources (menu bar + content + BrowserViews). Does **not** include the OS caption bar (min/max/close). Falls back to annotated content if unavailable. | Always `page.screenshot()` content |
+| `os-window` | Full OS window including the **caption bar** with real minimize / maximize / close buttons and borders. Screen-source capture cropped to `getBounds()` (outer frame). Falls back to `window`, then content. | content |
+| `content` | Viewport only (hole annotations when BrowserViews exist) | content |
+| `both` | Two image blocks (window + content). Does not add an extra os-window image. | content |
+
+`structuredContent.captureMode` reports what was actually used: `"window"` | `"os-window"` | `"os-window-fallback:window"` | `"content"` | `"content-fallback"`.
+
+**Caveats for `os-window`:**
+- **macOS:** requires Screen Recording permission; denied permission yields an all-black crop → automatic fallback.
+- **Occlusion:** the target window is raised/focused best-effort before capture; another window still on top can appear in the crop.
+- **Multi-monitor:** crops against the display the window is on (`getDisplayMatching`).
+
+## Config options
+
+Optional `electron-verify.config.json` in the app cwd (`.mcp.json` args/env remain primary):
+
+```json
+{
+  "appPath": "dist/main/index.js",
+  "cwd": ".",
+  "buildCommand": "node scripts/build.mjs",
+  "windowUrlMatch": "data:",
+  "criticalSelectors": ["#root", "[data-testid=sidebar]"],
+  "ignoreConsolePatterns": ["MyNoisyLibrary"],
+  "srcGlobs": ["src/**/*.{ts,tsx}"],
+  "strictConsole": false,
+  "thresholds": {
+    "readinessTimeoutMs": 10000,
+    "blankCoverage": 0.98,
+    "changeThreshold": 0.005,
+    "maxScreenshotWidth": 1280
+  }
+}
+```
+
+`app_launch` also accepts the same knobs inline: `buildCommand`, `windowUrlMatch`, `ignoreConsolePatterns`, `criticalSelectors`, `srcGlobs`, `args`, `env`, `strictConsole`.
+
+## CLI (one-shot)
+
+```bash
+electron-verify --app test/fixtures/good-app/main.js --cwd test/fixtures/good-app --out .
+# writes verify.png + verdict.json; exit 1 only on verdict FAIL
+
+electron-verify --app dist/main/index.js --build "npm run build" --expect "dashboard loads"
+electron-verify --app … --no-fresh              # skip reload (interaction-style check)
+electron-verify --app … --capture window        # default; composited Electron chrome
+electron-verify --app … --capture os-window     # full OS caption (min/max/close)
+electron-verify --app … --mode os-window        # --mode is an alias for --capture
+electron-verify --app … --capture content
+electron-verify --app … --strict-console        # console.error → FAIL
+```
+
+## Library use
+
+```ts
+import { AppSession, verify } from "electron-verify-mcp";
+
+const session = await AppSession.launch({ appPath: "dist/main/index.js", cwd: "." });
+const result = await verify(session, { expect: "dashboard", captureMode: "window" });
+await session.close();
+```
+
+## Development
+
+```bash
+npm test          # fixture suite
+npm run test:mcp  # real stdio MCP client smoke
+npm run typecheck
+npm run build
+```
+
+## License
+
+MIT © 2026 dpraj007

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,172 @@
+#!/usr/bin/env node
+/**
+ * CLI — one-shot: [build] → launch → verify → write verify.png + verdict.json → close.
+ * Exit 1 only on verdict === FAIL (WARN exits 0).
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { AppSession } from "./core/session.js";
+import { verify } from "./core/verify.js";
+import { loadConfig, findDefaultConfig } from "./core/config.js";
+function parseArgs(argv) {
+    const args = { out: "." };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const next = () => {
+            const v = argv[++i];
+            if (v === undefined)
+                throw new Error(`Missing value for ${a}`);
+            return v;
+        };
+        switch (a) {
+            case "--app":
+                args.app = next();
+                break;
+            case "--cwd":
+                args.cwd = next();
+                break;
+            case "--build":
+                args.build = next();
+                break;
+            case "--out":
+                args.out = next();
+                break;
+            case "--expect":
+                args.expect = next();
+                break;
+            case "--config":
+                args.config = next();
+                break;
+            case "--window-url-match":
+                args.windowUrlMatch = next();
+                break;
+            case "--no-fresh":
+                args.noFresh = true;
+                break;
+            case "--capture":
+            case "--capture-mode":
+            case "--mode": {
+                const v = next();
+                if (v !== "content" &&
+                    v !== "window" &&
+                    v !== "os-window" &&
+                    v !== "both") {
+                    throw new Error(`--capture must be content|window|os-window|both, got ${v}`);
+                }
+                args.captureMode = v;
+                break;
+            }
+            case "--strict-console":
+                args.strictConsole = true;
+                break;
+            case "--help":
+            case "-h":
+                printUsage();
+                process.exit(0);
+                break;
+            default:
+                throw new Error(`Unknown argument: ${a}`);
+        }
+    }
+    return args;
+}
+function printUsage() {
+    console.log(`Usage: electron-verify --app <mainEntry> [options]
+
+  --app                 Path to the app's main entry (required unless set in config)
+  --cwd                 App working directory (defaults to dirname of --app)
+  --build               Command to run in cwd before launch
+  --out                 Directory for verify.png + verdict.json (default: .)
+  --expect <text>       Intent string echoed into verdict.json
+  --config <file>       Optional electron-verify.config.json
+  --window-url-match    Force target window URL substring
+  --no-fresh            Skip reload-before-verify (use for interaction flows)
+  --capture <mode>      window (default) | content | os-window | both
+  --mode <mode>         Alias for --capture
+  --strict-console      Promote bare console.error to hard-FAIL
+
+  Capture modes:
+    window     Composited Electron window (menu bar + content; no OS caption)
+    os-window  Full OS window including caption bar (min/max/close buttons)
+    content    Web viewport only (also used for all signal analysis)
+    both       content + window images
+`);
+}
+async function main() {
+    const opts = parseArgs(process.argv.slice(2));
+    const configPath = opts.config ?? findDefaultConfig(opts.cwd ?? process.cwd());
+    const config = loadConfig(configPath);
+    const appPath = opts.app ?? config.appPath;
+    if (!appPath)
+        throw new Error("--app <mainEntry> is required (or set appPath in config)");
+    const cwd = opts.cwd ?? config.cwd;
+    const buildCommand = opts.build ?? config.buildCommand;
+    const windowUrlMatch = opts.windowUrlMatch ?? config.windowUrlMatch;
+    const captureMode = opts.captureMode ?? "window";
+    const strictConsole = opts.strictConsole ?? config.strictConsole;
+    const outDir = path.resolve(opts.out);
+    fs.mkdirSync(outDir, { recursive: true });
+    const pngPath = path.join(outDir, "verify.png");
+    const jsonPath = path.join(outDir, "verdict.json");
+    let session;
+    try {
+        session = await AppSession.launch({
+            appPath,
+            cwd,
+            buildCommand,
+            executablePath: config.executablePath,
+            windowUrlMatch,
+            ignoreConsolePatterns: config.ignoreConsolePatterns,
+            criticalSelectors: config.criticalSelectors,
+            srcGlobs: config.srcGlobs,
+            strictConsole,
+        });
+        const result = await verify(session, {
+            expect: opts.expect,
+            windowUrlMatch,
+            criticalSelectors: config.criticalSelectors,
+            srcGlobs: config.srcGlobs,
+            readinessTimeoutMs: config.thresholds?.readinessTimeoutMs,
+            maxScreenshotWidth: config.thresholds?.maxScreenshotWidth,
+            blankCoverage: config.thresholds?.blankCoverage,
+            changeThreshold: config.thresholds?.changeThreshold,
+            // Default freshLoad=true for one-shot boot verify; --no-fresh for interactions.
+            freshLoad: opts.noFresh ? false : true,
+            captureMode,
+            strictConsole,
+        });
+        fs.writeFileSync(pngPath, result.screenshot);
+        if (captureMode === "both" && result.contentScreenshot) {
+            fs.writeFileSync(path.join(outDir, "verify-content.png"), result.contentScreenshot);
+        }
+        if (captureMode === "both" && result.windowScreenshot) {
+            fs.writeFileSync(path.join(outDir, "verify-window.png"), result.windowScreenshot);
+        }
+        const verdictJson = {
+            verdict: result.verdict,
+            hardFails: result.hardFails,
+            warns: result.warns,
+            signals: result.signals,
+            ...(result.expect !== undefined ? { expect: result.expect } : {}),
+            windowStrategy: result.windowStrategy,
+            windowWarning: result.windowWarning,
+            holes: result.holes,
+            captureMode: result.captureMode,
+            ...(result.captureNote ? { captureNote: result.captureNote } : {}),
+        };
+        fs.writeFileSync(jsonPath, JSON.stringify(verdictJson, null, 2));
+        const failBit = result.hardFails.length > 0 ? ` hardFails=${result.hardFails.join(",")}` : "";
+        const warnBit = result.warns.length > 0 ? ` warns=${result.warns.join(",")}` : "";
+        console.log(`${result.verdict}${failBit}${warnBit} capture=${result.captureMode} png=${pngPath} (${result.screenshot.length} bytes) json=${jsonPath}`);
+        process.exitCode = result.verdict === "FAIL" ? 1 : 0;
+    }
+    finally {
+        if (session)
+            await session.close();
+    }
+}
+main().catch((err) => {
+    const msg = err instanceof Error ? (err.stack ?? err.message) : String(err);
+    console.error(msg);
+    process.exit(1);
+});

package/dist/core/config.d.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+/**
+ * Optional electron-verify.config.json schema.
+ * .mcp.json env/args remain primary; this file is optional convenience.
+ */
+export declare const ConfigSchema: z.ZodObject<{
+    appPath: z.ZodOptional<z.ZodString>;
+    cwd: z.ZodOptional<z.ZodString>;
+    buildCommand: z.ZodOptional<z.ZodString>;
+    executablePath: z.ZodOptional<z.ZodString>;
+    windowUrlMatch: z.ZodOptional<z.ZodString>;
+    criticalSelectors: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ignoreConsolePatterns: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    srcGlobs: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    strictConsole: z.ZodOptional<z.ZodBoolean>;
+    thresholds: z.ZodOptional<z.ZodObject<{
+        readinessTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        /** Dominant-color coverage for blank-screen pixel check (default 0.98). */
+        blankCoverage: z.ZodOptional<z.ZodNumber>;
+        /** Max pixel-change fraction for readiness stability (default 0.005). */
+        changeThreshold: z.ZodOptional<z.ZodNumber>;
+        maxScreenshotWidth: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        changeThreshold?: number | undefined;
+        readinessTimeoutMs?: number | undefined;
+        blankCoverage?: number | undefined;
+        maxScreenshotWidth?: number | undefined;
+    }, {
+        changeThreshold?: number | undefined;
+        readinessTimeoutMs?: number | undefined;
+        blankCoverage?: number | undefined;
+        maxScreenshotWidth?: number | undefined;
+    }>>;
+}, "strict", z.ZodTypeAny, {
+    executablePath?: string | undefined;
+    cwd?: string | undefined;
+    windowUrlMatch?: string | undefined;
+    ignoreConsolePatterns?: string[] | undefined;
+    criticalSelectors?: string[] | undefined;
+    strictConsole?: boolean | undefined;
+    appPath?: string | undefined;
+    buildCommand?: string | undefined;
+    srcGlobs?: string[] | undefined;
+    thresholds?: {
+        changeThreshold?: number | undefined;
+        readinessTimeoutMs?: number | undefined;
+        blankCoverage?: number | undefined;
+        maxScreenshotWidth?: number | undefined;
+    } | undefined;
+}, {
+    executablePath?: string | undefined;
+    cwd?: string | undefined;
+    windowUrlMatch?: string | undefined;
+    ignoreConsolePatterns?: string[] | undefined;
+    criticalSelectors?: string[] | undefined;
+    strictConsole?: boolean | undefined;
+    appPath?: string | undefined;
+    buildCommand?: string | undefined;
+    srcGlobs?: string[] | undefined;
+    thresholds?: {
+        changeThreshold?: number | undefined;
+        readinessTimeoutMs?: number | undefined;
+        blankCoverage?: number | undefined;
+        maxScreenshotWidth?: number | undefined;
+    } | undefined;
+}>;
+export type ElectronVerifyConfig = z.infer<typeof ConfigSchema>;
+/**
+ * Load and zod-validate an optional config file.
+ * Returns `{}` when path is missing / not provided.
+ */
+export declare function loadConfig(configPath?: string): ElectronVerifyConfig;
+/** Resolve config path: explicit arg, else ./electron-verify.config.json if present. */
+export declare function findDefaultConfig(cwd?: string): string | undefined;

package/dist/core/config.js

@@ -0,0 +1,55 @@
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+/**
+ * Optional electron-verify.config.json schema.
+ * .mcp.json env/args remain primary; this file is optional convenience.
+ */
+export const ConfigSchema = z
+    .object({
+    appPath: z.string().optional(),
+    cwd: z.string().optional(),
+    buildCommand: z.string().optional(),
+    executablePath: z.string().optional(),
+    windowUrlMatch: z.string().optional(),
+    criticalSelectors: z.array(z.string()).optional(),
+    ignoreConsolePatterns: z.array(z.string()).optional(),
+    srcGlobs: z.array(z.string()).optional(),
+    strictConsole: z.boolean().optional(),
+    thresholds: z
+        .object({
+        readinessTimeoutMs: z.number().optional(),
+        /** Dominant-color coverage for blank-screen pixel check (default 0.98). */
+        blankCoverage: z.number().optional(),
+        /** Max pixel-change fraction for readiness stability (default 0.005). */
+        changeThreshold: z.number().optional(),
+        maxScreenshotWidth: z.number().optional(),
+    })
+        .optional(),
+})
+    .strict();
+/**
+ * Load and zod-validate an optional config file.
+ * Returns `{}` when path is missing / not provided.
+ */
+export function loadConfig(configPath) {
+    if (!configPath)
+        return {};
+    const abs = path.resolve(configPath);
+    if (!fs.existsSync(abs)) {
+        throw new Error(`Config file not found: ${abs}`);
+    }
+    const raw = JSON.parse(fs.readFileSync(abs, "utf8"));
+    const parsed = ConfigSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`Invalid electron-verify config: ${parsed.error.issues
+            .map((i) => `${i.path.join(".")}: ${i.message}`)
+            .join("; ")}`);
+    }
+    return parsed.data;
+}
+/** Resolve config path: explicit arg, else ./electron-verify.config.json if present. */
+export function findDefaultConfig(cwd = process.cwd()) {
+    const candidate = path.join(cwd, "electron-verify.config.json");
+    return fs.existsSync(candidate) ? candidate : undefined;
+}

package/dist/core/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Public core API for electron-verify-mcp (library consumers).
+ */
+export { verify, scaleHolesToPhysical, type VerifyOptions, type VerifyResult } from "./verify.js";
+export { AppSession, type SessionLaunchOptions } from "./session.js";
+export { launchApp, resolveElectron, runBuildCommand, type LaunchOptions } from "./launch.js";
+export { computeVerdict, type VerdictOptions } from "./verdict.js";
+export { loadConfig, findDefaultConfig, ConfigSchema, type ElectronVerifyConfig } from "./config.js";
+export { waitUntilReady, type ReadinessOptions } from "./readiness.js";
+export { captureScreenshot, captureRawScreenshot, annotateHoles, downscaleIfNeeded, type CaptureOptions, } from "./screenshot.js";
+export { captureWindow, captureOsWindow, type WindowCaptureResult, } from "./windowCapture.js";
+export { selectTargetWindow, detectHoles, type SelectWindowOptions, type SelectWindowResult } from "./windows.js";
+export { clickEl, typeEl, waitForSel, evalJs, resolveSelector, type WaitBy } from "./interact.js";
+export { collectSignals, type CollectOptions } from "./signals/collect.js";
+export { ConsoleCollector, DEFAULT_IGNORE_PATTERNS } from "./signals/console.js";
+export type { Verdict, CaptureMode, CaptureModeUsed, Signals, ConsoleSignal, ConsoleMessage, VerdictResult, HoleRect, ReadinessSignal, BlankScreenSignal, LayoutSignal, ResourceSignal, MainProcessSignal, StaleBuildSignal, } from "./types.js";

package/dist/core/index.js

@@ -0,0 +1,15 @@
+/**
+ * Public core API for electron-verify-mcp (library consumers).
+ */
+export { verify, scaleHolesToPhysical } from "./verify.js";
+export { AppSession } from "./session.js";
+export { launchApp, resolveElectron, runBuildCommand } from "./launch.js";
+export { computeVerdict } from "./verdict.js";
+export { loadConfig, findDefaultConfig, ConfigSchema } from "./config.js";
+export { waitUntilReady } from "./readiness.js";
+export { captureScreenshot, captureRawScreenshot, annotateHoles, downscaleIfNeeded, } from "./screenshot.js";
+export { captureWindow, captureOsWindow, } from "./windowCapture.js";
+export { selectTargetWindow, detectHoles } from "./windows.js";
+export { clickEl, typeEl, waitForSel, evalJs, resolveSelector } from "./interact.js";
+export { collectSignals } from "./signals/collect.js";
+export { ConsoleCollector, DEFAULT_IGNORE_PATTERNS } from "./signals/console.js";

package/dist/core/interact.d.ts

@@ -0,0 +1,40 @@
+import type { Page } from "playwright-core";
+/**
+ * Tiny interaction helpers for a Playwright Page.
+ * Used by the MCP layer; keep logic here so the server stays thin.
+ */
+export declare function clickEl(page: Page, selector: string): Promise<void>;
+export declare function typeEl(page: Page, selector: string, text: string): Promise<void>;
+export type WaitBy = "selector" | "text";
+/**
+ * Wait for a CSS selector or visible text.
+ *
+ * Heuristic (when `by` is omitted):
+ * - Starts with `.` / `#` / `[` → CSS selector
+ * - Contains selector chars (`>`, `:`, `[`, `]`, `+`, `~`) → CSS selector
+ * - Explicit Playwright engines (`text=`, `css=`, `xpath=`, …) → as-is
+ * - Otherwise → Playwright `text=` / getByText semantics
+ *
+ * Single-word plain labels like "Submit" are text matches, not tag selectors.
+ */
+export declare function waitForSel(page: Page, selectorOrText: string, opts?: {
+    timeoutMs?: number;
+    by?: WaitBy;
+}): Promise<void>;
+/**
+ * Evaluate a JS expression (or statement body) in the page.
+ *
+ * Passes the string directly to `page.evaluate` so Playwright uses CDP
+ * `Runtime.evaluate` — CSP-safe (no `new Function` / unsafe-eval in the renderer).
+ *
+ * Default: expression form (`document.title`, `{a:1}`).
+ * Pass `{ asStatement: true }` for a statement body that ends with `return …`.
+ */
+export declare function evalJs(page: Page, expression: string, opts?: {
+    asStatement?: boolean;
+}): Promise<unknown>;
+/**
+ * Resolve target → Playwright selector string.
+ * Exported for tests.
+ */
+export declare function resolveSelector(selectorOrText: string): string;

package/dist/core/interact.js

@@ -0,0 +1,98 @@
+/**
+ * Tiny interaction helpers for a Playwright Page.
+ * Used by the MCP layer; keep logic here so the server stays thin.
+ */
+export async function clickEl(page, selector) {
+    await page.click(selector);
+}
+export async function typeEl(page, selector, text) {
+    await page.fill(selector, text);
+}
+/**
+ * Wait for a CSS selector or visible text.
+ *
+ * Heuristic (when `by` is omitted):
+ * - Starts with `.` / `#` / `[` → CSS selector
+ * - Contains selector chars (`>`, `:`, `[`, `]`, `+`, `~`) → CSS selector
+ * - Explicit Playwright engines (`text=`, `css=`, `xpath=`, …) → as-is
+ * - Otherwise → Playwright `text=` / getByText semantics
+ *
+ * Single-word plain labels like "Submit" are text matches, not tag selectors.
+ */
+export async function waitForSel(page, selectorOrText, opts = {}) {
+    const timeout = opts.timeoutMs ?? 10_000;
+    if (opts.by === "text") {
+        await page.getByText(selectorOrText, { exact: false }).first().waitFor({
+            state: "visible",
+            timeout,
+        });
+        return;
+    }
+    if (opts.by === "selector") {
+        await page.waitForSelector(selectorOrText, { timeout, state: "visible" });
+        return;
+    }
+    const sel = resolveSelector(selectorOrText);
+    if (sel.startsWith("text=")) {
+        const text = sel.slice("text=".length);
+        await page.getByText(text, { exact: false }).first().waitFor({
+            state: "visible",
+            timeout,
+        });
+        return;
+    }
+    await page.waitForSelector(sel, { timeout, state: "visible" });
+}
+/**
+ * Evaluate a JS expression (or statement body) in the page.
+ *
+ * Passes the string directly to `page.evaluate` so Playwright uses CDP
+ * `Runtime.evaluate` — CSP-safe (no `new Function` / unsafe-eval in the renderer).
+ *
+ * Default: expression form (`document.title`, `{a:1}`).
+ * Pass `{ asStatement: true }` for a statement body that ends with `return …`.
+ */
+export async function evalJs(page, expression, opts = {}) {
+    const src = expression.trim();
+    if (!src)
+        throw new Error("expression is empty");
+    if (opts.asStatement) {
+        // Playwright accepts a string function body via evaluate when given a string.
+        // Wrap as an async IIFE body so multi-statement scripts work.
+        return page.evaluate(`(async () => { ${src} })()`);
+    }
+    // Direct expression — Playwright compiles via Runtime.evaluate (CSP-exempt).
+    return page.evaluate(src);
+}
+/**
+ * Resolve target → Playwright selector string.
+ * Exported for tests.
+ */
+export function resolveSelector(selectorOrText) {
+    const s = selectorOrText.trim();
+    if (!s)
+        return s;
+    if (s.startsWith("text=") ||
+        s.startsWith("css=") ||
+        s.startsWith("xpath=") ||
+        s.startsWith("id=") ||
+        s.startsWith("role=") ||
+        s.startsWith("internal:") ||
+        s.startsWith("//")) {
+        return s;
+    }
+    // CSS selector: starts with . # [ or contains combinators / attribute / pseudo.
+    if (/^[.#\[]/.test(s))
+        return s;
+    if (/[>\[\]+~]/.test(s))
+        return s;
+    // Pseudo-class like button:hover or #id:nth-child — has `:` with selector-ish form.
+    if (/:[a-zA-Z]/.test(s) && !/\s/.test(s))
+        return s;
+    // Tag with class/id: div.foo, span#bar
+    if (/^[a-zA-Z][\w-]*[#.]/.test(s))
+        return s;
+    // Compound like "div > span" already caught by `>`; bare multi-token CSS rare.
+    // Plain text (including single-word labels like "Submit") → text match.
+    return `text=${s}`;
+}