@skyramp/mcp 0.4.2 → 0.4.3-rc.2

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

@@ -55,6 +55,7 @@ var import_visualSnapshotTool = require("./visualSnapshotTool");
 var import_gojsTool = require("./gojsTool");
 var import_cssValue = require("./common/cssValue");
 var import_visualSnapshot = require("./common/visualSnapshot");
+var import_snapshotLocators = require("./snapshotLocators");
 var import_tableAssertTool = require("./tableAssertTool");
 var import_tableSelectorBuilder = require("./tableSelectorBuilder");
 var import_types = require("./types");
@@ -82,11 +83,14 @@ function dropDynamicParentChain(chain) {
   return m && (0, import_dynamicId.isDynamicId)(m[1]) ? null : chain;
 }
 const LIVE_READ_TIMEOUT_MS = 5e3;
+const REF_RESOLVE_TIMEOUT_MS = 1e3;
 const MAX_ANCESTOR_HOVERS = 8;
 const ANCESTOR_WALK_BUDGET_MS = 1e4;
 class TraceRecordingBackend {
   // per-type baseline filename counter
   constructor(options) {
+    // The attribute getByTestId() resolves against (configured or the default).
+    this._testIdAttribute = "data-testid";
     this._trackedActions = [];
     this._droppedActions = [];
     this._initialized = false;
@@ -120,6 +124,7 @@ class TraceRecordingBackend {
     ] : void 0;
     const headless = loadExtension?.length ? false : this._options.headless ?? (!!process.env.CI || import_os.default.platform() === "linux" && !process.env.DISPLAY);
     const testIdAttribute = process.env.PLAYWRIGHT_MCP_TEST_ID_ATTRIBUTE?.trim() || this._options.testIdAttribute?.trim();
+    this._testIdAttribute = testIdAttribute || "data-testid";
     const config = await (0, import_config.resolveConfig)({
       ...testIdAttribute ? { testIdAttribute } : {},
       browser: {
@@ -490,10 +495,9 @@ Reloaded current page: ${currentUrl}
       if (!params.ref)
         return { content: [{ type: "text", text: '### Error\nsnapshotType "element" requires a ref (from the latest browser_snapshot).' }], isError: true };
       const resolved = await this._resolveRefToLocator(params.ref, params.element ?? "");
-      if (!resolved)
-        return { content: [{ type: "text", text: `### Error
-Could not resolve a durable selector for ref=${params.ref}. Take a fresh browser_snapshot and retry, or use snapshotType "region".` }], isError: true };
-      input.selector = resolved.selector;
+      if ("error" in resolved)
+        return resolved.error;
+      input.selector = resolved.parsed.selector;
     }
     if (params.snapshotType === "gojsDiagram") {
       const diagramSelector = params.diagramSelector ?? "#divCenter";
@@ -531,33 +535,68 @@ Baseline "${input.filename}" (${params.snapshotType})${targetDesc} recorded; the
     return (0, import_visualSnapshot.nextSnapshotFilename)(type, this._visualSnapshotCounters[type] + 1);
   }
   /**
-   * Resolve a snapshot ref to a durable Playwright selector, mirroring the
-   * element-resolution path of _handleAssert: hover to get the resolved code,
-   * parse it to a selector, and prefer a snapshot-accessible-name selector over
-   * a brittle raw-CSS id (the Flutter-durable fallback). Returns null if the ref
-   * can't be resolved.
+   * The shared front of browser_assert and element visual snapshots: hover the
+   * ref for the generator's selector, parse it, take the snapshot, and prefer
+   * the snapshot's accessible name when the hover gave CSS (the Flutter-durable
+   * fallback). Hover records nothing and changes no data, but it does move the
+   * pointer: :hover styles and mouseenter handlers fire (the live css/class/
+   * attribute reads move it off again). `error` is the message body; each caller
+   * adds its own heading.
    */
-  async _resolveRefToLocator(ref, element) {
+  async _resolveRef(ref, element) {
     const hoverResult = await this._browserBackend.callTool("browser_hover", { element, ref });
-    if (hoverResult.isError)
-      return null;
-    const hoverCode = (0, import_response.parseResponse)(hoverResult)?.code ?? "";
-    const locatorMatch = hoverCode.match(/await\s+page\.(.*?)\.hover\(\)/s);
-    if (!locatorMatch)
-      return null;
-    const locatorExpr = locatorMatch[1].trim();
-    let parsed = this._codeToLocator(locatorExpr);
-    if (!parsed || parsed.locator.kind === "css") {
-      const snapResult = await this._browserBackend.callTool("browser_snapshot", {});
-      if (!snapResult.isError) {
-        const snapText = snapResult.content?.map((c) => c.type === "text" ? c.text : "").join("") || "";
-        const refLine = snapText.split("\n").find((l) => l.includes(`[ref=${ref}]`)) || "";
-        const fromSnapshot = this._extractLocatorForRef(refLine);
-        if (fromSnapshot)
-          parsed = fromSnapshot;
-      }
+    let locatorExpr;
+    if (hoverResult.isError) {
+      const errText = hoverResult.content?.[0]?.type === "text" ? hoverResult.content[0].text : "";
+      const tab = /intercepts pointer events/.test(errText) ? this._browserBackend.context?.currentTab() : void 0;
+      let tabError = "";
+      const viaTab = tab ? await tab.refLocator({ ref, element }).then((r) => r.resolved, (e) => {
+        tabError = String(e?.message ?? e).split("\n")[0];
+        traceDebug(`Ref ${ref} could not be resolved without hovering either: ${tabError}`);
+        return void 0;
+      }) : void 0;
+      if (!viaTab)
+        return { error: `Could not resolve element ref=${ref}. ${errText}${tabError ? ` Resolving it without hovering failed too: ${tabError}` : ""}` };
+      traceDebug(`Hover on ref ${ref} is intercepted; resolved its locator without hovering: ${viaTab}`);
+      locatorExpr = viaTab;
+    } else {
+      const hoverCode = (0, import_response.parseResponse)(hoverResult)?.code ?? "";
+      const locatorMatch = hoverCode.match(/await\s+page\.(.*?)\.hover\(\)/s);
+      if (!locatorMatch)
+        return { error: "Could not extract selector from hover result." };
+      locatorExpr = locatorMatch[1].trim();
     }
-    return parsed;
+    const fromHover = this._codeToLocator(locatorExpr);
+    const snapResult = await this._browserBackend.callTool("browser_snapshot", {});
+    if (snapResult.isError) {
+      const errText = snapResult.content?.[0]?.type === "text" ? snapResult.content[0].text : "";
+      return { error: `Could not capture page snapshot to verify ref=${ref}. ${errText}` };
+    }
+    const snapLines = (snapResult.content?.map((c) => c.type === "text" ? c.text : "").join("") || "").split("\n");
+    const refIdx = snapLines.findIndex((l) => l.includes(`[ref=${ref}]`));
+    const refLine = refIdx >= 0 ? snapLines[refIdx] : "";
+    const parsed = this._preferSnapshotLocator(fromHover, refLine);
+    if (parsed !== fromHover)
+      traceDebug(`Resolved selector from snapshot accessible name (hover code was ${fromHover ? "CSS" : "unparseable"}: ${locatorExpr})`);
+    if (!parsed)
+      return { error: `Could not parse locator: ${locatorExpr}` };
+    return { parsed, snapLines, refIdx, refLine };
+  }
+  /**
+   * The selector an element visual snapshot records for a ref: _resolveRef,
+   * then made to pick out the ref's own element as an assertion's is (the
+   * screenshot locator is strict at replay too) — a name repeated across a list
+   * is pinned, and one the live page says is another element is refused.
+   */
+  async _resolveRefToLocator(ref, element) {
+    const resolved = await this._resolveRef(ref, element);
+    if ("error" in resolved)
+      return { error: { content: [{ type: "text", text: `### Error
+${resolved.error} Take a fresh browser_snapshot and retry, or use snapshotType "region".` }], isError: true } };
+    const unique = await this._makeUnique(resolved.parsed, { snapLines: resolved.snapLines, ref, element, lineText: (0, import_snapshotLocators.snapshotLineText)(resolved.refLine) ?? "", exact: false });
+    if (unique.refusal)
+      return { error: unique.refusal };
+    return { parsed: unique.parsed };
   }
   /**
    * Load a prior Skyramp trace and replay it against the live browser, honoring
@@ -1322,47 +1361,23 @@ For "${params.type}" assertions, "property" (the ${params.type === "css" ? "CSS
     if ((params.type === "checked" || params.type === "disabled") && params.expected !== void 0 && params.expected !== "true" && params.expected !== "false")
       return { content: [{ type: "text", text: `### Error
 For "${params.type}" assertions, "expected" must be "true" or "false".` }], isError: true };
-    const hoverResult = await this._browserBackend.callTool("browser_hover", {
-      element: params.element,
-      ref: params.ref
-    });
-    if (hoverResult.isError) {
-      const errText = hoverResult.content?.[0]?.type === "text" ? hoverResult.content[0].text : "";
-      return { content: [{ type: "text", text: `### Assertion Failed
-Could not resolve element ref=${params.ref}. ${errText}` }], isError: true };
-    }
-    const hoverCode = (0, import_response.parseResponse)(hoverResult)?.code ?? "";
-    const locatorMatch = hoverCode.match(/await\s+page\.(.*?)\.hover\(\)/s);
-    if (!locatorMatch) {
-      return { content: [{ type: "text", text: `### Assertion Failed
-Could not extract selector from hover result.` }], isError: true };
-    }
-    const locatorExpr = locatorMatch[1].trim();
-    let parsed = this._codeToLocator(locatorExpr);
-    const snapResult = await this._browserBackend.callTool("browser_snapshot", {});
-    if (snapResult.isError) {
-      const errText = snapResult.content?.[0]?.type === "text" ? snapResult.content[0].text : "";
-      return { content: [{ type: "text", text: `### Assertion Failed
-Could not capture page snapshot to verify the assertion. ${errText}` }], isError: true };
-    }
-    const snapText = snapResult.content?.map((c) => c.type === "text" ? c.text : "").join("") || "";
-    const snapLines = snapText.split("\n");
-    const refLine = snapLines.find((l) => l.includes(`[ref=${params.ref}]`)) || "";
-    if (!parsed || parsed.locator.kind === "css") {
-      const fromSnapshot = this._extractLocatorForRef(refLine);
-      if (fromSnapshot) {
-        traceDebug(`Resolved assert selector from snapshot accessible name (hover code was ${parsed ? "brittle CSS" : "unparseable"}: ${locatorExpr})`);
-        parsed = fromSnapshot;
-      }
-    }
-    if (!parsed) {
+    const resolved = await this._resolveRef(params.ref, params.element);
+    if ("error" in resolved)
       return { content: [{ type: "text", text: `### Assertion Failed
-Could not parse locator: ${locatorExpr}` }], isError: true };
-    }
-    const textMatch = refLine.match(/^\s*-\s*\w+\s+"([^"]*)"/);
-    const elementText = textMatch?.[1] || "";
-    const valueMatch = refLine.match(/\]:\s*(.+)$/);
-    const elementValue = valueMatch?.[1]?.trim() || "";
+${resolved.error}` }], isError: true };
+    let parsed = resolved.parsed;
+    const { snapLines, refIdx, refLine } = resolved;
+    const inputLine = (0, import_snapshotLocators.isInputLine)(refLine);
+    const quotedName = refLine.match(/^\s*-\s*\w+\s+"([^"]*)"/)?.[1] ?? "";
+    const lineText = (0, import_snapshotLocators.snapshotLineText)(refLine) ?? "";
+    let elementText = inputLine ? quotedName : lineText;
+    if (params.type === "text" && !inputLine) {
+      const live = await this._liveText(params.ref);
+      if (live !== void 0)
+        elementText = live;
+    }
+    const readsValue = params.type === "value" || params.type === "text" && inputLine;
+    const elementValue = readsValue ? await this._inputValue(snapLines, refIdx, params.ref) : "";
     let passed = false;
     let details = "";
     let countSelector = "";
@@ -1375,13 +1390,10 @@ Could not parse locator: ${locatorExpr}` }], isError: true };
       const notReady = await this._requireLoadedPage(tab, "domcontentloaded");
       if (notReady)
         return notReady;
-      if (parsed.locator.kind === "text") {
-        const improved = await this._improveTextSelector(snapLines, params.ref, parsed);
-        if (improved) {
-          traceDebug(`Improved ambiguous text selector before live read: ${improved.selector}`);
-          parsed = improved;
-        }
-      }
+      const unique = await this._makeUnique(parsed, { snapLines, ref: params.ref, element: params.element, lineText, exact: false });
+      if (unique.refusal)
+        return unique.refusal;
+      parsed = unique.parsed;
       const live = tab.page.locator(parsed.selector);
       const kind = params.type;
       const name = kind === "class" ? "" : params.property.trim();
@@ -1440,6 +1452,18 @@ Could not read the un-hovered state of "${params.element}": the pointer could no
           const classes = (reading.value ?? "").split(" ").filter(Boolean);
           passed = classes.includes(className);
           details = passed ? `Class assertion passed: "${params.element}" carries class "${className}".` : `Class assertion FAILED: "${params.element}" has classes [${classes.join(" ")}], expected "${className}".`;
+          if (!passed) {
+            const depth = await live.evaluate((el, cls) => {
+              let up = el.parentElement;
+              for (let d = 1; up && d <= 3; d++, up = up.parentElement) {
+                if (up.classList.contains(cls))
+                  return d;
+              }
+              return 0;
+            }, className, { timeout: LIVE_READ_TIMEOUT_MS }).catch(() => 0);
+            if (depth)
+              details += ` "${className}" is on its ${depth === 1 ? "parent" : `ancestor ${depth} levels up`}: assert it on that element \u2014 with browser_assert on its ref if the snapshot has one, otherwise in the generated test.`;
+          }
         } else {
           const actual = reading.value;
           passed = actual !== null && actual === params.expected;
@@ -1450,16 +1474,18 @@ Could not read the un-hovered state of "${params.element}": the pointer could no
         const msg = String(e?.message ?? e);
         if (/strict mode violation/i.test(msg))
           return { content: [{ type: "text", text: `### Error
-Target ${parsed.selector} matches multiple elements, so the ${kind} read is ambiguous. Use a more specific target (a data-testid, or role + exact name). ${msg.split("\n")[0]}` }], isError: true };
+Target ${parsed.selector} matches multiple elements, so the ${kind} read is ambiguous${unique.pinFailure ? `, and ${unique.pinFailure}` : ""}. Use a more specific target (a data-testid, or role + exact name). ${msg.split("\n")[0]}` }], isError: true };
         if (e?.name === "TimeoutError")
           return { content: [{ type: "text", text: `### Error
 "${params.element}" (${parsed.selector}) did not resolve within ${LIVE_READ_TIMEOUT_MS} ms. Re-snapshot and retry with a fresh ref.` }], isError: true };
         return { content: [{ type: "text", text: `### Error
 Could not read ${kind} of "${params.element}": ${msg}` }], isError: true };
       }
+      if (passed)
+        details += unique.note;
     } else if (params.type === "text") {
-      passed = elementText.includes(params.expected) || elementValue.includes(params.expected);
-      details = passed ? `Text assertion passed: "${params.element}" contains "${params.expected}".` : `Text assertion FAILED: "${params.element}" has text "${elementText}"${elementValue ? ` / value "${elementValue}"` : ""}, expected "${params.expected}".`;
+      passed = elementText.includes(params.expected);
+      details = passed ? `Text assertion passed: "${params.element}" contains "${params.expected}".` : `Text assertion FAILED: "${params.element}" has text "${elementText}", expected "${params.expected}".` + (inputLine && elementValue.includes(params.expected) ? ` It is an input whose value contains it: assert what it holds with type: "value".` : "");
     } else if (params.type === "value") {
       passed = elementValue === params.expected || elementValue.includes(params.expected);
       details = passed ? `Value assertion passed: "${params.element}" has value "${params.expected}".` : `Value assertion FAILED: "${params.element}" has value "${elementValue}", expected "${params.expected}".`;
@@ -1512,77 +1538,86 @@ Could not count "${refRole}" elements: ${e.message}` }], isError: true };
     }
     if (passed) {
       const recordedExpected = params.type === "text" && params.substring !== false ? (0, import_utils.stableTextLead)(params.expected) : params.expected;
-      const selectorText = parsed.locator.kind === "text" ? parsed.locator.body : parsed.locator.next?.kind === "text" ? parsed.locator.next.body : parsed.locator.options?.name ?? null;
-      const tautological = Boolean((params.type === "text" || params.type === "value") && selectorText && selectorText === recordedExpected);
-      if (tautological) {
-        traceDebug(`Skipped tautological assertion: selector already matches "${recordedExpected}"`);
-      } else {
-        if (parsed.locator.kind === "text" && params.type !== "count" && params.type !== "css" && params.type !== "class" && params.type !== "attribute") {
-          const improved = await this._improveTextSelector(snapLines, params.ref, parsed);
-          if (improved) {
-            traceDebug(`Improved ambiguous text selector to: ${improved.selector}`);
-            parsed = improved;
+      const tail = (0, import_snapshotLocators.leaf)(parsed.locator);
+      const selectorText = tail.kind === "text" ? tail.body : tail.kind === "role" ? tail.options?.name ?? null : null;
+      const tautological = Boolean(params.type === "text" && selectorText && selectorText === recordedExpected);
+      const recordType = tautological ? "visible" : params.type;
+      if (recordType !== params.type) {
+        traceDebug(`Tautological text assertion recorded as presence: selector already matches "${recordedExpected}"`);
+        details += ` Recorded as a presence check (toBeVisible): the locator already selects by "${recordedExpected}".`;
+      }
+      if (params.type !== "count" && params.type !== "css" && params.type !== "class" && params.type !== "attribute") {
+        const unique = await this._makeUnique(parsed, { snapLines, ref: params.ref, element: params.element, lineText, exact: recordType === "visible" });
+        if (unique.refusal)
+          return unique.refusal;
+        parsed = unique.parsed;
+        details += unique.note;
+        if (recordType === "visible" && unique.verdict === "unverified") {
+          const matches = (0, import_snapshotLocators.snapshotMatches)(snapLines, parsed.locator);
+          if (matches !== void 0 && matches > 1) {
+            return { content: [{ type: "text", text: `### Error
+"${params.element}" is present, but ${parsed.selector} matches ${matches} elements on the page, so a presence check on it would be ambiguous at replay${unique.pinFailure ? `, and ${unique.pinFailure}` : ""}. Nothing was recorded. Assert it through a test id or a role with its exact name, or write the check in the generated test.` }], isError: true };
           }
         }
-        let assertName;
-        let args;
-        let code;
-        switch (params.type) {
-          case "checked": {
-            const expectChecked = params.expected !== "false";
-            assertName = "assertChecked";
-            args = { type: "checked", ref: params.ref, selector: parsed.selector, checked: expectChecked };
-            code = `assertChecked:${parsed.selector}:${expectChecked}`;
-            break;
-          }
-          case "disabled": {
-            const expectDisabled = params.expected !== "false";
-            assertName = "assertDisabled";
-            args = { type: "disabled", ref: params.ref, selector: parsed.selector, disabled: expectDisabled };
-            code = `assertDisabled:${parsed.selector}:${expectDisabled}`;
-            break;
-          }
-          case "visible":
-            assertName = "assertVisible";
-            args = { type: "visible", ref: params.ref, selector: parsed.selector };
-            code = `assertVisible:${parsed.selector}`;
-            break;
-          case "count":
-            assertName = "assertCount";
-            args = { type: "count", ref: params.ref, selector: countSelector, count: Number(params.expected) };
-            code = `assertCount:${countSelector}:${params.expected}`;
-            break;
-          case "value":
-            assertName = "assertValue";
-            args = { type: "value", ref: params.ref, selector: parsed.selector, expected: recordedExpected };
-            code = `assertValue:${parsed.selector}:${recordedExpected}`;
-            break;
-          case "css":
-            assertName = "assertCSS";
-            args = { type: "css", ref: params.ref, selector: parsed.selector, property: params.property.trim(), expected: liveValue ?? params.expected };
-            code = `assertCSS:${parsed.selector}:${params.property.trim()}:${liveValue ?? params.expected}`;
-            break;
-          case "class":
-            assertName = "assertClass";
-            args = { type: "class", ref: params.ref, selector: parsed.selector, expected: params.expected.trim() };
-            code = `assertClass:${parsed.selector}:${params.expected.trim()}`;
-            break;
-          case "attribute":
-            assertName = "assertAttribute";
-            args = { type: "attribute", ref: params.ref, selector: parsed.selector, property: params.property.trim(), expected: liveValue ?? params.expected };
-            code = `assertAttribute:${parsed.selector}:${params.property.trim()}:${liveValue ?? params.expected}`;
-            break;
-          default:
-            assertName = "assertText";
-            args = { type: "text", ref: params.ref, selector: parsed.selector, expected: recordedExpected, substring: params.substring };
-            code = `assertText:${parsed.selector}:${recordedExpected}:${params.substring}`;
-            break;
+      }
+      let assertName;
+      let args;
+      let code;
+      switch (recordType) {
+        case "checked": {
+          const expectChecked = params.expected !== "false";
+          assertName = "assertChecked";
+          args = { type: "checked", ref: params.ref, selector: parsed.selector, locator: parsed.locator, checked: expectChecked };
+          code = `assertChecked:${parsed.selector}:${expectChecked}`;
+          break;
+        }
+        case "disabled": {
+          const expectDisabled = params.expected !== "false";
+          assertName = "assertDisabled";
+          args = { type: "disabled", ref: params.ref, selector: parsed.selector, locator: parsed.locator, disabled: expectDisabled };
+          code = `assertDisabled:${parsed.selector}:${expectDisabled}`;
+          break;
         }
-        if (unhoverMove)
-          this._trackedActions.push({ toolName: "browser_mouse_action", args: { name: "mouse.move", position: unhoverMove }, code: "", timestamp: timestamp - 1, pageAlias: this._currentPageAlias });
-        this._trackedActions.push({ toolName: "browser_assert", args, code, timestamp, pageAlias: this._currentPageAlias });
-        traceDebug(`Assert: ${assertName} with selector ${args.selector}`);
+        case "visible":
+          assertName = "assertVisible";
+          args = { type: "visible", ref: params.ref, selector: parsed.selector, locator: parsed.locator };
+          code = `assertVisible:${parsed.selector}`;
+          break;
+        case "count":
+          assertName = "assertCount";
+          args = { type: "count", ref: params.ref, selector: countSelector, locator: { kind: "role", body: countSelector.slice("internal:role=".length), options: { attrs: [], exact: false } }, count: Number(params.expected) };
+          code = `assertCount:${countSelector}:${params.expected}`;
+          break;
+        case "value":
+          assertName = "assertValue";
+          args = { type: "value", ref: params.ref, selector: parsed.selector, locator: parsed.locator, expected: recordedExpected };
+          code = `assertValue:${parsed.selector}:${recordedExpected}`;
+          break;
+        case "css":
+          assertName = "assertCSS";
+          args = { type: "css", ref: params.ref, selector: parsed.selector, locator: parsed.locator, property: params.property.trim(), expected: liveValue ?? params.expected };
+          code = `assertCSS:${parsed.selector}:${params.property.trim()}:${liveValue ?? params.expected}`;
+          break;
+        case "class":
+          assertName = "assertClass";
+          args = { type: "class", ref: params.ref, selector: parsed.selector, locator: parsed.locator, expected: params.expected.trim() };
+          code = `assertClass:${parsed.selector}:${params.expected.trim()}`;
+          break;
+        case "attribute":
+          assertName = "assertAttribute";
+          args = { type: "attribute", ref: params.ref, selector: parsed.selector, locator: parsed.locator, property: params.property.trim(), expected: liveValue ?? params.expected };
+          code = `assertAttribute:${parsed.selector}:${params.property.trim()}:${liveValue ?? params.expected}`;
+          break;
+        default:
+          assertName = "assertText";
+          args = { type: "text", ref: params.ref, selector: parsed.selector, locator: parsed.locator, expected: recordedExpected, substring: params.substring };
+          code = `assertText:${parsed.selector}:${recordedExpected}:${params.substring}`;
+          break;
       }
+      if (unhoverMove)
+        this._trackedActions.push({ toolName: "browser_mouse_action", args: { name: "mouse.move", position: unhoverMove }, code: "", timestamp: timestamp - 1, pageAlias: this._currentPageAlias });
+      this._trackedActions.push({ toolName: "browser_assert", args, code, timestamp, pageAlias: this._currentPageAlias });
+      traceDebug(`Assert: ${assertName} with selector ${args.selector}`);
     }
     return {
       content: [{ type: "text", text: `### ${passed ? "Assertion Passed" : "Assertion Failed"}
@@ -1768,8 +1803,8 @@ ${text}` }], isError: true });
     let locator;
     if (params.testId?.trim()) {
       const testId = params.testId.trim();
-      selector = `internal:testid=[data-testid=${JSON.stringify(testId)}s]`;
-      locator = { kind: "test-id", body: testId, options: {} };
+      locator = { kind: "test-id", body: testId, options: this._testIdAttribute === "data-testid" ? {} : { attribute: this._testIdAttribute } };
+      selector = (0, import_snapshotLocators.renderSelector)(locator);
     } else if (params.role?.trim()) {
       const role = params.role.trim();
       if (!TraceRecordingBackend.ASSERTABLE_ROLES.has(role))
@@ -1822,47 +1857,30 @@ ${text}` }], isError: true });
 ${details}` }] };
   }
   /** Convert a Playwright locator expression to a selector + locator object for JSONL. */
+  /**
+   * The recorder locator for a hover's generated locator code, e.g.
+   * `getByRole('listitem').filter({ hasText: 'Walk the dog' }).getByLabel('Toggle Todo')`.
+   * playwright-core's own parser turns the code into its internal selector —
+   * chains, `.filter({ hasText })`, options and string escapes included — and
+   * locatorFromSelector maps each part to a kind the exporter and codegen carry.
+   * Null when the code does not parse, is an aria-ref (no durable selector), or
+   * has a part that cannot be carried (xpath, `has`, a frame hop, a regex): the
+   * caller then falls back to the snapshot's accessible name. The old
+   * per-method regexes matched anywhere in the expression, so a chain was cut
+   * to its first link (`getByRole('listitem')` for a checkbox inside a row).
+   */
   _codeToLocator(expr) {
-    const testidMatch = expr.match(/getByTestId\(\s*['"]([^'"]+)['"]\s*\)/);
-    if (testidMatch) {
-      return {
-        selector: `internal:testid=[data-testid="${testidMatch[1]}"s]`,
-        locator: { kind: "test-id", body: testidMatch[1], options: {} }
-      };
-    }
-    const roleMatch = expr.match(/getByRole\(\s*['"]([^'"]+)['"](?:\s*,\s*\{[^}]*name:\s*['"]([^'"]+)['"][^}]*\})?\s*\)/);
-    if (roleMatch) {
-      return {
-        selector: roleMatch[2] ? `internal:role=${roleMatch[1]}[name="${roleMatch[2]}"i]` : `internal:role=${roleMatch[1]}`,
-        locator: { kind: "role", body: roleMatch[1], options: { attrs: [], exact: false, ...roleMatch[2] ? { name: roleMatch[2] } : {} } }
-      };
-    }
-    const labelMatch = expr.match(/getByLabel\(\s*['"]([^'"]+)['"]\s*\)/);
-    if (labelMatch) {
-      return {
-        selector: `internal:label="${labelMatch[1]}"i`,
-        locator: { kind: "label", body: labelMatch[1], options: { exact: false } }
-      };
-    }
-    const textMatch = expr.match(/getByText\(\s*['"]([^'"]+)['"]\s*\)/);
-    if (textMatch) {
-      return {
-        selector: `internal:text="${textMatch[1]}"i`,
-        locator: { kind: "text", body: textMatch[1], options: { exact: false } }
-      };
-    }
-    const ariaRefMatch = expr.match(/locator\(\s*['"]aria-ref=(\w+)['"]\s*\)/);
-    if (ariaRefMatch) {
+    const selector = (0, import_utils.locatorOrSelectorAsSelector)("javascript", expr, this._testIdAttribute);
+    if (!selector) {
+      traceDebug(`Hover code did not parse as a locator (or did not round-trip): ${expr}`);
       return null;
     }
-    const cssMatch = expr.match(/locator\(\s*['"]([#.][^'"]+)['"]\s*\)/);
-    if (cssMatch) {
-      return {
-        selector: cssMatch[1],
-        locator: { kind: "css", body: cssMatch[1], options: {} }
-      };
-    }
-    return null;
+    if (selector.startsWith("aria-ref="))
+      return null;
+    const locator = (0, import_snapshotLocators.locatorFromSelector)(selector);
+    if (!locator)
+      traceDebug(`Hover code has a part the trace format cannot carry: ${expr} \u2192 ${selector}`);
+    return locator ? { selector: (0, import_snapshotLocators.renderSelector)(locator), locator } : null;
   }
   /**
    * When hover resolves to a text-based locator (e.g. getByText("$849.98")),
@@ -1872,10 +1890,7 @@ ${details}` }] };
    */
   async _improveTextSelector(snapLines, ref, original) {
     const textBody = original.locator.body;
-    const occurrences = snapLines.filter((l) => {
-      const lineText = TraceRecordingBackend._snapshotLineText(l);
-      return lineText !== null && lineText.includes(textBody);
-    }).length;
+    const occurrences = (0, import_snapshotLocators.snapshotMatches)(snapLines, original.locator) ?? 0;
     if (occurrences <= 1)
       return null;
     traceDebug(`Text "${textBody}" appears ${occurrences} times in snapshot \u2014 looking for parent test-id`);
@@ -1913,18 +1928,17 @@ ${details}` }] };
             const ancestorExpr = ancestorLocatorMatch[1].trim();
             const testidMatch = ancestorExpr.match(/getByTestId\(\s*['"]([^'"]+)['"]\s*\)/);
             if (testidMatch) {
-              const testid = testidMatch[1];
-              const chainedSelector = `internal:testid=[data-testid="${testid}"s] >> internal:text="${textBody}"i`;
-              traceDebug(`Improved to chained selector: ${chainedSelector}`);
-              return {
-                selector: chainedSelector,
-                locator: {
-                  kind: "test-id",
-                  body: testid,
-                  options: {},
-                  next: { kind: "text", body: textBody, options: { exact: false } }
-                }
+              const locator = {
+                kind: "test-id",
+                body: testidMatch[1],
+                // Under a configured testIdAttribute (data-cy) the rendered pin
+                // selector must use it, or the live pin finds nothing.
+                options: this._testIdAttribute === "data-testid" ? {} : { attribute: this._testIdAttribute },
+                next: { kind: "text", body: textBody, options: { exact: !!original.locator.options?.exact } }
               };
+              const chainedSelector = (0, import_snapshotLocators.renderSelector)(locator);
+              traceDebug(`Improved to chained selector: ${chainedSelector}`);
+              return { selector: chainedSelector, locator };
             }
           }
         }
@@ -1935,18 +1949,160 @@ ${details}` }] };
     }
     return null;
   }
+  /** The ref's value as Playwright's inputValue() reads it (which retargets a
+   *  `<label>` ref to its control), or undefined on any failure: not an
+   *  input/textarea/select, a ref that does not resolve within
+   *  REF_RESOLVE_TIMEOUT_MS, a closed page. The reason goes to the trace debug log. */
+  /** What an input holds, as toHaveValue compares at replay: read live from the
+   *  element, and from the snapshot (inline, or the child line under a
+   *  placeholder) when the live read is not available. */
+  async _inputValue(snapLines, refIdx, ref) {
+    const page = this._browserBackend.context?.currentTab()?.page;
+    const live = page ? await TraceRecordingBackend._liveInputValue(page, ref) : void 0;
+    return live ?? (0, import_snapshotLocators.snapshotInputValue)(snapLines, refIdx);
+  }
+  /** The ref's rendered text as toContainText compares it — Playwright's
+   *  injected elementText: a submit/button input's value, shadow-root text
+   *  included, script/style/noscript and <head> skipped; whitespace normalized —
+   *  or undefined when the page or ref is unavailable. */
+  async _liveText(ref) {
+    const page = this._browserBackend.context?.currentTab()?.page;
+    if (!page)
+      return void 0;
+    try {
+      const text = await page.locator(`aria-ref=${ref}`).evaluate((root) => {
+        const skip = (n) => n.nodeName === "SCRIPT" || n.nodeName === "NOSCRIPT" || n.nodeName === "STYLE" || !!(n.ownerDocument?.head && n.ownerDocument.head.contains(n));
+        const read = (n) => {
+          if (skip(n))
+            return "";
+          if (n instanceof HTMLInputElement && (n.type === "submit" || n.type === "button"))
+            return n.value;
+          let full = "";
+          for (let c = n.firstChild; c; c = c.nextSibling) {
+            if (c.nodeType === Node.TEXT_NODE)
+              full += c.nodeValue || "";
+            else if (c.nodeType === Node.ELEMENT_NODE)
+              full += read(c);
+          }
+          if (n.shadowRoot)
+            full += read(n.shadowRoot);
+          return full;
+        };
+        return read(root);
+      }, void 0, { timeout: REF_RESOLVE_TIMEOUT_MS });
+      return text.replace(/[\u200b\u00ad]/g, "").trim().replace(/\s+/g, " ");
+    } catch (e) {
+      traceDebug(`Live text read of ref ${ref} failed, using the snapshot: ${String(e?.message ?? e).split("\n")[0]}`);
+      return void 0;
+    }
+  }
+  static async _liveInputValue(page, ref) {
+    try {
+      return await page.locator(`aria-ref=${ref}`).inputValue({ timeout: REF_RESOLVE_TIMEOUT_MS });
+    } catch (e) {
+      traceDebug(`Live value read of ref ${ref} failed, using the snapshot: ${String(e?.message ?? e).split("\n")[0]}`);
+      return void 0;
+    }
+  }
   /**
-   * Text value of an aria-snapshot line, in either form the renderer emits:
-   * `- generic "foo" [ref=e1]` (quoted accessible name) or
-   * `- generic [ref=e1]: foo` (colon-delimited text for nodes with no name).
-   * Returns null for a line that carries no text.
+   * Make a locator pick out the ref's own element: a presence check's leaf made
+   * exact (when asked), the SKYR-4263 test-id walk for an ambiguous text
+   * locator, and — if the live page still finds more than one element — a pin
+   * to the ref's element by position (`>> nth=K`, the form the exporter and
+   * codegen already carry for clicks; SKYR-4505).
+   *
+   * `verdict`: `unique` (the live page found one match, the ref's own),
+   * `pinned`, or `unverified` (no page, or the lookup could not place the ref;
+   * `pinFailure` says why). `refusal` is set when what would be read or recorded
+   * is not this element: the locator matches nothing or only other elements
+   * (any kind), or it has a CSS link and could not be placed at all (CSS has no
+   * snapshot count to fall back on — a `row >> td` chain included). A role or
+   * text locator that could not be placed goes on unverified: a single-link
+   * `visible` record is then counted against the snapshot; other kinds, chains
+   * and the element visual snapshot path record it unpinned, as they did before
+   * the pin existed. A ref inside an iframe (`f<N>e<M>`) gets its own refusal: the
+   * lookup counts in the main frame, and the recorded selector has no frame.
    */
-  static _snapshotLineText(line) {
-    const quoted = line.match(/^\s*-\s*\w+\s+"([^"]*)"/);
-    if (quoted)
-      return quoted[1];
-    const colon = line.match(/\[ref=\w+\](?:\s*\[[^\]]*\])*\s*:\s*(.+?)\s*$/);
-    return colon?.[1]?.trim() || null;
+  async _makeUnique(parsed, opts) {
+    if (opts.exact)
+      parsed = (0, import_snapshotLocators.exactLeaf)(parsed, opts.lineText);
+    if (parsed.locator.kind === "text") {
+      const improved = await this._improveTextSelector(opts.snapLines, opts.ref, parsed);
+      if (improved) {
+        traceDebug(`Improved ambiguous text selector to: ${improved.selector}`);
+        parsed = improved;
+      }
+    }
+    const page = this._browserBackend.context?.currentTab()?.page;
+    if (!page)
+      return { parsed, note: "", verdict: "unverified" };
+    const pin = await TraceRecordingBackend._refIndexAmong(page, opts.ref, parsed.selector);
+    if ("index" in pin) {
+      if (pin.count === 1)
+        return { parsed, note: "", verdict: "unique" };
+      const unpinned = parsed.selector;
+      parsed = (0, import_snapshotLocators.withNth)(parsed, pin.index);
+      traceDebug(`${unpinned} matches ${pin.count} elements; pinned to the ref's own, nth=${pin.index}`);
+      return { parsed, note: ` Recorded as ${parsed.selector}: ${unpinned} matches ${pin.count} elements, so the assertion is pinned to this one by position.`, verdict: "pinned" };
+    }
+    traceDebug(`Could not pin ref ${opts.ref} among ${parsed.selector}: ${pin.reason}${pin.detail ? ` (${pin.detail})` : ""}`);
+    const pinFailure = pin.reason === "unresolved" ? `ref ${opts.ref} no longer resolves \u2014 take a new snapshot and use its ref` : pin.reason === "no-match" ? `it matches nothing on the live page` : pin.reason === "not-among-matches" ? `ref ${opts.ref} is not one of them \u2014 the hover locator points elsewhere; try the ref of the element that carries the property` : `placing ref ${opts.ref} among them failed (${pin.detail})`;
+    const notThisElement = pin.reason === "no-match" || pin.reason === "not-among-matches";
+    let hasCss = false;
+    for (let link = parsed.locator; link; link = link.next)
+      hasCss ||= link.kind === "default";
+    if (!notThisElement && !hasCss)
+      return { parsed, note: "", verdict: "unverified", pinFailure };
+    const text = /^f\d+e\d+$/.test(opts.ref) ? `### Error
+"${opts.element}" (ref ${opts.ref}) is inside an iframe, and ${parsed.selector} addresses the main page only, so it cannot pick the element out at replay. Nothing was recorded. Assert it in the generated test through the frame (page.frameLocator(\u2026) or locator.contentFrame()).` : `### Error
+${parsed.selector} does not pick out "${opts.element}" on the live page: ${pinFailure}. Nothing was recorded. Assert it through a test id or a role with its name, or on the ref of the element that carries it.`;
+    return { parsed, note: "", verdict: "unverified", pinFailure, refusal: { content: [{ type: "text", text }], isError: true } };
+  }
+  /** How many elements `selector` matches on the live page and where the ref's
+   *  own element sits among them — one evaluateAll — or why it cannot tell: the
+   *  ref no longer resolves (stale snapshot), the selector matches nothing, the
+   *  ref is not one of the matches (a single match included), or the lookup
+   *  failed. An index is returned only when it is the ref's own element's. */
+  static async _refIndexAmong(page, ref, selector) {
+    let handle;
+    try {
+      handle = await page.locator(`aria-ref=${ref}`).elementHandle({ timeout: REF_RESOLVE_TIMEOUT_MS });
+    } catch (e) {
+      return { reason: "unresolved", detail: String(e?.message ?? e).split("\n")[0] };
+    }
+    if (!handle)
+      return { reason: "unresolved" };
+    try {
+      const { count, index } = await page.locator(selector).evaluateAll((els, target) => ({ count: els.length, index: els.indexOf(target) }), handle);
+      if (!count)
+        return { reason: "no-match" };
+      return index >= 0 ? { index, count } : { reason: "not-among-matches" };
+    } catch (e) {
+      return { reason: "error", detail: String(e?.message ?? e).split("\n")[0] };
+    } finally {
+      await handle.dispose().catch(() => {
+      });
+    }
+  }
+  /**
+   * The locator to record for a ref: the hover's, unless it is missing or CSS
+   * and the snapshot names the element better. A bare role (no name) is no
+   * better than the hover's CSS unless that CSS is a framework-generated id,
+   * and nothing in the snapshot beats a data-* test hook on the element itself:
+   * a role name repeated across a list ("View Details" on every card) would
+   * otherwise replace the one handle that picks this card out.
+   * Shared by browser_assert and element visual snapshots so both paths agree.
+   */
+  _preferSnapshotLocator(parsed, refLine) {
+    if (parsed && (parsed.locator.kind !== "default" || (0, import_snapshotLocators.isTestHookCss)(parsed.selector)))
+      return parsed;
+    const fromSnapshot = this._extractLocatorForRef(refLine);
+    if (!fromSnapshot || !parsed)
+      return fromSnapshot ?? parsed;
+    const bareRole = fromSnapshot.locator.kind === "role" && typeof fromSnapshot.locator.options?.name !== "string";
+    if (bareRole && !(0, import_snapshotLocators.isVolatileCss)(parsed.selector))
+      return parsed;
+    return fromSnapshot;
   }
   static {
     /** Extract selector and locator info from a snapshot line for assertion tracking. */
@@ -1999,42 +2155,27 @@ ${details}` }] };
   _extractLocatorForRef(refLine) {
     const testidMatch = refLine.match(/testid="([^"]+)"/);
     if (testidMatch) {
-      return {
-        selector: `internal:testid=[data-testid="${testidMatch[1]}"s]`,
-        locator: { kind: "test-id", body: testidMatch[1], options: {} }
-      };
+      const locator = { kind: "test-id", body: testidMatch[1], options: {} };
+      return { selector: (0, import_snapshotLocators.renderSelector)(locator), locator };
     }
     const roleMatch = refLine.match(/^\s*-\s*(\w+)\s+"([^"]*)"/);
     if (roleMatch && TraceRecordingBackend.ASSERTABLE_ROLES.has(roleMatch[1])) {
-      const role = roleMatch[1];
-      const name = (0, import_utils.stableTextLead)(roleMatch[2]);
-      return {
-        selector: `internal:role=${role}[name="${name}"i]`,
-        locator: { kind: "role", body: role, options: { attrs: [], exact: false, name } }
-      };
+      const locator = { kind: "role", body: roleMatch[1], options: { attrs: [], exact: false, name: (0, import_utils.stableTextLead)(roleMatch[2]) } };
+      return { selector: (0, import_snapshotLocators.renderSelector)(locator), locator };
     }
     if (roleMatch && roleMatch[2]) {
-      const text = (0, import_utils.stableTextLead)(roleMatch[2]);
-      return {
-        selector: `internal:text="${text}"i`,
-        locator: { kind: "text", body: text, options: { exact: false } }
-      };
+      const locator = { kind: "text", body: (0, import_utils.stableTextLead)(roleMatch[2]), options: { exact: false } };
+      return { selector: (0, import_snapshotLocators.renderSelector)(locator), locator };
     }
     const colonTextMatch = refLine.match(/\[ref=\w+\](?:\s*\[[^\]]*\])*\s*:\s*(.+?)\s*$/);
-    if (colonTextMatch && colonTextMatch[1].trim()) {
-      const text = (0, import_utils.stableTextLead)(colonTextMatch[1].trim());
-      return {
-        selector: `internal:text="${text}"i`,
-        locator: { kind: "text", body: text, options: { exact: false } }
-      };
+    if (colonTextMatch && colonTextMatch[1].trim() && !(0, import_snapshotLocators.isInputLine)(refLine)) {
+      const locator = { kind: "text", body: (0, import_utils.stableTextLead)((0, import_snapshotLocators.unquoteYaml)(colonTextMatch[1].trim())), options: { exact: false } };
+      return { selector: (0, import_snapshotLocators.renderSelector)(locator), locator };
     }
     const bareRoleMatch = refLine.match(/^\s*-\s*(\w+)(?:\s+\[[^\]]*\])*\s+\[ref=\w+\]/);
     if (bareRoleMatch && TraceRecordingBackend.ASSERTABLE_ROLES.has(bareRoleMatch[1])) {
-      const role = bareRoleMatch[1];
-      return {
-        selector: `internal:role=${role}`,
-        locator: { kind: "role", body: role, options: { attrs: [], exact: false } }
-      };
+      const locator = { kind: "role", body: bareRoleMatch[1], options: { attrs: [], exact: false } };
+      return { selector: (0, import_snapshotLocators.renderSelector)(locator), locator };
     }
     return null;
   }
@@ -2440,7 +2581,7 @@ ${details}` }] };
       return null;
     let stripped = false;
     try {
-      const handle = await page.locator(`aria-ref=${ref}`).elementHandle({ timeout: 1e3 });
+      const handle = await page.locator(`aria-ref=${ref}`).elementHandle({ timeout: REF_RESOLVE_TIMEOUT_MS });
       if (!handle)
         return null;
       try {