playwright-e2e-mcp 0.4.2 → 0.5.1

package/dist/tools/probe-script.js

@@ -15,6 +15,13 @@
  *               on the live page or on a DOM snapshot taken from a trace
  * - a11y        run axe-core on the page (or a scoped part) and describe the
  *               offending elements, each with a verified locator
+ * - perf        lab Web Vitals (LCP, CLS, TBT, INP during actions, FCP, TTFB)
+ *               and the network cost per resource type, optionally under
+ *               CPU and network throttling; the LCP element and the elements
+ *               that shifted come back with verified locators
+ *
+ * Any mode that navigates applies the caller's network mocks (cfg.routes)
+ * first and reports how many requests each one handled.
  *
  * Every element the script reports carries Playwright locators that were
  * proven, in this same page, to resolve to exactly that one element.
@@ -30,7 +37,7 @@ function send(payload) {
 function classifyError(message) {
   const m = String(message);
   if (/Executable doesn't exist|Please run the following command to install/i.test(m)) {
-    return { kind: 'NO_PLAYWRIGHT', hint: 'Playwright browsers are not installed for this project. Run: npx playwright install chromium' };
+    return { kind: 'NO_PLAYWRIGHT', hint: 'Playwright browsers are not installed for this project. Run: npx playwright install chromium (or firefox / webkit for those engines)' };
   }
   if (/ECONNREFUSED|ERR_CONNECTION_REFUSED|ERR_NAME_NOT_RESOLVED|ERR_EMPTY_RESPONSE|getaddrinfo|net::ERR_/i.test(m)) {
     return { kind: 'SERVER_NOT_RUNNING', hint: 'The URL is not reachable. Start your dev server (e.g. npm run dev / npm start) and retry.' };
@@ -429,6 +436,152 @@ async function runActions(page, actions, timeout) {
   return done;
 }
 
+/* ---------------- performance (mode: perf) ---------------- */
+
+// Runs in every new document before its own scripts, so no early paint,
+// shift or long task is missed.
+function perfInit() {
+  const P = { lcp: null, shifts: [], longTasks: [], events: [] };
+  Object.defineProperty(window, '__pwmcpPerf', { value: P, configurable: true });
+  const watch = (type, fn, extra) => {
+    try {
+      new PerformanceObserver((list) => list.getEntries().forEach(fn)).observe(Object.assign({ type: type, buffered: true }, extra || {}));
+    } catch (err) { /* entry type not supported */ }
+  };
+  watch('largest-contentful-paint', (e) => { P.lcp = e; });
+  watch('layout-shift', (e) => { if (!e.hadRecentInput) P.shifts.push(e); });
+  watch('longtask', (e) => { P.longTasks.push({ start: e.startTime, duration: e.duration }); });
+  watch('event', (e) => { if (e.interactionId) P.events.push({ id: e.interactionId, duration: e.duration, name: e.name, target: e.target }); }, { durationThreshold: 16 });
+}
+
+function collectPerf() {
+  const h = window.__pwmcp;
+  const P = window.__pwmcpPerf || { lcp: null, shifts: [], longTasks: [], events: [] };
+  h.els = [];
+  const keep = (el) => {
+    if (!el || el.nodeType !== 1 || !el.isConnected) return -1;
+    const at = h.els.indexOf(el);
+    if (at >= 0) return at;
+    h.els.push(el);
+    return h.els.length - 1;
+  };
+  const nav = performance.getEntriesByType('navigation')[0];
+  const fcpEntry = performance.getEntriesByName('first-contentful-paint')[0];
+  const fcp = fcpEntry ? fcpEntry.startTime : undefined;
+
+  // CLS: the worst session window (shifts < 1s apart, window <= 5s).
+  let cls = 0, win = 0, winStart = 0, prev = 0, cur = [], worst = [];
+  for (const s of P.shifts) {
+    if (cur.length && (s.startTime - prev > 1000 || s.startTime - winStart > 5000)) { win = 0; cur = []; }
+    if (!cur.length) winStart = s.startTime;
+    win += s.value; cur.push(s); prev = s.startTime;
+    if (win > cls) { cls = win; worst = cur.slice(); }
+  }
+  const shiftElements = [];
+  for (const s of worst) {
+    for (const src of s.sources || []) {
+      const i = keep(src.node);
+      if (i >= 0 && !shiftElements.includes(i) && shiftElements.length < 5) shiftElements.push(i);
+    }
+  }
+
+  // TBT: blocking time of long tasks after first paint.
+  let tbt = 0, longest = 0;
+  for (const t of P.longTasks) {
+    longest = Math.max(longest, t.duration);
+    if (fcp === undefined || t.start >= fcp) tbt += Math.max(0, t.duration - 50);
+  }
+
+  // INP (lab): the slowest interaction, events grouped by interactionId.
+  const byInteraction = new Map();
+  for (const e of P.events) {
+    const prior = byInteraction.get(e.id);
+    if (!prior || e.duration > prior.duration) byInteraction.set(e.id, e);
+  }
+  let inp;
+  for (const e of byInteraction.values()) if (!inp || e.duration > inp.duration) inp = e;
+  let inpTarget;
+  if (inp) {
+    const i = keep(inp.target);
+    inpTarget = inp.name + (i >= 0 ? ' on ' + h.describe(inp.target).tag : '');
+  }
+
+  const lcpEl = P.lcp ? P.lcp.element : null;
+  const lcpElement = keep(lcpEl);
+  let lcpMs;
+  if (P.lcp) lcpMs = P.lcp.renderTime || P.lcp.loadTime || P.lcp.startTime;
+
+  const timings = {};
+  for (const r of performance.getEntriesByType('resource')) {
+    timings[r.name] = { duration: r.duration, blocking: r.renderBlockingStatus === 'blocking' };
+  }
+  let heap;
+  try { heap = performance.memory ? performance.memory.usedJSHeapSize : undefined; } catch (err) { /* not exposed */ }
+  return {
+    title: document.title,
+    finalUrl: location.href,
+    viewport: { width: window.innerWidth, height: window.innerHeight },
+    elements: h.els.map((el) => h.describe(el)),
+    perf: {
+      ttfbMs: nav ? nav.responseStart : undefined,
+      fcpMs: fcp,
+      lcpMs: lcpMs,
+      lcpElement: lcpElement,
+      lcpTag: lcpEl ? lcpEl.tagName.toLowerCase() : undefined,
+      lcpUrl: P.lcp && P.lcp.url ? String(P.lcp.url).slice(0, 300) : undefined,
+      cls: Math.round(cls * 1000) / 1000,
+      shiftElements: shiftElements,
+      tbtMs: Math.round(tbt),
+      longTasks: P.longTasks.length,
+      longestTaskMs: Math.round(longest),
+      inpMs: inp ? Math.round(inp.duration) : undefined,
+      inpTarget: inpTarget,
+      domContentLoadedMs: nav && nav.domContentLoadedEventEnd ? nav.domContentLoadedEventEnd : undefined,
+      loadMs: nav && nav.loadEventEnd ? nav.loadEventEnd : undefined,
+      domNodes: document.getElementsByTagName('*').length,
+      jsHeapBytes: heap,
+    },
+    timings: timings,
+  };
+}
+
+function registrableDomain(host) {
+  const parts = String(host).split('.');
+  return parts.length <= 2 ? host : parts.slice(-2).join('.');
+}
+
+function summariseRequests(requests, timings, pageUrl) {
+  const site = registrableDomain(new URL(pageUrl).hostname);
+  const byType = {};
+  const all = [];
+  const thirdParty = new Set();
+  let thirdPartyBytes = 0;
+  let total = 0;
+  for (const r of requests.values()) {
+    if (!r.url || /^data:|^blob:/.test(r.url)) continue;
+    const bytes = r.bytes || 0;
+    total += bytes;
+    const type = (r.type || 'Other').toLowerCase();
+    if (!byType[type]) byType[type] = { type: type, requests: 0, transferBytes: 0 };
+    byType[type].requests += 1;
+    byType[type].transferBytes += bytes;
+    let host = '';
+    try { host = new URL(r.url).hostname; } catch (err) { /* opaque */ }
+    if (host && registrableDomain(host) !== site) { thirdParty.add(host); thirdPartyBytes += bytes; }
+    const t = timings[r.url] || {};
+    all.push({ url: r.url.slice(0, 200), type: type, transferBytes: bytes, durationMs: Math.round(t.duration || 0), renderBlocking: !!t.blocking });
+  }
+  return {
+    requests: all.length,
+    transferBytes: total,
+    byType: Object.values(byType).sort((a, b) => b.transferBytes - a.transferBytes),
+    largest: all.slice().sort((a, b) => b.transferBytes - a.transferBytes).slice(0, 5),
+    renderBlocking: all.filter((r) => r.renderBlocking).slice(0, 8),
+    thirdPartyBytes: thirdPartyBytes,
+    thirdPartyOrigins: thirdParty.size,
+  };
+}
+
 (async () => {
   const { createRequire } = require('node:module');
   const req = createRequire(cfg.projectRoot + '/package.json');
@@ -439,6 +592,12 @@ async function runActions(page, actions, timeout) {
     try {
       pw = req('@playwright/test');
     } catch (errB) {
+      // The hosted bridge ships playwright-core next to its bundled Chromium.
+      try {
+        if (cfg.serverlessChromium) pw = req('playwright-core');
+      } catch (errC) {}
+    }
+    if (!pw) {
       send({
         ok: false,
         kind: 'NO_PLAYWRIGHT',
@@ -450,8 +609,16 @@ async function runActions(page, actions, timeout) {
   }
 
   let browser = null;
+  let openContext = null;
   let actionsDone = [];
+  // A recorded HAR is written when its context closes, so close the
+  // context before the browser.
+  const closeBrowser = async () => {
+    if (openContext) await openContext.close().catch(() => undefined);
+    await browser.close();
+  };
   try {
+    const engine = cfg.browser || 'chromium';
     const launchOptions = { headless: true };
     if (cfg.blockPrivate) {
       // SSRF guard: every browser connection (each redirect hop and
@@ -461,16 +628,77 @@ async function runActions(page, actions, timeout) {
       launchOptions.proxy = { server: 'http://127.0.0.1:' + proxyPort };
       // WebRTC STUN/TURN over UDP does not go through the proxy; keep it off
       // so a page cannot send UDP to (or scan) the private network.
-      launchOptions.args = ['--proxy-bypass-list=<-loopback>', '--force-webrtc-ip-handling-policy=disable_non_proxied_udp'];
+      if (engine === 'firefox') {
+        launchOptions.firefoxUserPrefs = { 'network.proxy.allow_hijacking_localhost': true, 'media.peerconnection.enabled': false };
+      } else {
+        launchOptions.args = ['--proxy-bypass-list=<-loopback>', '--force-webrtc-ip-handling-policy=disable_non_proxied_udp'];
+      }
     }
-    browser = await pw.chromium.launch(launchOptions);
+    if (cfg.serverlessChromium) {
+      launchOptions.executablePath = cfg.serverlessChromium.executablePath;
+      launchOptions.args = cfg.serverlessChromium.args.concat(launchOptions.args || []);
+    }
+    browser = await pw[engine].launch(launchOptions);
     const contextOptions = { viewport: cfg.viewport || { width: 1280, height: 720 } };
+    if (cfg.mobile) Object.assign(contextOptions, { isMobile: true, hasTouch: true, deviceScaleFactor: 1.75 });
     if (cfg.storageState) contextOptions.storageState = cfg.storageState;
     if (cfg.headers) contextOptions.extraHTTPHeaders = cfg.headers;
     if (cfg.testIdAttribute) pw.selectors.setTestIdAttribute(cfg.testIdAttribute);
+    const recording = cfg.har && cfg.har.mode === 'record' && !cfg.snapshotHtmlPath;
+    if (recording) contextOptions.recordHar = { path: cfg.har.path, urlFilter: cfg.har.url, mode: 'minimal' };
     const context = await browser.newContext(contextOptions);
+    openContext = context;
+    // Replay goes first so the network mocks below, registered later, win.
+    if (cfg.har && cfg.har.mode === 'replay' && !cfg.snapshotHtmlPath) {
+      await context.routeFromHAR(cfg.har.path, { url: cfg.har.url, notFound: cfg.har.notFound || 'abort' });
+    }
+
+    // Network mocks. Playwright runs the most recently registered handler
+    // first, so register in reverse to make the first listed mock win.
+    const routeHits = (cfg.routes || []).map(() => 0);
+    if (cfg.routes && cfg.routes.length && !cfg.snapshotHtmlPath) {
+      for (let i = cfg.routes.length - 1; i >= 0; i -= 1) {
+        const r = cfg.routes[i];
+        await context.route(r.url, async (route) => {
+          if (r.method && route.request().method() !== r.method) return route.fallback();
+          routeHits[i] += 1;
+          if (r.delayMs) await new Promise((resolve) => setTimeout(resolve, r.delayMs));
+          if (r.abort) return route.abort('failed');
+          if (r.status !== undefined) {
+            return route.fulfill({ status: r.status, body: r.body === undefined ? '' : r.body, contentType: r.contentType, headers: r.headers });
+          }
+          return route.fallback();
+        });
+      }
+    }
+
+    if (cfg.mode === 'perf') await context.addInitScript(perfInit);
     const page = await context.newPage();
 
+    // perf: count bytes per request over CDP (cross-origin sizes included)
+    // and apply CPU / network throttling before the first byte.
+    const requests = new Map();
+    if (cfg.mode === 'perf') {
+      const cdp = await context.newCDPSession(page);
+      cdp.on('Network.responseReceived', (e) => {
+        if (requests.size < 2000 || requests.has(e.requestId)) requests.set(e.requestId, Object.assign(requests.get(e.requestId) || {}, { url: e.response.url, type: e.type }));
+      });
+      cdp.on('Network.loadingFinished', (e) => {
+        const r = requests.get(e.requestId);
+        if (r) r.bytes = e.encodedDataLength;
+      });
+      await cdp.send('Network.enable');
+      if (cfg.network) {
+        await cdp.send('Network.emulateNetworkConditions', {
+          offline: false,
+          latency: cfg.network.latencyMs,
+          downloadThroughput: cfg.network.downloadBps,
+          uploadThroughput: cfg.network.uploadBps,
+        });
+      }
+      if (cfg.cpuThrottle && cfg.cpuThrottle > 1) await cdp.send('Emulation.setCPUThrottlingRate', { rate: cfg.cpuThrottle });
+    }
+
     const consoleMessages = [];
     page.on('console', (msg) => {
       if (consoleMessages.length < 50) consoleMessages.push({ type: msg.type(), text: String(msg.text()).slice(0, 300) });
@@ -487,7 +715,15 @@ async function runActions(page, actions, timeout) {
     } else {
       await page.goto(cfg.url, { waitUntil: cfg.waitUntil || 'domcontentloaded', timeout: cfg.gotoTimeout || 15000 });
       if (cfg.waitFor) await page.locator(cfg.waitFor).first().waitFor({ state: 'visible', timeout: cfg.waitTimeout || 5000 });
-      if (cfg.actions && cfg.actions.length) actionsDone = await runActions(page, cfg.actions, cfg.actionTimeout || 10000);
+      // perf: let late images, fonts and shifts land before anything else.
+      if (cfg.mode === 'perf' && cfg.settleMs) await page.waitForTimeout(cfg.settleMs);
+      if (cfg.actions && cfg.actions.length) {
+        actionsDone = await runActions(page, cfg.actions, cfg.actionTimeout || 10000);
+        if (cfg.mode === 'perf') {
+          await page.waitForLoadState('load', { timeout: cfg.waitTimeout || 5000 }).catch(() => undefined);
+          await page.waitForTimeout(Math.min(cfg.settleMs || 1000, 2000));
+        }
+      }
     }
 
     if (cfg.mode === 'screenshot') {
@@ -507,10 +743,11 @@ async function runActions(page, actions, timeout) {
           matchCount: 0,
           elements: [],
           actionsDone: actionsDone,
+          routeHits: routeHits,
           durationMs: Date.now() - cfg.startedAt,
         },
       });
-      await browser.close();
+      await closeBrowser();
       process.exit(0);
     }
 
@@ -584,6 +821,13 @@ async function runActions(page, actions, timeout) {
         };
       }, { tags: cfg.axeTags || [], selector: cfg.selector, maxNodes: cfg.maxNodes || 3 });
       await attachLocators(page, data.elements, 40, 2);
+    } else if (cfg.mode === 'perf') {
+      const collected = await page.evaluate(collectPerf);
+      const network = summariseRequests(requests, collected.timings, page.url());
+      delete collected.timings;
+      Object.assign(collected.perf, network);
+      data = Object.assign(collected, { matchCount: 0, elementCount: collected.elements.length });
+      await attachLocators(page, data.elements, 12, 2);
     } else if (cfg.mode === 'heal') {
       data = await page.evaluate((input) => {
         const h = window.__pwmcp;
@@ -612,6 +856,20 @@ async function runActions(page, actions, timeout) {
         return { matchCount: elements.length, elementCount: document.querySelectorAll('*').length, elements: elements, title: document.title };
       }, { tokens: cfg.healTokens || [], role: cfg.healRole });
       await attachLocators(page, data.elements, 5, 3);
+    } else if (cfg.view === 'aria') {
+      const scope = cfg.selector ? page.locator(cfg.selector) : page.locator('body');
+      const count = await scope.count();
+      data = { matchCount: count, elementCount: count, elements: [], title: await page.title(), finalUrl: page.url() };
+      if (count > 0) {
+        if (typeof scope.ariaSnapshot !== 'function') {
+          throw new Error('ariaSnapshot needs Playwright 1.49 or newer');
+        }
+        const snapshot = await scope.first().ariaSnapshot({ timeout: cfg.waitTimeout || 10000 });
+        const max = cfg.maxHtmlChars || 12000;
+        data.ariaSnapshot = snapshot.slice(0, max);
+        data.ariaTruncated = snapshot.length > max;
+      }
+      data.viewport = page.viewportSize() || undefined;
     } else {
       data = await page.evaluate((input) => {
         const h = window.__pwmcp;
@@ -671,16 +929,17 @@ async function runActions(page, actions, timeout) {
 
     data.consoleMessages = consoleMessages;
     data.actionsDone = actionsDone;
+    data.routeHits = routeHits;
     data.finalUrl = data.finalUrl || page.url();
     data.durationMs = Date.now() - cfg.startedAt;
     send({ ok: true, data: data });
-    await browser.close();
+    await closeBrowser();
     process.exit(0);
   } catch (err) {
     const message = err && err.message ? err.message : String(err);
     const classified = classifyError(message);
     send({ ok: false, kind: classified.kind, error: message, hint: classified.hint, actionsDone: err && err.actionsDone });
-    try { if (browser) await browser.close(); } catch (closeErr) { /* ignore */ }
+    try { if (browser) await closeBrowser(); } catch (closeErr) { /* ignore */ }
     process.exit(1);
   }
 })().catch((err) => {

package/dist/tools/probe-script.js.map

@@ -1 +1 @@
-{"version":3,"file":"probe-script.js","sourceRoot":"","sources":["../../src/tools/probe-script.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4pBrC,CAAC"}
+{"version":3,"file":"probe-script.js","sourceRoot":"","sources":["../../src/tools/probe-script.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAw5BrC,CAAC"}

package/dist/tools/shared.d.ts

@@ -72,6 +72,21 @@ export declare const sessionShape: {
     storageState: z.ZodOptional<z.ZodString>;
     headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
 };
+/**
+ * A network mock, applied with context.route before the page loads: fulfil
+ * with a canned response, abort, or only delay the real request.
+ */
+export declare const routeMockSchema: z.ZodObject<{
+    url: z.ZodString;
+    method: z.ZodOptional<z.ZodString>;
+    status: z.ZodOptional<z.ZodNumber>;
+    json: z.ZodOptional<z.ZodUnknown>;
+    body: z.ZodOptional<z.ZodString>;
+    contentType: z.ZodOptional<z.ZodString>;
+    headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    abort: z.ZodOptional<z.ZodBoolean>;
+    delayMs: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 /** Inputs shared by every tool that opens a page. */
 export declare const pageStateShape: {
     storageState: z.ZodOptional<z.ZodString>;
@@ -94,19 +109,67 @@ export declare const pageStateShape: {
         url: z.ZodOptional<z.ZodString>;
         ms: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>>;
+    routes: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        url: z.ZodString;
+        method: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodNumber>;
+        json: z.ZodOptional<z.ZodUnknown>;
+        body: z.ZodOptional<z.ZodString>;
+        contentType: z.ZodOptional<z.ZodString>;
+        headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+        abort: z.ZodOptional<z.ZodBoolean>;
+        delayMs: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>>;
     viewport: z.ZodOptional<z.ZodObject<{
         width: z.ZodNumber;
         height: z.ZodNumber;
     }, z.core.$strip>>;
+    har: z.ZodOptional<z.ZodObject<{
+        path: z.ZodString;
+        mode: z.ZodOptional<z.ZodEnum<{
+            record: "record";
+            replay: "replay";
+        }>>;
+        url: z.ZodOptional<z.ZodString>;
+        notFound: z.ZodOptional<z.ZodEnum<{
+            abort: "abort";
+            fallback: "fallback";
+        }>>;
+    }, z.core.$strip>>;
+    browser: z.ZodOptional<z.ZodEnum<{
+        chromium: "chromium";
+        firefox: "firefox";
+        webkit: "webkit";
+    }>>;
 };
 export interface PageStateInput {
     storageState?: string;
     headers?: Record<string, string>;
     actions?: Array<z.infer<typeof pageActionSchema>>;
+    routes?: Array<z.infer<typeof routeMockSchema>>;
     viewport?: {
         width: number;
         height: number;
     };
+    har?: {
+        path: string;
+        mode?: 'replay' | 'record';
+        url?: string;
+        notFound?: 'abort' | 'fallback';
+    };
+    browser?: BrowserEngine;
+}
+export type BrowserEngine = 'chromium' | 'firefox' | 'webkit';
+export interface ResolvedRouteMock {
+    url: string;
+    label: string;
+    method?: string;
+    status?: number;
+    body?: string;
+    contentType?: string;
+    headers?: Record<string, string>;
+    abort?: boolean;
+    delayMs?: number;
 }
 export interface ResolvedPageState {
     storageState?: string;
@@ -119,11 +182,21 @@ export interface ResolvedPageState {
         url?: string;
         ms?: number;
     }>;
+    routes?: ResolvedRouteMock[];
     viewport?: {
         width: number;
         height: number;
     };
+    har?: {
+        path: string;
+        mode: 'replay' | 'record';
+        url?: string;
+        notFound: 'abort' | 'fallback';
+    };
+    browser?: BrowserEngine;
 }
+/** Validate network mocks and turn each into a plain fulfil/abort/delay spec. */
+export declare function resolveRouteMocks(routes: NonNullable<PageStateInput['routes']>): ResolvedRouteMock[];
 /**
  * Validate page-state inputs: the storageState file must sit inside the
  * project root (symlinks resolved) and parse as JSON, every goto URL passes
@@ -133,10 +206,12 @@ export interface ResolvedPageState {
 export declare function resolvePageState(input: PageStateInput, root: string, entryUrl: string, ctx: ToolContext): Promise<ResolvedPageState>;
 /** One line describing the page state, for tool output headers. */
 export declare function describePageState(state: ResolvedPageState, root: string): string | undefined;
+/** One line per network mock with how often it matched; unmatched mocks are flagged. */
+export declare function describeRouteHits(state: ResolvedPageState, hits: number[] | undefined): string[];
 /** A hint when an unauthenticated page landed on a login screen. */
 export declare function loginHint(finalUrl: string | undefined, state: ResolvedPageState): string | undefined;
 export interface BrowserScriptConfig extends Omit<ResolvedPageState, never> {
-    mode: 'inspect' | 'validate' | 'screenshot' | 'heal' | 'a11y';
+    mode: 'inspect' | 'validate' | 'screenshot' | 'heal' | 'a11y' | 'perf';
     projectRoot: string;
     /** Page to open; omitted when rendering a snapshot. */
     url?: string;
@@ -147,7 +222,7 @@ export interface BrowserScriptConfig extends Omit<ResolvedPageState, never> {
     /** Parsed locator chain for validate / screenshot modes. */
     selectorChain?: LocatorCall[];
     /** inspect: 'elements' (DOM inventory) or 'locators' (compact locator map). */
-    view?: 'elements' | 'locators';
+    view?: 'elements' | 'locators' | 'aria';
     /** heal: words from the broken locator, and its role when it had one. */
     healTokens?: string[];
     healRole?: string;
@@ -166,8 +241,21 @@ export interface BrowserScriptConfig extends Omit<ResolvedPageState, never> {
     axeSourcePath?: string;
     axeTags?: string[];
     maxNodes?: number;
+    /** perf: CPU slowdown factor and network profile (CDP emulation). */
+    cpuThrottle?: number;
+    network?: NetworkProfile;
+    /** perf: emulate a phone (isMobile, touch, device pixel ratio). */
+    mobile?: boolean;
+    /** perf: ms to keep observing after load so late shifts and LCP land. */
+    settleMs?: number;
     startedAt: number;
 }
+/** Network emulation in Chrome DevTools terms (throughput in bytes/s). */
+export interface NetworkProfile {
+    latencyMs: number;
+    downloadBps: number;
+    uploadBps: number;
+}
 export interface BrowserScriptData {
     title?: string;
     finalUrl?: string;
@@ -188,6 +276,53 @@ export interface BrowserScriptData {
     durationMs?: number;
     /** mode 'a11y': axe-core violations; node.element indexes `elements`. */
     a11y?: AccessibilityScan;
+    /** mode 'perf': lab Web Vitals and resource stats; element fields index `elements`. */
+    perf?: PerformanceScan;
+    /** inspect view 'aria': the YAML accessibility snapshot of the scope. */
+    ariaSnapshot?: string;
+    ariaTruncated?: boolean;
+    /** Requests each network mock in `routes` handled, by index. */
+    routeHits?: number[];
+}
+export interface PerformanceResource {
+    url: string;
+    type: string;
+    transferBytes: number;
+    durationMs: number;
+    renderBlocking: boolean;
+}
+export interface PerformanceScan {
+    ttfbMs?: number;
+    fcpMs?: number;
+    lcpMs?: number;
+    /** Index into `elements` of the LCP element, -1 when unknown. */
+    lcpElement: number;
+    lcpTag?: string;
+    lcpUrl?: string;
+    cls: number;
+    /** Elements that moved most in the worst layout-shift window. */
+    shiftElements: number[];
+    tbtMs: number;
+    longTasks: number;
+    longestTaskMs: number;
+    /** Slowest interaction during `actions` (lab INP), when there were any. */
+    inpMs?: number;
+    inpTarget?: string;
+    domContentLoadedMs?: number;
+    loadMs?: number;
+    requests: number;
+    transferBytes: number;
+    byType: Array<{
+        type: string;
+        requests: number;
+        transferBytes: number;
+    }>;
+    largest: PerformanceResource[];
+    renderBlocking: PerformanceResource[];
+    thirdPartyBytes: number;
+    thirdPartyOrigins: number;
+    domNodes: number;
+    jsHeapBytes?: number;
 }
 export interface AccessibilityNode {
     target: string;