@skyramp/mcp 0.4.3-rc.1 → 0.4.3

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,31 +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 === "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}]`)) || "";
-        parsed = this._preferSnapshotLocator(parsed, refLine);
-      }
+    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
@@ -1320,46 +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) {
+    const resolved = await this._resolveRef(params.ref, params.element);
+    if ("error" in resolved)
       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}]`)) || "";
-    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 inputLine = TraceRecordingBackend._isInputLine(refLine);
+${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 = TraceRecordingBackend._snapshotLineText(refLine) ?? "";
-    const elementText = inputLine ? quotedName : lineText;
-    const valueMatch = refLine.match(/\]:\s*(.+)$/);
-    const elementValue = valueMatch?.[1]?.trim() || "";
+    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 = "";
@@ -1372,7 +1390,9 @@ Could not parse locator: ${locatorExpr}` }], isError: true };
       const notReady = await this._requireLoadedPage(tab, "domcontentloaded");
       if (notReady)
         return notReady;
-      const unique = await this._makeUnique(parsed, { snapLines, ref: params.ref, lineText, exact: false });
+      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;
@@ -1518,7 +1538,8 @@ 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 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) {
@@ -1526,11 +1547,13 @@ Could not count "${refRole}" elements: ${e.message}` }], isError: true };
         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" });
+        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.pinned && parsed.locator.kind !== "test-id") {
-          const matches = TraceRecordingBackend._snapshotMatches(snapLines, parsed.locator);
+        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 };
@@ -1780,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))
@@ -1834,40 +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) {
-      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) {
-      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) {
-      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) {
-      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) {
+    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*\)/);
-    const css = cssMatch?.[1] ?? cssMatch?.[2];
-    if (css && /^(?:[#.]|[a-z][\w-]*\[)/i.test(css)) {
-      return {
-        selector: css,
-        locator: { kind: "default", body: css, 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")),
@@ -1877,7 +1890,7 @@ ${details}` }] };
    */
   async _improveTextSelector(snapLines, ref, original) {
     const textBody = original.locator.body;
-    const occurrences = TraceRecordingBackend._snapshotMatches(snapLines, original.locator) ?? 0;
+    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`);
@@ -1918,10 +1931,12 @@ ${details}` }] };
               const locator = {
                 kind: "test-id",
                 body: testidMatch[1],
-                options: {},
+                // 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 = TraceRecordingBackend._renderSelector(locator);
+              const chainedSelector = (0, import_snapshotLocators.renderSelector)(locator);
               traceDebug(`Improved to chained selector: ${chainedSelector}`);
               return { selector: chainedSelector, locator };
             }
@@ -1934,81 +1949,83 @@ ${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 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 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;
+  /** 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;
     }
-    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 };
+  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;
+    }
   }
   /**
    * 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.
+   * 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.
    */
   async _makeUnique(parsed, opts) {
     if (opts.exact)
-      parsed = TraceRecordingBackend._exactLeaf(parsed, opts.lineText);
+      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) {
@@ -2018,28 +2035,38 @@ ${details}` }] };
     }
     const page = this._browserBackend.context?.currentTab()?.page;
     if (!page)
-      return { parsed, note: "", pinned: false };
+      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: "", pinned: false };
+      if (pin.count === 1)
+        return { parsed, note: "", verdict: "unique" };
       const unpinned = parsed.selector;
-      parsed = TraceRecordingBackend._withNth(parsed, pin.index);
+      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.`, pinned: true };
+      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 === "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 };
+    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), it is not one of the matches, or
-   *  the lookup failed. */
+   *  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: 1e3 });
+      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] };
     }
@@ -2047,8 +2074,8 @@ ${details}` }] };
       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 };
+      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] };
@@ -2057,65 +2084,26 @@ ${details}` }] };
       });
     }
   }
-  /** 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.
+   * 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")
+    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 && !TraceRecordingBackend._isVolatileCss(parsed.selector))
+    if (bareRole && !(0, import_snapshotLocators.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
-   * `- generic [ref=e1]: foo` (colon-delimited text for nodes with no name).
-   * Returns null for a line that carries no text.
-   */
-  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;
-  }
   static {
     /** Extract selector and locator info from a snapshot line for assertion tracking. */
     // Roles that map to valid Playwright getByRole() selectors.
@@ -2168,26 +2156,26 @@ ${details}` }] };
     const testidMatch = refLine.match(/testid="([^"]+)"/);
     if (testidMatch) {
       const locator = { kind: "test-id", body: testidMatch[1], options: {} };
-      return { selector: TraceRecordingBackend._renderSelector(locator), locator };
+      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 locator = { kind: "role", body: roleMatch[1], options: { attrs: [], exact: false, name: (0, import_utils.stableTextLead)(roleMatch[2]) } };
-      return { selector: TraceRecordingBackend._renderSelector(locator), locator };
+      return { selector: (0, import_snapshotLocators.renderSelector)(locator), locator };
     }
     if (roleMatch && roleMatch[2]) {
       const locator = { kind: "text", body: (0, import_utils.stableTextLead)(roleMatch[2]), options: { exact: false } };
-      return { selector: TraceRecordingBackend._renderSelector(locator), locator };
+      return { selector: (0, import_snapshotLocators.renderSelector)(locator), locator };
     }
     const colonTextMatch = refLine.match(/\[ref=\w+\](?:\s*\[[^\]]*\])*\s*:\s*(.+?)\s*$/);
-    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 };
+    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 locator = { kind: "role", body: bareRoleMatch[1], options: { attrs: [], exact: false } };
-      return { selector: TraceRecordingBackend._renderSelector(locator), locator };
+      return { selector: (0, import_snapshotLocators.renderSelector)(locator), locator };
     }
     return null;
   }
@@ -2593,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 {