@skyramp/mcp 0.1.8 → 0.2.0-rc.1

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

@@ -0,0 +1,226 @@
+"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 sitemap_exports = {};
+__export(sitemap_exports, {
+  default: () => sitemap_default
+});
+module.exports = __toCommonJS(sitemap_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 blueprint = sitemap.pages[normalizedQueryUrl];
+    if (!blueprint) {
+      response.addError(
+        `Page not found in Sitemap: ${normalizedQueryUrl}. Available pages: ${Object.keys(sitemap.pages).join(", ")}`
+      );
+      return;
+    }
+    if (type === "page") {
+      response.addTextResult(JSON.stringify(blueprint, 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)(blueprint), null, 2));
+      return;
+    }
+    if (type === "outline") {
+      response.addTextResult((0, import_blueprint.buildOutline)(blueprint));
+      return;
+    }
+  }
+});
+var sitemap_default = [sitemapBuild, sitemapQuery];

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

@@ -30,7 +30,7 @@ const snapshot = (0, import_tool.defineTool)({
   schema: {
     name: "browser_snapshot",
     title: "Page snapshot",
-    description: "Capture the ARIA accessibility tree of the current page. Returns element refs required by all interaction tools (browser_click, browser_type, browser_hover, etc.). Call before any interaction and after every action that changes the page to get fresh refs. If any interaction tool fails with a stale ref error, call this first to refresh.",
+    description: "Capture the ARIA accessibility tree of the current page. Returns element refs required by all interaction tools (browser_click, browser_type, browser_hover, etc.). Call before any interaction and after every action that changes the page to get fresh refs. If any interaction tool fails with a stale ref error, call this first to refresh. For semantic identity (role/accessibleName/testId/stableId) and recommendation grounding, use browser_blueprint instead \u2014 refs from this tool are ephemeral and must not appear in generated test code.",
     inputSchema: import_mcpBundle.z.object({
       filename: import_mcpBundle.z.string().optional().describe("Save snapshot to markdown file instead of returning it in the response.")
     }),
@@ -55,7 +55,7 @@ const click = (0, import_tool.defineTabTool)({
   schema: {
     name: "browser_click",
     title: "Click",
-    description: "Click an element on the page. Always click the actual interactive element (button, link, input) \u2014 never a container or wrapper div. NEVER click a text field before typing \u2014 browser_type auto-focuses; a prior click injects extra network requests that corrupt the trace. NEVER click a row or link in a file list to access contextual actions \u2014 use browser_hover on the row instead.",
+    description: "Click an element on the page. Always click the actual interactive element (button, link, input) \u2014 never a container or wrapper div. NEVER click a text field before typing \u2014 browser_type auto-focuses; a prior click injects extra network requests that corrupt the trace. NEVER click a row or link in a file list to access contextual actions \u2014 use browser_hover on the row instead. When recording a UI trace for capture-act-capture, capture browser_blueprint before this click and again after \u2014 the diff between them grounds your post-action assertions.",
     inputSchema: clickSchema,
     type: "input"
   },

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

@@ -0,0 +1,168 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+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 __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var widgetContract_exports = {};
+__export(widgetContract_exports, {
+  default: () => widgetContract_default
+});
+module.exports = __toCommonJS(widgetContract_exports);
+var import_mcpBundle = require("playwright-core/lib/mcpBundle");
+var import_tool = require("./tool");
+var import_widgetContract = require("../../../dom-analyzer/widgetContract");
+const widgetContractLookup = (0, import_tool.defineTabTool)({
+  capability: "core",
+  schema: {
+    name: "browser_widget_contract_lookup",
+    title: "Look up a widget interaction contract by fingerprint",
+    description: [
+      "Returns the interaction contract for a widget's fingerprint.",
+      "",
+      "Only call for elements whose `widgetType` is `custom` or `unknown` \u2014 native widgets don't",
+      "need contracts. Pass the element's ref along with the fingerprint.",
+      "",
+      'On `status: "needs_inference"`, synthesize a WidgetContract from your own reasoning using',
+      "the returned context (outerHtml, ancestor chain, aria subtree, optional portal candidate),",
+      "submit it via `browser_widget_contract_cache`, then execute the contract using existing",
+      "browser tools (`browser_click`, `browser_type`, etc.).",
+      "",
+      'On `status: "error", reason: "stale_ref"`, re-snapshot and retry.',
+      "",
+      'On `status: "error", reason: "context_gather_failed"`, inspect the message; the error may be transient (retry) or structural (give up and try a different ref).',
+      "",
+      "Do not speculatively pre-infer contracts \u2014 call only when about to interact."
+    ].join("\n"),
+    inputSchema: import_mcpBundle.z.object({
+      fingerprint: import_mcpBundle.z.string().regex(/^[0-9a-f]{16}$/).describe("16-hex fingerprint from the element's PageBlueprint entry"),
+      ref: import_mcpBundle.z.string().describe('Snapshot ref for the specific element instance (e.g. "e42")')
+    }),
+    type: "readOnly"
+  },
+  handle: async (tab, params, response) => {
+    const { fingerprint, ref } = params;
+    const pure = (0, import_widgetContract.lookupContract)(fingerprint, tab.context.inferredContracts);
+    if (pure.status === "found") {
+      response.addTextResult(JSON.stringify({ status: "found", contract: pure.contract }, null, 2));
+      return;
+    }
+    let locator;
+    try {
+      ({ locator } = await tab.refLocator({ ref, element: "widget-fingerprint-target" }));
+    } catch {
+      response.addTextResult(JSON.stringify({ status: "error", reason: "stale_ref" }, null, 2));
+      return;
+    }
+    let gather;
+    let ariaRaw;
+    try {
+      gather = await locator.evaluate((el) => {
+        function truncate(s, max) {
+          return s.length <= max ? s : s.slice(0, max - 1) + "\u2026";
+        }
+        const outerHtml = truncate(el.outerHTML, 2048);
+        const ancestorChain = [];
+        let cur = el.parentElement;
+        let depth = 0;
+        while (cur && depth < 8) {
+          const role = cur.getAttribute("role");
+          const tag = cur.tagName.toLowerCase();
+          ancestorChain.push(role ? `${tag}[role='${role}']` : tag);
+          if (tag === "body") break;
+          cur = cur.parentElement;
+          depth++;
+        }
+        let portalEl = null;
+        const ctrl = el.getAttribute("aria-controls");
+        if (ctrl) {
+          const t = document.getElementById(ctrl);
+          if (t && !el.contains(t)) portalEl = t;
+        }
+        if (!portalEl) {
+          let found = 0;
+          const walker = document.createTreeWalker(document.documentElement, NodeFilter.SHOW_ELEMENT);
+          let cur2;
+          while (cur2 = walker.nextNode()) {
+            const desc = cur2;
+            if (el.contains(desc)) continue;
+            for (const attr of Array.from(desc.attributes)) {
+              if (attr.name.startsWith("data-radix-") || attr.name.startsWith("data-headlessui-")) {
+                portalEl = desc;
+                break;
+              }
+            }
+            if (portalEl) break;
+            if (++found >= 20) break;
+          }
+        }
+        const portal = portalEl ? {
+          selector: portalEl.tagName.toLowerCase() + (portalEl.id ? `#${portalEl.id}` : ""),
+          outerHtml: truncate(portalEl.outerHTML, 2048)
+        } : void 0;
+        return { outerHtml, ancestorChain, portal };
+      });
+      ariaRaw = await locator.ariaSnapshot();
+    } catch (e) {
+      response.addTextResult(JSON.stringify({
+        status: "error",
+        reason: "context_gather_failed",
+        message: e.message
+      }, null, 2));
+      return;
+    }
+    const ariaSnapshot = ariaRaw.length <= 1024 ? ariaRaw : ariaRaw.slice(0, 1023) + "\u2026";
+    const result = {
+      status: "needs_inference",
+      fingerprint,
+      ref,
+      element: { outerHtml: gather.outerHtml, ancestorChain: gather.ancestorChain },
+      ariaSnapshot,
+      ...gather.portal ? { portalCandidate: gather.portal } : {}
+    };
+    response.addTextResult(JSON.stringify(result, null, 2));
+  }
+});
+const widgetContractCache = (0, import_tool.defineTabTool)({
+  capability: "core",
+  schema: {
+    name: "browser_widget_contract_cache",
+    title: "Cache an inferred widget contract",
+    description: [
+      "Writes an inferred widget contract into the session's cache.",
+      "",
+      "Refuses to overwrite curated entries. Mutable for inferred entries \u2014 resubmit to",
+      'correct a bad inference. Submit a contract with `source: "unknown"` and empty steps',
+      "to mark the fingerprint as unresolvable for the session.",
+      "",
+      "Execute the contract yourself after a successful write; the tool does not return it back."
+    ].join("\n"),
+    inputSchema: import_mcpBundle.z.object({
+      fingerprint: import_mcpBundle.z.string().regex(/^[0-9a-f]{16}$/).describe("16-hex fingerprint of the widget being cached \u2014 must match the fingerprint that browser_widget_contract_lookup returned in needs_inference status (or that you read from a PageBlueprint element's fingerprint field)."),
+      // InferredWidgetContractSchema (not WidgetContractSchema): narrows
+      // `source` to {'inferred','unknown'}. Curated contracts come only
+      // from the curated library — agents must not be able to mislabel an
+      // inferred entry as authoritative via this tool surface.
+      contract: import_widgetContract.InferredWidgetContractSchema.describe(`The widget's interaction contract. Set source to "inferred" for a real contract you authored, or "unknown" with empty steps to mark the widget as unresolvable for this session. Curated contracts come from the library \u2014 you cannot submit source: "curated".`)
+    }),
+    type: "readOnly"
+  },
+  handle: async (tab, params, response) => {
+    const { fingerprint, contract } = params;
+    const result = (0, import_widgetContract.cacheInferredContract)(fingerprint, contract, tab.context.inferredContracts);
+    response.addTextResult(JSON.stringify(result));
+  }
+});
+var widgetContract_default = [widgetContractLookup, widgetContractCache];

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

@@ -44,16 +44,22 @@ var import_mouse = __toESM(require("./tools/mouse"));
 var import_navigate = __toESM(require("./tools/navigate"));
 var import_network = __toESM(require("./tools/network"));
 var import_open = __toESM(require("./tools/open"));
+var import_pageBlueprint = __toESM(require("./tools/pageBlueprint"));
 var import_pdf = __toESM(require("./tools/pdf"));
 var import_runCode = __toESM(require("./tools/runCode"));
+var import_sitemap = __toESM(require("./tools/sitemap"));
 var import_snapshot = __toESM(require("./tools/snapshot"));
 var import_screenshot = __toESM(require("./tools/screenshot"));
 var import_tabs = __toESM(require("./tools/tabs"));
 var import_tracing = __toESM(require("./tools/tracing"));
 var import_wait = __toESM(require("./tools/wait"));
 var import_verify = __toESM(require("./tools/verify"));
+var import_widgetContract = __toESM(require("./tools/widgetContract"));
 const browserTools = [
   ...import_common.default,
+  ...import_sitemap.default,
+  ...import_pageBlueprint.default,
+  ...import_widgetContract.default,
   ...import_console.default,
   ...import_dialogs.default,
   ...import_evaluate.default,

package/node_modules/playwright/lib/mcp/skyramp/traceRecordingBackend.js

@@ -66,11 +66,22 @@ class TraceRecordingBackend {
     return this._trackedActions;
   }
   async initialize(clientInfo) {
-    const headless = this._options.headless ?? (!!process.env.CI || import_os.default.platform() === "linux" && !process.env.DISPLAY);
+    const userDataDir = this._options.userDataDir || process.env.PLAYWRIGHT_USER_DATA_DIR || void 0;
+    const loadExtension = this._options.loadExtension ?? splitExtensionPaths(process.env.PLAYWRIGHT_LOAD_EXTENSION);
+    const persistent = !!userDataDir || !!loadExtension?.length;
+    const extensionArgs = loadExtension?.length ? [
+      `--disable-extensions-except=${loadExtension.join(",")}`,
+      `--load-extension=${loadExtension.join(",")}`
+    ] : void 0;
+    const headless = loadExtension?.length ? false : this._options.headless ?? (!!process.env.CI || import_os.default.platform() === "linux" && !process.env.DISPLAY);
     const config = await (0, import_config.resolveConfig)({
       browser: {
-        isolated: true,
-        launchOptions: { headless },
+        isolated: !persistent,
+        ...persistent && userDataDir ? { userDataDir } : {},
+        launchOptions: {
+          headless,
+          ...extensionArgs ? { args: extensionArgs } : {}
+        },
         contextOptions: {
           viewport: { width: 1280, height: 900 },
           recordHar: { path: this._harPath, mode: "minimal" },
@@ -88,11 +99,18 @@ class TraceRecordingBackend {
         navigation: 6e4
       }
     });
+    if (loadExtension?.length && config.browser.launchOptions?.channel === "chrome")
+      delete config.browser.launchOptions.channel;
     const factory = (0, import_browserContextFactory.contextFactory)(config);
     this._browserBackend = new import_browserServerBackend.BrowserServerBackend(config, factory);
     await this._browserBackend.initialize(clientInfo);
     this._initialized = true;
-    traceDebug("TraceRecordingBackend initialized");
+    traceDebug("TraceRecordingBackend initialized", {
+      persistent,
+      userDataDir,
+      loadExtension,
+      channel: config.browser.launchOptions?.channel
+    });
     this._browserBackend.context.onBrowserContextCreated = (browserContext) => this._installPopupListener(browserContext);
   }
   async listTools() {
@@ -130,8 +148,10 @@ class TraceRecordingBackend {
     }
     if (name === "browser_tabs" && ["select", "switch"].includes(args?.action)) {
       const index = args?.index ?? 0;
-      this._currentPageAlias = index === 0 ? "page" : `page${index}`;
-      traceDebug(`Tab switched to index ${index} \u2192 pageAlias: ${this._currentPageAlias}`);
+      const targetUrl = this._browserBackend.context?.tabs()[index]?.page.url();
+      const urlAlias = targetUrl ? aliasForUrl(targetUrl) : null;
+      this._currentPageAlias = urlAlias ?? (index === 0 ? "page" : `page${index}`);
+      traceDebug(`Tab switched to index ${index} (url=${targetUrl}) \u2192 pageAlias: ${this._currentPageAlias}`);
       const tabResult = await this._browserBackend.callTool(name, args);
       return tabResult;
     }
@@ -731,7 +751,7 @@ ${details}` }]
    */
   _installPopupListener(browserContext) {
     let initialPageSeen = false;
-    browserContext.on("page", () => {
+    browserContext.on("page", (newPage) => {
       if (!initialPageSeen) {
         initialPageSeen = true;
         return;
@@ -745,16 +765,23 @@ ${details}` }]
       this._currentPageAlias = popupAlias;
       this._pendingPopupAlias = popupAlias;
       traceDebug(`Popup page opened: ${popupAlias} (pending stamp)`);
+      void newPage.waitForLoadState("domcontentloaded").then(() => {
+        const settled = newPage.url();
+        const semantic = aliasForUrl(settled);
+        if (!semantic)
+          return;
+        if (this._currentPageAlias === popupAlias)
+          this._currentPageAlias = semantic;
+        if (this._pendingPopupAlias === popupAlias)
+          this._pendingPopupAlias = semantic;
+        traceDebug(`Popup alias upgraded: ${popupAlias} \u2192 ${semantic} (url=${settled})`);
+      }).catch(() => {
+      });
     });
   }
   _maybeTrackAction(toolName, args, result, timestamp, pageAliasBeforeAction) {
     if (result.isError)
       return;
-    if (toolName === "browser_press_key") {
-      const key = String(args.key || "").toLowerCase();
-      if (key.includes("control+") || key.includes("meta+") || key === "tab" || key === "enter" || key === "escape")
-        return;
-    }
     const parsed = (0, import_response.parseResponse)(result);
     const code = parsed?.code ?? "";
     if (code || import_types.ARGS_ONLY_TOOLS.has(toolName)) {
@@ -811,6 +838,19 @@ ${details}` }]
     this._cleanupTempDir(false);
   }
 }
+function splitExtensionPaths(value) {
+  if (!value)
+    return void 0;
+  const parts = value.split(/[,;]/).map((p) => p.trim()).filter(Boolean);
+  return parts.length ? parts : void 0;
+}
+function aliasForUrl(url) {
+  if (!url)
+    return null;
+  if (/^chrome-extension:\/\/[a-p]{32}\/popup\//.test(url))
+    return "popupPage";
+  return null;
+}
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   TraceRecordingBackend