@skyramp/mcp 0.4.2 → 0.4.3-rc.1

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

@@ -547,14 +547,12 @@ Baseline "${input.filename}" (${params.snapshotType})${targetDesc} recorded; the
       return null;
     const locatorExpr = locatorMatch[1].trim();
     let parsed = this._codeToLocator(locatorExpr);
-    if (!parsed || parsed.locator.kind === "css") {
+    if (!parsed || parsed.locator.kind === "default") {
       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;
+        parsed = this._preferSnapshotLocator(parsed, refLine);
       }
     }
     return parsed;
@@ -1348,19 +1346,18 @@ Could not capture page snapshot to verify the assertion. ${errText}` }], isError
     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;
-      }
-    }
+    const resolved = this._preferSnapshotLocator(parsed, refLine);
+    if (resolved !== parsed)
+      traceDebug(`Resolved assert selector from snapshot accessible name (hover code was ${parsed ? "CSS" : "unparseable"}: ${locatorExpr})`);
+    parsed = resolved;
     if (!parsed) {
       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 inputLine = TraceRecordingBackend._isInputLine(refLine);
+    const quotedName = refLine.match(/^\s*-\s*\w+\s+"([^"]*)"/)?.[1] ?? "";
+    const lineText = TraceRecordingBackend._snapshotLineText(refLine) ?? "";
+    const elementText = inputLine ? quotedName : lineText;
     const valueMatch = refLine.match(/\]:\s*(.+)$/);
     const elementValue = valueMatch?.[1]?.trim() || "";
     let passed = false;
@@ -1375,13 +1372,8 @@ 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, lineText, exact: false });
+      parsed = unique.parsed;
       const live = tab.page.locator(parsed.selector);
       const kind = params.type;
       const name = kind === "class" ? "" : params.property.trim();
@@ -1440,6 +1432,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 +1454,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}".`;
@@ -1513,76 +1519,82 @@ 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 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, lineText, exact: recordType === "visible" });
+        parsed = unique.parsed;
+        details += unique.note;
+        if (recordType === "visible" && !unique.pinned && parsed.locator.kind !== "test-id") {
+          const matches = TraceRecordingBackend._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"}
@@ -1825,41 +1837,34 @@ ${details}` }] };
   _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 locator = { kind: "test-id", body: testidMatch[1], options: {} };
+      return { selector: TraceRecordingBackend._renderSelector(locator), locator };
     }
     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 locator = { kind: "role", body: roleMatch[1], options: { attrs: [], exact: false, ...roleMatch[2] ? { name: roleMatch[2] } : {} } };
+      return { selector: TraceRecordingBackend._renderSelector(locator), locator };
     }
     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 locator = { kind: "label", body: labelMatch[1], options: { exact: false } };
+      return { selector: TraceRecordingBackend._renderSelector(locator), locator };
     }
     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 locator = { kind: "text", body: textMatch[1], options: { exact: false } };
+      return { selector: TraceRecordingBackend._renderSelector(locator), locator };
     }
     const ariaRefMatch = expr.match(/locator\(\s*['"]aria-ref=(\w+)['"]\s*\)/);
     if (ariaRefMatch) {
       return null;
     }
-    const cssMatch = expr.match(/locator\(\s*['"]([#.][^'"]+)['"]\s*\)/);
-    if (cssMatch) {
+    const cssMatch = expr.match(/locator\(\s*(?:'([^']+)'|"([^"]+)")\s*\)/);
+    const css = cssMatch?.[1] ?? cssMatch?.[2];
+    if (css && /^(?:[#.]|[a-z][\w-]*\[)/i.test(css)) {
       return {
-        selector: cssMatch[1],
-        locator: { kind: "css", body: cssMatch[1], options: {} }
+        selector: css,
+        locator: { kind: "default", body: css, options: {} }
       };
     }
     return null;
@@ -1872,10 +1877,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 = TraceRecordingBackend._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 +1915,15 @@ ${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],
+                options: {},
+                next: { kind: "text", body: textBody, options: { exact: !!original.locator.options?.exact } }
               };
+              const chainedSelector = TraceRecordingBackend._renderSelector(locator);
+              traceDebug(`Improved to chained selector: ${chainedSelector}`);
+              return { selector: chainedSelector, locator };
             }
           }
         }
@@ -1935,6 +1934,175 @@ ${details}` }] };
     }
     return null;
   }
