@skyramp/mcp 0.1.8 → 0.2.0-rc.2

package/node_modules/playwright/lib/dom-analyzer/widgetContract.test.js

@@ -0,0 +1,212 @@
+"use strict";
+var import_widgetContract = require("./widgetContract");
+var import_curatedWidgets = require("./curatedWidgets");
+const cases = [];
+function test(name, run) {
+  cases.push({ name, run });
+}
+function assertEqual(actual, expected, msg) {
+  const a = JSON.stringify(actual);
+  const e = JSON.stringify(expected);
+  if (a !== e)
+    throw new Error(`${msg ?? "assertEqual"} \u2014 expected ${e}, got ${a}`);
+}
+function assertThrows(fn, substring) {
+  let threw = false;
+  let message = "";
+  try {
+    fn();
+  } catch (e) {
+    threw = true;
+    message = e.message;
+  }
+  if (!threw) throw new Error("expected function to throw");
+  if (substring && !message.includes(substring))
+    throw new Error(`thrown message "${message}" does not include "${substring}"`);
+}
+const curatedFingerprints = Object.keys(import_curatedWidgets.CURATED);
+const firstCurated = curatedFingerprints[0];
+test("lookupContract: curated takes precedence over inferred", () => {
+  const cache = /* @__PURE__ */ new Map();
+  cache.set(firstCurated, {
+    source: "inferred",
+    confidence: "low",
+    widgetIdentification: "cache-shadow attempt",
+    parameters: [],
+    steps: []
+  });
+  const result = (0, import_widgetContract.lookupContract)(firstCurated, cache);
+  if (result.status !== "found") throw new Error("expected found");
+  assertEqual(result.contract.source, "curated");
+});
+test("lookupContract: inferred returned when no curated entry exists", () => {
+  const cache = /* @__PURE__ */ new Map();
+  const inferred = {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "CustomDatePicker",
+    parameters: ["date"],
+    steps: [{ kind: "click", target: "trigger" }]
+  };
+  cache.set("0000000000000001", inferred);
+  const result = (0, import_widgetContract.lookupContract)("0000000000000001", cache);
+  if (result.status !== "found") throw new Error("expected found");
+  assertEqual(result.contract.source, "inferred");
+});
+test("lookupContract: unknown fingerprint returns needs_inference_marker", () => {
+  const cache = /* @__PURE__ */ new Map();
+  const result = (0, import_widgetContract.lookupContract)("ffffffffffffffff", cache);
+  assertEqual(result.status, "needs_inference_marker");
+});
+test("cacheInferredContract: refuses to overwrite curated entry", () => {
+  const cache = /* @__PURE__ */ new Map();
+  const result = (0, import_widgetContract.cacheInferredContract)(firstCurated, {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "X",
+    parameters: [],
+    steps: []
+  }, cache);
+  assertEqual(result, { ok: false, error: "fingerprint collides with curated entry; cannot overwrite" });
+});
+test("cacheInferredContract: accepts valid inferred contract", () => {
+  const cache = /* @__PURE__ */ new Map();
+  const result = (0, import_widgetContract.cacheInferredContract)("0000000000000002", {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "X",
+    parameters: ["v"],
+    steps: [{ kind: "fill", target: "inputByLabel", label: "Name", param: "v" }]
+  }, cache);
+  assertEqual(result, { ok: true });
+  assertEqual(cache.size, 1);
+});
+test("cacheInferredContract: overwrites previous inferred contract (mutable)", () => {
+  const cache = /* @__PURE__ */ new Map();
+  (0, import_widgetContract.cacheInferredContract)("0000000000000003", {
+    source: "inferred",
+    confidence: "low",
+    widgetIdentification: "bad",
+    parameters: [],
+    steps: []
+  }, cache);
+  (0, import_widgetContract.cacheInferredContract)("0000000000000003", {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "good",
+    parameters: [],
+    steps: []
+  }, cache);
+  assertEqual(cache.get("0000000000000003").widgetIdentification, "good");
+});
+test("cacheInferredContract: accepts unknown stub", () => {
+  const cache = /* @__PURE__ */ new Map();
+  const result = (0, import_widgetContract.cacheInferredContract)("0000000000000004", {
+    source: "unknown",
+    confidence: "low",
+    widgetIdentification: "",
+    parameters: [],
+    steps: []
+  }, cache);
+  assertEqual(result, { ok: true });
+});
+test("cacheInferredContract: rejects source=curated (defense in depth)", () => {
+  const cache = /* @__PURE__ */ new Map();
+  const result = (0, import_widgetContract.cacheInferredContract)("0000000000000005", {
+    source: "curated",
+    confidence: "high",
+    widgetIdentification: "forged",
+    parameters: [],
+    steps: []
+  }, cache);
+  if (result.ok)
+    throw new Error("expected reject when source=curated");
+  if (!result.error.includes("source: 'curated'"))
+    throw new Error(`expected error message to mention curated, got: ${result.error}`);
+  assertEqual(cache.size, 0);
+});
+test("validateContract: step.param must exist in parameters[]", () => {
+  const c = {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "X",
+    parameters: ["v"],
+    steps: [{ kind: "click", target: "option", matchBy: "accessibleName", param: "w" }]
+  };
+  assertThrows(() => (0, import_widgetContract.validateContract)(c), "param 'w'");
+});
+test("validateContract: EnterFrameStep.framePath must be non-empty", () => {
+  const c = {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "X",
+    parameters: [],
+    steps: [{ kind: "enterFrame", framePath: [] }, { kind: "exitFrame" }]
+  };
+  assertThrows(() => (0, import_widgetContract.validateContract)(c), "framePath");
+});
+test("validateContract: rule 1 (missing param) is reported before rule 2 (empty framePath)", () => {
+  const c = {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "X",
+    parameters: [],
+    steps: [
+      { kind: "click", target: "option", matchBy: "accessibleName", param: "v" },
+      { kind: "enterFrame", framePath: [] }
+    ]
+  };
+  assertThrows(() => (0, import_widgetContract.validateContract)(c), "param 'v'");
+});
+test("validateContract: at most one EnterFrameStep", () => {
+  const c = {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "X",
+    parameters: [],
+    steps: [
+      { kind: "enterFrame", framePath: ["iframe"] },
+      { kind: "exitFrame" },
+      { kind: "enterFrame", framePath: ["iframe"] }
+    ]
+  };
+  assertThrows(() => (0, import_widgetContract.validateContract)(c), "EnterFrameStep");
+});
+test("validateContract: HandoffStep-before-WaitForStep is a warning, not an error", () => {
+  const c = {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "X",
+    parameters: [],
+    steps: [{ kind: "click", target: "trigger" }, { kind: "handoff" }]
+  };
+  (0, import_widgetContract.validateContract)(c);
+});
+test("validateContract: widgetIdentification length is NOT enforced here (Zod schema concern)", () => {
+  const c = {
+    source: "inferred",
+    confidence: "high",
+    widgetIdentification: "a".repeat(200),
+    parameters: [],
+    steps: []
+  };
+  (0, import_widgetContract.validateContract)(c);
+});
+let failed = 0;
+for (const { name, run } of cases) {
+  try {
+    run();
+    console.log("  \u2713", name);
+  } catch (e) {
+    failed++;
+    console.log("  \u2717", name);
+    console.log("     ", e.message);
+  }
+}
+if (failed > 0) {
+  console.log(`
+${failed}/${cases.length} failed`);
+  process.exit(1);
+}
+console.log(`
+${cases.length} passed`);

