@rolepod/uiproof 0.4.0 → 0.5.0

package/dist/bin/rolepod-uiproof.js

@@ -582,6 +582,34 @@ var AppiumEngine = class {
     throw new UnsupportedPlatformError(_session.platform);
   }
   // -------------------------------------------------------------------------
+  // v0.5 cross-platform additions — mobile stubs.
+  // These ship as `not_implemented_in_v05` until the mobile gesture work lands.
+  // -------------------------------------------------------------------------
+  async hover(_session, _ref) {
+    throw new RolepodMcpError(
+      "engine_error",
+      "hover is not yet implemented for mobile (Appium). Use long-press via custom gesture if needed."
+    );
+  }
+  async drag(_session, _fromRef, _toRef) {
+    throw new RolepodMcpError(
+      "engine_error",
+      "drag is not yet implemented for mobile (Appium). Use the W3C Actions API directly if needed."
+    );
+  }
+  async fillForm(session, fields) {
+    for (const f of fields) {
+      const v = typeof f.value === "boolean" ? String(f.value) : f.value;
+      await this.type(session, f.ref, v);
+    }
+  }
+  async uploadFile(_session, _ref, _filePath) {
+    throw new RolepodMcpError(
+      "engine_error",
+      "upload_file is not supported on mobile (Appium)."
+    );
+  }
+  // -------------------------------------------------------------------------
   // Internals
   // -------------------------------------------------------------------------
   async loadWdio() {
@@ -696,6 +724,7 @@ function treeIncludesText(node, text) {
 
 // src/engine/PlaywrightEngine.ts
 import { randomUUID as randomUUID3 } from "crypto";
+import { resolve as resolvePath, isAbsolute } from "path";
 import {
   chromium,
   firefox,
@@ -805,6 +834,83 @@ function parseAriaSnapshot(snapshotYaml) {
 }
 
 // src/engine/PlaywrightEngine.ts
+var CONSOLE_BUFFER_CAP = 1e3;
+var NETWORK_BUFFER_CAP = 1e3;
+var NETWORK_PRESETS = {
+  offline: { offline: true, downloadThroughput: 0, uploadThroughput: 0, latency: 0 },
+  "slow-3g": {
+    offline: false,
+    // 500 Kbps down / 500 Kbps up / 400ms RTT
+    downloadThroughput: 500 * 1024 / 8,
+    uploadThroughput: 500 * 1024 / 8,
+    latency: 400
+  },
+  "fast-3g": {
+    offline: false,
+    downloadThroughput: 1.5 * 1024 * 1024 / 8,
+    uploadThroughput: 750 * 1024 / 8,
+    latency: 150
+  },
+  "slow-4g": {
+    offline: false,
+    downloadThroughput: 4 * 1024 * 1024 / 8,
+    uploadThroughput: 3 * 1024 * 1024 / 8,
+    latency: 100
+  },
+  "fast-4g": {
+    offline: false,
+    downloadThroughput: 9 * 1024 * 1024 / 8,
+    uploadThroughput: 4.5 * 1024 * 1024 / 8,
+    latency: 60
+  },
+  "no-throttling": {
+    offline: false,
+    downloadThroughput: -1,
+    uploadThroughput: -1,
+    latency: 0
+  }
+};
+function pushRing(buf, entry, cap) {
+  buf.push(entry);
+  if (buf.length > cap) buf.splice(0, buf.length - cap);
+}
+function mapConsoleLevel(t) {
+  switch (t) {
+    case "error":
+      return "error";
+    case "warning":
+      return "warning";
+    case "info":
+      return "info";
+    case "debug":
+      return "debug";
+    case "trace":
+      return "trace";
+    default:
+      return "log";
+  }
+}
+function formatConsoleLocation(msg) {
+  try {
+    const loc = msg.location();
+    if (!loc?.url) return void 0;
+    return `${loc.url}:${loc.lineNumber}:${loc.columnNumber}`;
+  } catch {
+    return void 0;
+  }
+}
+function findNetworkEntry(buf, req) {
+  const url = req.url();
+  const method = req.method();
+  for (let i = buf.length - 1; i >= 0; i--) {
+    const e = buf[i];
+    if (!e) continue;
+    if (e.url === url && e.method === method && e.status === void 0 && !e.failure) {
+      return e;
+    }
+  }
+  return void 0;
+}
 var PlaywrightEngine = class {
   id = "playwright";
   sessions = /* @__PURE__ */ new Map();
@@ -820,35 +926,80 @@ var PlaywrightEngine = class {
     if (opts.viewport) contextOptions.viewport = opts.viewport;
     if (opts.user_agent) contextOptions.userAgent = opts.user_agent;
     if (opts.locale) contextOptions.locale = opts.locale;
+    if (opts.capture?.har) {
+      contextOptions.recordHar = { path: opts.capture.har.path };
+    }
+    if (opts.capture?.video) {
+      contextOptions.recordVideo = {
+        dir: opts.capture.video.dir,
+        size: opts.capture.video.sizeWidth && opts.capture.video.sizeHeight ? {
+          width: opts.capture.video.sizeWidth,
+          height: opts.capture.video.sizeHeight
+        } : void 0
+      };
+    }
     const context = await browser.newContext(contextOptions);
-    const page = await context.newPage();
-    if (opts.url) {
-      await page.goto(opts.url, { waitUntil: "domcontentloaded" });
+    if (opts.capture?.trace) {
+      await context.tracing.start({
+        screenshots: true,
+        snapshots: true,
+        sources: false
+      });
     }
+    const page = await context.newPage();
     const sessionId = randomUUID3();
-    const session = {
-      id: sessionId,
-      platform: "web",
-      browser,
-      context,
-      page
-    };
-    this.sessions.set(sessionId, {
-      session,
+    const internals = {
+      session: {
+        id: sessionId,
+        platform: "web",
+        browser,
+        context,
+        mainPage: page
+      },
       refIndex: /* @__PURE__ */ new Map(),
       snapshotGeneration: 0,
       refGeneration: -1,
-      lastSnapshotAt: null
+      lastSnapshotAt: null,
+      pages: [page],
+      activePageIndex: 0,
+      consoleBuffer: [],
+      networkBuffer: [],
+      networkInflight: /* @__PURE__ */ new Map(),
+      networkNextId: 1,
+      dialogArming: null,
+      captureOpts: opts.capture,
+      traceStarted: !!opts.capture?.trace
+    };
+    this.attachPageListeners(internals, page);
+    context.on("page", (newPage) => {
+      internals.pages.push(newPage);
+      this.attachPageListeners(internals, newPage);
     });
+    if (opts.url) {
+      await page.goto(opts.url, { waitUntil: "domcontentloaded" });
+    }
+    this.sessions.set(sessionId, internals);
     log.info("session opened", {
       session_id: sessionId,
       browser: browserName,
-      url: opts.url ?? null
+      url: opts.url ?? null,
+      capture: opts.capture ? Object.keys(opts.capture).filter(
+        (k) => opts.capture[k]
+      ) : []
     });
     return { id: sessionId, platform: "web" };
   }
   async close(session) {
     const s = this.requireSession(session.id);
+    if (s.traceStarted && s.captureOpts?.trace) {
+      const tracePath = resolvePath(s.captureOpts.trace.artifactDir, "trace.zip");
+      await s.session.context.tracing.stop({ path: tracePath }).catch((err) => {
+        log.warn("trace stop failed", {
+          session_id: session.id,
+          err: String(err)
+        });
+      });
+    }
     await s.session.context.close().catch((err) => {
       log.warn("context close failed", { session_id: session.id, err: String(err) });
     });
@@ -860,7 +1011,7 @@ var PlaywrightEngine = class {
   }
   async snapshot(session, mode = "visible") {
     const s = this.requireSession(session.id);
-    const ariaYaml = await s.session.page.ariaSnapshot({ mode: "ai" });
+    const ariaYaml = await this.activePage(s).ariaSnapshot({ mode: "ai" });
     const { tree, refIndex } = parseAriaSnapshot(ariaYaml);
     void mode;
     s.snapshotGeneration += 1;
@@ -870,7 +1021,7 @@ var PlaywrightEngine = class {
     return {
       session_id: session.id,
       platform: "web",
-      url_or_screen: s.session.page.url(),
+      url_or_screen: this.activePage(s).url(),
       taken_at: s.lastSnapshotAt,
       tree
     };
@@ -890,7 +1041,7 @@ var PlaywrightEngine = class {
   }
   async key(session, key) {
     const s = this.requireSession(session.id);
-    await s.session.page.keyboard.press(key);
+    await this.activePage(s).keyboard.press(key);
     this.invalidateRefs(s);
   }
   async scroll(session, dir, amount = 400, ref) {
@@ -904,13 +1055,13 @@ var PlaywrightEngine = class {
         [dx, dy]
       );
     } else {
-      await s.session.page.mouse.wheel(dx, dy);
+      await this.activePage(s).mouse.wheel(dx, dy);
     }
     this.invalidateRefs(s);
   }
   async waitFor(session, cond, timeoutMs = 1e4) {
     const s = this.requireSession(session.id);
-    const page = s.session.page;
+    const page = this.activePage(s);
     switch (cond.kind) {
       case "text_visible":
         await page.getByText(cond.text, { exact: false }).first().waitFor({ state: "visible", timeout: timeoutMs });
@@ -930,14 +1081,14 @@ var PlaywrightEngine = class {
   }
   async screenshot(session, fullPage = false) {
     const s = this.requireSession(session.id);
-    return s.session.page.screenshot({ fullPage });
+    return this.activePage(s).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" });
+    await this.activePage(s).goto(url, { waitUntil: "domcontentloaded" });
     this.invalidateRefs(s);
   }
   /**
@@ -951,7 +1102,7 @@ var PlaywrightEngine = class {
     if (s.session.platform !== "web") {
       throw new UnsupportedPlatformError(s.session.platform);
     }
-    return s.session.page;
+    return this.activePage(s);
   }
   /** Increment generation; the next ref-using call will see them as stale. */
   bumpGeneration(sessionId) {
@@ -959,8 +1110,311 @@ var PlaywrightEngine = class {
     this.invalidateRefs(s);
   }
   // -------------------------------------------------------------------------
+  // v0.5 — input additions
+  // -------------------------------------------------------------------------
+  async hover(session, ref) {
+    const s = this.requireSession(session.id);
+    const locator = this.resolveLocator(s, ref);
+    await locator.hover();
+  }
+  async drag(session, fromRef, toRef) {
+    const s = this.requireSession(session.id);
+    const from = this.resolveLocator(s, fromRef);
+    const to = this.resolveLocator(s, toRef);
+    await from.dragTo(to);
+    this.invalidateRefs(s);
+  }
+  async fillForm(session, fields) {
+    const s = this.requireSession(session.id);
+    for (const field of fields) {
+      const locator = this.resolveLocator(s, field.ref);
+      const kind = field.kind;
+      if (kind === "checkbox" || kind === "radio") {
+        const checked = typeof field.value === "boolean" ? field.value : field.value === "true" || field.value === "on";
+        await locator.setChecked(checked);
+      } else if (kind === "select") {
+        await locator.selectOption(String(field.value));
+      } else {
+        await locator.fill(String(field.value));
+      }
+    }
+    this.invalidateRefs(s);
+  }
+  async uploadFile(session, ref, filePath) {
+    const s = this.requireSession(session.id);
+    if (!isAbsolute(filePath)) {
+      throw new RolepodMcpError(
+        "invalid_input",
+        `upload_file requires an absolute path; got "${filePath}".`,
+        { file_path: filePath }
+      );
+    }
+    const locator = this.resolveLocator(s, ref);
+    await locator.setInputFiles(filePath);
+    this.invalidateRefs(s);
+  }
+  // -------------------------------------------------------------------------
+  // v0.5 — web-only extensions (not on Engine interface; tools cast to
+  // PlaywrightEngine before calling).
+  // -------------------------------------------------------------------------
+  /**
+   * Pre-arm a one-shot dialog handler for the next dialog raised on the
+   * active page. Returns when either the dialog fires (and is handled)
+   * or the timeout elapses. The caller is expected to trigger the
+   * dialog (via click etc.) AFTER arming.
+   */
+  async handleDialog(sessionId, opts) {
+    const s = this.requireSession(sessionId);
+    const timeoutMs = opts.timeoutMs ?? 3e4;
+    const expiresAt = Date.now() + timeoutMs;
+    if (s.dialogArming) {
+      s.dialogArming.resolve(false);
+    }
+    return new Promise((resolve6) => {
+      const arming = {
+        action: opts.action,
+        text: opts.text,
+        expiresAt,
+        resolve: (handled) => {
+          s.dialogArming = null;
+          resolve6({ handled });
+        }
+      };
+      s.dialogArming = arming;
+      const timer = setTimeout(() => {
+        if (s.dialogArming === arming) {
+          s.dialogArming = null;
+          resolve6({ handled: false });
+        }
+      }, timeoutMs);
+      timer.unref?.();
+    });
+  }
+  getConsole(sessionId, opts) {
+    const s = this.requireSession(sessionId);
+    const levels = opts?.levels;
+    const contains = opts?.contains;
+    const limit = opts?.limit ?? 50;
+    let entries = s.consoleBuffer;
+    if (levels && levels.length > 0) {
+      entries = entries.filter((e) => levels.includes(e.level));
+    }
+    if (contains) {
+      entries = entries.filter((e) => e.text.includes(contains));
+    }
+    const result = entries.slice(-limit);
+    if (opts?.clear) s.consoleBuffer = [];
+    return result;
+  }
+  getNetwork(sessionId, opts) {
+    const s = this.requireSession(sessionId);
+    let entries = s.networkBuffer;
+    if (opts?.urlPattern) {
+      if (opts.patternKind === "regex") {
+        const re = new RegExp(opts.urlPattern);
+        entries = entries.filter((e) => re.test(e.url));
+      } else {
+        entries = entries.filter((e) => e.url.includes(opts.urlPattern));
+      }
+    }
+    if (opts?.method) {
+      const m = opts.method.toUpperCase();
+      entries = entries.filter((e) => e.method.toUpperCase() === m);
+    }
+    if (opts?.statusRange) {
+      const { min, max } = opts.statusRange;
+      entries = entries.filter(
+        (e) => e.status !== void 0 && e.status >= min && e.status <= max
+      );
+    }
+    if (opts?.onlyFailed) {
+      entries = entries.filter(
+        (e) => !!e.failure || e.status !== void 0 && e.status >= 400
+      );
+    }
+    const limit = opts?.limit ?? 50;
+    const result = entries.slice(-limit);
+    if (opts?.clear) s.networkBuffer = [];
+    return result;
+  }
+  /**
+   * Read the consoleBuffer/networkBuffer directly without filtering —
+   * used by verify_ui_flow expect evaluators.
+   */
+  peekBuffers(sessionId) {
+    const s = this.requireSession(sessionId);
+    return { console: s.consoleBuffer, network: s.networkBuffer };
+  }
+  /**
+   * Runtime mutation of context-level emulation. CPU + network throttle
+   * use CDP and only work on chromium; everything else is cross-browser.
+   */
+  async setEnv(sessionId, opts) {
+    const s = this.requireSession(sessionId);
+    const page = this.activePage(s);
+    const ctx = s.session.context;
+    if (opts.viewport) {
+      await page.setViewportSize(opts.viewport);
+    }
+    if (opts.offline !== void 0) {
+      await ctx.setOffline(opts.offline);
+    }
+    if (opts.geolocation) {
+      await ctx.setGeolocation(opts.geolocation);
+    }
+    if (opts.extraHeaders) {
+      await ctx.setExtraHTTPHeaders(opts.extraHeaders);
+    }
+    if (opts.colorScheme || opts.reducedMotion) {
+      await page.emulateMedia({
+        ...opts.colorScheme ? { colorScheme: opts.colorScheme } : {},
+        ...opts.reducedMotion ? { reducedMotion: opts.reducedMotion } : {}
+      });
+    }
+    if (opts.networkThrottle || opts.cpuThrottle !== void 0) {
+      const browserName = ctx.browser()?.browserType().name();
+      if (browserName !== "chromium") {
+        throw new RolepodMcpError(
+          "unsupported_engine",
+          `networkThrottle / cpuThrottle require chromium (CDP-backed); current browser is "${browserName}".`
+        );
+      }
+      const cdp = await ctx.newCDPSession(page);
+      try {
+        if (opts.networkThrottle) {
+          const preset = NETWORK_PRESETS[opts.networkThrottle];
+          await cdp.send("Network.enable");
+          await cdp.send("Network.emulateNetworkConditions", preset);
+        }
+        if (opts.cpuThrottle !== void 0) {
+          await cdp.send("Emulation.setCPUThrottlingRate", {
+            rate: opts.cpuThrottle
+          });
+        }
+      } finally {
+        await cdp.detach().catch(() => void 0);
+      }
+    }
+    this.invalidateRefs(s);
+  }
+  /**
+   * Execute a JavaScript function in the page context. ALWAYS gated by
+   * the tool layer (`ROLEPOD_ALLOW_EVAL=1`); this method does not enforce
+   * the env check.
+   */
+  async evaluate(sessionId, script, args) {
+    const s = this.requireSession(sessionId);
+    const page = this.activePage(s);
+    return page.evaluate(
+      ({ src, a }) => (
+        // eslint-disable-next-line no-new-func
+        new Function("args", `return (async () => { ${src} })();`)(a)
+      ),
+      { src: script, a: args ?? [] }
+    );
+  }
+  listPages(sessionId) {
+    const s = this.requireSession(sessionId);
+    return s.pages.map((p, i) => ({
+      index: i,
+      url: p.url(),
+      title_promise: p.title(),
+      active: i === s.activePageIndex
+    }));
+  }
+  async switchPage(sessionId, index) {
+    const s = this.requireSession(sessionId);
+    if (index < 0 || index >= s.pages.length) {
+      throw new RolepodMcpError(
+        "invalid_input",
+        `Page index ${index} out of range (have ${s.pages.length} page(s)).`,
+        { index, available: s.pages.length }
+      );
+    }
+    s.activePageIndex = index;
+    this.invalidateRefs(s);
+  }
+  // -------------------------------------------------------------------------
   // Internal helpers
   // -------------------------------------------------------------------------
+  activePage(s) {
+    return s.pages[s.activePageIndex] ?? s.session.mainPage;
+  }
+  attachPageListeners(s, page) {
+    page.on("console", (msg) => {
+      const level = mapConsoleLevel(msg.type());
+      pushRing(
+        s.consoleBuffer,
+        {
+          level,
+          text: msg.text(),
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          location: formatConsoleLocation(msg)
+        },
+        CONSOLE_BUFFER_CAP
+      );
+    });
+    page.on("request", (req) => {
+      const id = s.networkNextId++;
+      s.networkInflight.set(req.url() + "::" + req.method() + "::" + id, {
+        id,
+        startedAt: Date.now(),
+        resourceType: req.resourceType()
+      });
+      pushRing(
+        s.networkBuffer,
+        {
+          id,
+          url: req.url(),
+          method: req.method(),
+          resource_type: req.resourceType(),
+          ts: (/* @__PURE__ */ new Date()).toISOString()
+        },
+        NETWORK_BUFFER_CAP
+      );
+    });
+    page.on("response", (res) => {
+      const req = res.request();
+      const entry = findNetworkEntry(s.networkBuffer, req);
+      if (entry) {
+        entry.status = res.status();
+        entry.duration_ms = Date.now() - new Date(entry.ts).getTime();
+      }
+    });
+    page.on("requestfailed", (req) => {
+      const entry = findNetworkEntry(s.networkBuffer, req);
+      if (entry) {
+        entry.failure = req.failure()?.errorText ?? "request failed";
+      }
+    });
+    page.on("dialog", (dialog) => {
+      void this.handlePageDialog(s, dialog);
+    });
+  }
+  async handlePageDialog(s, dialog) {
+    const arm = s.dialogArming;
+    if (!arm || Date.now() > arm.expiresAt) {
+      await dialog.dismiss().catch(() => void 0);
+      if (arm) arm.resolve(false);
+      return;
+    }
+    try {
+      if (arm.action === "accept") {
+        await dialog.accept();
+      } else if (arm.action === "accept_with_text") {
+        await dialog.accept(arm.text ?? "");
+      } else {
+        await dialog.dismiss();
+      }
+      arm.resolve(true);
+    } catch (err) {
+      log.warn("dialog handle failed", {
+        session_id: s.session.id,
+        err: String(err)
+      });
+      arm.resolve(false);
+    }
+  }
   requireSession(sessionId) {
     const s = this.sessions.get(sessionId);
     if (!s) {
@@ -989,7 +1443,7 @@ var PlaywrightEngine = class {
     if (meta.ref.startsWith("s")) {
       throw new UnknownRefError(s.session.id, ref);
     }
-    return s.session.page.locator(`aria-ref=${meta.ref}`);
+    return this.activePage(s).locator(`aria-ref=${meta.ref}`);
   }
   invalidateRefs(s) {
     s.snapshotGeneration += 1;
@@ -1125,6 +1579,10 @@ var SessionRegistry = class {
   }
 };
 
+// src/tools/composite/verify_ui_flow.ts
+import { readdir } from "fs/promises";
+import { resolve as resolvePath2 } from "path";
+
 // src/schema/tools.ts
 import { z } from "zod";
 var platformSchema = z.enum(["web", "ios", "android"]);
@@ -1228,6 +1686,143 @@ var browserNavigateShape = {
   url: z.string().url()
 };
 var browserNavigateSchema = z.object(browserNavigateShape);
+var browserHoverShape = {
+  session_id: z.string().min(1),
+  ref: z.string().min(1)
+};
+var browserHoverSchema = z.object(browserHoverShape);
+var browserDragShape = {
+  session_id: z.string().min(1),
+  from_ref: z.string().min(1),
+  to_ref: z.string().min(1)
+};
+var browserDragSchema = z.object(browserDragShape);
+var fillFieldKindSchema = z.enum([
+  "input",
+  "select",
+  "checkbox",
+  "radio"
+]);
+var fillFormFieldSchema = z.object({
+  ref: z.string().min(1),
+  value: z.union([z.string(), z.boolean()]),
+  kind: fillFieldKindSchema.optional()
+});
+var browserFillFormShape = {
+  session_id: z.string().min(1),
+  fields: z.array(fillFormFieldSchema).min(1)
+};
+var browserFillFormSchema = z.object(browserFillFormShape);
+var browserUploadFileShape = {
+  session_id: z.string().min(1),
+  ref: z.string().min(1),
+  file_path: z.string().min(1)
+};
+var browserUploadFileSchema = z.object(browserUploadFileShape);
+var dialogActionSchema = z.enum([
+  "accept",
+  "dismiss",
+  "accept_with_text"
+]);
+var browserHandleDialogShape = {
+  session_id: z.string().min(1),
+  action: dialogActionSchema,
+  /** Only used when action='accept_with_text'. */
+  text: z.string().optional(),
+  /**
+   * Arming behavior: registers a one-shot handler for the NEXT dialog
+   * raised on the page. Call this BEFORE the action that triggers the
+   * dialog (e.g. before clicking the button that calls `confirm()`).
+   * Default 30s if no dialog appears, handler is auto-removed.
+   */
+  timeout_ms: z.number().int().positive().optional()
+};
+var browserHandleDialogSchema = z.object(browserHandleDialogShape);
+var consoleLevelSchema = z.enum([
+  "error",
+  "warning",
+  "info",
+  "log",
+  "debug",
+  "trace"
+]);
+var browserConsoleShape = {
+  session_id: z.string().min(1),
+  /** Filter to only these levels. Default: errors+warnings. */
+  levels: z.array(consoleLevelSchema).optional(),
+  /** Substring match on message text. */
+  contains: z.string().optional(),
+  /** Drop all buffered messages after returning. */
+  clear: z.boolean().default(false),
+  /** Cap on returned messages (artifact still holds full ring buffer). */
+  limit: z.number().int().positive().max(1e3).default(50)
+};
+var browserConsoleSchema = z.object(browserConsoleShape);
+var browserNetworkShape = {
+  session_id: z.string().min(1),
+  /** Substring or regex (per `pattern_kind`) match on URL. */
+  url_pattern: z.string().optional(),
+  pattern_kind: z.enum(["substring", "regex"]).default("substring"),
+  method: z.string().optional(),
+  /** Inclusive range — e.g. `{min: 400, max: 599}` for any error response. */
+  status_range: z.object({
+    min: z.number().int().min(100).max(599),
+    max: z.number().int().min(100).max(599)
+  }).optional(),
+  only_failed: z.boolean().default(false),
+  /** Write the full HAR file for this session to artifacts/{runId}/network.har. */
+  export_har: z.boolean().default(false),
+  /** Drop buffered entries after returning. */
+  clear: z.boolean().default(false),
+  limit: z.number().int().positive().max(1e3).default(50)
+};
+var browserNetworkSchema = z.object(browserNetworkShape);
+var networkPresetSchema = z.enum([
+  "offline",
+  "slow-3g",
+  "fast-3g",
+  "slow-4g",
+  "fast-4g",
+  "no-throttling"
+]);
+var geolocationSchema = z.object({
+  latitude: z.number().min(-90).max(90),
+  longitude: z.number().min(-180).max(180),
+  accuracy: z.number().nonnegative().optional()
+});
+var browserSetEnvShape = {
+  session_id: z.string().min(1),
+  viewport: viewportSchema.optional(),
+  offline: z.boolean().optional(),
+  geolocation: geolocationSchema.optional(),
+  color_scheme: z.enum(["light", "dark", "no-preference"]).optional(),
+  reduced_motion: z.enum(["reduce", "no-preference"]).optional(),
+  extra_headers: z.record(z.string(), z.string()).optional(),
+  network_throttle: networkPresetSchema.optional(),
+  /** CPU slowdown multiplier (1 = no throttle, 4 = 4x slower). Chromium only. */
+  cpu_throttle: z.number().min(1).max(20).optional()
+};
+var browserSetEnvSchema = z.object(browserSetEnvShape);
+var browserEvaluateShape = {
+  session_id: z.string().min(1),
+  script: z.string().min(1),
+  args: z.array(z.unknown()).optional()
+};
+var browserEvaluateSchema = z.object(browserEvaluateShape);
+var browserPagesShape = {
+  session_id: z.string().min(1)
+};
+var browserPagesSchema = z.object(browserPagesShape);
+var browserSwitchPageShape = {
+  session_id: z.string().min(1),
+  index: z.number().int().nonnegative()
+};
+var browserSwitchPageSchema = z.object(browserSwitchPageShape);
+var verifyFillFieldSchema = z.object({
+  query: z.string(),
+  value: z.union([z.string(), z.boolean()]),
+  kind: fillFieldKindSchema.optional()
+});
 var verifyStepSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("click"), query: z.string() }),
   z.object({
@@ -1238,7 +1833,44 @@ var verifyStepSchema = z.discriminatedUnion("kind", [
   }),
   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() })
+  z.object({ kind: z.literal("navigate"), url: z.string().url() }),
+  // v0.5 additions
+  z.object({ kind: z.literal("hover"), query: z.string() }),
+  z.object({
+    kind: z.literal("drag"),
+    from_query: z.string(),
+    to_query: z.string()
+  }),
+  z.object({
+    kind: z.literal("fill_form"),
+    fields: z.array(verifyFillFieldSchema).min(1)
+  }),
+  z.object({
+    kind: z.literal("upload"),
+    query: z.string(),
+    file_path: z.string().min(1)
+  }),
+  z.object({
+    kind: z.literal("dialog"),
+    action: dialogActionSchema,
+    text: z.string().optional()
+  }),
+  z.object({
+    kind: z.literal("set_env"),
+    viewport: viewportSchema.optional(),
+    offline: z.boolean().optional(),
+    geolocation: geolocationSchema.optional(),
+    color_scheme: z.enum(["light", "dark", "no-preference"]).optional(),
+    reduced_motion: z.enum(["reduce", "no-preference"]).optional(),
+    extra_headers: z.record(z.string(), z.string()).optional(),
+    network_throttle: networkPresetSchema.optional(),
+    cpu_throttle: z.number().min(1).max(20).optional()
+  }),
+  z.object({
+    kind: z.literal("switch_page"),
+    index: z.number().int().nonnegative()
+  }),
+  z.object({ kind: z.literal("evaluate"), script: z.string().min(1) })
 ]);
 var verifyExpectSchema = z.discriminatedUnion("kind", [
   z.object({ kind: z.literal("text_visible"), text: z.string() }),
@@ -1248,6 +1880,28 @@ var verifyExpectSchema = z.discriminatedUnion("kind", [
     kind: z.literal("ref_in_state"),
     query: z.string(),
     state: z.enum(["visible", "enabled", "focused"])
+  }),
+  // v0.5 additions
+  z.object({
+    kind: z.literal("no_console_errors"),
+    exclude_patterns: z.array(z.string()).optional()
+  }),
+  z.object({
+    kind: z.literal("no_failed_requests"),
+    exclude_patterns: z.array(z.string()).optional(),
+    /** When true, only 5xx counts as a failure. Default false (4xx + 5xx). */
+    allow_4xx: z.boolean().optional()
+  }),
+  z.object({
+    kind: z.literal("request_made"),
+    url_pattern: z.string(),
+    method: z.string().optional(),
+    min_count: z.number().int().positive().optional()
+  }),
+  z.object({
+    kind: z.literal("response_status"),
+    url_pattern: z.string(),
+    status: z.number().int().min(100).max(599)
   })
 ]);
 var captureKindSchema = z.enum([
@@ -1255,7 +1909,8 @@ var captureKindSchema = z.enum([
   "har",
   "console",
   "a11y_tree",
-  "video"
+  "video",
+  "trace"
 ]);
 var verifyUiFlowShape = {
   mode: z.enum(["assert", "reproduce"]).default("assert"),
@@ -1333,6 +1988,19 @@ var ToolNames = {
   browserWaitFor: "rolepod_browser_wait_for",
   browserScreenshot: "rolepod_browser_screenshot",
   browserNavigate: "rolepod_browser_navigate",
+  // v0.5 atomics
+  browserHover: "rolepod_browser_hover",
+  browserDrag: "rolepod_browser_drag",
+  browserFillForm: "rolepod_browser_fill_form",
+  browserUploadFile: "rolepod_browser_upload_file",
+  browserHandleDialog: "rolepod_browser_handle_dialog",
+  browserConsole: "rolepod_browser_console",
+  browserNetwork: "rolepod_browser_network",
+  browserSetEnv: "rolepod_browser_set_env",
+  browserEvaluate: "rolepod_browser_evaluate",
+  browserPages: "rolepod_browser_pages",
+  browserSwitchPage: "rolepod_browser_switch_page",
+  // composite
   verifyUiFlow: "rolepod_verify_ui_flow",
   auditA11y: "rolepod_audit_a11y",
   visualDiff: "rolepod_visual_diff",
@@ -1437,13 +2105,32 @@ var verifyUiFlowTool = {
     });
   }
 };
+function buildCaptureOptions(captures, runDir) {
+  const cap = {};
+  if (captures.has("har")) {
+    cap.har = { path: resolvePath2(runDir, "network.har") };
+  }
+  if (captures.has("video")) {
+    cap.video = { dir: resolvePath2(runDir, "videos") };
+  }
+  if (captures.has("trace")) {
+    cap.trace = { artifactDir: runDir };
+  }
+  return Object.keys(cap).length > 0 ? cap : void 0;
+}
 async function runFlow(ctx, args, steps, runDir, opts) {
   const evidence = { screenshots: [] };
+  const captures = new Set(args.capture ?? ["screenshot"]);
   let passed = false;
   let failedAtStep;
   let failureReason;
   let finalSnapshot;
-  const session = await ctx.registry.open(args.open);
+  const openOpts = { ...args.open };
+  const captureCfg = buildCaptureOptions(captures, runDir);
+  if (captureCfg) {
+    openOpts.capture = captureCfg;
+  }
+  const session = await ctx.registry.open(openOpts);
   const engine = ctx.registry.engineFor(session.id);
   const sessionHandle = { id: session.id, platform: session.platform };
   try {
@@ -1462,7 +2149,7 @@ async function runFlow(ctx, args, steps, runDir, opts) {
     const failures = [];
     for (let i = 0; i < args.expect.length; i++) {
       const expectation = args.expect[i];
-      if (!evaluateExpect(expectation, finalSnapshot)) {
+      if (!evaluateExpect(expectation, finalSnapshot, engine, session.id)) {
         failures.push(`expect[${i}] ${describeExpect(expectation)}`);
       }
     }
@@ -1476,8 +2163,7 @@ async function runFlow(ctx, args, steps, runDir, opts) {
     passed = false;
   } finally {
     if (opts.captureEvidence) {
-      const wantScreenshot = !args.capture || args.capture.includes("screenshot");
-      if (wantScreenshot) {
+      if (captures.has("screenshot")) {
         try {
           const buf = await engine.screenshot(sessionHandle, true);
           const p = await ctx.store.writeScreenshot(runDir, buf, "final");
@@ -1486,6 +2172,37 @@ async function runFlow(ctx, args, steps, runDir, opts) {
           failureReason ??= `screenshot capture failed: ${describeError(err)}`;
         }
       }
+      if (captures.has("console") && engine instanceof PlaywrightEngine) {
+        try {
+          const messages = engine.peekBuffers(session.id).console;
+          evidence.console = await ctx.store.writeReport(
+            runDir,
+            "console.json",
+            JSON.stringify(
+              {
+                count: messages.length,
+                by_level: countByLevel(messages),
+                messages
+              },
+              null,
+              2
+            )
+          );
+        } catch (err) {
+          failureReason ??= `console capture failed: ${describeError(err)}`;
+        }
+      }
+      if (captures.has("a11y_tree") && finalSnapshot) {
+        try {
+          evidence.a11y_tree = await ctx.store.writeReport(
+            runDir,
+            "a11y_tree.json",
+            JSON.stringify(finalSnapshot, null, 2)
+          );
+        } catch (err) {
+          failureReason ??= `a11y_tree capture failed: ${describeError(err)}`;
+        }
+      }
       try {
         evidence.replay_bundle = await ctx.store.writeReplayBundle(
           runDir,
@@ -1506,12 +2223,32 @@ async function runFlow(ctx, args, steps, runDir, opts) {
       await ctx.registry.close(sessionHandle).catch(() => void 0);
     }
   }
+  if (opts.captureEvidence) {
+    if (captureCfg?.har) evidence.har = captureCfg.har.path;
+    if (captureCfg?.trace) {
+      evidence.trace = resolvePath2(captureCfg.trace.artifactDir, "trace.zip");
+    }
+    if (captureCfg?.video) {
+      try {
+        const files = await readdir(captureCfg.video.dir).catch(() => []);
+        evidence.video = files.filter((f) => f.endsWith(".webm")).map((f) => resolvePath2(captureCfg.video.dir, f));
+      } catch {
+      }
+    }
+  }
   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;
 }
+function countByLevel(messages) {
+  const counts = {};
+  for (const m of messages) {
+    counts[m.level] = (counts[m.level] ?? 0) + 1;
+  }
+  return counts;
+}
 async function minimize(ctx, args, initialSteps, runDir) {
   const tagged = initialSteps.map((step, origIndex) => ({ step, origIndex }));
   let attempts = 0;
@@ -1575,9 +2312,84 @@ async function runStep(engine, session, step, snap) {
     case "navigate":
       await engine.navigate(session, step.url);
       return;
+    case "hover": {
+      const ref = findRefByQuery(snap.tree, step.query);
+      if (!ref) throw missingQuery(step.query);
+      await engine.hover(session, ref);
+      return;
+    }
+    case "drag": {
+      const fromRef = findRefByQuery(snap.tree, step.from_query);
+      if (!fromRef) throw missingQuery(step.from_query);
+      const toRef = findRefByQuery(snap.tree, step.to_query);
+      if (!toRef) throw missingQuery(step.to_query);
+      await engine.drag(session, fromRef, toRef);
+      return;
+    }
+    case "fill_form": {
+      const resolved = step.fields.map((f) => {
+        const ref = findRefByQuery(snap.tree, f.query);
+        if (!ref) throw missingQuery(f.query);
+        return f.kind !== void 0 ? { ref, value: f.value, kind: f.kind } : { ref, value: f.value };
+      });
+      await engine.fillForm(session, resolved);
+      return;
+    }
+    case "upload": {
+      const ref = findRefByQuery(snap.tree, step.query);
+      if (!ref) throw missingQuery(step.query);
+      await engine.uploadFile(session, ref, step.file_path);
+      return;
+    }
+    case "dialog": {
+      requirePlaywright(engine, "dialog");
+      void engine.handleDialog(session.id, {
+        action: step.action,
+        ...step.text !== void 0 ? { text: step.text } : {}
+      }).catch(() => void 0);
+      return;
+    }
+    case "set_env": {
+      requirePlaywright(engine, "set_env");
+      await engine.setEnv(session.id, {
+        ...step.viewport !== void 0 ? { viewport: step.viewport } : {},
+        ...step.offline !== void 0 ? { offline: step.offline } : {},
+        ...step.geolocation !== void 0 ? { geolocation: step.geolocation } : {},
+        ...step.color_scheme !== void 0 ? { colorScheme: step.color_scheme } : {},
+        ...step.reduced_motion !== void 0 ? { reducedMotion: step.reduced_motion } : {},
+        ...step.extra_headers !== void 0 ? { extraHeaders: step.extra_headers } : {},
+        ...step.network_throttle !== void 0 ? { networkThrottle: step.network_throttle } : {},
+        ...step.cpu_throttle !== void 0 ? { cpuThrottle: step.cpu_throttle } : {}
+      });
+      return;
+    }
+    case "switch_page": {
+      requirePlaywright(engine, "switch_page");
+      await engine.switchPage(session.id, step.index);
+      return;
+    }
+    case "evaluate": {
+      requirePlaywright(engine, "evaluate");
+      if (process.env.ROLEPOD_ALLOW_EVAL !== "1") {
+        throw new RolepodMcpError(
+          "engine_error",
+          "verify_ui_flow step kind 'evaluate' is disabled. Restart the rolepod-uiproof MCP server with ROLEPOD_ALLOW_EVAL=1 to enable."
+        );
+      }
+      await engine.evaluate(session.id, step.script);
+      return;
+    }
+  }
+}
+function requirePlaywright(engine, stepKind) {
+  if (!(engine instanceof PlaywrightEngine)) {
+    throw new RolepodMcpError(
+      "unsupported_engine",
+      `verify_ui_flow step kind "${stepKind}" is web-only and requires PlaywrightEngine.`
+    );
   }
 }
-function evaluateExpect(exp, snap) {
+function evaluateExpect(exp, snap, engine, sessionId) {
   switch (exp.kind) {
     case "text_visible":
       return treeHasText(snap.tree, exp.text);
@@ -1597,6 +2409,49 @@ function evaluateExpect(exp, snap) {
           return node.state?.focused === true;
       }
     }
+    case "no_console_errors": {
+      if (!(engine instanceof PlaywrightEngine)) return true;
+      const msgs = engine.peekBuffers(sessionId).console.filter(
+        (m) => m.level === "error"
+      );
+      const excludes = exp.exclude_patterns ?? [];
+      const remaining = msgs.filter(
+        (m) => !excludes.some((p) => m.text.includes(p))
+      );
+      return remaining.length === 0;
+    }
+    case "no_failed_requests": {
+      if (!(engine instanceof PlaywrightEngine)) return true;
+      const reqs = engine.peekBuffers(sessionId).network.filter((r) => {
+        if (r.failure) return true;
+        if (r.status === void 0) return false;
+        if (exp.allow_4xx) return r.status >= 500;
+        return r.status >= 400;
+      });
+      const excludes = exp.exclude_patterns ?? [];
+      const remaining = reqs.filter(
+        (r) => !excludes.some((p) => r.url.includes(p))
+      );
+      return remaining.length === 0;
+    }
+    case "request_made": {
+      if (!(engine instanceof PlaywrightEngine)) return false;
+      const re = new RegExp(exp.url_pattern);
+      const wantMethod = exp.method?.toUpperCase();
+      const matches = engine.peekBuffers(sessionId).network.filter((r) => {
+        if (!re.test(r.url)) return false;
+        if (wantMethod && r.method.toUpperCase() !== wantMethod) return false;
+        return true;
+      });
+      const min = exp.min_count ?? 1;
+      return matches.length >= min;
+    }
+    case "response_status": {
+      if (!(engine instanceof PlaywrightEngine)) return false;
+      const re = new RegExp(exp.url_pattern);
+      const match = engine.peekBuffers(sessionId).network.find((r) => re.test(r.url) && r.status === exp.status);
+      return match !== void 0;
+    }
   }
 }
 function describeExpect(exp) {
@@ -1609,6 +2464,14 @@ function describeExpect(exp) {
       return `url_matches /${exp.pattern}/`;
     case "ref_in_state":
       return `ref_in_state "${exp.query}" \u2192 ${exp.state}`;
+    case "no_console_errors":
+      return "no_console_errors";
+    case "no_failed_requests":
+      return "no_failed_requests";
+    case "request_made":
+      return `request_made ${exp.method ?? ""} ${exp.url_pattern}`.trim();
+    case "response_status":
+      return `response_status ${exp.url_pattern} = ${exp.status}`;
   }
 }
 function missingQuery(query) {
@@ -1725,6 +2588,151 @@ var browserCloseTool = {
   }
 };
 
+// src/tools/atomic/browser_console.ts
+var browserConsoleTool = {
+  name: ToolNames.browserConsole,
+  description: "List console messages emitted by the active page since the session opened (or since the last `clear`). Filters: `levels` (default: errors+warnings), substring `contains`, and `limit` (default 50, max 1000). Set `clear: true` to drain the buffer after returning. Read-only.",
+  inputShape: browserConsoleShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      if (!(engine instanceof PlaywrightEngine)) {
+        throw new RolepodMcpError(
+          "unsupported_engine",
+          "console is web-only and requires PlaywrightEngine."
+        );
+      }
+      const levels = args.levels && args.levels.length > 0 ? args.levels : ["error", "warning"];
+      const messages = engine.getConsole(args.session_id, {
+        levels,
+        ...args.contains !== void 0 ? { contains: args.contains } : {},
+        clear: args.clear,
+        limit: args.limit
+      });
+      return ok({
+        count: messages.length,
+        messages
+      });
+    });
+  }
+};
+
+// src/tools/atomic/browser_drag.ts
+var browserDragTool = {
+  name: ToolNames.browserDrag,
+  description: "Drag the element identified by `from_ref` onto the element identified by `to_ref`. Both refs come from the most recent snapshot. Invalidates all refs on success.",
+  inputShape: browserDragShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      await engine.drag(
+        {
+          id: args.session_id,
+          platform: ctx.registry.platformOf(args.session_id)
+        },
+        args.from_ref,
+        args.to_ref
+      );
+      return ok({ dragged: true });
+    });
+  }
+};
+
+// src/tools/atomic/browser_evaluate.ts
+var browserEvaluateTool = {
+  name: ToolNames.browserEvaluate,
+  description: "Execute JavaScript in the active page's context. The `script` is the body of an async function \u2014 use `return` for the result and reference inputs via the implicit `args` array. DISABLED unless the MCP server was launched with `ROLEPOD_ALLOW_EVAL=1`; intended for trusted automation setups only (state seeding, computed-style reads, synthetic event dispatch).",
+  inputShape: browserEvaluateShape,
+  build(ctx) {
+    const allowed = process.env.ROLEPOD_ALLOW_EVAL === "1";
+    return safeHandler(async (args) => {
+      if (!allowed) {
+        throw new RolepodMcpError(
+          "engine_error",
+          "browser_evaluate is disabled. Restart the rolepod-uiproof MCP server with the env var ROLEPOD_ALLOW_EVAL=1 to enable arbitrary JavaScript execution in the page context."
+        );
+      }
+      const engine = ctx.registry.engineFor(args.session_id);
+      if (!(engine instanceof PlaywrightEngine)) {
+        throw new RolepodMcpError(
+          "unsupported_engine",
+          "evaluate is web-only and requires PlaywrightEngine."
+        );
+      }
+      const result = await engine.evaluate(
+        args.session_id,
+        args.script,
+        args.args
+      );
+      return ok({ result });
+    });
+  }
+};
+
+// src/tools/atomic/browser_fill_form.ts
+var browserFillFormTool = {
+  name: ToolNames.browserFillForm,
+  description: "Batch-fill multiple form fields (inputs, selects, checkboxes, radios) in one call. Each field needs a `ref` from the latest snapshot and a `value`; pass `kind` to disambiguate non-input controls. Token-efficient alternative to a sequence of `type` calls. Invalidates all refs on success.",
+  inputShape: browserFillFormShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      await engine.fillForm(
+        {
+          id: args.session_id,
+          platform: ctx.registry.platformOf(args.session_id)
+        },
+        args.fields
+      );
+      return ok({ filled: args.fields.length });
+    });
+  }
+};
+
+// src/tools/atomic/browser_handle_dialog.ts
+var browserHandleDialogTool = {
+  name: ToolNames.browserHandleDialog,
+  description: "Pre-arm a one-shot handler for the NEXT JavaScript dialog (`alert`/`confirm`/`prompt`/`beforeunload`) on the active page. Call this BEFORE the action that triggers the dialog (e.g. before clicking the button that calls `confirm()`). Returns when the dialog fires or the timeout (default 30s) elapses. Un-armed dialogs are auto-dismissed so the page does not hang.",
+  inputShape: browserHandleDialogShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      if (!(engine instanceof PlaywrightEngine)) {
+        throw new RolepodMcpError(
+          "unsupported_engine",
+          "handle_dialog is web-only and requires PlaywrightEngine."
+        );
+      }
+      const { handled } = await engine.handleDialog(args.session_id, {
+        action: args.action,
+        ...args.text !== void 0 ? { text: args.text } : {},
+        ...args.timeout_ms !== void 0 ? { timeoutMs: args.timeout_ms } : {}
+      });
+      return ok({ handled, action: args.action });
+    });
+  }
+};
+
+// src/tools/atomic/browser_hover.ts
+var browserHoverTool = {
+  name: ToolNames.browserHover,
+  description: "Hover the pointer over the element identified by `ref`. Refs remain valid afterwards (read-mostly).",
+  inputShape: browserHoverShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      await engine.hover(
+        {
+          id: args.session_id,
+          platform: ctx.registry.platformOf(args.session_id)
+        },
+        args.ref
+      );
+      return ok({ hovered: true });
+    });
+  }
+};
+
 // src/tools/atomic/browser_key.ts
 var browserKeyTool = {
   name: ToolNames.browserKey,
@@ -1753,6 +2761,46 @@ var browserNavigateTool = {
   }
 };
 
+// src/tools/atomic/browser_network.ts
+var browserNetworkTool = {
+  name: ToolNames.browserNetwork,
+  description: 'List network requests captured on the active page. Filters: `url_pattern` (substring or regex via `pattern_kind`), `method`, `status_range`, `only_failed`. Set `export_har: true` to require the session to have been opened with HAR recording \u2014 see `verify_ui_flow` capture=["har"] or call `browser_open` with capture.har=true. Read-only unless `clear: true`.',
+  inputShape: browserNetworkShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      if (!(engine instanceof PlaywrightEngine)) {
+        throw new RolepodMcpError(
+          "unsupported_engine",
+          "network is web-only and requires PlaywrightEngine."
+        );
+      }
+      const requests = engine.getNetwork(args.session_id, {
+        ...args.url_pattern !== void 0 ? { urlPattern: args.url_pattern } : {},
+        patternKind: args.pattern_kind,
+        ...args.method !== void 0 ? { method: args.method } : {},
+        ...args.status_range !== void 0 ? { statusRange: args.status_range } : {},
+        onlyFailed: args.only_failed,
+        clear: args.clear,
+        limit: args.limit
+      });
+      const failed = requests.filter(
+        (r) => !!r.failure || r.status !== void 0 && r.status >= 400
+      ).length;
+      return ok({
+        count: requests.length,
+        failed_count: failed,
+        requests,
+        // HAR file lives wherever the session was opened with
+        // `capture.har.path`. We don't echo it here to avoid leaking
+        // filesystem paths into untrusted logs; the verify_ui_flow run
+        // result surfaces it in `evidence_paths.har`.
+        har_recording: args.export_har ? "HAR is written at session close to the path passed via capture.har at open time." : void 0
+      });
+    });
+  }
+};
+
 // src/tools/atomic/browser_open.ts
 var browserOpenTool = {
   name: ToolNames.browserOpen,
@@ -1766,6 +2814,34 @@ var browserOpenTool = {
   }
 };
 
+// src/tools/atomic/browser_pages.ts
+var browserPagesTool = {
+  name: ToolNames.browserPages,
+  description: "List all pages currently open in the session's browser context \u2014 typically just the main page, plus any popups, OAuth windows, or `target=_blank` tabs that the page itself opened. Each entry carries `{ index, url, title, active }`. Read-only.",
+  inputShape: browserPagesShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      if (!(engine instanceof PlaywrightEngine)) {
+        throw new RolepodMcpError(
+          "unsupported_engine",
+          "pages is web-only and requires PlaywrightEngine."
+        );
+      }
+      const raw = engine.listPages(args.session_id);
+      const pages = await Promise.all(
+        raw.map(async (p) => ({
+          index: p.index,
+          url: p.url,
+          title: await p.title_promise.catch(() => ""),
+          active: p.active
+        }))
+      );
+      return ok({ count: pages.length, pages });
+    });
+  }
+};
+
 // src/tools/atomic/browser_screenshot.ts
 var browserScreenshotTool = {
   name: ToolNames.browserScreenshot,
@@ -1810,6 +2886,35 @@ var browserScrollTool = {
   }
 };
 