+  static {
+    /** Roles whose colon text in the aria snapshot is the element's VALUE (what it
+     *  holds), not text it renders: `- textbox [ref=e1]: Google Pixel 4`. */
+    this.INPUT_ROLES = /* @__PURE__ */ new Set(["textbox", "searchbox", "combobox", "spinbutton"]);
+  }
+  static _isInputLine(refLine) {
+    const role = refLine.match(/^\s*-\s*(\w+)/)?.[1];
+    return !!role && TraceRecordingBackend.INPUT_ROLES.has(role);
+  }
+  /** A CSS selector that is a framework-generated id (per the shared isDynamicId). */
+  static _isVolatileCss(selector) {
+    return selector.startsWith("#") && (0, import_dynamicId.isDynamicId)(selector.slice(1));
+  }
+  /**
+   * The one renderer from a locator object to its internal selector string.
+   * Values are JSON-quoted (as _handleAssertHidden does), so a name containing
+   * `"` still produces a valid selector; exactness is the `s` (exact) or `i`
+   * (substring, case-insensitive) suffix.
+   */
+  static _renderSelector(locator) {
+    const q = (v, exact) => `${JSON.stringify(v)}${exact ? "s" : "i"}`;
+    let head;
+    switch (locator.kind) {
+      case "test-id":
+        head = `internal:testid=[data-testid=${JSON.stringify(locator.body)}s]`;
+        break;
+      case "role":
+        head = `internal:role=${locator.body}${typeof locator.options?.name === "string" ? `[name=${q(locator.options.name, locator.options.exact)}]` : ""}`;
+        break;
+      case "text":
+        head = `internal:text=${q(locator.body, locator.options?.exact)}`;
+        break;
+      case "label":
+        head = `internal:label=${q(locator.body, locator.options?.exact)}`;
+        break;
+      case "nth":
+        head = `nth=${locator.body}`;
+        break;
+      default:
+        head = String(locator.body);
+        break;
+    }
+    return locator.next ? `${head} >> ${TraceRecordingBackend._renderSelector(locator.next)}` : head;
+  }
+  /** The last link of a locator chain. */
+  static _leaf(locator) {
+    let tail = locator;
+    while (tail.next)
+      tail = tail.next;
+    return tail;
+  }
+  /** The chain with its leaf made exact, when the element's whole name/text is
+   *  exactly the leaf's (so a sibling whose name merely contains it cannot match).
+   *  Returns the locator unchanged otherwise, or for a leaf with no text. */
+  static _exactLeaf(parsed, fullText) {
+    const copy = (l) => ({ ...l, options: { ...l.options }, ...l.next ? { next: copy(l.next) } : {} });
+    const locator = copy(parsed.locator);
+    const leaf = TraceRecordingBackend._leaf(locator);
+    const leafText = leaf.kind === "text" ? leaf.body : leaf.kind === "role" ? leaf.options?.name : void 0;
+    if (typeof leafText !== "string" || leafText !== fullText)
+      return parsed;
+    leaf.options = { ...leaf.options, exact: true };
+    return { selector: TraceRecordingBackend._renderSelector(locator), locator };
+  }
+  /**
+   * 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). `note` describes a pin for the
+   * tool result; `pinFailure` says why an ambiguous locator could not be pinned.
+   */
+  async _makeUnique(parsed, opts) {
+    if (opts.exact)
+      parsed = TraceRecordingBackend._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: "", pinned: false };
+    const pin = await TraceRecordingBackend._refIndexAmong(page, opts.ref, parsed.selector);
+    if ("index" in pin) {
+      if (pin.count <= 1)
+        return { parsed, note: "", pinned: false };
+      const unpinned = parsed.selector;
+      parsed = TraceRecordingBackend._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.`, pinned: true };
+    }
+    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 === "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})`;
+    return { parsed, note: "", pinned: false, pinFailure };
+  }
+  /** 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), it is not one of the matches, or
+   *  the lookup failed. */
+  static async _refIndexAmong(page, ref, selector) {
+    let handle;
+    try {
+      handle = await page.locator(`aria-ref=${ref}`).elementHandle({ timeout: 1e3 });
+    } 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 <= 1)
+        return { index: Math.max(index, 0), count };
+      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 with a trailing `nth` link, re-rendered. */
+  static _withNth(parsed, index) {
+    const copy = (l) => ({ ...l, options: { ...l.options }, ...l.next ? { next: copy(l.next) } : {} });
+    const locator = copy(parsed.locator);
+    TraceRecordingBackend._leaf(locator).next = { kind: "nth", body: String(index), options: { attrs: [], exact: false } };
+    return { selector: TraceRecordingBackend._renderSelector(locator), locator };
+  }
+  /**
+   * How many snapshot lines a single role or text locator matches, with the
+   * locator's own semantics: exact is equality, otherwise case-insensitive
+   * substring (what `"X"i` does at replay). Undefined for a shape it cannot
+   * count from the snapshot (a chain, CSS, a label).
+   */
+  static _snapshotMatches(snapLines, locator) {
+    if (locator.next)
+      return void 0;
+    const text = locator.kind === "text" ? locator.body : locator.kind === "role" ? locator.options?.name : void 0;
+    if (typeof text !== "string")
+      return void 0;
+    const exact = !!locator.options?.exact;
+    const same = (v) => v !== null && (exact ? v === text : v.toLowerCase().includes(text.toLowerCase()));
+    return snapLines.filter((l) => {
+      if (locator.kind === "role") {
+        const m = l.match(/^\s*-\s*(\w+)\s+"([^"]*)"/);
+        return !!m && m[1] === locator.body && same(m[2]);
+      }
+      return same(TraceRecordingBackend._snapshotLineText(l));
+    }).length;
+  }
+  /**
+   * 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.
+   * Shared by browser_assert and element visual snapshots so both paths agree.
+   */
+  _preferSnapshotLocator(parsed, refLine) {
+    if (parsed && parsed.locator.kind !== "default")
+      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 && !TraceRecordingBackend._isVolatileCss(parsed.selector))
+      return parsed;
+    return fromSnapshot;
+  }
   /**
    * Text value of an aria-snapshot line, in either form the renderer emits:
    * `- generic "foo" [ref=e1]` (quoted accessible name) or
@@ -1999,42 +2167,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: TraceRecordingBackend._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: TraceRecordingBackend._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: TraceRecordingBackend._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() && !TraceRecordingBackend._isInputLine(refLine)) {
+      const locator = { kind: "text", body: (0, import_utils.stableTextLead)(colonTextMatch[1].trim()), options: { exact: false } };
+      return { selector: TraceRecordingBackend._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: TraceRecordingBackend._renderSelector(locator), locator };
     }
     return null;
   }