package/node_modules/playwright/lib/mcp/browser/browserContextFactory.js

@@ -184,6 +184,7 @@ class PersistentContextFactory {
     (0, import_log.testDebug)("lock user data dir", userDataDir);
     const browserType = playwright[this.config.browser.browserName];
     for (let i = 0; i < 5; i++) {
+      const hasLoadExtension = this.config.browser.launchOptions?.args?.some((arg) => arg.startsWith("--load-extension=")) ?? false;
       const launchOptions = {
         tracesDir,
         ...this.config.browser.launchOptions,
@@ -191,7 +192,8 @@ class PersistentContextFactory {
         handleSIGINT: false,
         handleSIGTERM: false,
         ignoreDefaultArgs: [
-          "--disable-extensions"
+          "--disable-extensions",
+          ...hasLoadExtension ? ["--disable-component-extensions-with-background-pages"] : []
         ],
         assistantMode: true,
         ...options.forceHeadless !== void 0 ? { headless: options.forceHeadless === "headless" } : {}

package/node_modules/playwright/lib/mcp/browser/config.js

@@ -248,7 +248,7 @@ function configFromEnv() {
   options.timeoutAction = numberParser(process.env.PLAYWRIGHT_MCP_TIMEOUT_ACTION);
   options.timeoutNavigation = numberParser(process.env.PLAYWRIGHT_MCP_TIMEOUT_NAVIGATION);
   options.userAgent = envToString(process.env.PLAYWRIGHT_MCP_USER_AGENT);
-  options.userDataDir = envToString(process.env.PLAYWRIGHT_MCP_USER_DATA_DIR);
+  options.userDataDir = envToString(process.env.PLAYWRIGHT_USER_DATA_DIR);
   options.viewportSize = resolutionParser("--viewport-size", process.env.PLAYWRIGHT_MCP_VIEWPORT_SIZE);
   return configFromCLIOptions(options);
 }

package/node_modules/playwright/lib/mcp/browser/context.js

@@ -45,6 +45,18 @@ class Context {
   constructor(options) {
     this._tabs = [];
     this._abortController = new AbortController();
+    // DOM Analyzer state — stored per session so the LLM can query it lazily.
+    // Keyed by (normalizedEntryUrl, storageStateHash, probeButtonsMode) —
+    // see crawler.ts and tools/sitemap.ts for cache-key composition.
+    this.sitemapCache = /* @__PURE__ */ new Map();
+    /**
+     * Phase B widget-contract inferred cache — per-session, in-memory.
+     * Key: 16-hex fingerprint. Value: agent-authored WidgetContract.
+     * Curated contracts are NOT stored here — they live in curatedWidgets.ts.
+     * Mutable for non-curated fingerprints; cacheInferredContract refuses to
+     * overwrite curated entries (see widgetContract.ts).
+     */
+    this.inferredContracts = /* @__PURE__ */ new Map();
     this.config = options.config;
     this.sessionLog = options.sessionLog;
     this.options = options;
@@ -185,7 +197,11 @@ class Context {
     if (this.sessionLog)
       await InputRecorder.create(this, browserContext);
     if (!this.config.allowUnrestrictedFileAccess) {
-      browserContext._setAllowedProtocols(["http:", "https:", "about:", "data:"]);
+      const allowedProtocols = ["http:", "https:", "about:", "data:"];
+      const launchArgs = this.config.browser.launchOptions?.args;
+      if (launchArgs?.some((arg) => arg.startsWith("--load-extension=")))
+        allowedProtocols.push("chrome-extension:");
+      browserContext._setAllowedProtocols(allowedProtocols);
       browserContext._setAllowedDirectories(allRootPaths(this._clientInfo));
     }
     await this._setupRequestInterception(browserContext);

package/node_modules/playwright/lib/mcp/browser/tab.js

@@ -27,10 +27,12 @@ module.exports = __toCommonJS(tab_exports);
 var import_events = require("events");
 var import_utils = require("playwright-core/lib/utils");
 var import_utils2 = require("./tools/utils");
+var import_extensionFrames = require("./tools/extensionFrames");
 var import_log = require("../log");
 var import_dialogs = require("./tools/dialogs");
 var import_files = require("./tools/files");
 var import_transform = require("../../transform/transform");
+var import_blueprintCache = require("../../dom-analyzer/blueprintCache");
 const TabEvents = {
   modalState: "modalState"
 };
@@ -45,6 +47,19 @@ class Tab extends import_events.EventEmitter {
     this._needsFullSnapshot = false;
     this._eventEntries = [];
     this._recentEventEntries = [];
+    /**
+     * Refs for elements inside chrome-extension iframes that live under closed
+     * shadow DOMs on the host page. Keyed by refs of the form `ef<frameIdx>-<seq>`
+     * and populated by captureSnapshot(); consumed by refLocators().
+     */
+    this._extensionFrameRefs = /* @__PURE__ */ new Map();
+    /**
+     * Per-tab cache of the most-recent PageBlueprint per URL. Used by
+     * browser_blueprint to return a delta against the prior capture at the
+     * same URL instead of the full payload. Cleared on tab close (not on
+     * navigation — same-URL revisits should reuse the prior blueprint).
+     */
+    this.blueprintCache = new import_blueprintCache.BlueprintCache(10);
     this.context = context;
     this.page = page;
     this._onPageClose = onPageClose;
@@ -148,6 +163,7 @@ class Tab extends import_events.EventEmitter {
   }
   _onClose() {
     this._clearCollectedArtifacts();
+    this.blueprintCache.clear();
     this._onPageClose(this);
   }
   async headerSnapshot() {
@@ -211,6 +227,20 @@ class Tab extends import_events.EventEmitter {
     if (tabSnapshot) {
       tabSnapshot.events = this._recentEventEntries;
       this._recentEventEntries = [];
+      try {
+        const extSnap = await (0, import_extensionFrames.enumerateExtensionFrames)(this.page);
+        if (extSnap.lines.length) {
+          tabSnapshot.ariaSnapshot = tabSnapshot.ariaSnapshot ? `${tabSnapshot.ariaSnapshot}
+${extSnap.lines.join("\n")}` : extSnap.lines.join("\n");
+          if (tabSnapshot.ariaSnapshotDiff !== void 0) {
+            tabSnapshot.ariaSnapshotDiff = tabSnapshot.ariaSnapshotDiff ? `${tabSnapshot.ariaSnapshotDiff}
+${extSnap.lines.join("\n")}` : extSnap.lines.join("\n");
+          }
+        }
+        this._extensionFrameRefs = extSnap.refMap;
+      } catch {
+        this._extensionFrameRefs = /* @__PURE__ */ new Map();
+      }
     }
     this._needsFullSnapshot = !tabSnapshot;
     return tabSnapshot ?? {
@@ -248,6 +278,14 @@ class Tab extends import_events.EventEmitter {
   async refLocators(params) {
     await this._initializedPromise;
     return Promise.all(params.map(async (param) => {
+      if (param.ref.startsWith("ef")) {
+        const ext = this._extensionFrameRefs.get(param.ref);
+        if (!ext)
+          throw new Error(`Extension-frame ref ${param.ref} not found. Call browser_snapshot to refresh.`);
+        const escapedMatch = ext.urlMatch.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+        const resolved = `frames().find(f => f.url().includes('${escapedMatch}')).${ext.expr}`;
+        return { locator: ext.locator, resolved };
+      }
       try {
         let locator = this.page.locator(`aria-ref=${param.ref}`);
         if (param.element)

package/node_modules/playwright/lib/mcp/browser/tools/domAnalyzer.js

@@ -0,0 +1,261 @@
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var domAnalyzer_exports = {};
+__export(domAnalyzer_exports, {
+  default: () => domAnalyzer_default
+});
+module.exports = __toCommonJS(domAnalyzer_exports);
+var crypto = __toESM(require("crypto"));
+var fs = __toESM(require("fs"));
+var import_mcpBundle = require("playwright-core/lib/mcpBundle");
+var import_tool = require("./tool");
+var import_crawler = require("../../../dom-analyzer/crawler");
+var import_blueprint = require("../../../dom-analyzer/blueprint");
+var import_serialization = require("../../../dom-analyzer/serialization");
+function hashStorageState(path) {
+  if (!path)
+    return null;
+  try {
+    const contents = fs.readFileSync(path, "utf-8");
+    return crypto.createHash("sha256").update(contents).digest("hex").slice(0, 16);
+  } catch {
+    const pathHash = crypto.createHash("sha256").update(path).digest("hex").slice(0, 16);
+    return `unreadable:${pathHash}`;
+  }
+}
+function cacheKey(entryUrl, storageStateHash, probeButtons) {
+  return `${entryUrl}::${storageStateHash ?? "no-auth"}::${probeButtons}`;
+}
+function humanDuration(ms) {
+  if (ms < 6e4)
+    return `${Math.round(ms / 1e3)}s`;
+  return `${Math.round(ms / 6e4)}m`;
+}
+const sitemapBuild = (0, import_tool.defineTool)({
+  capability: "core",
+  schema: {
+    name: "browser_sitemap_build",
+    title: "Build Sitemap (graph of PageBlueprints)",
+    description: [
+      "Crawl an application starting from a URL and build a Sitemap \u2014 a graph of PageBlueprints (one per URL)",
+      "connected by navigation edges. The Sitemap is cached in the session.",
+      "",
+      "Call once at the start of a session. Subsequent calls within the TTL (~30 minutes) reuse the cached",
+      "Sitemap unless `refresh: true` is passed. Use `browser_sitemap_query` to read already-crawled pages",
+      "rather than re-calling this tool.",
+      "",
+      "Depth defaults to 5, maxPages to 50 (the real bound in practice).",
+      "",
+      '\u26A0\uFE0F SAFETY: By default, `probeButtons: "immutable-only"` skips destructive-looking buttons',
+      "(Delete / Submit / Place Order / etc.) and buttons inside forms to prevent side effects during",
+      'crawling. Use `probeButtons: "all"` only against dev / staging environments \u2014 it will click every',
+      "unique button, which can submit forms, create records, send notifications, or mutate server state."
+    ].join("\n"),
+    inputSchema: import_mcpBundle.z.object({
+      url: import_mcpBundle.z.string().describe("Entry URL to start crawling from"),
+      depth: import_mcpBundle.z.number().optional().default(5).describe("Max crawl depth (default: 5)"),
+      maxPages: import_mcpBundle.z.number().optional().default(50).describe("Max pages to visit (default: 50)"),
+      sameOriginOnly: import_mcpBundle.z.boolean().optional().default(true).describe("Only follow same-origin links (default: true)"),
+      probeButtons: import_mcpBundle.z.enum(["immutable-only", "all", "none"]).optional().default("immutable-only").describe('Button-probing safety mode. Default: immutable-only (safe; skips destructive-verb buttons and buttons inside forms). Use "all" only against dev/staging \u2014 probes every button. "none" disables button probing entirely.'),
+      playwrightStoragePath: import_mcpBundle.z.string().optional().describe("Path to a Playwright storageState.json file \u2014 cookies, localStorage, sessionStorage per origin. Use this to crawl apps behind a login."),
+      refresh: import_mcpBundle.z.boolean().optional().default(false).describe("Force a full re-crawl, bypassing the cache")
+    }),
+    type: "readOnly"
+  },
+  handle: async (context, params, response) => {
+    const { url, depth, maxPages, sameOriginOnly, probeButtons, playwrightStoragePath, refresh } = params;
+    const normalizedUrl = (0, import_serialization.normalizeUrl)(url);
+    const storageStateHash = hashStorageState(playwrightStoragePath);
+    const probeMode = probeButtons;
+    const key = cacheKey(normalizedUrl, storageStateHash, probeMode);
+    const cached = context.sitemapCache.get(key);
+    if (cached && !refresh) {
+      const age = Date.now() - new Date(cached.sitemap.cachedAt).getTime();
+      if (age < import_serialization.CRAWL_TTL_MS) {
+        const pageCount2 = Object.keys(cached.sitemap.pages).length;
+        response.addTextResult(
+          `Reusing cached Sitemap from ${humanDuration(age)} ago.
+Entry: ${cached.sitemap.entryUrl}
+Pages: ${pageCount2}
+Edges: ${cached.sitemap.edges.length}
+Storage state: ${storageStateHash ? `auth hash ${storageStateHash}` : "none"}
+Probe mode: ${probeMode}
+
+Use browser_sitemap_query to read any page. Pass refresh=true to recrawl.`
+        );
+        return;
+      }
+    }
+    let sitemap;
+    if (depth > 0) {
+      sitemap = await (0, import_crawler.crawl)(url, {
+        depth,
+        maxPages,
+        sameOriginOnly,
+        probeButtons: probeMode,
+        playwrightStoragePath
+      });
+    } else {
+      sitemap = await (0, import_crawler.crawlSinglePage)(url, { playwrightStoragePath });
+    }
+    context.sitemapCache.set(key, { sitemap, storageStateHash, probeButtonsMode: probeMode });
+    const pageCount = Object.keys(sitemap.pages).length;
+    const pageList = Object.keys(sitemap.pages).map((u) => {
+      const bp = sitemap.pages[u];
+      const elCount = bp.sections.reduce((sum, s) => sum + s.elements.length + s.repeatingElements.length, 0);
+      return `  - ${u} (${elCount} elements across ${bp.sections.length} sections)`;
+    }).join("\n");
+    response.addTextResult(
+      `Sitemap built for ${sitemap.entryUrl}
+Pages: ${pageCount}
+Edges: ${sitemap.edges.length}
+Storage state: ${storageStateHash ? `auth hash ${storageStateHash}` : "none"}
+Probe mode: ${probeMode}
+
+Pages:
+${pageList}
+
+Use browser_sitemap_query to read page blueprints, edges, or derived views (mapJson, outline).`
+    );
+  }
+});
+const sitemapQuery = (0, import_tool.defineTool)({
+  capability: "core",
+  schema: {
+    name: "browser_sitemap_query",
+    title: "Query the cached Sitemap",
+    description: [
+      "Query the Sitemap cached by browser_sitemap_build. Use this instead of re-calling sitemap_build.",
+      "",
+      "Modes:",
+      "  page     \u2014 returns the full canonical PageBlueprint for the given URL",
+      "             (sections with enrichment, logical names, XPaths)",
+      "  edges    \u2014 returns navigation edges originating from the given URL",
+      "  mapJson  \u2014 returns the derived flat logicalName \u2192 xpath map for the URL",
+      "  outline  \u2014 returns the derived textual section-to-element hierarchy for the URL",
+      "  overview \u2014 (when url is omitted) returns page list + edge list summary"
+    ].join("\n"),
+    inputSchema: import_mcpBundle.z.object({
+      type: import_mcpBundle.z.enum(["page", "edges", "mapJson", "outline"]).optional().describe("Query mode. Omit with url to get overview."),
+      url: import_mcpBundle.z.string().optional().describe("Page URL to query. Omit to get overview across all pages.")
+    }),
+    type: "readOnly"
+  },
+  handle: async (context, params, response) => {
+    if (context.sitemapCache.size === 0) {
+      response.addError("No Sitemap available. Run browser_sitemap_build first.");
+      return;
+    }
+    const latest = [...context.sitemapCache.values()].sort(
+      (a, b) => new Date(b.sitemap.cachedAt).getTime() - new Date(a.sitemap.cachedAt).getTime()
+    )[0];
+    const sitemap = latest.sitemap;
+    const { type, url } = params;
+    if (!url || !type) {
+      const overview = {
+        schemaVersion: sitemap.schemaVersion,
+        entryUrl: sitemap.entryUrl,
+        cachedAt: sitemap.cachedAt,
+        pages: Object.keys(sitemap.pages).map((u) => ({
+          url: u,
+          sections: sitemap.pages[u].sections.length,
+          elements: sitemap.pages[u].sections.reduce(
+            (s, sec) => s + sec.elements.length + sec.repeatingElements.length,
+            0
+          ),
+          pageHash: sitemap.pages[u].pageHash
+        })),
+        edges: sitemap.edges
+      };
+      response.addTextResult(JSON.stringify(overview, null, 2));
+      return;
+    }
+    const normalizedQueryUrl = (0, import_serialization.normalizeUrl)(url);
+    const blueprint2 = sitemap.pages[normalizedQueryUrl];
+    if (!blueprint2) {
+      response.addError(
+        `Page not found in Sitemap: ${normalizedQueryUrl}. Available pages: ${Object.keys(sitemap.pages).join(", ")}`
+      );
+      return;
+    }
+    if (type === "page") {
+      response.addTextResult(JSON.stringify(blueprint2, null, 2));
+      return;
+    }
+    if (type === "edges") {
+      const edges = sitemap.edges.filter((e) => e.from === normalizedQueryUrl);
+      response.addTextResult(JSON.stringify({ url: normalizedQueryUrl, edges }, null, 2));
+      return;
+    }
+    if (type === "mapJson") {
+      response.addTextResult(JSON.stringify((0, import_blueprint.buildMap)(blueprint2), null, 2));
+      return;
+    }
+    if (type === "outline") {
+      response.addTextResult((0, import_blueprint.buildOutline)(blueprint2));
+      return;
+    }
+  }
+});
+const blueprint = (0, import_tool.defineTabTool)({
+  capability: "core",
+  schema: {
+    name: "browser_blueprint",
+    title: "Build PageBlueprint for the current page",
+    description: [
+      "Build a PageBlueprint for the currently loaded page. Returns the canonical `sections` tree",
+      "containing singular elements and repeating-element shapes, each carrying enrichment fields",
+      "(mutability, widgetType, framePath, shadowRoot, stableId, testId).",
+      "",
+      "Call this only when the DOM has changed since the last known-good blueprint \u2014 e.g. after a",
+      "modal opens, a form submits, a filter changes a list, or any mutable action. For pure navigation",
+      "to an already-crawled URL, reuse the Sitemap cache via browser_sitemap_query.",
+      "",
+      "Logical names are stable \u2014 use them in generated test code. Refs (from browser_snapshot) are",
+      "ephemeral \u2014 use them only for dispatching the next interaction, never in generated code."
+    ].join("\n"),
+    inputSchema: import_mcpBundle.z.object({}),
+    type: "readOnly"
+  },
+  handle: async (tab, _params, response) => {
+    try {
+      const bp = await (0, import_blueprint.buildPageBlueprint)(tab.page);
+      response.addTextResult(JSON.stringify(bp, null, 2));
+    } catch (err) {
+      if (err instanceof import_blueprint.BlueprintInvariantError) {
+        response.addError(
+          `Blueprint invariant violated: ${err.message}. This is a builder bug; please file an issue with the URL of the page that triggered it.`
+        );
+        return;
+      }
+      throw err;
+    }
+  }
+});
+var domAnalyzer_default = [sitemapBuild, sitemapQuery, blueprint];

package/node_modules/playwright/lib/mcp/browser/tools/keyboard.js

@@ -29,9 +29,9 @@ const pressKey = (0, import_tool.defineTabTool)({
   schema: {
     name: "browser_press_key",
     title: "Press a key",
-    description: "Press a key on the keyboard",
+    description: "Press a single key on the globally-focused element. This is a FALLBACK tool \u2014 prefer higher-level tools whenever possible: browser_click for buttons and links, browser_type for text entry, browser_type with submit: true for form submission (bundles the fill and the Enter into one recorded action). Only use browser_press_key when no semantic alternative exists: arrow-key navigation in an already-open listbox or combobox, Escape to close a modal that has no visible close button, Tab to shift focus between fields, or an app-specific keyboard shortcut the user actually relies on (e.g. Ctrl+K to open a command palette).",
     inputSchema: import_mcpBundle.z.object({
-      key: import_mcpBundle.z.string().describe("Name of the key to press or a character to generate, such as `ArrowLeft` or `a`")
+      key: import_mcpBundle.z.string().describe('Key name or character, e.g. "ArrowDown", "Enter", "Escape", "a". Supports modifier combinations like "Control+a" or "Meta+v".')
     }),
     type: "input"
   },
@@ -77,7 +77,7 @@ const type = (0, import_tool.defineTabTool)({
   schema: {
     name: "browser_type",
     title: "Type text",
-    description: "Type text into an editable element. Auto-focuses and replaces existing content. NEVER call browser_click on the field first \u2014 clicking before typing injects extra network requests that corrupt the trace.",
+    description: "Type text into an editable element. Auto-focuses and replaces existing content. NEVER call browser_click on the field first \u2014 clicking before typing injects extra network requests that corrupt the trace. When recording a UI trace for capture-act-capture, capture browser_blueprint before and after to derive form-state assertions from the textChanges delta.",
     inputSchema: typeSchema,
     type: "input"
   },