@skyramp/mcp 0.1.8 → 0.2.0-rc.2

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

package/node_modules/playwright/lib/mcp/test/skyRampExport.js

@@ -66,6 +66,16 @@ function jsonlHeader(browserName, harPath) {
   });
 }
 function extractLocatorFromCode(code) {
+  const extensionFrameMatch = code.match(
+    /await\s+page\.frames\(\)\.find\(\s*f\s*=>\s*f\.url\(\)\.includes\(\s*(['"])([^'"]+)\1\s*\)\s*\)!?\.(.*?)\.(click|dblclick|fill|pressSequentially|check|uncheck|selectOption|hover|dragTo)\s*\(/s
+  );
+  if (extensionFrameMatch) {
+    return {
+      locatorExpr: extensionFrameMatch[3].trim(),
+      framePath: [],
+      frameUrlMatch: extensionFrameMatch[2]
+    };
+  }
   const contentFrameMatch = code.match(/await\s+page\.locator\((['"])(iframe[^\n]*?)\1\)(?:\.contentFrame\(\))+\.(.*?)\.(click|dblclick|fill|pressSequentially|check|uncheck|selectOption|hover|dragTo)\s*\(/s);
   if (contentFrameMatch) {
     return { locatorExpr: contentFrameMatch[3].trim(), framePath: [contentFrameMatch[2]] };
@@ -206,10 +216,13 @@ function trackedActionToJsonl(action, pageGuid, timestamp) {
   if (toolName === "browser_wait_for") {
     const text = args.text;
     const textGone = args.textGone;
+    const time = args.time;
     if (text)
       return JSON.stringify({ name: "waitForSelector", selector: `text=${text}`, ...base });
     if (textGone)
       return JSON.stringify({ name: "waitForSelector", selector: `text=${textGone}`, state: "hidden", ...base });
+    if (typeof time === "number")
+      return JSON.stringify({ name: "waitForTimeout", duration: time * 1e3, ...base });
     return null;
   }
   if (toolName === "browser_press_key")
@@ -219,9 +232,11 @@ function trackedActionToJsonl(action, pageGuid, timestamp) {
   const extracted = extractLocatorFromCode(code);
   if (!extracted)
     return null;
-  const { locatorExpr, framePath: codeFramePath } = extracted;
+  const { locatorExpr, framePath: codeFramePath, frameUrlMatch } = extracted;
   if (codeFramePath.length > 0)
     base.framePath = codeFramePath;
+  if (frameUrlMatch)
+    base.frameUrlMatch = frameUrlMatch;
   const parsed = locatorToJsonl(locatorExpr);
   if (!parsed)
     return null;
@@ -373,18 +388,51 @@ function removeRedundantClicks(actions) {
   });
 }
 function deduplicateRetries(actions) {
-  const firstNavigate = actions.find((a) => a.toolName === "browser_navigate");
-  if (!firstNavigate)
-    return actions;
-  const startUrl = firstNavigate.args.url;
-  let lastRestartIdx = 0;
-  for (let i = 1; i < actions.length; i++) {
-    if (actions[i].toolName === "browser_navigate" && actions[i].args.url === startUrl)
-      lastRestartIdx = i;
+  const result = [];
+  let lastNavIdx = -1;
+  for (const action of actions) {
+    if (action.toolName !== "browser_navigate") {
+      result.push(action);
+      continue;
+    }
+    const url = action.args.url;
+    if (lastNavIdx >= 0 && result[lastNavIdx].args.url === url) {
+      result.length = lastNavIdx;
+      lastNavIdx = -1;
+      for (let k = result.length - 1; k >= 0; k--) {
+        if (result[k].toolName === "browser_navigate") {
+          lastNavIdx = k;
+          break;
+        }
+      }
+    }
+    result.push(action);
+    lastNavIdx = result.length - 1;
+  }
+  return result;
+}
+function normalizePrimaryPageAlias(actions) {
+  const DEFAULT = DEFAULT_PAGE_ALIAS;
+  const counts = /* @__PURE__ */ new Map();
+  for (const a of actions) {
+    const alias = a.pageAlias ?? DEFAULT;
+    counts.set(alias, (counts.get(alias) ?? 0) + 1);
+  }
+  if ((counts.get(DEFAULT) ?? 0) > 0)
+    return;
+  const candidates = [...counts.keys()].filter((a) => /^page\d+$/.test(a));
+  if (candidates.length !== 1)
+    return;
+  const from = candidates[0];
+  for (const a of actions) {
+    if (a.pageAlias === from)
+      a.pageAlias = DEFAULT;
+    if (a.popupAlias === from)
+      a.popupAlias = DEFAULT;
   }
-  return lastRestartIdx > 0 ? actions.slice(lastRestartIdx) : actions;
 }
 function buildJsonlContent(actions, browserName, harPath) {
+  normalizePrimaryPageAlias(actions);
   const deduplicated = removeRedundantClicks(deduplicateRetries(actions));
   const startTime = deduplicated[0]?.timestamp ?? Date.now();
   const pageGuids = /* @__PURE__ */ new Map();
@@ -416,7 +464,9 @@ function buildJsonlContent(actions, browserName, harPath) {
           const obj = JSON.parse(lines[i]);
           if (obj.name === "openPage" || obj.name === "closePage")
             continue;
-          if (!obj.pageAlias || obj.pageAlias !== alias) {
+          if (!obj.pageAlias)
+            continue;
+          if (obj.pageAlias !== alias) {
             obj.signals = [...obj.signals || [], { name: "popup", popupAlias: alias }];
             lines[i] = JSON.stringify(obj);
             break;
@@ -453,7 +503,7 @@ function buildJsonlContent(actions, browserName, harPath) {
       }
       const parsed = extractLocatorFromCode(action.code);
       if (parsed) {
-        const { locatorExpr, framePath } = parsed;
+        const { locatorExpr, framePath, frameUrlMatch } = parsed;
         const locatorInfo = locatorToJsonl(locatorExpr);
         if (locatorInfo) {
           const { selector, locator: locatorObj } = locatorInfo;
@@ -466,7 +516,8 @@ function buildJsonlContent(actions, browserName, harPath) {
             timestamp: String(action.timestamp + 100),
             pageGuid,
             pageAlias: alias,
-            framePath
+            framePath,
+            ...frameUrlMatch ? { frameUrlMatch } : {}
           });
           lines.push(pressLine);
           actionCount++;

package/node_modules/playwright/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/playwright",
-  "version": "1.58.2-skyramp.8.9.0",
+  "version": "1.58.2-skyramp.8.9.6",
   "description": "Skyramp's fork of Playwright with trace recording for UI test generation",
   "publishConfig": {
     "access": "public"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skyramp/mcp",
-  "version": "0.1.8",
+  "version": "0.2.0-rc.2",
   "main": "build/index.js",
   "exports": {
     ".": "./build/index.js",
@@ -55,11 +55,11 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.24.3",
     "@playwright/test": "^1.55.0",
-    "@skyramp/skyramp": "1.3.24",
+    "@skyramp/skyramp": "1.3.25",
     "dockerode": "^5.0.0",
     "fast-glob": "^3.3.3",
     "js-yaml": "^4.1.1",
-    "playwright": "file:vendor/skyramp-playwright-1.58.2-skyramp.8.9.0.tgz",
+    "playwright": "file:vendor/skyramp-playwright-1.58.2-skyramp.8.9.6.tgz",
     "simple-git": "^3.30.0",
     "zod": "^3.25.3"
   },