@skyramp/mcp 0.2.1-rc.1 → 0.2.2

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

@@ -43,6 +43,10 @@ var import_log = require("../log");
 var import_skyRampExport = require("../test/skyRampExport");
 var import_exportTool = require("./exportTool");
 var import_assertTool = require("./assertTool");
+var import_assertApiRequestTool = require("./assertApiRequestTool");
+var import_loadTraceTool = require("./loadTraceTool");
+var import_skyRampImport = require("./skyRampImport");
+var import_utils = require("playwright-core/lib/utils");
 var import_types = require("./types");
 const traceDebug = (0, import_utilsBundle.debug)("pw:mcp:trace");
 class TraceRecordingBackend {
@@ -115,7 +119,7 @@ class TraceRecordingBackend {
   }
   async listTools() {
     const browserTools = await this._browserBackend.listTools();
-    return [...browserTools, (0, import_exportTool.exportZipMcpTool)(), (0, import_assertTool.assertMcpTool)()];
+    return [...browserTools, (0, import_exportTool.exportZipMcpTool)(), (0, import_assertTool.assertMcpTool)(), (0, import_assertApiRequestTool.assertApiRequestMcpTool)(), (0, import_loadTraceTool.loadTraceMcpTool)()];
   }
   async callTool(name, args, progress) {
     if (!this._initialized)
@@ -138,10 +142,27 @@ class TraceRecordingBackend {
       }
       return exportResult;
     }
+    if (name === import_loadTraceTool.loadTraceSchema.name) {
+      const parsed = import_loadTraceTool.loadTraceSchema.inputSchema.parse(args || {});
+      return this._handleLoadTrace(parsed);
+    }
     if (name === import_assertTool.assertToolSchema.name) {
       const parsed = import_assertTool.assertToolSchema.inputSchema.parse(args || {});
       return this._handleAssert(parsed);
     }
+    if (name === import_assertApiRequestTool.assertApiRequestSchema.name) {
+      this._trackedActions.push({
+        toolName: "browser_assert_api_request",
+        args: {},
+        code: "",
+        timestamp: Date.now(),
+        pageAlias: this._currentPageAlias
+      });
+      traceDebug("Assert API request marker recorded");
+      return {
+        content: [{ type: "text", text: "### Result\nAPI request assertion marker recorded. The next action that triggers a network request will have its payload captured for validation in the generated test." }]
+      };
+    }
     if (name === "browser_select_option") {
       const result2 = await this._handleSelectOption(args || {});
       return result2;
@@ -178,6 +199,7 @@ class TraceRecordingBackend {
           timestamp: ts,
           pageAlias: this._currentPageAlias
         });
+        await this._enableFlutterAccessibility();
         const snapResult = await this._browserBackend.callTool("browser_snapshot", {});
         return {
           content: [
@@ -191,17 +213,88 @@ Reloaded current page: ${currentUrl}
     }
     const timestampBeforeAction = Date.now();
     const pageAliasBeforeAction = this._currentPageAlias;
+    const stripRestore = await this._maybeStripWrapperRoles(name, args);
     let preClickHoverCode = null;
-    if (name === "browser_click" && args?.ref) {
-      const hoverResult = await this._browserBackend.callTool("browser_hover", {
-        element: args.element || "element",
-        ref: args.ref
-      });
-      if (!hoverResult.isError)
-        preClickHoverCode = (0, import_response.parseResponse)(hoverResult)?.code ?? null;
+    let preClickSnapshot = null;
+    let preClickLocatorCount = 0;
+    let preClickParentChain = null;
+    let result;
+    try {
+      if (name === "browser_click" && args?.ref) {
+        const hoverResult = await this._browserBackend.callTool("browser_hover", {
+          element: args.element || "element",
+          ref: args.ref
+        });
+        if (!hoverResult.isError) {
+          const parsed = (0, import_response.parseResponse)(hoverResult);
+          preClickHoverCode = parsed?.code ?? null;
+          preClickSnapshot = parsed?.snapshot ?? null;
+          if (preClickHoverCode) {
+            const roleCountMatch = preClickHoverCode.match(/getByRole\(\s*['"](\w+)['"]\s*(?:,\s*\{[^}]*name:\s*(?:'([^']*)'|"([^"]*)")\s*[^}]*\})?\s*\)/);
+            if (roleCountMatch) {
+              try {
+                const page = this._browserBackend.context?.currentTab()?.page;
+                if (page) {
+                  const r = roleCountMatch[1];
+                  const n = roleCountMatch[2] ?? roleCountMatch[3];
+                  preClickLocatorCount = n ? await page.getByRole(r, { name: n }).count() : await page.getByRole(r).count();
+                  traceDebug(`[pre-click count] getByRole("${r}"${n ? `, { name: "${n}" }` : ""}) = ${preClickLocatorCount}`);
+                }
+              } catch {
+              }
+            }
+          }
+          try {
+            const page = this._browserBackend.context?.currentTab()?.page;
+            if (page) {
+              preClickParentChain = await page.locator(`aria-ref=${args.ref}`).evaluate((el) => {
+                const ARIA_LANDMARKS = /* @__PURE__ */ new Set(["navigation", "main", "banner", "contentinfo", "complementary", "search", "form"]);
+                const SEMANTIC_TAGS_UNIQUE_CANDIDATES = ["nav", "main", "header", "footer", "aside"];
+                const SKIP_TESTID = /^(container|wrapper|content|main|root|app)$/i;
+                const SKIP_ID = /^(root|app|main|container|wrapper|content)$/i;
+                const isDynamic = (s) => /[-_]\d+$/.test(s) || /^[0-9a-f]{8,}/.test(s);
+                let cur = el.parentElement;
+                while (cur && cur !== el.ownerDocument.body) {
+                  const tid = cur.getAttribute("data-testid") || cur.getAttribute("data-test-id");
+                  if (tid && !isDynamic(tid) && !SKIP_TESTID.test(tid))
+                    return `getByTestId(${JSON.stringify(tid)})`;
+                  const id = cur.id;
+                  if (id && !isDynamic(id) && !SKIP_ID.test(id)) {
+                    const escapedId = id.replace(/(["\\])/g, "\\$1");
+                    return `locator(${JSON.stringify("#" + escapedId)})`;
+                  }
+                  const role = cur.getAttribute("role");
+                  if (role && ARIA_LANDMARKS.has(role)) {
+                    const ariaLabel = cur.getAttribute("aria-label");
+                    if (ariaLabel)
+                      return `getByRole(${JSON.stringify(role)}, { name: ${JSON.stringify(ariaLabel)} })`;
+                    if (el.ownerDocument.querySelectorAll(`[role="${role}"]`).length === 1)
+                      return `getByRole(${JSON.stringify(role)})`;
+                  }
+                  const tag = cur.tagName.toLowerCase();
+                  if (SEMANTIC_TAGS_UNIQUE_CANDIDATES.includes(tag)) {
+                    if (el.ownerDocument.querySelectorAll(tag).length === 1)
+                      return `locator(${JSON.stringify(tag)})`;
+                  }
+                  cur = cur.parentElement;
+                }
+                return null;
+              }).catch(() => null);
+              traceDebug(`[pre-click parent chain] ${preClickParentChain}`);
+            }
+          } catch {
+          }
+        }
+      }
+      result = await this._browserBackend.callTool(name, args);
+    } finally {
+      if (stripRestore)
+        await stripRestore();
     }
-    let result = await this._browserBackend.callTool(name, args);
-    result = await this._improveActionSelector(name, args || {}, result, preClickHoverCode);
+    if (name === "browser_navigate" && !result.isError) {
+      await this._enableFlutterAccessibility();
+    }
+    result = await this._improveActionSelector(name, args || {}, result, preClickHoverCode, preClickSnapshot, preClickLocatorCount, preClickParentChain);
     if (name === "browser_fill_form" && result.isError) {
       const resultText = result.content?.[0]?.type === "text" ? result.content[0].text : "";
       if (resultText.includes("not a <select> element") || resultText.includes("selectOption") && resultText.includes("Timeout")) {
@@ -227,6 +320,216 @@ Reloaded current page: ${currentUrl}
   serverClosed() {
     void this._autoExportAndClose().catch(import_log.logUnhandledError);
   }
+  /**
+   * Load a prior Skyramp trace and replay it against the live browser, honoring
+   * an optional stop point, then seed _trackedActions with the replayed actions
+   * so the model can continue recording and export a combined trace.
+   */
+  async _handleLoadTrace(params) {
+    const stopParams = ["stopAtStep", "stopAtUrl", "stopBefore"].filter((k) => {
+      const v = params[k];
+      return v !== void 0 && v !== "";
+    });
+    if (stopParams.length > 1)
+      return { content: [{ type: "text", text: `### Error
+Pass at most ONE of stopAtStep / stopAtUrl / stopBefore (got ${stopParams.join(", ")}). Omit all three to replay the whole trace.` }], isError: true };
+    let loadedActions;
+    try {
+      loadedActions = await (0, import_skyRampImport.actionsFromPath)(params.path);
+    } catch (e) {
+      return { content: [{ type: "text", text: `### Error
+Failed to load trace from ${params.path}: ${e.message}` }], isError: true };
+    }
+    if (!loadedActions.length)
+      return { content: [{ type: "text", text: `### Error
+No actions found in ${params.path}.` }], isError: true };
+    if (params.dryRun) {
+      const stepList = loadedActions.map((a, i) => (0, import_loadTraceTool.describeStep)(a, i)).join("\n");
+      return {
+        content: [{
+          type: "text",
+          text: `### Trace loaded (dry run)
+${loadedActions.length} steps in ${params.path}. Nothing was replayed.
+
+Steps:
+${stepList}
+
+Call skyramp_load_trace again with stopAtStep / stopAtUrl / stopBefore (or none of them to replay all) to replay.`
+        }]
+      };
+    }
+    try {
+      await this._browserBackend.context.ensureTab();
+    } catch {
+    }
+    let result;
+    try {
+      result = await (0, import_loadTraceTool.replayActions)(loadedActions, { pageForAlias: (alias) => this._pageForAlias(alias) }, params);
+    } catch (e) {
+      return { content: [{ type: "text", text: `### Error
+Replay failed: ${e.message}` }], isError: true };
+    }
+    for (let i = 0; i < result.stopIndex; i++)
+      this._seedTrackedAction(loadedActions[i]);
+    if (result.stopIndex > 0)
+      this._currentPageAlias = loadedActions[result.stopIndex - 1].frame.pageAlias || "page";
+    const remaining = (0, import_loadTraceTool.listStepsFrom)(loadedActions, result.stopIndex);
+    const stoppedNote = (0, import_loadTraceTool.describeStopReason)(result);
+    const errorNote = result.error ? `
+
+\u26A0\uFE0F Replay stopped at step ${result.error.stepIndex} (${result.error.actionName}): ${result.error.message}
+You can continue recording from this point or fix the issue.` : "";
+    return {
+      content: [{
+        type: "text",
+        text: `### Trace replayed
+${result.completedCount} of ${loadedActions.length} steps replayed from ${params.path}. ${stoppedNote}${errorNote}
+
+Remaining steps (NOT replayed):
+${remaining}
+
+Continue recording with browser_* tools, then call skyramp_export_zip to write the combined trace.`
+      }],
+      isError: result.stopReason === "error"
+    };
+  }
+  /**
+   * Resolve a JSONL page alias to a live page. Numeric aliases ('page',
+   * 'pageN') map by tab index; semantic aliases ('popupPage') match by the
+   * popup URL pattern, falling back to the most recently opened tab.
+   */
+  _pageForAlias(alias) {
+    const tabs = this._browserBackend.context?.tabs() ?? [];
+    if (!tabs.length)
+      return void 0;
+    const numeric = alias === "page" ? 0 : /^page(\d+)$/.exec(alias)?.[1];
+    if (numeric !== void 0 && numeric !== null) {
+      const idx = Number(numeric);
+      return (tabs[idx] ?? tabs[tabs.length - 1]).page;
+    }
+    const popupTab = tabs.find((t) => /chrome-extension:\/\/[a-p]{32}\/popup\//.test(t.page.url()));
+    return (popupTab ?? tabs[tabs.length - 1]).page;
+  }
+  /**
+   * Convert a replayed ActionInContext back into a TrackedAction so it merges
+   * with freshly-recorded actions. The export pipeline (buildJsonlContent)
+   * re-derives the JSONL selector from the `code` field, so we regenerate clean
+   * Playwright code from the stored internal: selector via asLocator.
+   */
+  _seedTrackedAction(action) {
+    const a = action.action;
+    const pageAlias = action.frame.pageAlias || "page";
+    if (a.name === "navigate") {
+      this._trackedActions.push({
+        toolName: "browser_navigate",
+        args: { url: a.url },
+        code: "",
+        timestamp: action.startTime,
+        pageAlias
+      });
+      return;
+    }
+    const locatorExpr = a.selector ? (0, import_utils.asLocator)("javascript", a.selector) : "";
+    const seeded = this._seedTrackedActionFields(a, locatorExpr);
+    if (!seeded)
+      return;
+    this._trackedActions.push({
+      ...seeded,
+      timestamp: action.startTime,
+      pageAlias,
+      framePath: action.frame.framePath?.length ? action.frame.framePath : void 0
+    });
+  }
+  /**
+   * Build the { toolName, code, args } triple a seeded (replayed) action must
+   * carry so it round-trips through skyRampExport.buildJsonlContent exactly as
+   * a freshly-recorded action would. toolName, code and args are emitted
+   * together (not via separate mappers) because export keys on all three:
+   * trackedActionToJsonl dispatches on toolName, derives the locator from code,
+   * and reads specific args (checked, values, type). A mismatch silently
+   * mis-exports (e.g. hover as click) or drops the action.
+   *
+   * Code uses single quotes to match the live recorder's format
+   * (extractFillText / extractSelectOptions only match single-quoted calls).
+   * Returns null for unsupported actions so they are skipped, never defaulted.
+   */
+  _seedTrackedActionFields(a, locatorExpr) {
+    const sq = (s) => `'${String(s).replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t")}'`;
+    const SELECTOR_REQUIRED = /* @__PURE__ */ new Set(["click", "hover", "fill", "pressSequentially", "check", "uncheck", "select"]);
+    if (SELECTOR_REQUIRED.has(a.name) && !locatorExpr)
+      return null;
+    const root = a.frameUrlMatch ? `page.frames().find(f => f.url().includes(${sq(a.frameUrlMatch)}))!` : "page";
+    switch (a.name) {
+      case "click": {
+        const isDouble = (a.clickCount ?? 1) > 1;
+        const verb = isDouble ? "dblclick" : "click";
+        const args = {};
+        if (a.button && a.button !== "left")
+          args.button = a.button;
+        const mods = (0, import_loadTraceTool.decodeModifiers)(a.modifiers);
+        if (mods.length)
+          args.modifiers = mods;
+        return { toolName: "browser_click", code: `await ${root}.${locatorExpr}.${verb}();`, args };
+      }
+      case "hover":
+        return { toolName: "browser_hover", code: `await ${root}.${locatorExpr}.hover();`, args: {} };
+      case "fill":
+        return { toolName: "browser_type", code: `await ${root}.${locatorExpr}.fill(${sq(a.text ?? "")});`, args: { text: a.text ?? "" } };
+      case "pressSequentially":
+        return { toolName: "browser_type", code: `await ${root}.${locatorExpr}.pressSequentially(${sq(a.text ?? "")});`, args: { text: a.text ?? "", slowly: true } };
+      case "press": {
+        const args = { key: a.key };
+        const mods = (0, import_loadTraceTool.decodeModifiers)(a.modifiers);
+        if (mods.length)
+          args.modifiers = mods;
+        return { toolName: "browser_press_key", code: "", args };
+      }
+      case "assertApiRequest":
+        return { toolName: "browser_assert_api_request", code: "", args: {} };
+      case "waitForTimeout":
+        return { toolName: "browser_wait_for", code: "", args: { time: (a.duration ?? 0) / 1e3 } };
+      case "check":
+        return { toolName: "browser_set_checked", code: `await ${root}.${locatorExpr}.check();`, args: { checked: true } };
+      case "uncheck":
+        return { toolName: "browser_set_checked", code: `await ${root}.${locatorExpr}.uncheck();`, args: { checked: false } };
+      case "select":
+        return { toolName: "browser_select_option", code: `await ${root}.${locatorExpr}.selectOption(${sq((a.options ?? [])[0] ?? "")});`, args: { values: a.options ?? [] } };
+      case "waitForSelector": {
+        const sel = a.selector ?? "";
+        const m = /^text=(.*)$/.exec(sel);
+        if (!m)
+          return null;
+        return a.state === "hidden" ? { toolName: "browser_wait_for", code: "", args: { textGone: m[1] } } : { toolName: "browser_wait_for", code: "", args: { text: m[1] } };
+      }
+      case "dragAndDrop":
+      case "dragTo": {
+        const srcSel = a.source ?? a.selector;
+        const tgtSel = a.target ?? a.targetSelector;
+        if (!srcSel || !tgtSel)
+          return null;
+        const srcExpr = (0, import_utils.asLocator)("javascript", srcSel);
+        const tgtExpr = (0, import_utils.asLocator)("javascript", tgtSel);
+        return { toolName: "browser_drag", code: `await page.${srcExpr}.dragTo(page.${tgtExpr});`, args: {} };
+      }
+      // Assertions are encoded the same way _handleAssert encodes them, so
+      // assertActionToJsonl in skyRampExport parses them identically. That
+      // parser dispatches on toolName === 'browser_assert' and keys on args.type.
+      // Assertions pass selector/expected as structured args (unambiguous even
+      // when the value contains ':'). assertActionToJsonl reads these directly;
+      // the legacy colon-encoded code string is kept only as a human-readable
+      // breadcrumb / backward-compat fallback.
+      case "assertText":
+        return { toolName: "browser_assert", code: `assertText:${a.selector}:${a.text}:${a.substring ?? true}`, args: { type: "text", selector: a.selector, expected: a.text, substring: a.substring ?? true } };
+      case "assertValue":
+        return { toolName: "browser_assert", code: `assertValue:${a.selector}:${a.value}`, args: { type: "value", selector: a.selector, expected: a.value } };
+      case "assertChecked":
+        return { toolName: "browser_assert", code: `assertChecked:${a.selector}:${!!a.checked}`, args: { type: "checked", selector: a.selector, checked: !!a.checked } };
+      case "assertVisible":
+        return { toolName: "browser_assert", code: `assertVisible:${a.selector}`, args: { type: "visible", selector: a.selector } };
+      default:
+        return null;
+    }
+  }
   /**
    * Handle browser_select_option with automatic fallback for custom dropdowns.
    * 1. Try native selectOption first.
@@ -387,7 +690,10 @@ Could not parse locator: ${locatorExpr}` }], isError: true };
         const assertName = params.type === "value" ? "assertValue" : "assertText";
         this._trackedActions.push({
           toolName: "browser_assert",
-          args: { type: params.type, ref: params.ref, expected: params.expected },
+          // Pass selector/expected as structured args so assertActionToJsonl can
+          // decode unambiguously (the colon-encoded code below corrupts values
+          // that contain ':', e.g. URLs). The code string is a fallback only.
+          args: { type: params.type, ref: params.ref, selector: parsed.selector, expected: params.expected, ...params.type === "text" ? { substring: params.substring } : {} },
           code: `${assertName}:${parsed.selector}:${params.expected}${params.type === "text" ? ":" + params.substring : ""}`,
           timestamp
         });
@@ -563,7 +869,7 @@ ${details}` }]
    * preClickHoverCode: hover result taken BEFORE the click (needed for navigation clicks
    * where the element ref is no longer valid after navigation).
    */
-  async _improveActionSelector(toolName, args, result, preClickHoverCode = null) {
+  async _improveActionSelector(toolName, args, result, preClickHoverCode = null, preClickSnapshot = null, preClickLocatorCount = 0, preClickParentChain = null) {
     if (result.isError)
       return result;
     const selectorTools = /* @__PURE__ */ new Set(["browser_click", "browser_hover", "browser_type", "browser_fill"]);
@@ -606,43 +912,64 @@ ${details}` }]
       }
       return result;
     }
-    const roleMatch = code.match(/getByRole\(\s*['"](\w+)['"]\s*\)(?!\s*\.(?:filter|nth|first|last))/);
-    if (!roleMatch)
+    if (code.includes(".filter(") || code.includes(".nth(") || code.includes(".first(") || code.includes(".last("))
+      return result;
+    if (/page\.(getByTestId|locator|getByRole)\([^)]*\)\.getByRole/.test(code))
+      return result;
+    const bareRoleMatch = code.match(/getByRole\(\s*['"](\w+)['"]\s*\)/);
+    const namedRoleMatch = code.match(/getByRole\(\s*['"](\w+)['"]\s*,\s*\{[^}]*name:\s*(?:'([^']*)'|"([^"]*)")/);
+    if (!bareRoleMatch && !namedRoleMatch)
       return result;
-    const role = roleMatch[1];
+    const role = bareRoleMatch?.[1] ?? namedRoleMatch[1];
+    const roleName = namedRoleMatch ? namedRoleMatch[2] ?? namedRoleMatch[3] : void 0;
     const ref = args.ref;
     if (!ref)
       return result;
-    const snapText = parsed?.snapshot ?? "";
-    if (!snapText)
-      return result;
-    const snapLines = snapText.split("\n");
+    const snapText = preClickSnapshot || parsed?.snapshot || "";
+    const snapLines = (snapText || "").split("\n");
     const rolePattern = new RegExp(`^\\s*-\\s*${role}\\s+`, "m");
-    const roleCount = snapLines.filter((l) => rolePattern.test(l)).length;
-    if (roleCount <= 1) {
-      traceDebug(`Role "${role}" is unique, no improvement needed`);
-      return result;
+    let snapshotMatchCount = 0;
+    if (snapText) {
+      if (roleName) {
+        const escapedName = roleName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const namedPattern = new RegExp(`^\\s*-\\s*${role}\\s+"[^"]*${escapedName}`, "i");
+        snapshotMatchCount = snapLines.filter((l) => namedPattern.test(l)).length;
+      } else {
+        snapshotMatchCount = snapLines.filter((l) => rolePattern.test(l)).length;
+      }
     }
-    traceDebug(`Role "${role}" appears ${roleCount} times \u2014 attempting to disambiguate`);
+    const ambiguousCount = Math.max(preClickLocatorCount, snapshotMatchCount);
+    traceDebug(`[disambig] role="${role}" name="${roleName ?? ""}" preClickCount=${preClickLocatorCount} snapshotCount=${snapshotMatchCount} \u2192 ambiguousCount=${ambiguousCount}`);
+    traceDebug(`Role "${role}"${roleName ? ` name="${roleName}"` : ""} matches ${ambiguousCount} elements \u2014 attempting to disambiguate`);
     const refPattern = `[ref=${ref}]`;
     const refIdx = snapLines.findIndex((l) => l.includes(refPattern));
     if (refIdx < 0)
       return result;
     const refLine = snapLines[refIdx];
-    const textMatch = refLine.match(/^\s*-\s*\w+\s+"([^"]*)"/);
-    if (textMatch && textMatch[1]) {
-      const visibleText = textMatch[1];
-      const textPattern = new RegExp(`^\\s*-\\s*${role}\\s+"[^"]*${visibleText.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "i");
-      const textCount = snapLines.filter((l) => textPattern.test(l)).length;
-      if (textCount === 1) {
-        const improvedCode = code.replace(
-          /getByRole\((\s*['"](\w+)['"]\s*)\)/,
-          `getByRole($1).filter({ hasText: "${visibleText}" })`
-        );
-        traceDebug(`Improved selector with text filter: ${visibleText}`);
-        return this._modifyResultCode(result, improvedCode);
+    if (!roleName && ambiguousCount > 1) {
+      const textMatch = refLine.match(/^\s*-\s*\w+\s+"([^"]*)"/);
+      if (textMatch && textMatch[1]) {
+        const visibleText = textMatch[1];
+        const textPattern = new RegExp(`^\\s*-\\s*${role}\\s+"[^"]*${visibleText.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`, "i");
+        const textCount = snapLines.filter((l) => textPattern.test(l)).length;
+        if (textCount === 1) {
+          const improvedCode = code.replace(
+            /getByRole\((\s*['"](\w+)['"]\s*)\)/,
+            `getByRole($1).filter({ hasText: "${visibleText}" })`
+          );
+          traceDebug(`Improved selector with text filter: ${visibleText}`);
+          return this._modifyResultCode(result, improvedCode);
+        }
       }
     }
+    if (preClickParentChain) {
+      const improvedCode = code.replace(
+        /await\s+page\./,
+        `await page.${preClickParentChain}.`
+      );
+      traceDebug(`Improved selector by chaining from parent: ${preClickParentChain}`);
+      return this._modifyResultCode(result, improvedCode);
+    }
     const refIndent = refLine.match(/^(\s*)/)?.[1]?.length ?? 0;
     for (let i = refIdx - 1; i >= 0; i--) {
       const line = snapLines[i];
@@ -667,7 +994,7 @@ ${details}` }]
               /await\s+page\./,
               `await page.getByTestId("${testid}").`
             );
-            traceDebug(`Improved selector by chaining from test-id: ${testid}`);
+            traceDebug(`Improved selector by chaining from test-id (snapshot walk): ${testid}`);
             return this._modifyResultCode(result, improvedCode);
           }
         }
@@ -676,22 +1003,24 @@ ${details}` }]
       if (indent === 0)
         break;
     }
-    const roleRefs = [];
-    for (const line of snapLines) {
-      if (rolePattern.test(line)) {
-        const m = line.match(/\[ref=(\w+)\]/);
-        if (m)
-          roleRefs.push(m[1]);
+    if (ambiguousCount > 1) {
+      const roleRefs = [];
+      for (const line of snapLines) {
+        if (rolePattern.test(line)) {
+          const m = line.match(/\[ref=(\w+)\]/);
+          if (m)
+            roleRefs.push(m[1]);
+        }
+      }
+      const index = roleRefs.indexOf(ref);
+      if (index >= 0) {
+        const improvedCode = code.replace(
+          /getByRole\((\s*['"][^'"]+['"](?:\s*,\s*\{[^}]*\})?)\s*\)/,
+          `getByRole($1).nth(${index})`
+        );
+        traceDebug(`Improved selector with .nth(${index})`);
+        return this._modifyResultCode(result, improvedCode);
       }
-    }
-    const index = roleRefs.indexOf(ref);
-    if (index >= 0) {
-      const improvedCode = code.replace(
-        /getByRole\((\s*['"](\w+)['"]\s*)\)/,
-        `getByRole($1).nth(${index})`
-      );
-      traceDebug(`Improved selector with .nth(${index})`);
-      return this._modifyResultCode(result, improvedCode);
     }
     return result;
   }
@@ -779,6 +1108,51 @@ ${details}` }]
       });
     });
   }
+  /**
+   * SKYR-3728: detect a wrapper-button around args.ref and, if found, strip
+   * role="button"/role="link" from every wrapper in the document so that
+   * upstream's closestCrossShadow can't retarget UP during selector
+   * regeneration. Returns a restore function the caller MUST invoke (via
+   * try/finally) once the click has been recorded.
+   *
+   * Works for browser_click, browser_type, browser_fill, browser_hover —
+   * anything that goes through tab.refLocator → upstream generateSelector.
+   */
+  async _maybeStripWrapperRoles(toolName, args) {
+    const interactiveTools = /* @__PURE__ */ new Set(["browser_click", "browser_type", "browser_fill", "browser_hover"]);
+    if (!interactiveTools.has(toolName))
+      return null;
+    const ref = args?.ref;
+    if (!ref)
+      return null;
+    const tab = this._browserBackend.context?.currentTab();
+    const page = tab?.page;
+    if (!page)
+      return null;
+    let stripped = false;
+    try {
+      const handle = await page.locator(`aria-ref=${ref}`).elementHandle({ timeout: 1e3 });
+      if (!handle)
+        return null;
+      try {
+        stripped = await page.evaluate(pageEvaluateStripWrapperRoles, handle);
+      } finally {
+        await handle.dispose();
+      }
+    } catch {
+      return null;
+    }
+    if (!stripped)
+      return null;
+    traceDebug(`Wrapper-leak detected for ref=${ref}; stripped role=button/link document-wide for the action`);
+    return async () => {
+      try {
+        await page.evaluate(pageEvaluateRestoreWrapperRoles);
+        traceDebug("Restored stripped roles");
+      } catch {
+      }
+    };
+  }
   _maybeTrackAction(toolName, args, result, timestamp, pageAliasBeforeAction) {
     if (result.isError)
       return;
@@ -809,6 +1183,54 @@ ${details}` }]
       return url.replace(/\/$/, "");
     }
   }
+  /**
+   * Enable Flutter web accessibility mode by clicking the hidden
+   * flt-semantics-placeholder button. Flutter web apps render to canvas by
+   * default, making DOM automation impossible. This creates a parallel ARIA
+   * tree that Playwright can interact with.
+   */
+  async _enableFlutterAccessibility() {
+    const page = this._browserBackend.context?.currentTab()?.page;
+    if (!page) return;
+    const url = page.url();
+    if (url.startsWith("chrome-extension://") || url.startsWith("about:") || url.startsWith("file://"))
+      return;
+    const alreadyEnabled = await page.evaluate(() => {
+      const host = document.querySelector("flt-semantics-host");
+      return host && host.children.length > 0;
+    }).catch(() => false);
+    if (alreadyEnabled) {
+      traceDebug("Flutter accessibility already enabled");
+      return;
+    }
+    let isFlutter = await page.evaluate(
+      () => !!document.querySelector("flt-glass-pane, flutter-view, flt-semantics-placeholder")
+    ).catch(() => false);
+    if (!isFlutter) {
+      const hasCanvas = await page.evaluate(() => !!document.querySelector("canvas")).catch(() => false);
+      if (hasCanvas) {
+        isFlutter = await page.waitForFunction(
+          () => !!document.querySelector("flt-glass-pane, flutter-view, flt-semantics-placeholder"),
+          { timeout: 5e3 }
+        ).then(() => true).catch(() => false);
+      }
+    }
+    if (!isFlutter) return;
+    const placeholder = page.locator("flt-semantics-placeholder").first();
+    const clicked = await placeholder.click({ force: true }).then(() => true).catch(() => false);
+    if (!clicked) {
+      traceDebug("Flutter detected but placeholder click failed");
+      return;
+    }
+    const enabled = await page.waitForFunction(() => {
+      const host = document.querySelector("flt-semantics-host");
+      return host && host.children.length > 0;
+    }, { timeout: 5e3 }).then(() => true).catch(() => false);
+    if (enabled)
+      traceDebug("Flutter accessibility mode enabled");
+    else
+      traceDebug("Flutter placeholder clicked but semantics host did not appear");
+  }
   /** Clean up temp directory and optionally recreate it for next session. */
   _cleanupTempDir(recreate = false) {
     try {
@@ -838,6 +1260,51 @@ ${details}` }]
     this._cleanupTempDir(false);
   }
 }
+function pageEvaluateStripWrapperRoles(target) {
+  const TOKEN = "__skyr_3728_stripped__";
+  const w = window;
+  if (w[TOKEN])
+    return false;
+  if (!target || !(target instanceof Element))
+    return false;
+  const labelSelector = 'input, textarea, select, label, [role="checkbox"], [role="radio"], [role="switch"], [role="textbox"], [role="combobox"]';
+  let wrapper = null;
+  for (let el = target; el; el = el.parentElement) {
+    const role = el.getAttribute && el.getAttribute("role");
+    if (role !== "button" && role !== "link")
+      continue;
+    if (el.children.length === 0)
+      continue;
+    if (!el.querySelector(labelSelector))
+      continue;
+    wrapper = el;
+    break;
+  }
+  if (!wrapper)
+    return false;
+  const stripped = [];
+  document.querySelectorAll('[role="button"], [role="link"]').forEach((el) => {
+    if (el.children.length === 0)
+      return;
+    const role = el.getAttribute("role");
+    stripped.push({ el, role });
+    el.removeAttribute("role");
+  });
+  w[TOKEN] = stripped;
+  return true;
+}
+function pageEvaluateRestoreWrapperRoles() {
+  const TOKEN = "__skyr_3728_stripped__";
+  const w = window;
+  const stripped = w[TOKEN];
+  if (!stripped)
+    return;
+  for (const { el, role } of stripped) {
+    if (el.isConnected)
+      el.setAttribute("role", role);
+  }
+  delete w[TOKEN];
+}
 function splitExtensionPaths(value) {
   if (!value)
     return void 0;