@rolepod/uiproof 0.4.0

package/dist/bin/rolepod-uiproof.js

@@ -0,0 +1,2530 @@
+#!/usr/bin/env node
+
+// bin/rolepod-uiproof.ts
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+
+// src/cli/doctor.ts
+import { existsSync } from "fs";
+import { resolve, join } from "path";
+import { homedir, platform as osPlatform } from "os";
+async function runDoctor() {
+  const checks = [];
+  const major = Number(process.versions.node.split(".")[0]);
+  checks.push({
+    name: "Node \u226520",
+    status: major >= 20 ? "ok" : "fail",
+    detail: process.versions.node
+  });
+  checks.push(checkPlaywrightChromium());
+  checks.push(await checkWebdriverIO());
+  checks.push(await checkAppiumServer());
+  if (osPlatform() === "darwin") {
+    checks.push(checkXcode());
+  }
+  checks.push(checkAndroidSdk());
+  checks.push({
+    name: "SeleniumEngine (roadmap v0.4)",
+    status: "warn",
+    detail: "Not implemented \u2014 deferred to v0.4 (legacy Selenium grid support, opt-in via ROLEPOD_MCP_WEB_ENGINE=selenium)."
+  });
+  checks.push(checkArtifactDir());
+  print(checks);
+  const failed = checks.some((c) => c.status === "fail");
+  return failed ? 1 : 0;
+}
+function checkPlaywrightChromium() {
+  const candidates = [
+    join(homedir(), "Library", "Caches", "ms-playwright"),
+    join(homedir(), ".cache", "ms-playwright"),
+    process.env.PLAYWRIGHT_BROWSERS_PATH
+  ].filter((x) => typeof x === "string");
+  for (const base of candidates) {
+    if (existsSync(base)) {
+      return {
+        name: "Playwright Chromium installed",
+        status: "ok",
+        detail: base
+      };
+    }
+  }
+  return {
+    name: "Playwright Chromium installed",
+    status: "fail",
+    detail: "Run: npx playwright install chromium"
+  };
+}
+async function checkWebdriverIO() {
+  try {
+    const url = await import.meta.resolve?.("webdriverio");
+    return {
+      name: "webdriverio (mobile client, v0.3)",
+      status: "ok",
+      detail: url ?? "resolved"
+    };
+  } catch {
+    return {
+      name: "webdriverio (mobile client, v0.3)",
+      status: "warn",
+      detail: "Not installed \u2014 web works fine without it. Mobile is roadmap v0.3. For mobile: npm i webdriverio"
+    };
+  }
+}
+async function checkAppiumServer() {
+  const host = process.env.APPIUM_HOST ?? "127.0.0.1";
+  const port = Number(process.env.APPIUM_PORT ?? 4723);
+  const path = process.env.APPIUM_BASE_PATH ?? "/";
+  const url = `http://${host}:${port}${path.endsWith("/") ? path : path + "/"}status`;
+  try {
+    const ctrl = new AbortController();
+    const timeout = setTimeout(() => ctrl.abort(), 1500);
+    const res = await fetch(url, { signal: ctrl.signal });
+    clearTimeout(timeout);
+    return {
+      name: "Appium server (roadmap v0.3)",
+      status: res.ok ? "ok" : "warn",
+      detail: `${url} \u2192 HTTP ${res.status}`
+    };
+  } catch {
+    return {
+      name: "Appium server (roadmap v0.3)",
+      status: "warn",
+      detail: `Not reachable at ${url} \u2014 mobile sessions need a running Appium daemon. Web sessions are unaffected.`
+    };
+  }
+}
+function checkXcode() {
+  const path = "/Applications/Xcode.app";
+  if (existsSync(path)) {
+    return { name: "Xcode (iOS, roadmap v0.3)", status: "ok", detail: path };
+  }
+  return {
+    name: "Xcode (iOS, roadmap v0.3)",
+    status: "warn",
+    detail: "Install Xcode via the App Store; required for iOS simulators. Not needed for web targets."
+  };
+}
+function checkAndroidSdk() {
+  const candidates = [
+    process.env.ANDROID_HOME,
+    process.env.ANDROID_SDK_ROOT,
+    join(homedir(), "Library", "Android", "sdk"),
+    join(homedir(), "Android", "Sdk")
+  ].filter((x) => typeof x === "string");
+  for (const path of candidates) {
+    if (existsSync(path)) {
+      return { name: "Android SDK (roadmap v0.3)", status: "ok", detail: path };
+    }
+  }
+  return {
+    name: "Android SDK (roadmap v0.3)",
+    status: "warn",
+    detail: "Set ANDROID_HOME \u2014 needed only for Android testing. Not needed for web or iOS targets."
+  };
+}
+function checkArtifactDir() {
+  const dir = resolve(process.cwd(), ".rolepod-uiproof");
+  return {
+    name: "Artifact root writable",
+    status: "ok",
+    detail: `Will be created at: ${dir}/artifacts/{run_id}/`
+  };
+}
+function print(checks) {
+  const icon = (s) => s === "ok" ? "\u2713" : s === "warn" ? "\u2022" : "\u2717";
+  for (const c of checks) {
+    process.stdout.write(`  ${icon(c.status)} ${c.name.padEnd(30)} ${c.detail}
+`);
+  }
+}
+
+// src/cli/install_mobile.ts
+import { platform as osPlatform2 } from "os";
+function runInstallMobile() {
+  const os = osPlatform2();
+  const lines = [];
+  lines.push("rolepod-uiproof install:mobile \u2014 setup checklist\n");
+  lines.push("Mobile support is OPTIONAL. Skip if you only target the web.\n");
+  lines.push("1. Install the Node client:");
+  lines.push("     npm install webdriverio\n");
+  lines.push("2. Install the Appium server (2.x):");
+  lines.push("     npm install -g appium");
+  lines.push("     appium driver install xcuitest      # iOS");
+  lines.push("     appium driver install uiautomator2  # Android");
+  lines.push("     appium                              # leave running\n");
+  if (os === "darwin") {
+    lines.push("3. iOS \u2014 macOS host required:");
+    lines.push("     \u2022 Install Xcode + Command Line Tools");
+    lines.push("     \u2022 Open Xcode \u2192 Settings \u2192 Platforms \u2192 install an iOS Simulator");
+    lines.push("     \u2022 `xcrun simctl list devices` confirms a device is available\n");
+  } else {
+    lines.push("3. iOS: not supported on this OS (macOS host required).\n");
+  }
+  lines.push("4. Android \u2014 any host:");
+  lines.push("     \u2022 Install Android Studio OR command-line tools");
+  lines.push("     \u2022 Set ANDROID_HOME to the SDK location");
+  lines.push("     \u2022 `adb devices` confirms an emulator or device is reachable\n");
+  lines.push("5. Verify:");
+  lines.push("     npx rolepod-uiproof doctor\n");
+  lines.push("Environment overrides (optional):");
+  lines.push("     APPIUM_HOST       default: 127.0.0.1");
+  lines.push("     APPIUM_PORT       default: 4723");
+  lines.push("     APPIUM_BASE_PATH  default: /");
+  for (const l of lines) process.stdout.write(l + "\n");
+  return 0;
+}
+
+// src/cli/replay.ts
+import { readFile } from "fs/promises";
+import { resolve as resolve3 } from "path";
+
+// src/artifact/ArtifactStore.ts
+import { randomUUID } from "crypto";
+import { mkdir, writeFile } from "fs/promises";
+import { resolve as resolve2 } from "path";
+
+// src/util/log.ts
+function emit(level, msg, extra) {
+  const line = JSON.stringify({
+    ts: (/* @__PURE__ */ new Date()).toISOString(),
+    level,
+    msg,
+    ...extra !== void 0 ? { extra } : {}
+  });
+  process.stderr.write(line + "\n");
+}
+var log = {
+  info: (msg, extra) => emit("info", msg, extra),
+  warn: (msg, extra) => emit("warn", msg, extra),
+  error: (msg, extra) => emit("error", msg, extra),
+  debug: (msg, extra) => {
+    if (process.env.ROLEPOD_MCP_DEBUG) emit("debug", msg, extra);
+  }
+};
+
+// src/artifact/ArtifactStore.ts
+var ArtifactStore = class {
+  rootDir;
+  constructor(opts = {}) {
+    this.rootDir = opts.rootDir ?? resolve2(process.cwd(), ".rolepod-uiproof", "artifacts");
+  }
+  /** Allocate a fresh run id and ensure its directory exists. */
+  async startRun(prefix = "run") {
+    const runId = `${prefix}_${this.timestampSlug()}_${randomUUID().slice(0, 8)}`;
+    const runDir = resolve2(this.rootDir, runId);
+    await mkdir(runDir, { recursive: true });
+    log.debug("artifact run started", { run_id: runId, dir: runDir });
+    return { runId, runDir };
+  }
+  async writeScreenshot(runDir, buf, name) {
+    const path = resolve2(runDir, `${name}.png`);
+    await writeFile(path, buf);
+    return path;
+  }
+  async writeReplayBundle(runDir, bundle, name = "replay.json") {
+    const path = resolve2(runDir, name);
+    await writeFile(path, JSON.stringify(bundle, null, 2), "utf8");
+    return path;
+  }
+  async writeReport(runDir, name, body) {
+    const path = resolve2(runDir, name);
+    await writeFile(path, body, "utf8");
+    return path;
+  }
+  async writeBytes(runDir, name, buf) {
+    const path = resolve2(runDir, name);
+    await writeFile(path, buf);
+    return path;
+  }
+  async ensureDir(absDir) {
+    await mkdir(absDir, { recursive: true });
+    return absDir;
+  }
+  /** Root for stored visual baselines: `./.rolepod-uiproof/baselines/`. */
+  get baselineDir() {
+    return resolve2(this.rootDir, "..", "baselines");
+  }
+  timestampSlug() {
+    const d = /* @__PURE__ */ new Date();
+    const pad = (n) => String(n).padStart(2, "0");
+    return `${d.getUTCFullYear()}` + pad(d.getUTCMonth() + 1) + pad(d.getUTCDate()) + "T" + pad(d.getUTCHours()) + pad(d.getUTCMinutes()) + pad(d.getUTCSeconds());
+  }
+};
+
+// src/util/errors.ts
+var RolepodMcpError = class extends Error {
+  constructor(code, message, detail) {
+    super(message);
+    this.code = code;
+    this.detail = detail;
+  }
+  code;
+  detail;
+  name = "RolepodMcpError";
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      ...this.detail ? { detail: this.detail } : {}
+    };
+  }
+};
+var UnknownRefError = class extends RolepodMcpError {
+  constructor(sessionId, ref) {
+    super("unknown_ref", `Ref "${ref}" was not found in the current snapshot.`, {
+      session_id: sessionId,
+      ref
+    });
+  }
+};
+var UnknownSessionError = class extends RolepodMcpError {
+  constructor(sessionId) {
+    super("unknown_session", `No open session with id "${sessionId}".`, {
+      session_id: sessionId
+    });
+  }
+};
+var UnsupportedPlatformError = class extends RolepodMcpError {
+  constructor(platform) {
+    super(
+      "unsupported_platform",
+      `Platform "${platform}" is not supported in v0.1 \u2014 only "web" is implemented. Mobile (ios/android) ships in v0.3.`,
+      { platform }
+    );
+  }
+};
+
+// src/engine/AppiumEngine.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/engine/a11y/uiautomator2.ts
+import { XMLParser } from "fast-xml-parser";
+var parser = new XMLParser({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@",
+  alwaysCreateTextNode: false,
+  preserveOrder: true
+});
+function parseUiAutomator2Tree(xmlString) {
+  const refIndex = /* @__PURE__ */ new Map();
+  let counter = 0;
+  const nextRef = () => `e${++counter}`;
+  let raw = [];
+  try {
+    raw = parser.parse(xmlString);
+  } catch {
+    raw = [];
+  }
+  const visit = (node, siblingOcc) => {
+    const tagName = firstTagName(node);
+    if (!tagName) return null;
+    const attrs = node[":@"] ?? {};
+    const childrenRaw = node[tagName] ?? [];
+    const idx = (siblingOcc.get(tagName) ?? 0) + 1;
+    siblingOcc.set(tagName, idx);
+    const ref = nextRef();
+    refIndex.set(ref, {
+      kind: "android",
+      resourceId: attrs["@resource-id"],
+      contentDesc: attrs["@content-desc"],
+      text: attrs["@text"],
+      androidClass: tagName,
+      classIndex: idx
+    });
+    const role = simplifyAndroidClass(tagName);
+    const a11y = { ref, role };
+    const name = attrs["@content-desc"] ?? attrs["@text"];
+    if (name) a11y.name = name;
+    if (attrs["@text"] && attrs["@text"] !== name) a11y.value = attrs["@text"];
+    const state = {};
+    if (attrs["@enabled"] === "false") state.disabled = true;
+    if (attrs["@focused"] === "true") state.focused = true;
+    if (attrs["@selected"] === "true") state.selected = true;
+    if (Object.keys(state).length > 0) a11y.state = state;
+    if (childrenRaw.length > 0) {
+      const siblings = /* @__PURE__ */ new Map();
+      const children = [];
+      for (const child of childrenRaw) {
+        const built = visit(child, siblings);
+        if (built) children.push(built);
+      }
+      if (children.length > 0) a11y.children = children;
+    }
+    return a11y;
+  };
+  const hierarchy = raw.find((n) => Object.keys(n).some((k) => k === "hierarchy")) ?? raw[0];
+  if (!hierarchy) {
+    return {
+      tree: { ref: "e0", role: "RootWebArea" },
+      refIndex
+    };
+  }
+  const top = visit(hierarchy, /* @__PURE__ */ new Map());
+  if (top) return { tree: top, refIndex };
+  return { tree: { ref: "e0", role: "RootWebArea" }, refIndex };
+}
+function firstTagName(node) {
+  for (const key of Object.keys(node)) {
+    if (key === ":@") continue;
+    if (key.startsWith("?")) continue;
+    return key;
+  }
+  return null;
+}
+function simplifyAndroidClass(cls) {
+  const last = cls.split(".").pop();
+  return last ?? cls;
+}
+
+// src/engine/a11y/xcuitest.ts
+import { XMLParser as XMLParser2 } from "fast-xml-parser";
+var parser2 = new XMLParser2({
+  ignoreAttributes: false,
+  attributeNamePrefix: "@",
+  alwaysCreateTextNode: false,
+  preserveOrder: true
+});
+function parseXcuiTestTree(xmlString) {
+  const refIndex = /* @__PURE__ */ new Map();
+  let counter = 0;
+  const nextRef = () => `e${++counter}`;
+  let raw = [];
+  try {
+    raw = parser2.parse(xmlString);
+  } catch {
+    raw = [];
+  }
+  const visit = (node, classChainOcc) => {
+    const tagName = firstTagName2(node);
+    if (!tagName) return null;
+    const attrs = node[":@"] ?? {};
+    const childrenRaw = node[tagName] ?? [];
+    const idx = (classChainOcc.get(tagName) ?? 0) + 1;
+    classChainOcc.set(tagName, idx);
+    const ref = nextRef();
+    refIndex.set(ref, {
+      kind: "ios",
+      accessibilityId: attrs["@name"],
+      name: attrs["@name"],
+      label: attrs["@label"],
+      type: tagName,
+      classChainIndex: idx
+    });
+    const role = tagName.startsWith("XCUIElementType") ? tagName.slice("XCUIElementType".length).toLowerCase() : tagName;
+    const a11y = { ref, role };
+    const name = attrs["@label"] ?? attrs["@name"];
+    if (name) a11y.name = name;
+    if (attrs["@value"]) a11y.value = attrs["@value"];
+    const state = {};
+    if (attrs["@enabled"] === "false") state.disabled = true;
+    if (attrs["@selected"] === "true") state.selected = true;
+    if (Object.keys(state).length > 0) a11y.state = state;
+    if (childrenRaw.length > 0) {
+      const siblings = /* @__PURE__ */ new Map();
+      const children = [];
+      for (const child of childrenRaw) {
+        const built = visit(child, siblings);
+        if (built) children.push(built);
+      }
+      if (children.length > 0) a11y.children = children;
+    }
+    return a11y;
+  };
+  const topLevel = [];
+  const rootOcc = /* @__PURE__ */ new Map();
+  for (const node of raw) {
+    const built = visit(node, rootOcc);
+    if (built) topLevel.push(built);
+  }
+  if (topLevel.length === 1) {
+    return { tree: topLevel[0], refIndex };
+  }
+  const rootRef = nextRef();
+  refIndex.set(rootRef, {
+    kind: "ios",
+    type: "XCUIElementTypeApplication",
+    classChainIndex: 1
+  });
+  const root = { ref: rootRef, role: "application" };
+  if (topLevel.length > 0) root.children = topLevel;
+  return { tree: root, refIndex };
+}
+function firstTagName2(node) {
+  for (const key of Object.keys(node)) {
+    if (key === ":@") continue;
+    if (key.startsWith("?")) continue;
+    return key;
+  }
+  return null;
+}
+
+// src/engine/AppiumEngine.ts
+var AppiumEngine = class {
+  id = "appium";
+  sessions = /* @__PURE__ */ new Map();
+  wdioCache = null;
+  async open(opts) {
+    if (opts.platform !== "ios" && opts.platform !== "android") {
+      throw new UnsupportedPlatformError(opts.platform);
+    }
+    const remote = await this.loadWdio();
+    const caps = this.buildCapabilities(opts);
+    const driver = await remote({
+      hostname: process.env.APPIUM_HOST ?? "127.0.0.1",
+      port: Number(process.env.APPIUM_PORT ?? 4723),
+      path: process.env.APPIUM_BASE_PATH ?? "/",
+      capabilities: caps
+    });
+    const sessionId = randomUUID2();
+    const session = { id: sessionId, platform: opts.platform, driver };
+    this.sessions.set(sessionId, {
+      session,
+      refIndex: /* @__PURE__ */ new Map(),
+      snapshotGeneration: 0,
+      refGeneration: -1,
+      lastSnapshotAt: null
+    });
+    log.info("mobile session opened", {
+      session_id: sessionId,
+      platform: opts.platform,
+      remote_session: driver.sessionId
+    });
+    return { id: sessionId, platform: opts.platform };
+  }
+  async close(session) {
+    const s = this.requireSession(session.id);
+    await s.session.driver.deleteSession().catch(
+      (err) => log.warn("appium deleteSession failed", { session_id: session.id, err: String(err) })
+    );
+    this.sessions.delete(session.id);
+    log.info("mobile session closed", { session_id: session.id });
+  }
+  async snapshot(session, _mode) {
+    void _mode;
+    const s = this.requireSession(session.id);
+    const xml = await s.session.driver.getPageSource();
+    const normalized = s.session.platform === "ios" ? parseXcuiTestTree(xml) : parseUiAutomator2Tree(xml);
+    s.snapshotGeneration += 1;
+    s.refGeneration = s.snapshotGeneration;
+    s.refIndex = normalized.refIndex;
+    s.lastSnapshotAt = (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      session_id: session.id,
+      platform: s.session.platform,
+      url_or_screen: this.screenIdentifier(s),
+      taken_at: s.lastSnapshotAt,
+      tree: normalized.tree
+    };
+  }
+  async click(session, ref) {
+    const s = this.requireSession(session.id);
+    const el = await this.resolveElement(s, ref);
+    await el.click();
+    this.invalidateRefs(s);
+  }
+  async type(session, ref, text, opts) {
+    const s = this.requireSession(session.id);
+    const el = await this.resolveElement(s, ref);
+    if (opts?.clearFirst) await el.clearValue();
+    await el.setValue(text);
+    this.invalidateRefs(s);
+  }
+  async key(session, key) {
+    const s = this.requireSession(session.id);
+    if (s.session.platform === "android" && s.session.driver.pressKeyCode) {
+      const code = ANDROID_KEY_CODES[key];
+      if (code !== void 0) {
+        await s.session.driver.pressKeyCode(code);
+        this.invalidateRefs(s);
+        return;
+      }
+    }
+    throw new RolepodMcpError(
+      "not_implemented_in_v02",
+      `Mobile key("${key}") is partially supported in v0.3 \u2014 only well-known Android keycodes are mapped. iOS hardware keys land later.`,
+      { platform: s.session.platform, key }
+    );
+  }
+  async scroll(session, dir, amount = 400, _ref) {
+    void _ref;
+    const s = this.requireSession(session.id);
+    const action = s.session.platform === "ios" ? "mobile: swipe" : "mobile: scrollGesture";
+    const params = s.session.platform === "ios" ? { direction: dir } : { left: 100, top: 200, width: 400, height: 600, direction: dir, percent: amount / 1e3 };
+    await s.session.driver.execute(action, params).catch((err) => log.warn("scroll gesture failed", { err: String(err) }));
+    this.invalidateRefs(s);
+  }
+  async waitFor(session, cond, timeoutMs = 1e4) {
+    const s = this.requireSession(session.id);
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      if (cond.kind === "idle") {
+        await s.session.driver.pause(cond.ms);
+        this.invalidateRefs(s);
+        return;
+      }
+      const snap = await this.snapshot(session);
+      const matched = cond.kind === "text_visible" ? treeIncludesText(snap.tree, cond.text) : cond.kind === "ref_exists" ? treeIncludesText(snap.tree, cond.query) : false;
+      if (matched) return;
+      await s.session.driver.pause(250);
+    }
+    throw new RolepodMcpError(
+      "engine_error",
+      `wait_for ${cond.kind} timed out after ${timeoutMs}ms`,
+      { condition: cond, timeout_ms: timeoutMs }
+    );
+  }
+  async screenshot(session, _fullPage) {
+    void _fullPage;
+    const s = this.requireSession(session.id);
+    const b64 = await s.session.driver.takeScreenshot();
+    return Buffer.from(b64, "base64");
+  }
+  async navigate(_session, _url) {
+    throw new UnsupportedPlatformError(_session.platform);
+  }
+  // -------------------------------------------------------------------------
+  // Internals
+  // -------------------------------------------------------------------------
+  async loadWdio() {
+    if (this.wdioCache) return this.wdioCache;
+    try {
+      const mod = await import(
+        /* @vite-ignore */
+        "webdriverio"
+      );
+      this.wdioCache = mod.remote;
+      return mod.remote;
+    } catch {
+      throw new RolepodMcpError(
+        "engine_error",
+        "Mobile support needs webdriverio (and a running Appium server). Run `npx rolepod-uiproof install:mobile` for the setup checklist."
+      );
+    }
+  }
+  buildCapabilities(opts) {
+    const caps = {};
+    if (opts.platform === "ios") {
+      caps.platformName = "iOS";
+      caps["appium:automationName"] = "XCUITest";
+      if (opts.device) caps["appium:deviceName"] = opts.device;
+      if (opts.bundle_id) caps["appium:bundleId"] = opts.bundle_id;
+    } else {
+      caps.platformName = "Android";
+      caps["appium:automationName"] = "UiAutomator2";
+      if (opts.emulator) caps["appium:avd"] = opts.emulator;
+      if (opts.app_package) caps["appium:appPackage"] = opts.app_package;
+      if (opts.app_activity) caps["appium:appActivity"] = opts.app_activity;
+    }
+    if (opts.locale) caps["appium:language"] = opts.locale;
+    return caps;
+  }
+  screenIdentifier(s) {
+    const caps = s.session.driver.capabilities;
+    return String(
+      caps["appium:bundleId"] ?? caps["appium:appPackage"] ?? caps.platformName ?? s.session.platform
+    );
+  }
+  requireSession(sessionId) {
+    const s = this.sessions.get(sessionId);
+    if (!s) throw new UnknownSessionError(sessionId);
+    return s;
+  }
+  async resolveElement(s, ref) {
+    if (s.refGeneration !== s.snapshotGeneration) {
+      throw new RolepodMcpError(
+        "stale_ref",
+        `Ref "${ref}" is stale \u2014 re-snapshot before retrying.`,
+        {
+          session_id: s.session.id,
+          ref,
+          last_valid_snapshot_at: s.lastSnapshotAt
+        }
+      );
+    }
+    const meta = s.refIndex.get(ref);
+    if (!meta) throw new UnknownRefError(s.session.id, ref);
+    const selector = this.toSelector(meta);
+    return s.session.driver.$(selector);
+  }
+  toSelector(meta) {
+    if (meta.kind === "ios") {
+      if (meta.accessibilityId) return `~${meta.accessibilityId}`;
+      const chain = `**/${meta.type}[${meta.classChainIndex}]`;
+      return `-ios class chain:${chain}`;
+    }
+    if (meta.resourceId) {
+      return `-android uiautomator:new UiSelector().resourceId("${escape(meta.resourceId)}")`;
+    }
+    if (meta.contentDesc) return `~${meta.contentDesc}`;
+    if (meta.text) {
+      return `-android uiautomator:new UiSelector().text("${escape(meta.text)}")`;
+    }
+    return `-android uiautomator:new UiSelector().className("${meta.androidClass}").instance(${meta.classIndex - 1})`;
+  }
+  invalidateRefs(s) {
+    s.snapshotGeneration += 1;
+  }
+};
+var ANDROID_KEY_CODES = {
+  Enter: 66,
+  Tab: 61,
+  Escape: 111,
+  Back: 4,
+  Home: 3,
+  Menu: 82,
+  Search: 84,
+  Backspace: 67,
+  ArrowUp: 19,
+  ArrowDown: 20,
+  ArrowLeft: 21,
+  ArrowRight: 22
+};
+function escape(s) {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function treeIncludesText(node, text) {
+  const target = text.toLowerCase();
+  const visit = (n) => {
+    if (n.name && n.name.toLowerCase().includes(target) || n.value && n.value.toLowerCase().includes(target)) return true;
+    if (!n.children) return false;
+    for (const c of n.children) {
+      if (visit(c)) return true;
+    }
+    return false;
+  };
+  return visit(node);
+}
+
+// src/engine/PlaywrightEngine.ts
+import { randomUUID as randomUUID3 } from "crypto";
+import {
+  chromium,
+  firefox,
+  webkit
+} from "playwright";
+
+// src/engine/a11y/normalize.ts
+import yaml from "js-yaml";
+var KEY_RE = /^(?<role>\S+?)(?:\s+"(?<name>(?:[^"\\]|\\.)*)")?(?<rest>(?:\s+\[[^\]]+\])*)\s*$/;
+var ATTR_RE = /\[([^=\]]+)(?:=([^\]]+))?\]/g;
+function parseKey(key) {
+  const trimmed = key.trim();
+  const m = KEY_RE.exec(trimmed);
+  if (!m) {
+    return { role: trimmed, attrs: {} };
+  }
+  const groups = m.groups;
+  const out = { role: groups.role, attrs: {} };
+  if (groups.name !== void 0) out.name = unescapeQuoted(groups.name);
+  const rest = groups.rest ?? "";
+  for (const attrMatch of rest.matchAll(ATTR_RE)) {
+    const [, k, v] = attrMatch;
+    if (k) out.attrs[k] = v ?? "true";
+  }
+  return out;
+}
+function unescapeQuoted(s) {
+  return s.replace(/\\(.)/g, "$1");
+}
+function parseAriaSnapshot(snapshotYaml) {
+  const refIndex = /* @__PURE__ */ new Map();
+  let synthCounter = 0;
+  const nextSynthRef = () => `s${++synthCounter}`;
+  const consumeNode = (value) => {
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      const keys = Object.keys(value);
+      if (keys.length !== 1) return null;
+      const key = keys[0];
+      if (key.startsWith("/")) return null;
+      const inner = value[key];
+      if (typeof inner === "string") return buildNode(key, null, inner);
+      if (Array.isArray(inner)) return buildNode(key, inner, void 0);
+      return buildNode(key, null, void 0);
+    }
+    if (typeof value === "string") {
+      return buildNode(value, null, void 0);
+    }
+    return null;
+  };
+  const buildNode = (key, rawChildren, inlineText) => {
+    const parsed = parseKey(key);
+    const ref = parsed.attrs.ref ?? nextSynthRef();
+    refIndex.set(ref, { kind: "web", ref });
+    const node = {
+      ref,
+      role: parsed.role
+    };
+    if (parsed.name !== void 0) node.name = parsed.name;
+    if (inlineText !== void 0) {
+      node.value = inlineText;
+    } else if (parsed.attrs.level) {
+      node.value = parsed.attrs.level;
+    }
+    const state = {};
+    if ("disabled" in parsed.attrs) state.disabled = parsed.attrs.disabled !== "false";
+    if ("focused" in parsed.attrs) state.focused = parsed.attrs.focused !== "false";
+    if ("selected" in parsed.attrs) state.selected = parsed.attrs.selected !== "false";
+    if ("expanded" in parsed.attrs) state.expanded = parsed.attrs.expanded !== "false";
+    if (Object.keys(state).length > 0) node.state = state;
+    if (Array.isArray(rawChildren)) {
+      const children = [];
+      for (const child of rawChildren) {
+        const built = consumeNode(child);
+        if (built) children.push(built);
+      }
+      if (children.length > 0) node.children = children;
+    }
+    return node;
+  };
+  let loaded;
+  try {
+    loaded = yaml.load(snapshotYaml) ?? [];
+  } catch {
+    loaded = [];
+  }
+  const topLevel = [];
+  if (Array.isArray(loaded)) {
+    for (const entry of loaded) {
+      const node = consumeNode(entry);
+      if (node) topLevel.push(node);
+    }
+  } else if (loaded && typeof loaded === "object") {
+    const node = consumeNode(loaded);
+    if (node) topLevel.push(node);
+  } else if (typeof loaded === "string" && loaded.length > 0) {
+    const node = consumeNode(loaded);
+    if (node) topLevel.push(node);
+  }
+  if (topLevel.length === 1) {
+    return { tree: topLevel[0], refIndex };
+  }
+  const rootRef = nextSynthRef();
+  refIndex.set(rootRef, { kind: "web", ref: rootRef });
+  const root = { ref: rootRef, role: "RootWebArea" };
+  if (topLevel.length > 0) root.children = topLevel;
+  return { tree: root, refIndex };
+}
+
+// src/engine/PlaywrightEngine.ts
+var PlaywrightEngine = class {
+  id = "playwright";
+  sessions = /* @__PURE__ */ new Map();
+  async open(opts) {
+    if (opts.platform !== "web") {
+      throw new UnsupportedPlatformError(opts.platform);
+    }
+    const browserName = opts.browser ?? "chromium";
+    const launcher = browserName === "firefox" ? firefox : browserName === "webkit" ? webkit : chromium;
+    const headless = opts.headless ?? (process.env.CI ? true : false);
+    const browser = await launcher.launch({ headless });
+    const contextOptions = {};
+    if (opts.viewport) contextOptions.viewport = opts.viewport;
+    if (opts.user_agent) contextOptions.userAgent = opts.user_agent;
+    if (opts.locale) contextOptions.locale = opts.locale;
+    const context = await browser.newContext(contextOptions);
+    const page = await context.newPage();
+    if (opts.url) {
+      await page.goto(opts.url, { waitUntil: "domcontentloaded" });
+    }
+    const sessionId = randomUUID3();
+    const session = {
+      id: sessionId,
+      platform: "web",
+      browser,
+      context,
+      page
+    };
+    this.sessions.set(sessionId, {
+      session,
+      refIndex: /* @__PURE__ */ new Map(),
+      snapshotGeneration: 0,
+      refGeneration: -1,
+      lastSnapshotAt: null
+    });
+    log.info("session opened", {
+      session_id: sessionId,
+      browser: browserName,
+      url: opts.url ?? null
+    });
+    return { id: sessionId, platform: "web" };
+  }
+  async close(session) {
+    const s = this.requireSession(session.id);
+    await s.session.context.close().catch((err) => {
+      log.warn("context close failed", { session_id: session.id, err: String(err) });
+    });
+    await s.session.browser.close().catch((err) => {
+      log.warn("browser close failed", { session_id: session.id, err: String(err) });
+    });
+    this.sessions.delete(session.id);
+    log.info("session closed", { session_id: session.id });
+  }
+  async snapshot(session, mode = "visible") {
+    const s = this.requireSession(session.id);
+    const ariaYaml = await s.session.page.ariaSnapshot({ mode: "ai" });
+    const { tree, refIndex } = parseAriaSnapshot(ariaYaml);
+    void mode;
+    s.snapshotGeneration += 1;
+    s.refGeneration = s.snapshotGeneration;
+    s.refIndex = refIndex;
+    s.lastSnapshotAt = (/* @__PURE__ */ new Date()).toISOString();
+    return {
+      session_id: session.id,
+      platform: "web",
+      url_or_screen: s.session.page.url(),
+      taken_at: s.lastSnapshotAt,
+      tree
+    };
+  }
+  async click(session, ref, opts) {
+    const s = this.requireSession(session.id);
+    const locator = this.resolveLocator(s, ref);
+    await locator.click(opts?.button ? { button: opts.button } : void 0);
+    this.invalidateRefs(s);
+  }
+  async type(session, ref, text, opts) {
+    const s = this.requireSession(session.id);
+    const locator = this.resolveLocator(s, ref);
+    if (opts?.clearFirst) await locator.fill("");
+    await locator.fill(text);
+    this.invalidateRefs(s);
+  }
+  async key(session, key) {
+    const s = this.requireSession(session.id);
+    await s.session.page.keyboard.press(key);
+    this.invalidateRefs(s);
+  }
+  async scroll(session, dir, amount = 400, ref) {
+    const s = this.requireSession(session.id);
+    const dx = dir === "left" ? -amount : dir === "right" ? amount : 0;
+    const dy = dir === "up" ? -amount : dir === "down" ? amount : 0;
+    if (ref) {
+      const locator = this.resolveLocator(s, ref);
+      await locator.evaluate(
+        (el, [x, y]) => el.scrollBy(x, y),
+        [dx, dy]
+      );
+    } else {
+      await s.session.page.mouse.wheel(dx, dy);
+    }
+    this.invalidateRefs(s);
+  }
+  async waitFor(session, cond, timeoutMs = 1e4) {
+    const s = this.requireSession(session.id);
+    const page = s.session.page;
+    switch (cond.kind) {
+      case "text_visible":
+        await page.getByText(cond.text, { exact: false }).first().waitFor({ state: "visible", timeout: timeoutMs });
+        break;
+      case "ref_exists":
+        await page.getByRole("button", { name: cond.query }).first().waitFor({ state: "attached", timeout: timeoutMs });
+        break;
+      case "url_matches":
+        await page.waitForURL(new RegExp(cond.pattern), { timeout: timeoutMs });
+        break;
+      case "idle":
+        await page.waitForLoadState("networkidle", { timeout: timeoutMs });
+        await page.waitForTimeout(cond.ms);
+        break;
+    }
+    this.invalidateRefs(s);
+  }
+  async screenshot(session, fullPage = false) {
+    const s = this.requireSession(session.id);
+    return s.session.page.screenshot({ fullPage });
+  }
+  async navigate(session, url) {
+    const s = this.requireSession(session.id);
+    if (s.session.platform !== "web") {
+      throw new UnsupportedPlatformError(s.session.platform);
+    }
+    await s.session.page.goto(url, { waitUntil: "domcontentloaded" });
+    this.invalidateRefs(s);
+  }
+  /**
+   * Composite-only escape hatch — exposes the raw Playwright Page so a
+   * composite tool that genuinely needs page-level APIs (axe-core,
+   * `getByText`, etc.) can use them without bloating the Engine interface
+   * with web-specific verbs. Throws if the session is not web.
+   */
+  getPageForSession(sessionId) {
+    const s = this.requireSession(sessionId);
+    if (s.session.platform !== "web") {
+      throw new UnsupportedPlatformError(s.session.platform);
+    }
+    return s.session.page;
+  }
+  /** Increment generation; the next ref-using call will see them as stale. */
+  bumpGeneration(sessionId) {
+    const s = this.requireSession(sessionId);
+    this.invalidateRefs(s);
+  }
+  // -------------------------------------------------------------------------
+  // Internal helpers
+  // -------------------------------------------------------------------------
+  requireSession(sessionId) {
+    const s = this.sessions.get(sessionId);
+    if (!s) {
+      throw new RolepodMcpError(
+        "unknown_session",
+        `No open session with id "${sessionId}".`,
+        { session_id: sessionId }
+      );
+    }
+    return s;
+  }
+  resolveLocator(s, ref) {
+    if (s.refGeneration !== s.snapshotGeneration) {
+      throw new RolepodMcpError(
+        "stale_ref",
+        `Ref "${ref}" is stale \u2014 re-snapshot before retrying.`,
+        {
+          session_id: s.session.id,
+          ref,
+          last_valid_snapshot_at: s.lastSnapshotAt
+        }
+      );
+    }
+    const meta = s.refIndex.get(ref);
+    if (!meta) throw new UnknownRefError(s.session.id, ref);
+    if (meta.ref.startsWith("s")) {
+      throw new UnknownRefError(s.session.id, ref);
+    }
+    return s.session.page.locator(`aria-ref=${meta.ref}`);
+  }
+  invalidateRefs(s) {
+    s.snapshotGeneration += 1;
+  }
+  /**
+   * Test / shutdown helper. Closes every open session.
+   */
+  async shutdown() {
+    const ids = [...this.sessions.keys()];
+    await Promise.all(
+      ids.map((id) => this.close({ id, platform: "web" }).catch(() => void 0))
+    );
+  }
+};
+
+// src/engine/factory.ts
+function createWebEngine() {
+  const choice = (process.env.ROLEPOD_MCP_WEB_ENGINE ?? "playwright").toLowerCase();
+  switch (choice) {
+    case "playwright":
+      return new PlaywrightEngine();
+    case "selenium":
+      throw new RolepodMcpError(
+        "unsupported_engine",
+        "SeleniumEngine ships in v0.4 \u2014 set ROLEPOD_MCP_WEB_ENGINE=playwright until then.",
+        { requested: choice }
+      );
+    default:
+      throw new RolepodMcpError(
+        "unsupported_engine",
+        `Unknown web engine "${choice}" \u2014 supported: playwright.`,
+        { requested: choice }
+      );
+  }
+}
+function createMobileEngine() {
+  return new AppiumEngine();
+}
+
+// src/session/SessionRegistry.ts
+var SessionRegistry = class {
+  enginesByPlatform = /* @__PURE__ */ new Map();
+  engineBySession = /* @__PURE__ */ new Map();
+  platformBySession = /* @__PURE__ */ new Map();
+  lastActivity = /* @__PURE__ */ new Map();
+  idleTimeoutMs;
+  idleTimer = null;
+  constructor(opts = {}) {
+    this.idleTimeoutMs = opts.idleTimeoutMs ?? 5 * 60 * 1e3;
+  }
+  /** Register an engine as the handler for a given platform. */
+  register(platform, engine) {
+    this.enginesByPlatform.set(platform, engine);
+  }
+  async open(opts) {
+    const engine = this.enginesByPlatform.get(opts.platform);
+    if (!engine) throw new UnsupportedPlatformError(opts.platform);
+    const session = await engine.open(opts);
+    this.engineBySession.set(session.id, engine);
+    this.platformBySession.set(session.id, session.platform);
+    this.touch(session.id);
+    this.ensureIdleSweep();
+    return session;
+  }
+  engineFor(sessionId) {
+    const engine = this.engineBySession.get(sessionId);
+    if (!engine) throw new UnknownSessionError(sessionId);
+    this.touch(sessionId);
+    return engine;
+  }
+  async close(session) {
+    const engine = this.engineBySession.get(session.id);
+    if (!engine) throw new UnknownSessionError(session.id);
+    await engine.close(session);
+    this.engineBySession.delete(session.id);
+    this.platformBySession.delete(session.id);
+    this.lastActivity.delete(session.id);
+  }
+  /** Look up the platform recorded for an open session. */
+  platformOf(sessionId) {
+    const platform = this.platformBySession.get(sessionId);
+    if (!platform) throw new UnknownSessionError(sessionId);
+    return platform;
+  }
+  async shutdown() {
+    if (this.idleTimer) {
+      clearInterval(this.idleTimer);
+      this.idleTimer = null;
+    }
+    const closes = [];
+    for (const [sessionId, engine] of this.engineBySession) {
+      const platform = this.platformFor(sessionId);
+      closes.push(
+        engine.close({ id: sessionId, platform }).catch(
+          (err) => log.warn("shutdown close failed", { sessionId, err: String(err) })
+        )
+      );
+    }
+    await Promise.all(closes);
+    this.engineBySession.clear();
+    this.platformBySession.clear();
+    this.lastActivity.clear();
+  }
+  touch(sessionId) {
+    this.lastActivity.set(sessionId, Date.now());
+  }
+  platformFor(sessionId) {
+    return this.platformBySession.get(sessionId) ?? "web";
+  }
+  ensureIdleSweep() {
+    if (this.idleTimer || this.idleTimeoutMs <= 0) return;
+    const interval = Math.max(3e4, Math.floor(this.idleTimeoutMs / 4));
+    this.idleTimer = setInterval(() => {
+      const cutoff = Date.now() - this.idleTimeoutMs;
+      for (const [sessionId, lastSeen] of this.lastActivity) {
+        if (lastSeen < cutoff) {
+          const engine = this.engineBySession.get(sessionId);
+          if (!engine) {
+            this.lastActivity.delete(sessionId);
+            continue;
+          }
+          log.info("idle session sweep \u2014 closing", { sessionId });
+          engine.close({ id: sessionId, platform: this.platformFor(sessionId) }).catch(
+            (err) => log.warn("idle close failed", { sessionId, err: String(err) })
+          ).finally(() => {
+            this.engineBySession.delete(sessionId);
+            this.lastActivity.delete(sessionId);
+          });
+        }
+      }
+    }, interval);
+    this.idleTimer.unref();
+  }
+};
+
+// src/schema/tools.ts
+import { z } from "zod";
+var platformSchema = z.enum(["web", "ios", "android"]);
+var browserSchema = z.enum(["chromium", "firefox", "webkit"]);
+var viewportSchema = z.object({
+  width: z.number().int().positive(),
+  height: z.number().int().positive()
+});
+var bboxSchema = z.object({
+  x: z.number(),
+  y: z.number(),
+  w: z.number(),
+  h: z.number()
+});
+var a11yStateSchema = z.object({
+  focused: z.boolean().optional(),
+  selected: z.boolean().optional(),
+  expanded: z.boolean().optional(),
+  disabled: z.boolean().optional()
+});
+var a11yNodeSchema = z.lazy(
+  () => z.object({
+    ref: z.string(),
+    role: z.string(),
+    name: z.string().optional(),
+    value: z.string().optional(),
+    state: a11yStateSchema.optional(),
+    bbox: bboxSchema.optional(),
+    children: z.array(a11yNodeSchema).optional()
+  })
+);
+var waitConditionSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("text_visible"), text: z.string() }),
+  z.object({ kind: z.literal("ref_exists"), query: z.string() }),
+  z.object({ kind: z.literal("url_matches"), pattern: z.string() }),
+  z.object({ kind: z.literal("idle"), ms: z.number().int().positive() })
+]);
+var browserOpenShape = {
+  platform: platformSchema.default("web"),
+  url: z.string().url().optional(),
+  browser: browserSchema.optional(),
+  viewport: viewportSchema.optional(),
+  // mobile fields kept for forward compat; v0.1 only handles platform='web'
+  bundle_id: z.string().optional(),
+  device: z.string().optional(),
+  app_package: z.string().optional(),
+  app_activity: z.string().optional(),
+  emulator: z.string().optional(),
+  headless: z.boolean().optional(),
+  user_agent: z.string().optional(),
+  locale: z.string().optional()
+};
+var browserOpenSchema = z.object(browserOpenShape);
+var browserCloseShape = {
+  session_id: z.string().min(1)
+};
+var browserCloseSchema = z.object(browserCloseShape);
+var browserSnapshotShape = {
+  session_id: z.string().min(1),
+  mode: z.enum(["visible", "full"]).optional()
+};
+var browserSnapshotSchema = z.object(browserSnapshotShape);
+var browserClickShape = {
+  session_id: z.string().min(1),
+  ref: z.string().min(1),
+  button: z.enum(["left", "right", "middle"]).optional()
+};
+var browserClickSchema = z.object(browserClickShape);
+var browserTypeShape = {
+  session_id: z.string().min(1),
+  ref: z.string().min(1),
+  text: z.string(),
+  clear_first: z.boolean().optional()
+};
+var browserTypeSchema = z.object(browserTypeShape);
+var browserKeyShape = {
+  session_id: z.string().min(1),
+  key: z.string().min(1)
+};
+var browserKeySchema = z.object(browserKeyShape);
+var browserScrollShape = {
+  session_id: z.string().min(1),
+  direction: z.enum(["up", "down", "left", "right"]),
+  amount: z.number().int().positive().optional(),
+  ref: z.string().min(1).optional()
+};
+var browserScrollSchema = z.object(browserScrollShape);
+var browserWaitForShape = {
+  session_id: z.string().min(1),
+  condition: waitConditionSchema,
+  timeout_ms: z.number().int().positive().optional()
+};
+var browserWaitForSchema = z.object(browserWaitForShape);
+var browserScreenshotShape = {
+  session_id: z.string().min(1),
+  full_page: z.boolean().optional()
+};
+var browserScreenshotSchema = z.object(browserScreenshotShape);
+var browserNavigateShape = {
+  session_id: z.string().min(1),
+  url: z.string().url()
+};
+var browserNavigateSchema = z.object(browserNavigateShape);
+var verifyStepSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("click"), query: z.string() }),
+  z.object({
+    kind: z.literal("type"),
+    query: z.string(),
+    text: z.string(),
+    clear_first: z.boolean().optional()
+  }),
+  z.object({ kind: z.literal("key"), key: z.string() }),
+  z.object({ kind: z.literal("wait_for"), condition: waitConditionSchema }),
+  z.object({ kind: z.literal("navigate"), url: z.string().url() })
+]);
+var verifyExpectSchema = z.discriminatedUnion("kind", [
+  z.object({ kind: z.literal("text_visible"), text: z.string() }),
+  z.object({ kind: z.literal("text_absent"), text: z.string() }),
+  z.object({ kind: z.literal("url_matches"), pattern: z.string() }),
+  z.object({
+    kind: z.literal("ref_in_state"),
+    query: z.string(),
+    state: z.enum(["visible", "enabled", "focused"])
+  })
+]);
+var captureKindSchema = z.enum([
+  "screenshot",
+  "har",
+  "console",
+  "a11y_tree",
+  "video"
+]);
+var verifyUiFlowShape = {
+  mode: z.enum(["assert", "reproduce"]).default("assert"),
+  open: browserOpenSchema,
+  steps: z.array(verifyStepSchema).default([]),
+  expect: z.array(verifyExpectSchema).default([]),
+  capture: z.array(captureKindSchema).optional(),
+  close_on_finish: z.boolean().default(true),
+  /**
+   * Only consulted when `mode='reproduce'`. When true (default) and the
+   * initial run reproduces the bug, the composite tries to remove each
+   * step in turn and re-runs to find a smaller reproducer.
+   */
+  minimize: z.boolean().default(true)
+};
+var verifyUiFlowSchema = z.object(verifyUiFlowShape);
+var wcagLevelSchema = z.enum(["wcag-a", "wcag-aa", "wcag-aaa"]);
+var a11ySeveritySchema = z.enum([
+  "critical",
+  "serious",
+  "moderate",
+  "minor"
+]);
+var auditScopeSchema = z.union([
+  z.literal("page"),
+  z.object({ ref: z.string().min(1) })
+]);
+var auditA11yShape = {
+  open: browserOpenSchema,
+  level: wcagLevelSchema.default("wcag-aa"),
+  scope: auditScopeSchema.default("page"),
+  report_format: z.enum(["json", "markdown"]).default("json"),
+  close_on_finish: z.boolean().default(true)
+};
+var auditA11ySchema = z.object(auditA11yShape);
+var visualDiffShape = {
+  open: browserOpenSchema,
+  baseline_id: z.string().min(1),
+  viewport: viewportSchema.optional(),
+  threshold_pct: z.number().min(0).max(1).default(0.1),
+  close_on_finish: z.boolean().default(true),
+  /** Pixel sensitivity for pixelmatch (0 = strict, 1 = lax). Default 0.1. */
+  pixel_threshold: z.number().min(0).max(1).default(0.1)
+};
+var visualDiffSchema = z.object(visualDiffShape);
+var e2eFrameworkSchema = z.enum([
+  "playwright-test",
+  "vitest+playwright",
+  "pytest+selenium"
+]);
+var scaffoldE2eShape = {
+  framework: e2eFrameworkSchema,
+  scenario_nl: z.string().min(1),
+  url: z.string().url(),
+  recorded_bundle: z.string().min(1).optional(),
+  /** Override the generated test file name. */
+  filename: z.string().min(1).optional()
+};
+var scaffoldE2eSchema = z.object(scaffoldE2eShape);
+var extractUiStateShape = {
+  session_id: z.string().min(1).optional(),
+  open: browserOpenSchema.optional(),
+  question_nl: z.string().min(1),
+  close_on_finish: z.boolean().default(false)
+};
+var extractUiStateSchema = z.object(extractUiStateShape);
+var ToolNames = {
+  browserOpen: "rolepod_browser_open",
+  browserClose: "rolepod_browser_close",
+  browserSnapshot: "rolepod_browser_snapshot",
+  browserClick: "rolepod_browser_click",
+  browserType: "rolepod_browser_type",
+  browserKey: "rolepod_browser_key",
+  browserScroll: "rolepod_browser_scroll",
+  browserWaitFor: "rolepod_browser_wait_for",
+  browserScreenshot: "rolepod_browser_screenshot",
+  browserNavigate: "rolepod_browser_navigate",
+  verifyUiFlow: "rolepod_verify_ui_flow",
+  auditA11y: "rolepod_audit_a11y",
+  visualDiff: "rolepod_visual_diff",
+  scaffoldE2e: "rolepod_scaffold_e2e",
+  extractUiState: "rolepod_extract_ui_state"
+};
+
+// src/replay/minimize.ts
+async function ddmin(input, reproduces) {
+  let current = [...input];
+  let n = 2;
+  while (current.length >= 2) {
+    const chunkSize = Math.max(1, Math.floor(current.length / n));
+    let reduced = false;
+    for (let i = 0; i < current.length; i += chunkSize) {
+      const complement = [
+        ...current.slice(0, i),
+        ...current.slice(i + chunkSize)
+      ];
+      if (complement.length === 0) continue;
+      if (await reproduces(complement)) {
+        current = complement;
+        n = Math.max(n - 1, 2);
+        reduced = true;
+        break;
+      }
+    }
+    if (reduced) continue;
+    if (n >= current.length) break;
+    n = Math.min(n * 2, current.length);
+  }
+  return current;
+}
+
+// src/tools/result.ts
+function ok(value) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(value, null, 2) }],
+    structuredContent: value
+  };
+}
+function failure(err) {
+  if (err instanceof RolepodMcpError) {
+    const payload2 = err.toJSON();
+    return {
+      isError: true,
+      content: [{ type: "text", text: JSON.stringify(payload2, null, 2) }],
+      structuredContent: payload2
+    };
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  const payload = { code: "engine_error", message };
+  return {
+    isError: true,
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    structuredContent: payload
+  };
+}
+function safeHandler(fn) {
+  return async (args) => {
+    try {
+      return await fn(args);
+    } catch (err) {
+      return failure(err);
+    }
+  };
+}
+
+// src/tools/composite/verify_ui_flow.ts
+var verifyUiFlowTool = {
+  name: ToolNames.verifyUiFlow,
+  description: "Open a session, run UI steps, evaluate assertions, and save evidence. Set mode='reproduce' for bug reproduction with optional step minimization.",
+  inputShape: verifyUiFlowShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const { runId, runDir } = await ctx.store.startRun("verify");
+      const initial = await runFlow(ctx, args, args.steps, runDir, {
+        captureEvidence: true,
+        bundleName: "replay.json"
+      });
+      const result = {
+        run_id: runId,
+        mode: args.mode,
+        passed: initial.passed,
+        evidence_paths: initial.evidence
+      };
+      if (initial.failedAtStep !== void 0) result.failed_at_step = initial.failedAtStep;
+      if (initial.failureReason !== void 0) result.failure_reason = initial.failureReason;
+      if (initial.finalUrl !== void 0) result.final_url_or_screen = initial.finalUrl;
+      if (args.mode === "reproduce" && initial.passed && args.minimize) {
+        const min = await minimize(ctx, args, args.steps, runDir);
+        result.minimized = {
+          original_step_count: args.steps.length,
+          minimized_step_count: min.steps.length,
+          minimal_steps: min.steps,
+          steps_removed: min.removed,
+          replay_bundle: min.replayPath,
+          attempts: min.attempts
+        };
+      }
+      return ok(result);
+    });
+  }
+};
+async function runFlow(ctx, args, steps, runDir, opts) {
+  const evidence = { screenshots: [] };
+  let passed = false;
+  let failedAtStep;
+  let failureReason;
+  let finalSnapshot;
+  const session = await ctx.registry.open(args.open);
+  const engine = ctx.registry.engineFor(session.id);
+  const sessionHandle = { id: session.id, platform: session.platform };
+  try {
+    for (let i = 0; i < steps.length; i++) {
+      const step = steps[i];
+      const beforeSnap = await engine.snapshot(sessionHandle);
+      try {
+        await runStep(engine, sessionHandle, step, beforeSnap);
+      } catch (err) {
+        failedAtStep = i;
+        failureReason = `Step ${i} (${step.kind}) failed: ${describeError(err)}`;
+        throw err;
+      }
+    }
+    finalSnapshot = await engine.snapshot(sessionHandle);
+    const failures = [];
+    for (let i = 0; i < args.expect.length; i++) {
+      const expectation = args.expect[i];
+      if (!evaluateExpect(expectation, finalSnapshot)) {
+        failures.push(`expect[${i}] ${describeExpect(expectation)}`);
+      }
+    }
+    if (failures.length === 0) {
+      passed = true;
+    } else {
+      failureReason = `Expectations failed: ${failures.join("; ")}`;
+    }
+  } catch (err) {
+    if (!failureReason) failureReason = describeError(err);
+    passed = false;
+  } finally {
+    if (opts.captureEvidence) {
+      const wantScreenshot = !args.capture || args.capture.includes("screenshot");
+      if (wantScreenshot) {
+        try {
+          const buf = await engine.screenshot(sessionHandle, true);
+          const p = await ctx.store.writeScreenshot(runDir, buf, "final");
+          evidence.screenshots.push(p);
+        } catch (err) {
+          failureReason ??= `screenshot capture failed: ${describeError(err)}`;
+        }
+      }
+      try {
+        evidence.replay_bundle = await ctx.store.writeReplayBundle(
+          runDir,
+          {
+            version: 1,
+            run_id: runDir.split("/").pop() ?? "run",
+            recorded_at: (/* @__PURE__ */ new Date()).toISOString(),
+            open: args.open,
+            steps,
+            expect: args.expect
+          },
+          opts.bundleName
+        );
+      } catch {
+      }
+    }
+    if (args.close_on_finish) {
+      await ctx.registry.close(sessionHandle).catch(() => void 0);
+    }
+  }
+  const out = { passed, evidence };
+  if (failedAtStep !== void 0) out.failedAtStep = failedAtStep;
+  if (failureReason !== void 0) out.failureReason = failureReason;
+  if (finalSnapshot) out.finalUrl = finalSnapshot.url_or_screen;
+  return out;
+}
+async function minimize(ctx, args, initialSteps, runDir) {
+  const tagged = initialSteps.map((step, origIndex) => ({ step, origIndex }));
+  let attempts = 0;
+  const predicate = async (subset) => {
+    attempts += 1;
+    const outcome = await runFlow(
+      ctx,
+      args,
+      subset.map((t) => t.step),
+      runDir,
+      { captureEvidence: false, bundleName: "minimize-tmp.json" }
+    );
+    return outcome.passed;
+  };
+  const minimal = await ddmin(tagged, predicate);
+  const remainingIdx = new Set(minimal.map((t) => t.origIndex));
+  const removed = tagged.map((t) => t.origIndex).filter((i) => !remainingIdx.has(i));
+  let replayPath;
+  if (minimal.length !== initialSteps.length) {
+    const finalRun = await runFlow(
+      ctx,
+      args,
+      minimal.map((t) => t.step),
+      runDir,
+      { captureEvidence: true, bundleName: "replay-minimized.json" }
+    );
+    replayPath = finalRun.evidence.replay_bundle;
+  }
+  return {
+    steps: minimal.map((t) => t.step),
+    removed: removed.sort((a, b) => a - b),
+    attempts,
+    replayPath
+  };
+}
+async function runStep(engine, session, step, snap) {
+  switch (step.kind) {
+    case "click": {
+      const ref = findRefByQuery(snap.tree, step.query);
+      if (!ref) throw missingQuery(step.query);
+      await engine.click(session, ref);
+      return;
+    }
+    case "type": {
+      const ref = findRefByQuery(snap.tree, step.query);
+      if (!ref) throw missingQuery(step.query);
+      await engine.type(
+        session,
+        ref,
+        step.text,
+        step.clear_first ? { clearFirst: true } : void 0
+      );
+      return;
+    }
+    case "key":
+      await engine.key(session, step.key);
+      return;
+    case "wait_for":
+      await engine.waitFor(session, step.condition);
+      return;
+    case "navigate":
+      await engine.navigate(session, step.url);
+      return;
+  }
+}
+function evaluateExpect(exp, snap) {
+  switch (exp.kind) {
+    case "text_visible":
+      return treeHasText(snap.tree, exp.text);
+    case "text_absent":
+      return !treeHasText(snap.tree, exp.text);
+    case "url_matches":
+      return new RegExp(exp.pattern).test(snap.url_or_screen);
+    case "ref_in_state": {
+      const node = findNodeByQuery(snap.tree, exp.query);
+      if (!node) return false;
+      switch (exp.state) {
+        case "visible":
+          return true;
+        case "enabled":
+          return node.state?.disabled !== true;
+        case "focused":
+          return node.state?.focused === true;
+      }
+    }
+  }
+}
+function describeExpect(exp) {
+  switch (exp.kind) {
+    case "text_visible":
+      return `text_visible "${exp.text}"`;
+    case "text_absent":
+      return `text_absent "${exp.text}"`;
+    case "url_matches":
+      return `url_matches /${exp.pattern}/`;
+    case "ref_in_state":
+      return `ref_in_state "${exp.query}" \u2192 ${exp.state}`;
+  }
+}
+function missingQuery(query) {
+  return new RolepodMcpError(
+    "invalid_input",
+    `No element matched query "${query}" in the current snapshot.`,
+    { query }
+  );
+}
+function describeError(err) {
+  if (err instanceof Error) return err.message;
+  return String(err);
+}
+function findRefByQuery(tree, query) {
+  const node = findNodeByQuery(tree, query);
+  return node ? node.ref : null;
+}
+function findNodeByQuery(tree, query) {
+  const target = query.toLowerCase();
+  const visit = (node) => {
+    if (node.name && node.name.toLowerCase().includes(target) || node.value && node.value.toLowerCase().includes(target)) {
+      return node;
+    }
+    if (node.children) {
+      for (const c of node.children) {
+        const hit = visit(c);
+        if (hit) return hit;
+      }
+    }
+    return null;
+  };
+  return visit(tree);
+}
+function treeHasText(tree, text) {
+  const target = text.toLowerCase();
+  const visit = (node) => {
+    if (node.name && node.name.toLowerCase().includes(target) || node.value && node.value.toLowerCase().includes(target)) {
+      return true;
+    }
+    return node.children?.some(visit) ?? false;
+  };
+  return visit(tree);
+}
+
+// src/cli/replay.ts
+async function runReplay(bundlePath) {
+  const abs = resolve3(bundlePath);
+  const raw = await readFile(abs, "utf8");
+  const bundle = JSON.parse(raw);
+  if (bundle.version !== 1) {
+    process.stderr.write(`Unsupported replay bundle version: ${bundle.version}
+`);
+    return 1;
+  }
+  const webEngine = createWebEngine();
+  const registry = new SessionRegistry({ idleTimeoutMs: 0 });
+  registry.register("web", webEngine);
+  const mobileEngine = createMobileEngine();
+  registry.register("ios", mobileEngine);
+  registry.register("android", mobileEngine);
+  const store = new ArtifactStore();
+  const ctx = { registry, store };
+  try {
+    const handler = verifyUiFlowTool.build(ctx);
+    const result = await handler({
+      mode: "assert",
+      open: bundle.open ?? {},
+      steps: bundle.steps ?? [],
+      expect: bundle.expect ?? [],
+      capture: ["screenshot"],
+      close_on_finish: true,
+      minimize: false
+    });
+    const body = result.structuredContent;
+    process.stdout.write(JSON.stringify(body, null, 2) + "\n");
+    return body.passed === true ? 0 : 1;
+  } finally {
+    await registry.shutdown().catch(() => void 0);
+  }
+}
+
+// src/server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+// src/tools/atomic/browser_click.ts
+var browserClickTool = {
+  name: ToolNames.browserClick,
+  description: "Click the element identified by `ref` from the most recent snapshot. Invalidates all refs on success.",
+  inputShape: browserClickShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      await engine.click(
+        { id: args.session_id, platform: ctx.registry.platformOf(args.session_id) },
+        args.ref,
+        args.button ? { button: args.button } : void 0
+      );
+      return ok({ clicked: true });
+    });
+  }
+};
+
+// src/tools/atomic/browser_close.ts
+var browserCloseTool = {
+  name: ToolNames.browserClose,
+  description: "Close an open session and free its browser / driver resources.",
+  inputShape: browserCloseShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const platform = ctx.registry.platformOf(args.session_id);
+      await ctx.registry.close({ id: args.session_id, platform });
+      return ok({ closed: true });
+    });
+  }
+};
+
+// src/tools/atomic/browser_key.ts
+var browserKeyTool = {
+  name: ToolNames.browserKey,
+  description: "Press a single key (e.g. 'Enter', 'Tab', 'Escape'). Invalidates all refs on success.",
+  inputShape: browserKeyShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      await engine.key({ id: args.session_id, platform: ctx.registry.platformOf(args.session_id) }, args.key);
+      return ok({ pressed: true });
+    });
+  }
+};
+
+// src/tools/atomic/browser_navigate.ts
+var browserNavigateTool = {
+  name: ToolNames.browserNavigate,
+  description: "Navigate the session to a new URL (web only). Invalidates all refs on success.",
+  inputShape: browserNavigateShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      await engine.navigate({ id: args.session_id, platform: ctx.registry.platformOf(args.session_id) }, args.url);
+      return ok({ navigated: true, url: args.url });
+    });
+  }
+};
+
+// src/tools/atomic/browser_open.ts
+var browserOpenTool = {
+  name: ToolNames.browserOpen,
+  description: "Open a new browser or mobile session against a target. v0.1 supports platform='web' only; mobile lands in v0.3.",
+  inputShape: browserOpenShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const session = await ctx.registry.open(args);
+      return ok({ session_id: session.id, platform: session.platform });
+    });
+  }
+};
+
+// src/tools/atomic/browser_screenshot.ts
+var browserScreenshotTool = {
+  name: ToolNames.browserScreenshot,
+  description: "Capture a screenshot and save under ./.rolepod-uiproof/artifacts/{run_id}/. Set `full_page: true` for full-page capture; default is viewport only. Read-only (does NOT invalidate refs).",
+  inputShape: browserScreenshotShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      const { runId, runDir } = await ctx.store.startRun("snap");
+      const buf = await engine.screenshot(
+        { id: args.session_id, platform: ctx.registry.platformOf(args.session_id) },
+        args.full_page ?? false
+      );
+      const path = await ctx.store.writeScreenshot(runDir, buf, "shot");
+      return ok({
+        run_id: runId,
+        path,
+        width: void 0,
+        height: void 0,
+        bytes: buf.byteLength
+      });
+    });
+  }
+};
+
+// src/tools/atomic/browser_scroll.ts
+var browserScrollTool = {
+  name: ToolNames.browserScroll,
+  description: "Scroll the page (or a specific scrollable element when `ref` is set) by `amount` pixels in `direction`. Invalidates all refs on success.",
+  inputShape: browserScrollShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      await engine.scroll(
+        { id: args.session_id, platform: ctx.registry.platformOf(args.session_id) },
+        args.direction,
+        args.amount,
+        args.ref
+      );
+      return ok({ scrolled: true });
+    });
+  }
+};
+
+// src/tools/atomic/browser_snapshot.ts
+var browserSnapshotTool = {
+  name: ToolNames.browserSnapshot,
+  description: "Return the current accessibility tree with stable refs (e1, e2, \u2026). Refs are valid only until the next state-changing call (D-010).",
+  inputShape: browserSnapshotShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      const snap = await engine.snapshot(
+        { id: args.session_id, platform: ctx.registry.platformOf(args.session_id) },
+        args.mode
+      );
+      return ok({
+        session_id: snap.session_id,
+        url_or_screen: snap.url_or_screen,
+        tree: snap.tree,
+        taken_at: snap.taken_at
+      });
+    });
+  }
+};
+
+// src/tools/atomic/browser_type.ts
+var browserTypeTool = {
+  name: ToolNames.browserType,
+  description: "Type `text` into the element identified by `ref`. Set `clear_first: true` to replace the existing value. Invalidates all refs on success.",
+  inputShape: browserTypeShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      await engine.type(
+        { id: args.session_id, platform: ctx.registry.platformOf(args.session_id) },
+        args.ref,
+        args.text,
+        args.clear_first ? { clearFirst: true } : void 0
+      );
+      return ok({ typed: true });
+    });
+  }
+};
+
+// src/tools/atomic/browser_wait_for.ts
+var browserWaitForTool = {
+  name: ToolNames.browserWaitFor,
+  description: "Wait until a condition holds: text_visible, ref_exists, url_matches, or idle. Defaults to a 10s timeout. Invalidates all refs on success.",
+  inputShape: browserWaitForShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      const start = Date.now();
+      await engine.waitFor(
+        { id: args.session_id, platform: ctx.registry.platformOf(args.session_id) },
+        args.condition,
+        args.timeout_ms
+      );
+      return ok({ matched: true, waited_ms: Date.now() - start });
+    });
+  }
+};
+
+// src/tools/composite/audit_a11y.ts
+import AxeBuilder from "@axe-core/playwright";
+var TAGS_BY_LEVEL = {
+  "wcag-a": ["wcag2a", "wcag21a"],
+  "wcag-aa": ["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"],
+  "wcag-aaa": [
+    "wcag2a",
+    "wcag2aa",
+    "wcag2aaa",
+    "wcag21a",
+    "wcag21aa",
+    "wcag21aaa"
+  ]
+};
+var AXE_TO_SEVERITY = {
+  critical: "critical",
+  serious: "serious",
+  moderate: "moderate",
+  minor: "minor"
+};
+var auditA11yTool = {
+  name: ToolNames.auditA11y,
+  description: "Run an accessibility audit on the page using axe-core. Returns issues grouped by severity with WCAG references and fix suggestions. v0.2: scope='page' only.",
+  inputShape: auditA11yShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const { runId, runDir } = await ctx.store.startRun("audit");
+      const session = await ctx.registry.open(args.open);
+      const engine = ctx.registry.engineFor(session.id);
+      if (!(engine instanceof PlaywrightEngine)) {
+        throw new RolepodMcpError(
+          "unsupported_engine",
+          "audit_a11y currently requires PlaywrightEngine (mobile a11y audit lands later)."
+        );
+      }
+      const page = engine.getPageForSession(session.id);
+      let reportPath;
+      let issues = [];
+      let scopeTagged = false;
+      try {
+        if (args.scope !== "page") {
+          await engine.snapshot({ id: session.id, platform: "web" });
+          const ref = args.scope.ref;
+          const locator = page.locator(`aria-ref=${ref}`);
+          if (await locator.count() === 0) {
+            throw new RolepodMcpError(
+              "unknown_ref",
+              `Ref "${ref}" not found in the current snapshot.`,
+              { session_id: session.id, ref }
+            );
+          }
+          await locator.first().evaluate((el) => el.setAttribute("data-rolepod-axe-scope", "true"));
+          scopeTagged = true;
+        }
+        const builder = new AxeBuilder({ page }).withTags(TAGS_BY_LEVEL[args.level]);
+        if (scopeTagged) builder.include("[data-rolepod-axe-scope]");
+        const results = await builder.analyze();
+        issues = results.violations.flatMap(
+          (v) => v.nodes.map((n, idx) => ({
+            wcag_ref: pickWcagRef(v.tags) ?? v.id,
+            severity: AXE_TO_SEVERITY[v.impact ?? "minor"] ?? "minor",
+            ref: `${v.id}#${idx}`,
+            description: v.help,
+            fix_suggestion: v.helpUrl,
+            target: n.target.join(" ")
+          }))
+        );
+        const payload = {
+          run_id: runId,
+          level: args.level,
+          counts: countBySeverity(issues),
+          issues
+        };
+        if (args.report_format === "markdown") {
+          reportPath = await ctx.store.writeReport(
+            runDir,
+            "report.md",
+            renderMarkdown(payload)
+          );
+        } else {
+          reportPath = await ctx.store.writeReport(
+            runDir,
+            "report.json",
+            JSON.stringify(payload, null, 2)
+          );
+        }
+      } finally {
+        if (scopeTagged) {
+          await page.locator("[data-rolepod-axe-scope]").first().evaluate((el) => el.removeAttribute("data-rolepod-axe-scope")).catch(() => void 0);
+        }
+        if (args.close_on_finish) {
+          await ctx.registry.close(session).catch(() => void 0);
+        }
+      }
+      return ok({
+        run_id: runId,
+        counts: countBySeverity(issues),
+        issues,
+        report_path: reportPath
+      });
+    });
+  }
+};
+function pickWcagRef(tags) {
+  return tags.find((t) => /^wcag\d/.test(t));
+}
+function countBySeverity(issues) {
+  const out = {
+    critical: 0,
+    serious: 0,
+    moderate: 0,
+    minor: 0
+  };
+  for (const i of issues) {
+    const s = String(i.severity);
+    out[s] = (out[s] ?? 0) + 1;
+  }
+  return out;
+}
+function renderMarkdown(p) {
+  const header = `# A11y audit \u2014 ${p.run_id}
+
+Level: \`${p.level}\`
+
+## Counts
+
+- critical: ${p.counts.critical}
+- serious: ${p.counts.serious}
+- moderate: ${p.counts.moderate}
+- minor: ${p.counts.minor}
+
+## Issues
+
+`;
+  const body = p.issues.map(
+    (i) => `### ${i.severity} \u2014 ${i.description}
+
+- WCAG: ${i.wcag_ref}
+- Target: \`${i.target}\`
+- Fix: ${i.fix_suggestion}
+`
+  ).join("\n");
+  return header + body;
+}
+
+// src/tools/composite/extract_ui_state.ts
+var extractUiStateTool = {
+  name: ToolNames.extractUiState,
+  description: "Return the AT-tree subtree most likely to answer a natural-language question, plus matched refs. No LLM is called \u2014 the Lead does the interpretation.",
+  inputShape: extractUiStateShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      let session;
+      let openedHere = false;
+      if (args.session_id) {
+        const platform = ctx.registry.platformOf(args.session_id);
+        session = { id: args.session_id, platform };
+      } else if (args.open) {
+        session = await ctx.registry.open(args.open);
+        openedHere = true;
+      } else {
+        throw new RolepodMcpError(
+          "invalid_input",
+          "Provide either `session_id` (existing session) or `open` (to start one)."
+        );
+      }
+      try {
+        const engine = ctx.registry.engineFor(session.id);
+        const snap = await engine.snapshot(session);
+        const tokens = tokenize(args.question_nl);
+        const matches = scoreTree(snap.tree, tokens);
+        const top = matches[0];
+        const subtree = top ? top.subtree : snap.tree;
+        const matchedRefs = matches.slice(0, 8).map((m) => m.ref);
+        let confidence = "low";
+        if (top) {
+          if (top.score >= tokens.length && tokens.length > 0) confidence = "high";
+          else if (top.score >= Math.max(1, Math.ceil(tokens.length / 2)))
+            confidence = "medium";
+        }
+        return ok({
+          snapshot_ref: snap.taken_at,
+          confidence,
+          matched_refs: matchedRefs,
+          value: subtree,
+          url_or_screen: snap.url_or_screen
+        });
+      } finally {
+        if (openedHere && args.close_on_finish) {
+          await ctx.registry.close(session).catch(() => void 0);
+        }
+      }
+    });
+  }
+};
+function tokenize(q) {
+  return q.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter((t) => t.length >= 2);
+}
+function scoreTree(root, tokens) {
+  const matches = [];
+  const visit = (node, ancestors) => {
+    const hay = `${node.name ?? ""} ${node.value ?? ""}`.toLowerCase();
+    let score = 0;
+    for (const t of tokens) if (hay.includes(t)) score += 1;
+    if (score > 0) {
+      const subtree = ancestors.length > 0 ? ancestors[ancestors.length - 1] : node;
+      matches.push({ ref: node.ref, score, subtree });
+    }
+    if (node.children) {
+      for (const c of node.children) visit(c, [...ancestors, node]);
+    }
+  };
+  visit(root, []);
+  matches.sort((a, b) => b.score - a.score);
+  return matches;
+}
+
+// src/tools/composite/scaffold_e2e.ts
+import { readFile as readFile2 } from "fs/promises";
+import { resolve as resolve4 } from "path";
+var scaffoldE2eTool = {
+  name: ToolNames.scaffoldE2e,
+  description: "Generate a runnable e2e test file (playwright-test, vitest+playwright, or pytest+selenium) from a scenario description and optional replay bundle from a prior verify_ui_flow run.",
+  inputShape: scaffoldE2eShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const { runId, runDir } = await ctx.store.startRun("scaffold");
+      const slug = slugify(args.scenario_nl);
+      const bundle = args.recorded_bundle ? await loadReplay(args.recorded_bundle) : null;
+      const ctxObj = { args, slug, bundle };
+      let body;
+      let language;
+      let filename;
+      let dependencies;
+      let setupNotes;
+      switch (args.framework) {
+        case "playwright-test":
+          body = renderPlaywrightTest(ctxObj);
+          language = "typescript";
+          filename = args.filename ?? `${slug}.spec.ts`;
+          dependencies = ["@playwright/test"];
+          setupNotes = "Install: `npm i -D @playwright/test && npx playwright install`. Run: `npx playwright test`.";
+          break;
+        case "vitest+playwright":
+          body = renderVitestPlaywright(ctxObj);
+          language = "typescript";
+          filename = args.filename ?? `${slug}.test.ts`;
+          dependencies = ["vitest", "playwright"];
+          setupNotes = "Install: `npm i -D vitest playwright && npx playwright install chromium`. Run: `npx vitest`.";
+          break;
+        case "pytest+selenium":
+          body = renderPytestSelenium(ctxObj);
+          language = "python";
+          filename = args.filename ?? `test_${slug}.py`;
+          dependencies = ["pytest", "selenium"];
+          setupNotes = "Install: `pip install pytest selenium`. Ensure a Chrome driver is on PATH. Run: `pytest`.";
+          break;
+        default:
+          throw new RolepodMcpError(
+            "invalid_input",
+            `Unknown framework "${args.framework}".`
+          );
+      }
+      const path = await ctx.store.writeReport(runDir, filename, body);
+      return ok({
+        run_id: runId,
+        test_file_path: path,
+        language,
+        dependencies,
+        setup_notes: setupNotes,
+        from_replay_bundle: Boolean(bundle)
+      });
+    });
+  }
+};
+async function loadReplay(bundlePath) {
+  const raw = await readFile2(resolve4(bundlePath), "utf8");
+  return JSON.parse(raw);
+}
+function slugify(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 40) || "scenario";
+}
+function renderPlaywrightTest(c) {
+  const url = c.bundle?.open?.url ?? c.args.url;
+  const stepLines = c.bundle?.steps?.length ? c.bundle.steps.map(playwrightStepLine).join("\n") : `  // TODO: implement steps for: ${c.args.scenario_nl}`;
+  const expectLines = c.bundle?.expect?.length ? c.bundle.expect.map(playwrightExpectLine).join("\n") : `  // TODO: add expectations`;
+  return [
+    `import { test, expect } from "@playwright/test";`,
+    ``,
+    `test(${JSON.stringify(c.args.scenario_nl)}, async ({ page }) => {`,
+    `  await page.goto(${JSON.stringify(url)});`,
+    stepLines,
+    expectLines,
+    `});`,
+    ``
+  ].join("\n");
+}
+function renderVitestPlaywright(c) {
+  const url = c.bundle?.open?.url ?? c.args.url;
+  const stepLines = c.bundle?.steps?.length ? c.bundle.steps.map(playwrightStepLine).join("\n") : `    // TODO: implement steps for: ${c.args.scenario_nl}`;
+  const expectLines = c.bundle?.expect?.length ? c.bundle.expect.map(playwrightExpectLine).join("\n") : `    // TODO: add expectations`;
+  return [
+    `import { test } from "vitest";`,
+    `import { chromium, expect } from "playwright/test";`,
+    ``,
+    `test(${JSON.stringify(c.args.scenario_nl)}, async () => {`,
+    `  const browser = await chromium.launch();`,
+    `  const page = await browser.newPage();`,
+    `  try {`,
+    `    await page.goto(${JSON.stringify(url)});`,
+    indent(stepLines, 2),
+    indent(expectLines, 2),
+    `  } finally {`,
+    `    await browser.close();`,
+    `  }`,
+    `});`,
+    ``
+  ].join("\n");
+}
+function renderPytestSelenium(c) {
+  const url = c.bundle?.open?.url ?? c.args.url;
+  const stepLines = c.bundle?.steps?.length ? c.bundle.steps.map(seleniumStepLine).join("\n") : `    # TODO: implement steps for: ${c.args.scenario_nl}`;
+  const expectLines = c.bundle?.expect?.length ? c.bundle.expect.map(seleniumExpectLine).join("\n") : `    # TODO: add expectations`;
+  return [
+    `import pytest`,
+    `from selenium import webdriver`,
+    `from selenium.webdriver.common.by import By`,
+    `from selenium.webdriver.common.keys import Keys`,
+    ``,
+    `def test_${slugifyPy(c.args.scenario_nl)}():`,
+    `    """${c.args.scenario_nl}"""`,
+    `    driver = webdriver.Chrome()`,
+    `    try:`,
+    `        driver.get(${JSON.stringify(url)})`,
+    indent(stepLines, 2),
+    indent(expectLines, 2),
+    `    finally:`,
+    `        driver.quit()`,
+    ``
+  ].join("\n");
+}
+function playwrightStepLine(step) {
+  switch (step.kind) {
+    case "click":
+      return `  await page.getByText(${JSON.stringify(step.query)}, { exact: false }).first().click();`;
+    case "type":
+      return `  await page.getByRole("textbox", { name: ${JSON.stringify(step.query)} }).fill(${JSON.stringify(step.text)});`;
+    case "key":
+      return `  await page.keyboard.press(${JSON.stringify(step.key)});`;
+    case "navigate":
+      return `  await page.goto(${JSON.stringify(step.url)});`;
+    case "wait_for":
+      return `  // wait_for: ${JSON.stringify(step.condition)} \u2014 translate to page.waitForXxx()`;
+    default:
+      return `  // unsupported step kind: ${step.kind}`;
+  }
+}
+function playwrightExpectLine(exp) {
+  switch (exp.kind) {
+    case "text_visible":
+      return `  await expect(page.getByText(${JSON.stringify(exp.text)}, { exact: false }).first()).toBeVisible();`;
+    case "text_absent":
+      return `  await expect(page.getByText(${JSON.stringify(exp.text)}, { exact: false }).first()).toHaveCount(0);`;
+    case "url_matches":
+      return `  await expect(page).toHaveURL(new RegExp(${JSON.stringify(exp.pattern)}));`;
+    case "ref_in_state":
+      return `  // ref_in_state ${JSON.stringify(exp.query)} \u2192 ${String(exp.state)} \u2014 translate as needed`;
+    default:
+      return `  // unsupported expect kind: ${exp.kind}`;
+  }
+}
+function seleniumStepLine(step) {
+  switch (step.kind) {
+    case "click":
+      return `    driver.find_element(By.XPATH, f"//*[contains(text(), \\"${escapePy(String(step.query))}\\")]").click()`;
+    case "type":
+      return `    driver.find_element(By.XPATH, f"//*[@aria-label=\\"${escapePy(String(step.query))}\\" or @placeholder=\\"${escapePy(String(step.query))}\\"]").send_keys(${JSON.stringify(step.text)})`;
+    case "key":
+      return `    driver.switch_to.active_element.send_keys(Keys.${pyKeyName(String(step.key))})`;
+    case "navigate":
+      return `    driver.get(${JSON.stringify(step.url)})`;
+    case "wait_for":
+      return `    # wait_for: ${JSON.stringify(step.condition)} \u2014 translate to WebDriverWait`;
+    default:
+      return `    # unsupported step kind: ${step.kind}`;
+  }
+}
+function seleniumExpectLine(exp) {
+  switch (exp.kind) {
+    case "text_visible":
+      return `    assert ${JSON.stringify(exp.text)} in driver.page_source`;
+    case "text_absent":
+      return `    assert ${JSON.stringify(exp.text)} not in driver.page_source`;
+    case "url_matches":
+      return `    import re; assert re.search(${JSON.stringify(exp.pattern)}, driver.current_url)`;
+    case "ref_in_state":
+      return `    # ref_in_state ${JSON.stringify(exp.query)} \u2192 ${String(exp.state)}`;
+    default:
+      return `    # unsupported expect kind: ${exp.kind}`;
+  }
+}
+function slugifyPy(s) {
+  return s.toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "").slice(0, 40) || "scenario";
+}
+function escapePy(s) {
+  return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+function pyKeyName(k) {
+  const map = {
+    Enter: "ENTER",
+    Tab: "TAB",
+    Escape: "ESCAPE",
+    Backspace: "BACK_SPACE",
+    ArrowUp: "ARROW_UP",
+    ArrowDown: "ARROW_DOWN",
+    ArrowLeft: "ARROW_LEFT",
+    ArrowRight: "ARROW_RIGHT"
+  };
+  return map[k] ?? `RETURN  # unknown key: ${k}`;
+}
+function indent(block, n) {
+  const pad = " ".repeat(n);
+  return block.split("\n").map((l) => l.length > 0 ? pad + l : l).join("\n");
+}
+
+// src/tools/composite/visual_diff.ts
+import { existsSync as existsSync2 } from "fs";
+import { readFile as readFile3 } from "fs/promises";
+import { resolve as resolve5 } from "path";
+import pixelmatch from "pixelmatch";
+import { PNG } from "pngjs";
+var visualDiffTool = {
+  name: ToolNames.visualDiff,
+  description: "Capture a screenshot and compare against a named baseline under ./.rolepod-uiproof/baselines/. First call for a baseline_id seeds the baseline (passed=true, diff_pct=0). Subsequent calls return the diff percentage and an annotated diff image.",
+  inputShape: visualDiffShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const { runId, runDir } = await ctx.store.startRun("vdiff");
+      const session = await ctx.registry.open({
+        ...args.open,
+        ...args.viewport ? { viewport: args.viewport } : {}
+      });
+      const engine = ctx.registry.engineFor(session.id);
+      if (!(engine instanceof PlaywrightEngine)) {
+        throw new RolepodMcpError(
+          "unsupported_engine",
+          "visual_diff currently requires PlaywrightEngine."
+        );
+      }
+      try {
+        const buf = await engine.screenshot(
+          { id: session.id, platform: session.platform },
+          true
+        );
+        const currentPath = await ctx.store.writeScreenshot(runDir, buf, "current");
+        await ctx.store.ensureDir(ctx.store.baselineDir);
+        const baselinePath = resolve5(
+          ctx.store.baselineDir,
+          `${args.baseline_id}.png`
+        );
+        if (!existsSync2(baselinePath)) {
+          await ctx.store.writeBytes(
+            ctx.store.baselineDir,
+            `${args.baseline_id}.png`,
+            buf
+          );
+          return ok({
+            run_id: runId,
+            baseline_id: args.baseline_id,
+            diff_pct: 0,
+            passed: true,
+            baseline_path: baselinePath,
+            current_path: currentPath,
+            note: "Baseline did not exist \u2014 current capture saved as the new baseline."
+          });
+        }
+        const [baselineRaw, currentRaw] = await Promise.all([
+          readFile3(baselinePath),
+          readFile3(currentPath)
+        ]);
+        const baseline = PNG.sync.read(baselineRaw);
+        const current = PNG.sync.read(currentRaw);
+        if (baseline.width !== current.width || baseline.height !== current.height) {
+          throw new RolepodMcpError(
+            "engine_error",
+            `Dimension mismatch for baseline "${args.baseline_id}" \u2014 baseline ${baseline.width}x${baseline.height}, current ${current.width}x${current.height}. Delete the baseline or pass a matching viewport.`,
+            {
+              baseline: { w: baseline.width, h: baseline.height },
+              current: { w: current.width, h: current.height }
+            }
+          );
+        }
+        const diff = new PNG({ width: baseline.width, height: baseline.height });
+        const diffPixels = pixelmatch(
+          baseline.data,
+          current.data,
+          diff.data,
+          baseline.width,
+          baseline.height,
+          { threshold: args.pixel_threshold, includeAA: true }
+        );
+        const total = baseline.width * baseline.height;
+        const diffPct = diffPixels / total;
+        const diffImagePath = await ctx.store.writeBytes(
+          runDir,
+          "diff.png",
+          PNG.sync.write(diff)
+        );
+        return ok({
+          run_id: runId,
+          baseline_id: args.baseline_id,
+          diff_pct: Number(diffPct.toFixed(6)),
+          diff_pixels: diffPixels,
+          total_pixels: total,
+          passed: diffPct <= args.threshold_pct,
+          baseline_path: baselinePath,
+          current_path: currentPath,
+          diff_image_path: diffImagePath
+        });
+      } finally {
+        if (args.close_on_finish) {
+          await ctx.registry.close(session).catch(() => void 0);
+        }
+      }
+    });
+  }
+};
+
+// src/server.ts
+var SERVER_NAME = "rolepod-uiproof";
+var SERVER_VERSION = "0.4.0";
+function buildServer(opts = {}) {
+  const webEngine = createWebEngine();
+  const registry = new SessionRegistry({ idleTimeoutMs: opts.idleTimeoutMs });
+  registry.register("web", webEngine);
+  const mobileEngine = createMobileEngine();
+  registry.register("ios", mobileEngine);
+  registry.register("android", mobileEngine);
+  const storeOpts = {};
+  if (opts.artifactRoot !== void 0) storeOpts.rootDir = opts.artifactRoot;
+  const store = new ArtifactStore(storeOpts);
+  const ctx = { registry, store };
+  const mcp = new McpServer({
+    name: SERVER_NAME,
+    version: SERVER_VERSION
+  });
+  const tools = [
+    // atomic
+    browserOpenTool,
+    browserCloseTool,
+    browserSnapshotTool,
+    browserClickTool,
+    browserTypeTool,
+    browserKeyTool,
+    browserScrollTool,
+    browserWaitForTool,
+    browserScreenshotTool,
+    browserNavigateTool,
+    // composite
+    verifyUiFlowTool,
+    auditA11yTool,
+    visualDiffTool,
+    scaffoldE2eTool,
+    extractUiStateTool
+  ];
+  for (const t of tools) {
+    mcp.registerTool(
+      t.name,
+      { description: t.description, inputSchema: t.inputShape },
+      t.build(ctx)
+    );
+  }
+  log.info("rolepod-uiproof server built", {
+    version: SERVER_VERSION,
+    tools: tools.map((t) => t.name)
+  });
+  return {
+    mcp,
+    registry,
+    store,
+    async shutdown() {
+      await registry.shutdown();
+      await mcp.close().catch(() => void 0);
+    }
+  };
+}
+
+// bin/rolepod-uiproof.ts
+var HELP = `rolepod-uiproof ${SERVER_VERSION}
+
+Usage:
+  rolepod-uiproof                 Start the MCP server on stdio (default)
+  rolepod-uiproof doctor          Health check (Node, Playwright, Appium, SDKs)
+  rolepod-uiproof install:mobile  Print mobile setup checklist (iOS / Android)
+  rolepod-uiproof replay <file>   Re-run a verify_ui_flow replay bundle
+  rolepod-uiproof --version       Print version
+  rolepod-uiproof --help          This help
+`;
+async function main() {
+  const [, , sub, ...rest] = process.argv;
+  switch (sub) {
+    case void 0:
+    case "serve":
+      return startServer();
+    case "doctor":
+      process.exit(await runDoctor());
+      return;
+    case "install:mobile":
+    case "install":
+      process.exit(runInstallMobile());
+      return;
+    case "replay": {
+      const target = rest[0];
+      if (!target) {
+        process.stderr.write("Usage: rolepod-uiproof replay <bundle.json>\n");
+        process.exit(2);
+      }
+      process.exit(await runReplay(target));
+      return;
+    }
+    case "--version":
+    case "-v":
+      process.stdout.write(`${SERVER_VERSION}
+`);
+      return;
+    case "--help":
+    case "-h":
+    case "help":
+      process.stdout.write(HELP);
+      return;
+    default:
+      process.stderr.write(`Unknown subcommand: ${sub}
+${HELP}`);
+      process.exit(2);
+  }
+}
+async function startServer() {
+  const server = buildServer();
+  const transport = new StdioServerTransport();
+  const shutdown = async (signal) => {
+    log.info("shutting down", { signal });
+    await server.shutdown().catch(
+      (err) => log.error("shutdown failed", { err: String(err) })
+    );
+    process.exit(0);
+  };
+  process.on("SIGINT", () => void shutdown("SIGINT"));
+  process.on("SIGTERM", () => void shutdown("SIGTERM"));
+  await server.mcp.connect(transport);
+  log.info("rolepod-uiproof connected on stdio");
+}
+main().catch((err) => {
+  log.error("fatal startup error", {
+    err: err instanceof Error ? err.stack : String(err)
+  });
+  process.exit(1);
+});
+//# sourceMappingURL=rolepod-uiproof.js.map