+// src/tools/atomic/browser_set_env.ts
+var browserSetEnvTool = {
+  name: ToolNames.browserSetEnv,
+  description: "Mutate session environment at runtime: viewport, offline state, geolocation, color_scheme (`light`/`dark`), reduced_motion, extra HTTP headers, network throttle preset (`slow-3g`/`fast-3g`/`slow-4g`/`fast-4g`/`offline`/`no-throttling`), and CPU throttle multiplier. `network_throttle` and `cpu_throttle` are chromium-only (CDP). `user_agent`, `locale`, and `timezone` cannot be changed mid-session \u2014 set them at `browser_open` time. Invalidates all refs.",
+  inputShape: browserSetEnvShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      if (!(engine instanceof PlaywrightEngine)) {
+        throw new RolepodMcpError(
+          "unsupported_engine",
+          "set_env is web-only and requires PlaywrightEngine."
+        );
+      }
+      await engine.setEnv(args.session_id, {
+        ...args.viewport !== void 0 ? { viewport: args.viewport } : {},
+        ...args.offline !== void 0 ? { offline: args.offline } : {},
+        ...args.geolocation !== void 0 ? { geolocation: args.geolocation } : {},
+        ...args.color_scheme !== void 0 ? { colorScheme: args.color_scheme } : {},
+        ...args.reduced_motion !== void 0 ? { reducedMotion: args.reduced_motion } : {},
+        ...args.extra_headers !== void 0 ? { extraHeaders: args.extra_headers } : {},
+        ...args.network_throttle !== void 0 ? { networkThrottle: args.network_throttle } : {},
+        ...args.cpu_throttle !== void 0 ? { cpuThrottle: args.cpu_throttle } : {}
+      });
+      return ok({ applied: true });
+    });
+  }
+};
+
 // src/tools/atomic/browser_snapshot.ts
 var browserSnapshotTool = {
   name: ToolNames.browserSnapshot,
@@ -1832,6 +2937,26 @@ var browserSnapshotTool = {
   }
 };
 
+// src/tools/atomic/browser_switch_page.ts
+var browserSwitchPageTool = {
+  name: ToolNames.browserSwitchPage,
+  description: "Set the active page for subsequent tool calls. Use `browser_pages` to discover indexes. Switching invalidates all refs because each page has its own DOM. Page 0 is the main page; popups land at higher indexes in the order they opened.",
+  inputShape: browserSwitchPageShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      if (!(engine instanceof PlaywrightEngine)) {
+        throw new RolepodMcpError(
+          "unsupported_engine",
+          "switch_page is web-only and requires PlaywrightEngine."
+        );
+      }
+      await engine.switchPage(args.session_id, args.index);
+      return ok({ active_index: args.index });
+    });
+  }
+};
+
 // src/tools/atomic/browser_type.ts
 var browserTypeTool = {
   name: ToolNames.browserType,
@@ -1851,6 +2976,27 @@ var browserTypeTool = {
   }
 };
 
+// src/tools/atomic/browser_upload_file.ts
+var browserUploadFileTool = {
+  name: ToolNames.browserUploadFile,
+  description: "Attach a local file to the `<input type=file>` element identified by `ref`. `file_path` MUST be an absolute path on the host filesystem. Invalidates all refs on success.",
+  inputShape: browserUploadFileShape,
+  build(ctx) {
+    return safeHandler(async (args) => {
+      const engine = ctx.registry.engineFor(args.session_id);
+      await engine.uploadFile(
+        {
+          id: args.session_id,
+          platform: ctx.registry.platformOf(args.session_id)
+        },
+        args.ref,
+        args.file_path
+      );
+      return ok({ uploaded: true, file_path: args.file_path });
+    });
+  }
+};
+
 // src/tools/atomic/browser_wait_for.ts
 var browserWaitForTool = {
   name: ToolNames.browserWaitFor,
@@ -2223,6 +3369,67 @@ function playwrightStepLine(step) {
       return `  await page.goto(${JSON.stringify(step.url)});`;
     case "wait_for":
       return `  // wait_for: ${JSON.stringify(step.condition)} \u2014 translate to page.waitForXxx()`;
+    case "hover":
+      return `  await page.getByText(${JSON.stringify(step.query)}, { exact: false }).first().hover();`;
+    case "drag":
+      return [
+        `  await page`,
+        `    .getByText(${JSON.stringify(step.from_query)}, { exact: false })`,
+        `    .first()`,
+        `    .dragTo(page.getByText(${JSON.stringify(step.to_query)}, { exact: false }).first());`
+      ].join("\n");
+    case "fill_form": {
+      const fields = Array.isArray(step.fields) ? step.fields : [];
+      return fields.map((f) => {
+        const q = JSON.stringify(f.query);
+        if (f.kind === "select") {
+          return `  await page.getByLabel(${q}).selectOption(${JSON.stringify(String(f.value))});`;
+        }
+        if (f.kind === "checkbox" || f.kind === "radio") {
+          const checked = typeof f.value === "boolean" ? f.value : String(f.value) === "true" || String(f.value) === "on";
+          return `  await page.getByLabel(${q}).setChecked(${checked});`;
+        }
+        return `  await page.getByLabel(${q}).fill(${JSON.stringify(String(f.value))});`;
+      }).join("\n");
+    }
+    case "upload":
+      return `  await page.getByLabel(${JSON.stringify(step.query)}).setInputFiles(${JSON.stringify(step.file_path)});`;
+    case "dialog":
+      return [
+        `  page.once("dialog", async (dialog) => {`,
+        step.action === "accept" ? `    await dialog.accept();` : step.action === "accept_with_text" ? `    await dialog.accept(${JSON.stringify(step.text ?? "")});` : `    await dialog.dismiss();`,
+        `  });`
+      ].join("\n");
+    case "set_env": {
+      const lines = [];
+      if (step.viewport && typeof step.viewport === "object") {
+        const v = step.viewport;
+        lines.push(`  await page.setViewportSize({ width: ${v.width}, height: ${v.height} });`);
+      }
+      if (step.offline !== void 0) {
+        lines.push(`  await page.context().setOffline(${Boolean(step.offline)});`);
+      }
+      if (step.geolocation) {
+        lines.push(`  await page.context().setGeolocation(${JSON.stringify(step.geolocation)});`);
+      }
+      if (step.color_scheme || step.reduced_motion) {
+        const opts = {};
+        if (step.color_scheme) opts.colorScheme = step.color_scheme;
+        if (step.reduced_motion) opts.reducedMotion = step.reduced_motion;
+        lines.push(`  await page.emulateMedia(${JSON.stringify(opts)});`);
+      }
+      if (step.extra_headers) {
+        lines.push(`  await page.context().setExtraHTTPHeaders(${JSON.stringify(step.extra_headers)});`);
+      }
+      if (step.network_throttle || step.cpu_throttle !== void 0) {
+        lines.push(`  // network/cpu throttle requires CDP \u2014 see Playwright docs (chromium only)`);
+      }
+      return lines.length > 0 ? lines.join("\n") : `  // set_env: nothing to apply`;
+    }
+    case "switch_page":
+      return `  const allPages = page.context().pages(); /* switch to index ${step.index} */ if (allPages[${step.index}]) await allPages[${step.index}].bringToFront();`;
+    case "evaluate":
+      return `  await page.evaluate(${JSON.stringify(step.script)});`;
     default:
       return `  // unsupported step kind: ${step.kind}`;
   }
@@ -2237,6 +3444,20 @@ function playwrightExpectLine(exp) {
       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`;
+    case "no_console_errors":
+      return [
+        `  // no_console_errors \u2014 collect via page.on('console') before the steps, then:`,
+        `  // expect(consoleErrors).toEqual([]);`
+      ].join("\n");
+    case "no_failed_requests":
+      return [
+        `  // no_failed_requests \u2014 collect via page.on('requestfailed'/'response') before the steps, then:`,
+        `  // expect(failedRequests).toEqual([]);`
+      ].join("\n");
+    case "request_made":
+      return `  await page.waitForRequest(new RegExp(${JSON.stringify(exp.url_pattern)}));`;
+    case "response_status":
+      return `  await page.waitForResponse((r) => new RegExp(${JSON.stringify(exp.url_pattern)}).test(r.url()) && r.status() === ${Number(exp.status)});`;
     default:
       return `  // unsupported expect kind: ${exp.kind}`;
   }
@@ -2253,6 +3474,56 @@ function seleniumStepLine(step) {
       return `    driver.get(${JSON.stringify(step.url)})`;
     case "wait_for":
       return `    # wait_for: ${JSON.stringify(step.condition)} \u2014 translate to WebDriverWait`;
+    case "hover":
+      return [
+        `    from selenium.webdriver.common.action_chains import ActionChains`,
+        `    target = driver.find_element(By.XPATH, f"//*[contains(text(), \\"${escapePy(String(step.query))}\\")]")`,
+        `    ActionChains(driver).move_to_element(target).perform()`
+      ].join("\n");
+    case "drag":
+      return [
+        `    from selenium.webdriver.common.action_chains import ActionChains`,
+        `    src = driver.find_element(By.XPATH, f"//*[contains(text(), \\"${escapePy(String(step.from_query))}\\")]")`,
+        `    dst = driver.find_element(By.XPATH, f"//*[contains(text(), \\"${escapePy(String(step.to_query))}\\")]")`,
+        `    ActionChains(driver).drag_and_drop(src, dst).perform()`
+      ].join("\n");
+    case "fill_form": {
+      const fields = Array.isArray(step.fields) ? step.fields : [];
+      return fields.map((f) => {
+        const q = escapePy(f.query);
+        if (f.kind === "select") {
+          return [
+            `    from selenium.webdriver.support.ui import Select`,
+            `    Select(driver.find_element(By.XPATH, f"//*[@aria-label=\\"${q}\\"]")).select_by_visible_text(${JSON.stringify(String(f.value))})`
+          ].join("\n");
+        }
+        if (f.kind === "checkbox" || f.kind === "radio") {
+          const checked = typeof f.value === "boolean" ? f.value : String(f.value) === "true";
+          return `    el = driver.find_element(By.XPATH, f"//*[@aria-label=\\"${q}\\"]"); el.click() if el.is_selected() != ${checked ? "True" : "False"} else None`;
+        }
+        return `    driver.find_element(By.XPATH, f"//*[@aria-label=\\"${q}\\"]").send_keys(${JSON.stringify(String(f.value))})`;
+      }).join("\n");
+    }
+    case "upload":
+      return `    driver.find_element(By.XPATH, f"//*[@aria-label=\\"${escapePy(String(step.query))}\\"]").send_keys(${JSON.stringify(step.file_path)})`;
+    case "dialog":
+      return [
+        `    alert = driver.switch_to.alert`,
+        step.action === "accept" ? `    alert.accept()` : step.action === "accept_with_text" ? `    alert.send_keys(${JSON.stringify(step.text ?? "")}); alert.accept()` : `    alert.dismiss()`
+      ].join("\n");
+    case "set_env": {
+      const lines = [];
+      if (step.viewport && typeof step.viewport === "object") {
+        const v = step.viewport;
+        lines.push(`    driver.set_window_size(${v.width}, ${v.height})`);
+      }
+      lines.push(`    # set_env partially supported in Selenium \u2014 see selenium docs for offline/geolocation/colorScheme via CDP`);
+      return lines.join("\n");
+    }
+    case "switch_page":
+      return `    driver.switch_to.window(driver.window_handles[${step.index}])`;
+    case "evaluate":
+      return `    driver.execute_script(${JSON.stringify(step.script)})`;
     default:
       return `    # unsupported step kind: ${step.kind}`;
   }
@@ -2267,6 +3538,18 @@ function seleniumExpectLine(exp) {
       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)}`;
+    case "no_console_errors":
+      return [
+        `    # no_console_errors \u2014 read browser logs via driver.get_log("browser")`,
+        `    errors = [l for l in driver.get_log("browser") if l.get("level") == "SEVERE"]`,
+        `    assert errors == [], f"console errors: {errors}"`
+      ].join("\n");
+    case "no_failed_requests":
+      return `    # no_failed_requests \u2014 selenium has no built-in network capture. Enable selenium-wire or BiDi for this.`;
+    case "request_made":
+      return `    # request_made ${JSON.stringify(exp.url_pattern)} \u2014 use selenium-wire (driver.requests) or BiDi`;
+    case "response_status":
+      return `    # response_status ${JSON.stringify(exp.url_pattern)} == ${Number(exp.status)} \u2014 use selenium-wire (driver.requests) or BiDi`;
     default:
       return `    # unsupported expect kind: ${exp.kind}`;
   }
@@ -2398,9 +3681,265 @@ var visualDiffTool = {
   }
 };
 
+// src/tools/metadata.ts
+var toolMetadata = {
+  // ---------- atomic ----------
+  [ToolNames.browserOpen]: {
+    title: "Open Browser/Mobile Session",
+    annotations: {
+      title: "Open Browser/Mobile Session",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.browserClose]: {
+    title: "Close Session",
+    annotations: {
+      title: "Close Session",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  },
+  [ToolNames.browserSnapshot]: {
+    title: "Capture Accessibility Snapshot",
+    annotations: {
+      title: "Capture Accessibility Snapshot",
+      readOnlyHint: true,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.browserClick]: {
+    title: "Click Element",
+    annotations: {
+      title: "Click Element",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.browserType]: {
+    title: "Type Text",
+    annotations: {
+      title: "Type Text",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.browserKey]: {
+    title: "Press Key",
+    annotations: {
+      title: "Press Key",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.browserScroll]: {
+    title: "Scroll Viewport",
+    annotations: {
+      title: "Scroll Viewport",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.browserWaitFor]: {
+    title: "Wait For Condition",
+    annotations: {
+      title: "Wait For Condition",
+      readOnlyHint: true,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.browserScreenshot]: {
+    title: "Take Screenshot",
+    annotations: {
+      title: "Take Screenshot",
+      readOnlyHint: true,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.browserNavigate]: {
+    title: "Navigate URL",
+    annotations: {
+      title: "Navigate URL",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    }
+  },
+  // ---------- composite ----------
+  [ToolNames.verifyUiFlow]: {
+    title: "Verify UI Flow",
+    annotations: {
+      title: "Verify UI Flow",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.auditA11y]: {
+    title: "Audit Accessibility (axe-core)",
+    annotations: {
+      title: "Audit Accessibility (axe-core)",
+      readOnlyHint: true,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.visualDiff]: {
+    title: "Visual Diff vs Baseline",
+    annotations: {
+      title: "Visual Diff vs Baseline",
+      // Writes to ./.rolepod-uiproof/{baselines,artifacts}/ but only adds files —
+      // never destroys an existing baseline silently.
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.scaffoldE2e]: {
+    title: "Scaffold E2E Test File",
+    annotations: {
+      title: "Scaffold E2E Test File",
+      // Writes a test file to the local repo.
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: false
+    }
+  },
+  [ToolNames.extractUiState]: {
+    title: "Extract UI State (NL Query)",
+    annotations: {
+      title: "Extract UI State (NL Query)",
+      readOnlyHint: true,
+      openWorldHint: true
+    }
+  },
+  // ---------- v0.5 atomic additions ----------
+  [ToolNames.browserHover]: {
+    title: "Hover Element",
+    annotations: {
+      title: "Hover Element",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.browserDrag]: {
+    title: "Drag Element",
+    annotations: {
+      title: "Drag Element",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.browserFillForm]: {
+    title: "Fill Form (Batch)",
+    annotations: {
+      title: "Fill Form (Batch)",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.browserUploadFile]: {
+    title: "Upload File",
+    annotations: {
+      title: "Upload File",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.browserHandleDialog]: {
+    title: "Pre-arm Dialog Handler",
+    annotations: {
+      title: "Pre-arm Dialog Handler",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: false
+    }
+  },
+  [ToolNames.browserConsole]: {
+    title: "Inspect Console Logs",
+    annotations: {
+      title: "Inspect Console Logs",
+      readOnlyHint: true,
+      openWorldHint: false
+    }
+  },
+  [ToolNames.browserNetwork]: {
+    title: "Inspect Network Requests",
+    annotations: {
+      title: "Inspect Network Requests",
+      readOnlyHint: true,
+      openWorldHint: false
+    }
+  },
+  [ToolNames.browserSetEnv]: {
+    title: "Set Browser Environment",
+    annotations: {
+      title: "Set Browser Environment",
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  },
+  [ToolNames.browserEvaluate]: {
+    title: "Evaluate JavaScript (gated; arbitrary code execution)",
+    annotations: {
+      title: "Evaluate JavaScript",
+      // Arbitrary code execution in the page context. Gated by
+      // ROLEPOD_ALLOW_EVAL=1 server-side. Always treat as destructive.
+      readOnlyHint: false,
+      destructiveHint: true,
+      idempotentHint: false,
+      openWorldHint: true
+    }
+  },
+  [ToolNames.browserPages]: {
+    title: "List Open Pages",
+    annotations: {
+      title: "List Open Pages",
+      readOnlyHint: true,
+      openWorldHint: false
+    }
+  },
+  [ToolNames.browserSwitchPage]: {
+    title: "Switch Active Page",
+    annotations: {
+      title: "Switch Active Page",
+      readOnlyHint: false,
+      destructiveHint: false,
+      idempotentHint: true,
+      openWorldHint: false
+    }
+  }
+};
+
 // src/server.ts
 var SERVER_NAME = "rolepod-uiproof";
-var SERVER_VERSION = "0.4.0";
+var SERVER_VERSION = "0.5.0";
 function buildServer(opts = {}) {
   const webEngine = createWebEngine();
   const registry = new SessionRegistry({ idleTimeoutMs: opts.idleTimeoutMs });
@@ -2417,7 +3956,7 @@ function buildServer(opts = {}) {
     version: SERVER_VERSION
   });
   const tools = [
-    // atomic
+    // atomic (v0.1-v0.4)
     browserOpenTool,
     browserCloseTool,
     browserSnapshotTool,
@@ -2428,6 +3967,18 @@ function buildServer(opts = {}) {
     browserWaitForTool,
     browserScreenshotTool,
     browserNavigateTool,
+    // atomic (v0.5)
+    browserHoverTool,
+    browserDragTool,
+    browserFillFormTool,
+    browserUploadFileTool,
+    browserHandleDialogTool,
+    browserConsoleTool,
+    browserNetworkTool,
+    browserSetEnvTool,
+    browserEvaluateTool,
+    browserPagesTool,
+    browserSwitchPageTool,
     // composite
     verifyUiFlowTool,
     auditA11yTool,
@@ -2436,9 +3987,15 @@ function buildServer(opts = {}) {
     extractUiStateTool
   ];
   for (const t of tools) {
+    const meta = toolMetadata[t.name];
     mcp.registerTool(
       t.name,
-      { description: t.description, inputSchema: t.inputShape },
+      {
+        title: meta?.title,
+        description: t.description,
+        inputSchema: t.inputShape,
+        annotations: meta?.annotations
+      },
       t.build(ctx)
     );
   }