@piwitests/reporter 0.12.0 → 0.13.0

package/dist/internal/capture/locator-healing.js

@@ -1,855 +1,639 @@
 "use strict";
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/internal/capture/locator-healing.ts
+var locator_healing_exports = {};
+__export(locator_healing_exports, {
+  ACTION_METHODS: () => ACTION_METHODS,
+  CAPTURED_ATTRIBUTES: () => CAPTURED_ATTRIBUTES,
+  CHAIN_METHODS: () => CHAIN_METHODS,
+  INPUT_TYPE_TO_ROLE: () => INPUT_TYPE_TO_ROLE,
+  LOCATOR_CREATING_CHAINS: () => LOCATOR_CREATING_CHAINS,
+  LOCATOR_METHODS: () => LOCATOR_METHODS,
+  TAG_TO_ROLE: () => TAG_TO_ROLE,
+  approximateAccessibleName: () => approximateAccessibleName,
+  captureCallerLocation: () => captureCallerLocation,
+  classifyCssStability: () => classifyCssStability,
+  dedupeSnapshotsByLocation: () => dedupeSnapshotsByLocation,
+  extractAccessibleName: () => extractAccessibleName,
+  generateAlternatives: () => generateAlternatives,
+  headingLevel: () => headingLevel,
+  isAutoGenerated: () => isAutoGenerated,
+  renderFailing: () => renderFailing,
+  resolveAriaRole: () => resolveAriaRole,
+  suggestLocatorsFromAria: () => suggestLocatorsFromAria
 });
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.INPUT_TYPE_TO_ROLE = exports.TAG_TO_ROLE = exports.CAPTURED_ATTRIBUTES = exports.LOCATOR_CREATING_CHAINS = exports.ACTION_METHODS = exports.CHAIN_METHODS = exports.LOCATOR_METHODS = void 0;
-exports.dedupeSnapshotsByLocation = dedupeSnapshotsByLocation;
-exports.resolveAriaRole = resolveAriaRole;
-exports.headingLevel = headingLevel;
-exports.generateAlternatives = generateAlternatives;
-exports.classifyCssStability = classifyCssStability;
-exports.isAutoGenerated = isAutoGenerated;
-exports.extractAccessibleName = extractAccessibleName;
-exports.approximateAccessibleName = approximateAccessibleName;
-exports.parseAriaRoleName = parseAriaRoleName;
-exports.nameSimilarity = nameSimilarity;
-exports.suggestLocatorsFromAria = suggestLocatorsFromAria;
-exports.captureCallerLocation = captureCallerLocation;
-const path = __importStar(require("node:path"));
-/**
- * Drop repeated captures of the same call site before attaching: a loop (or a
- * page-object method called repeatedly) produces one snapshot per action, but
- * the server keeps only the latest per location anyway. Keeps the last
- * element-bearing snapshot per location — falling back to the last placeholder
- * when no capture resolved, so the location still counts as "seen this run"
- * for the server's stale-location purge. Entries with no location pass through.
- */
-function dedupeSnapshotsByLocation(snaps) {
-    const lastWithElement = new Map();
-    const lastAny = new Map();
-    snaps.forEach((s, i) => {
-        if (!s.location)
-            return;
-        lastAny.set(s.location, i);
-        if (s.element)
-            lastWithElement.set(s.location, i);
-    });
-    return snaps.filter((s, i) => {
-        if (!s.location)
-            return true;
-        return (lastWithElement.get(s.location) ?? lastAny.get(s.location)) === i;
-    });
+module.exports = __toCommonJS(locator_healing_exports);
+var path = __toESM(require("path"));
+
+// ../packages/core/src/locator-fingerprint.ts
+var PRESENT_SIMILARITY = 0.8;
+var MATCH_SIMILARITY = 0.2;
+function parseAriaCandidates(ariaSnapshot) {
+  if (!ariaSnapshot) return [];
+  const out = [];
+  for (const line of ariaSnapshot.split("\n")) {
+    const m = line.match(/^\s*-\s+([a-z]+)(?:\s+"((?:[^"\\]|\\.)*)")?/i);
+    if (!m) continue;
+    const role = m[1];
+    const name = m[2] != null ? m[2].replace(/\\(.)/g, "$1") : null;
+    if (!name && (role === "generic" || role === "group" || role === "list" || role === "paragraph")) continue;
+    const levelMatch = line.slice(m[0].length).match(/\[level=(\d+)\]/);
+    const level = levelMatch ? Number(levelMatch[1]) : null;
+    out.push({ role, name, level });
+  }
+  return out;
 }
-// ── Playwright method surface (shared with the fixture proxy) ────────────────
-/**
- * Page-level locator-building methods wrapped by the capture proxy. Imported by
- * both the capture fixtures (`capture-fixtures.ts`) and the dogfooding
- * `application/tests/fixtures.ts` so the two stay in sync (a prior drift missed
- * `scrollIntoViewIfNeeded`).
- */
-exports.LOCATOR_METHODS = [
-    'getByRole',
-    'getByTestId',
-    'getByText',
-    'getByLabel',
-    'getByPlaceholder',
-    'getByAltText',
-    'getByTitle',
-    'locator',
-];
-/**
- * Methods that can be chained onto a wrapped locator. Locator-creating chains
- * (those also in `LOCATOR_METHODS`) update the origin; positional/filter chains
- * (`first`, `nth`, `filter`, …) narrow without changing locator identity.
- */
-exports.CHAIN_METHODS = [
-    'first',
-    'nth',
-    'last',
-    'filter',
-    'and',
-    'or',
-    'locator',
-    'getByRole',
-    'getByTestId',
-    'getByText',
-    'getByLabel',
-    'getByPlaceholder',
-    'getByAltText',
-    'getByTitle',
-];
-/** Locator action methods that trigger element capture. */
-exports.ACTION_METHODS = [
-    'click',
-    'fill',
-    'check',
-    'uncheck',
-    'selectOption',
-    'dblclick',
-    'tap',
-    'hover',
-    'press',
-    'type',
-    'pressSequentially',
-    'clear',
-    'setInputFiles',
-    'dragTo',
-    'focus',
-    'blur',
-    'scrollIntoViewIfNeeded',
-    'dispatchEvent',
-    'selectText',
-    // Not an action, but a successful waitFor proves the element resolved — the
-    // closest capture hook available for assertion-style usage of a locator.
-    'waitFor',
-];
-/** Chain methods that create a new locator scope (origin tracks the chain call). */
-exports.LOCATOR_CREATING_CHAINS = new Set(exports.LOCATOR_METHODS);
-/**
- * Element attributes to capture after a successful action, passed into the
- * in-page `evaluate`. Shared so the reporter and dogfooding fixtures capture
- * the same attribute set.
- */
-exports.CAPTURED_ATTRIBUTES = [
-    'id',
-    'class',
-    'name',
-    'data-testid',
-    'placeholder',
-    'alt',
-    'title',
-    'aria-label',
-    // `aria-level` carries the heading level for `role="heading"` elements
-    // (h1-h6 levels come from the tag itself).
-    'aria-level',
-    'role',
-    'type',
-    'href',
-    // `multiple` distinguishes listbox vs combobox for <select>. `value` is
-    // deliberately NOT captured: no alternative generator uses it, and reading
-    // the live value after fill() would leak user-typed secrets (passwords,
-    // tokens) into the snapshot payload and server storage.
-    'multiple',
+function textSimilarity(a, b) {
+  const tok = (s) => new Set(
+    (s ?? "").toLowerCase().split(/[^a-z0-9]+/i).filter(Boolean)
+  );
+  const sa = tok(a);
+  const sb = tok(b);
+  if (sa.size === 0 && sb.size === 0) return 1;
+  if (sa.size === 0 || sb.size === 0) return 0;
+  let common = 0;
+  for (const t of sa) if (sb.has(t)) common++;
+  return 2 * common / (sa.size + sb.size);
+}
+function fingerprintPresent(fp, candidates) {
+  if (!fp.name) return false;
+  return candidates.some(
+    (c) => (!fp.role || c.role === fp.role) && textSimilarity(c.name, fp.name) >= PRESENT_SIMILARITY
+  );
+}
+function matchRenamedElement(fp, candidates) {
+  if (candidates.length === 0) return null;
+  const sameRole = fp.role ? candidates.filter((c) => c.role === fp.role) : candidates;
+  if (sameRole.length === 0) return null;
+  let pool = sameRole;
+  if (fp.level != null) {
+    const sameLevel = sameRole.filter((c) => c.level === fp.level);
+    if (sameLevel.length > 0) pool = sameLevel;
+  }
+  if (pool.length === 1) {
+    return { candidate: pool[0], confidence: 0.7 };
+  }
+  let best = null;
+  let bestScore = -1;
+  for (const c of pool) {
+    const s = textSimilarity(c.name, fp.name);
+    if (s > bestScore) {
+      bestScore = s;
+      best = c;
+    }
+  }
+  if (best && bestScore >= MATCH_SIMILARITY) return { candidate: best, confidence: bestScore };
+  const pos = fp.rolePosition;
+  if (pos && fp.role && pos.role === fp.role && sameRole.length >= 2 && sameRole.length === pos.count) {
+    const byIndex = sameRole[pos.index];
+    if (byIndex) return { candidate: byIndex, confidence: 0.5 };
+  }
+  return null;
+}
+
+// ../packages/core/src/locator-methods.ts
+var LOCATOR_BUILDER_METHODS = [
+  "getByRole",
+  "getByTestId",
+  "getByText",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle",
+  "locator"
 ];
-// ── ARIA role resolution ─────────────────────────────────────────────────────
-/**
- * Implicit ARIA role for an HTML tag (when no explicit `role` is set). Exported
- * so the in-page probe (`capture-fixtures.ts#probeElementAttrs`) can receive
- * this same map as an `evaluate` argument instead of re-declaring it — the
- * probe is serialized into the browser and can't reference this module's
- * closure, but the map is pure data and rides in as an argument.
- */
-exports.TAG_TO_ROLE = {
-    a: 'link',
-    button: 'button',
-    nav: 'navigation',
-    main: 'main',
-    article: 'article',
-    section: 'region',
-    form: 'form',
-    img: 'img',
-    figure: 'figure',
-    figcaption: 'caption',
-    blockquote: 'blockquote',
-    table: 'table',
-    ul: 'list',
-    ol: 'list',
-    li: 'listitem',
-    dialog: 'dialog',
-    output: 'status',
-    progress: 'progressbar',
-    meter: 'meter',
-    textarea: 'textbox',
-    h1: 'heading',
-    h2: 'heading',
-    h3: 'heading',
-    h4: 'heading',
-    h5: 'heading',
-    h6: 'heading',
-    details: 'group',
-    summary: 'button',
-    search: 'search',
+
+// ../packages/core/src/locator-generation.ts
+var TAG_TO_ROLE = {
+  a: "link",
+  button: "button",
+  nav: "navigation",
+  main: "main",
+  article: "article",
+  section: "region",
+  form: "form",
+  img: "img",
+  figure: "figure",
+  figcaption: "caption",
+  blockquote: "blockquote",
+  table: "table",
+  ul: "list",
+  ol: "list",
+  li: "listitem",
+  dialog: "dialog",
+  output: "status",
+  progress: "progressbar",
+  meter: "meter",
+  textarea: "textbox",
+  h1: "heading",
+  h2: "heading",
+  h3: "heading",
+  h4: "heading",
+  h5: "heading",
+  h6: "heading",
+  details: "group",
+  summary: "button",
+  search: "search"
 };
-/** Implicit ARIA role for an `<input>` keyed by its `type` attribute. Exported for the probe (see {@link TAG_TO_ROLE}). */
-exports.INPUT_TYPE_TO_ROLE = {
-    button: 'button',
-    submit: 'button',
-    reset: 'button',
-    image: 'button',
-    checkbox: 'checkbox',
-    radio: 'radio',
-    range: 'slider',
-    search: 'searchbox',
-    number: 'spinbutton',
-    text: 'textbox',
-    email: 'textbox',
-    tel: 'textbox',
-    url: 'textbox',
-    password: 'textbox',
+var INPUT_TYPE_TO_ROLE = {
+  button: "button",
+  submit: "button",
+  reset: "button",
+  image: "button",
+  checkbox: "checkbox",
+  radio: "radio",
+  range: "slider",
+  search: "searchbox",
+  number: "spinbutton",
+  text: "textbox",
+  email: "textbox",
+  tel: "textbox",
+  url: "textbox",
+  password: "textbox"
 };
-/**
- * Resolve the ARIA role for an element. An explicit `role` attribute wins;
- * otherwise the implicit role is derived from the tag name (and `type` for
- * `<input>`). Returns null when the element has no ARIA role (e.g. `<div>`,
- * `<span>`, `<a>` without `href`) — `getByRole` is not a valid locator for
- * such elements and other alternatives take over.
- */
+var CAPTURED_ATTRIBUTES = [
+  "id",
+  "class",
+  "name",
+  "data-testid",
+  "placeholder",
+  "alt",
+  "title",
+  "aria-label",
+  "aria-level",
+  "role",
+  "type",
+  "href",
+  "multiple"
+];
 function resolveAriaRole(attrs) {
-    const explicit = attrs.attributes['role'];
-    if (explicit)
-        return explicit;
-    const tag = attrs.tagName;
-    if (!tag)
-        return null;
-    if (tag === 'input') {
-        const type = (attrs.attributes['type'] ?? 'text').toLowerCase();
-        return exports.INPUT_TYPE_TO_ROLE[type] ?? 'textbox';
-    }
-    // A plain <select> is a combobox; only with `multiple` (or size > 1, not
-    // captured) does it become a listbox. Matches the server's implicitRoleForTag.
-    if (tag === 'select') {
-        return attrs.attributes['multiple'] != null ? 'listbox' : 'combobox';
-    }
-    if (tag === 'a') {
-        return attrs.attributes['href'] != null ? 'link' : null;
-    }
-    return exports.TAG_TO_ROLE[tag] ?? null;
+  const explicit = attrs.attributes["role"];
+  if (explicit) return explicit;
+  const tag = attrs.tagName;
+  if (!tag) return null;
+  if (tag === "input") {
+    const type = (attrs.attributes["type"] ?? "text").toLowerCase();
+    return INPUT_TYPE_TO_ROLE[type] ?? "textbox";
+  }
+  if (tag === "select") {
+    return attrs.attributes["multiple"] != null ? "listbox" : "combobox";
+  }
+  if (tag === "a") {
+    return attrs.attributes["href"] != null ? "link" : null;
+  }
+  return TAG_TO_ROLE[tag] ?? null;
 }
-/**
- * Heading level for a `heading`-role element: h1-h6 from the tag, else an
- * explicit `aria-level` attribute. Null when unknown (don't guess the ARIA
- * default) or when the element isn't a heading.
- */
 function headingLevel(attrs, role) {
-    if (role !== 'heading')
-        return null;
-    const tagMatch = attrs.tagName.match(/^h([1-6])$/);
-    if (tagMatch)
-        return Number(tagMatch[1]);
-    const ariaLevel = attrs.attributes['aria-level'];
-    if (ariaLevel && /^\d+$/.test(ariaLevel))
-        return Number(ariaLevel);
-    return null;
+  if (role !== "heading") return null;
+  const tagMatch = attrs.tagName.match(/^h([1-6])$/);
+  if (tagMatch) return Number(tagMatch[1]);
+  const ariaLevel = attrs.attributes["aria-level"];
+  if (ariaLevel && /^\d+$/.test(ariaLevel)) return Number(ariaLevel);
+  return null;
+}
+var attr = (a, key) => a.attributes[key] || null;
+var esc = (s) => s.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+var escCssAttrValue = (s) => s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+var isCssSafeId = (id) => /^[A-Za-z][A-Za-z0-9_-]*$/.test(id);
+function classifyCssStability(className) {
+  if (/[a-f0-9]{8,}/i.test(className)) return 10;
+  if (/^(?:css|sc|emotion|styled)-/i.test(className)) return 15;
+  if (/^(bg|text|border|shadow|opacity|font|w-|h-|m[tblrxy]?-|p[tblrxy]?-|flex|grid|gap|rounded|absolute|relative|fixed|sticky|block|inline|hidden|overflow|z-|top-|right-|bottom-|left-|inset-|justify-|items-|self-|content-|order-|col-|row-)/.test(
+    className
+  ))
+    return 25;
+  if (/__/.test(className) || /--/.test(className)) return 35;
+  if (/^[a-z]+(-[a-z]+)+$/.test(className)) return 40;
+  if (/^[a-z]+[A-Z][a-zA-Z]+$/.test(className)) return 40;
+  if (className.includes("_")) return 15;
+  if (/^[a-z]+-[a-z0-9]{5,}$/.test(className) && /[0-9]/.test(className)) return 15;
+  return 15;
+}
+function isAutoGenerated(value) {
+  if (/^[a-f0-9]{8}-([a-f0-9]{4}-){3}[a-f0-9]{12}$/i.test(value)) return true;
+  if (/^[a-f0-9]{8,}$/i.test(value)) return true;
+  if (/^[a-z]+-\d+$/.test(value)) return true;
+  if (/^(emotion-|styled-|css-|sc-)/.test(value)) return true;
+  if (value.startsWith("ng-")) return true;
+  if (/^(radix-|headlessui-|mui-|mantine-|chakra-)/i.test(value)) return true;
+  if (/^:r[0-9a-z]+:$/i.test(value) || /^«r[0-9a-z]+»$/i.test(value)) return true;
+  return false;
 }
-// ── Alternative generation ───────────────────────────────────────────────────
-const attr = (a, key) => a.attributes[key] || null;
-const esc = (s) => s.replace(/\\/g, '\\\\').replace(/'/g, "\\'");
-/** Escape a value for use inside a double-quoted CSS attribute selector. */
-const escCssAttrValue = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-/** An id usable as a bare `#id` CSS selector without escaping (framework ids like `:r3:` are not). */
-const isCssSafeId = (id) => /^[A-Za-z][A-Za-z0-9_-]*$/.test(id);
-/**
- * Build a ranked list of alternative locators from the captured element
- * attributes. The list is sorted descending by stability score.
- *
- * Only generates alternatives that differ from each other — no duplicates
- * of the same locator expression.
- */
 function generateAlternatives(attrs) {
-    const alts = [];
-    const seen = new Set();
-    const add = (loc) => {
-        if (!seen.has(loc.locator)) {
-            seen.add(loc.locator);
-            alts.push(loc);
-        }
-    };
-    const { accessibleName } = attrs;
-    const tag = attrs.tagName;
-    const role = resolveAriaRole(attrs);
-    // A probed count > 1 means the selector matches several elements on the
-    // captured page — a strict-mode violation, so the alternative is suppressed.
-    // Unknown counts (probe absent/failed) keep the alternative.
-    const counts = attrs.selectorCounts;
-    const isUnique = (n) => n == null || n <= 1;
-    // Collapse whitespace: multi-line/indented textContent would otherwise
-    // produce a getByText with literal newlines — invalid when pasted as code.
-    const text = attrs.textContent ? attrs.textContent.replace(/\s+/g, ' ').trim() : null;
-    // 1. data-testid — highest stability (100)
-    const testId = attr(attrs, 'data-testid');
-    if (testId && isUnique(counts?.testId)) {
-        add({
-            locator: `getByTestId('${esc(testId)}')`,
-            method: 'getByTestId',
-            args: { testId },
-            score: 100,
-        });
+  const alts = [];
+  const seen = /* @__PURE__ */ new Set();
+  const add = (loc) => {
+    if (!seen.has(loc.locator)) {
+      seen.add(loc.locator);
+      alts.push(loc);
     }
-    // Heading level rides along in every heading getByRole — it survives renames
-    // and disambiguates same-named headings at different levels.
-    const level = headingLevel(attrs, role);
-    const levelPart = level != null ? `, level: ${level}` : '';
-    const withLevel = (base) => level != null ? { ...base, level } : base;
-    // 2. role + accessible name from browser ARIA tree (85-95)
-    if (role && accessibleName) {
-        add({
-            locator: `getByRole('${role}', { name: '${esc(accessibleName)}'${levelPart} })`,
-            method: 'getByRole',
-            args: withLevel({ role, name: accessibleName }),
-            score: 90,
-        });
-    }
-    // 3. role + explicit aria-label (85, fallback when no browser-computed name)
-    const ariaLabel = attr(attrs, 'aria-label');
-    if (role && ariaLabel && ariaLabel !== accessibleName) {
-        add({
-            locator: `getByRole('${role}', { name: '${esc(ariaLabel)}'${levelPart} })`,
-            method: 'getByRole',
-            args: withLevel({ role, name: ariaLabel }),
-            score: 85,
-        });
-    }
-    // 4. getByLabel — for form fields (85). getByLabel only matches a real
-    // <label> association or aria-label — but the accessible name may have been
-    // computed (or approximated) from placeholder/title, where getByLabel would
-    // match nothing. Only emit when a label/aria-label actually backs the name;
-    // legacy payloads without the hasLabel probe keep the old permissive behavior.
-    if (accessibleName && ['input', 'select', 'textarea'].includes(tag)) {
-        const label = attr(attrs, 'aria-label');
-        const labelBacked = attrs.hasLabel === undefined ? true : attrs.hasLabel === true || label === accessibleName;
-        if (labelBacked) {
-            add({
-                locator: `getByLabel('${esc(accessibleName)}')`,
-                method: 'getByLabel',
-                args: { label: accessibleName },
-                score: 85,
-            });
-        }
-    }
-    // 5. getByPlaceholder — for inputs (80)
-    const placeholder = attr(attrs, 'placeholder');
-    if (placeholder) {
-        add({
-            locator: `getByPlaceholder('${esc(placeholder)}')`,
-            method: 'getByPlaceholder',
-            args: { placeholder },
-            score: 80,
-        });
-    }
-    // 6. getByText — from visible text content (70-80)
-    if (text && text.length < 80) {
-        add({
-            locator: `getByText('${esc(text)}')`,
-            method: 'getByText',
-            args: { text },
-            score: 75,
-        });
-    }
-    // 7. locator('#id') — if id exists and doesn't look auto-generated (50-70).
-    // Framework ids that aren't valid bare CSS identifiers (React useId's
-    // `:r3:`, ids with dots) fall back to an attribute selector.
-    const id = attr(attrs, 'id');
-    if (id && !isAutoGenerated(id) && isUnique(counts?.id)) {
-        const selector = isCssSafeId(id) ? `#${id}` : `[id="${escCssAttrValue(id)}"]`;
-        add({
-            locator: `locator('${esc(selector)}')`,
-            method: 'locator',
-            args: { selector },
-            score: 65,
-        });
+  };
+  const { accessibleName } = attrs;
+  const tag = attrs.tagName;
+  const role = resolveAriaRole(attrs);
+  const counts = attrs.selectorCounts;
+  const isUnique = (n) => n == null || n <= 1;
+  const text = attrs.textContent ? attrs.textContent.replace(/\s+/g, " ").trim() : null;
+  const testId = attr(attrs, "data-testid");
+  if (testId && isUnique(counts?.testId)) {
+    add({
+      locator: `getByTestId('${esc(testId)}')`,
+      method: "getByTestId",
+      args: { testId },
+      score: 100
+    });
+  }
+  const level = headingLevel(attrs, role);
+  const levelPart = level != null ? `, level: ${level}` : "";
+  const withLevel = (base) => level != null ? { ...base, level } : base;
+  if (role && accessibleName) {
+    add({
+      locator: `getByRole('${role}', { name: '${esc(accessibleName)}'${levelPart} })`,
+      method: "getByRole",
+      args: withLevel({ role, name: accessibleName }),
+      score: 90
+    });
+  }
+  const ariaLabel = attr(attrs, "aria-label");
+  if (role && ariaLabel && ariaLabel !== accessibleName) {
+    add({
+      locator: `getByRole('${role}', { name: '${esc(ariaLabel)}'${levelPart} })`,
+      method: "getByRole",
+      args: withLevel({ role, name: ariaLabel }),
+      score: 85
+    });
+  }
+  if (accessibleName && ["input", "select", "textarea"].includes(tag)) {
+    const label = attr(attrs, "aria-label");
+    const labelBacked = attrs.hasLabel === void 0 ? true : attrs.hasLabel === true || label === accessibleName;
+    if (labelBacked) {
+      add({
+        locator: `getByLabel('${esc(accessibleName)}')`,
+        method: "getByLabel",
+        args: { label: accessibleName },
+        score: 85
+      });
     }
-    // 8. locator('[name="..."]') — for form elements (60)
-    const name = attr(attrs, 'name');
-    if (name && isUnique(counts?.name)) {
-        const selector = `[name="${escCssAttrValue(name)}"]`;
+  }
+  const placeholder = attr(attrs, "placeholder");
+  if (placeholder) {
+    add({
+      locator: `getByPlaceholder('${esc(placeholder)}')`,
+      method: "getByPlaceholder",
+      args: { placeholder },
+      score: 80
+    });
+  }
+  if (text && text.length < 80) {
+    add({
+      locator: `getByText('${esc(text)}')`,
+      method: "getByText",
+      args: { text },
+      score: 75
+    });
+  }
+  const id = attr(attrs, "id");
+  if (id && !isAutoGenerated(id) && isUnique(counts?.id)) {
+    const selector = isCssSafeId(id) ? `#${id}` : `[id="${escCssAttrValue(id)}"]`;
+    add({
+      locator: `locator('${esc(selector)}')`,
+      method: "locator",
+      args: { selector },
+      score: 65
+    });
+  }
+  const name = attr(attrs, "name");
+  if (name && isUnique(counts?.name)) {
+    const selector = `[name="${escCssAttrValue(name)}"]`;
+    add({
+      locator: `locator('${esc(selector)}')`,
+      method: "locator",
+      args: { selector },
+      score: 60
+    });
+  }
+  const alt = attr(attrs, "alt");
+  if (alt) {
+    add({
+      locator: `getByAltText('${esc(alt)}')`,
+      method: "getByAltText",
+      args: { text: alt },
+      score: 60
+    });
+  }
+  const title = attr(attrs, "title");
+  if (title) {
+    add({
+      locator: `getByTitle('${esc(title)}')`,
+      method: "getByTitle",
+      args: { title },
+      score: 50
+    });
+  }
+  const hasOwnTestId = !!(testId && isUnique(counts?.testId));
+  if (role && !hasOwnTestId) {
+    const rolePart = level != null ? `'${role}', { level: ${level} }` : `'${role}'`;
+    const leafArgs = withLevel({ role });
+    let testIdAnchorDone = false;
+    let idAnchorDone = false;
+    let roleAnchorDone = false;
+    for (const anc of attrs.ancestors ?? []) {
+      if (anc.scopedRoleCount !== 1) continue;
+      if (!testIdAnchorDone && anc.testId && anc.testIdCount === 1) {
+        testIdAnchorDone = true;
         add({
-            locator: `locator('${esc(selector)}')`,
-            method: 'locator',
-            args: { selector },
-            score: 60,
+          locator: `getByTestId('${esc(anc.testId)}').getByRole(${rolePart})`,
+          method: "getByRole",
+          args: { ...leafArgs, anchorTestId: anc.testId },
+          score: 72
         });
-    }
-    // 9. getByAltText — for images (60)
-    const alt = attr(attrs, 'alt');
-    if (alt) {
+      }
+      if (!idAnchorDone && anc.id && !isAutoGenerated(anc.id) && anc.idCount === 1) {
+        idAnchorDone = true;
+        const anchorSelector = isCssSafeId(anc.id) ? `#${anc.id}` : `[id="${escCssAttrValue(anc.id)}"]`;
         add({
-            locator: `getByAltText('${esc(alt)}')`,
-            method: 'getByAltText',
-            args: { text: alt },
-            score: 60,
+          locator: `locator('${esc(anchorSelector)}').getByRole(${rolePart})`,
+          method: "getByRole",
+          args: { ...leafArgs, anchorSelector },
+          score: 64
         });
-    }
-    // 10. getByTitle (50)
-    const title = attr(attrs, 'title');
-    if (title) {
+      }
+      const ancestorRole = anc.role || TAG_TO_ROLE[anc.tag] || null;
+      if (!roleAnchorDone && ancestorRole && ancestorRole !== role && anc.roleCount === 1) {
+        roleAnchorDone = true;
         add({
-            locator: `getByTitle('${esc(title)}')`,
-            method: 'getByTitle',
-            args: { title },
-            score: 50,
+          locator: `getByRole('${esc(ancestorRole)}').getByRole(${rolePart})`,
+          method: "getByRole",
+          args: { ...leafArgs, anchorRole: ancestorRole },
+          score: 55
         });
+      }
     }
-    // Structural alternatives (55-72) — name-free, so they survive label/text
-    // renames that break every name-derived locator above. Skipped when the
-    // element has its own unique data-testid (already the top alternative).
-    // Chained alternatives carry the LEAF method with flat args (never a `name`
-    // key) so the recommendation's method-family logic and the server's
-    // fingerprint reader treat them correctly.
-    const hasOwnTestId = !!(testId && isUnique(counts?.testId));
-    if (role && !hasOwnTestId) {
-        const rolePart = level != null ? `'${role}', { level: ${level} }` : `'${role}'`;
-        const leafArgs = withLevel({ role });
-        // Ancestor-anchored role locators: nearest anchor of each kind whose own
-        // hook is document-unique and that contains exactly one leaf-role match
-        // (level-scoped for headings — the probe counts accordingly).
-        let testIdAnchorDone = false;
-        let idAnchorDone = false;
-        let roleAnchorDone = false;
-        for (const anc of attrs.ancestors ?? []) {
-            if (anc.scopedRoleCount !== 1)
-                continue;
-            if (!testIdAnchorDone && anc.testId && anc.testIdCount === 1) {
-                testIdAnchorDone = true;
-                add({
-                    locator: `getByTestId('${esc(anc.testId)}').getByRole(${rolePart})`,
-                    method: 'getByRole',
-                    args: { ...leafArgs, anchorTestId: anc.testId },
-                    score: 72,
-                });
-            }
-            if (!idAnchorDone && anc.id && !isAutoGenerated(anc.id) && anc.idCount === 1) {
-                idAnchorDone = true;
-                const anchorSelector = isCssSafeId(anc.id) ? `#${anc.id}` : `[id="${escCssAttrValue(anc.id)}"]`;
-                add({
-                    locator: `locator('${esc(anchorSelector)}').getByRole(${rolePart})`,
-                    method: 'getByRole',
-                    args: { ...leafArgs, anchorSelector },
-                    score: 64,
-                });
-            }
-            const ancestorRole = anc.role || exports.TAG_TO_ROLE[anc.tag] || null;
-            if (!roleAnchorDone && ancestorRole && ancestorRole !== role && anc.roleCount === 1) {
-                roleAnchorDone = true;
-                add({
-                    locator: `getByRole('${esc(ancestorRole)}').getByRole(${rolePart})`,
-                    method: 'getByRole',
-                    args: { ...leafArgs, anchorRole: ancestorRole },
-                    score: 55,
-                });
-            }
-        }
-        // Name-free bare role — the sole element of its role on the page, or the
-        // sole heading at its level (a lone h1 among many h2s).
-        const pos = attrs.rolePosition;
-        if (pos && pos.role === role && (pos.count === 1 || (level != null && pos.levelCount === 1))) {
-            add({
-                locator: `getByRole(${rolePart})`,
-                method: 'getByRole',
-                args: leafArgs,
-                score: 58,
-            });
-        }
+    const pos = attrs.rolePosition;
+    if (pos && pos.role === role && (pos.count === 1 || level != null && pos.levelCount === 1)) {
+      add({
+        locator: `getByRole(${rolePart})`,
+        method: "getByRole",
+        args: leafArgs,
+        score: 58
+      });
     }
-    // 11. CSS class-based locators — capped at 3 most stable classes; classes
-    // the uniqueness probe saw on more than one element are dropped outright.
-    const clsStr = attr(attrs, 'class');
-    if (clsStr) {
-        const classes = clsStr
-            .split(/\s+/)
-            // Only classes valid as a bare `.cls` selector — Tailwind variants
-            // (`hover:bg-red-500`) and arbitrary values (`w-[10px]`) are not.
-            .filter((c) => c.length > 1 && /^[A-Za-z_-][A-Za-z0-9_-]*$/.test(c) && isUnique(counts?.classes?.[c]))
-            .map((cls) => ({
-            cls,
-            score: classifyCssStability(cls),
-        }))
-            .sort((a, b) => b.score - a.score)
-            .slice(0, 3);
-        for (const { cls, score } of classes) {
-            add({
-                locator: `locator('.${esc(cls)}')`,
-                method: 'locator',
-                args: { selector: `.${cls}` },
-                score,
-            });
-        }
+  }
+  const clsStr = attr(attrs, "class");
+  if (clsStr) {
+    const countsClasses = counts?.classes;
+    const classes = clsStr.split(/\s+/).filter((c) => c.length > 1 && /^[A-Za-z_-][A-Za-z0-9_-]*$/.test(c) && isUnique(countsClasses?.[c])).map((cls) => ({ cls, score: classifyCssStability(cls) })).sort((a, b) => b.score - a.score).slice(0, 3);
+    for (const { cls, score } of classes) {
+      add({
+        locator: `locator('.${esc(cls)}')`,
+        method: "locator",
+        args: { selector: `.${cls}` },
+        score
+      });
     }
-    return alts.sort((a, b) => b.score - a.score);
+  }
+  return alts.sort((a, b) => b.score - a.score);
 }
-// ── CSS class stability ──────────────────────────────────────────────────────
-/**
- * Score a CSS class name on a 0-40 stability scale.
- *
- * Heuristics (inherited from common CSS-naming conventions):
- * - Hash-like suffixes (≥4 hex chars) → 10 — auto-generated, fragile
- * - CSS-in-JS patterns (css-, sc-, emotion-, styled-, _) → 15
- * - Tailwind/utility classes → 25
- * - BEM-style semantic → 35
- * - Plain semantic → 40
- */
-function classifyCssStability(className) {
-    // Hex hash patterns: contains 8+ consecutive hex digits
-    if (/[a-f0-9]{8,}/i.test(className))
-        return 10;
-    // CSS-in-JS patterns — check before utility/semantic since prefixes like
-    // "css-", "emotion-" are generated and fragile
-    if (/^(?:css|sc|emotion|styled)-/i.test(className))
-        return 15;
-    // Tailwind/utility classes
-    if (/^(bg|text|border|shadow|opacity|font|w-|h-|m[tblrxy]?-|p[tblrxy]?-|flex|grid|gap|rounded|absolute|relative|fixed|sticky|block|inline|hidden|overflow|z-|top-|right-|bottom-|left-|inset-|justify-|items-|self-|content-|order-|col-|row-)/.test(className))
-        return 25;
-    // BEM-style: block__element--modifier
-    if (/__/.test(className) || /--/.test(className))
-        return 35;
-    // Plain semantic class: hyphenated word pairs or camelCase
-    if (/^[a-z]+(-[a-z]+)+$/.test(className))
-        return 40;
-    if (/^[a-z]+[A-Z][a-zA-Z]+$/.test(className))
-        return 40;
-    // Hyphenated strings with digit-containing suffixes that look hashed
-    if (className.includes('_'))
-        return 15;
-    if (/^[a-z]+-[a-z0-9]{5,}$/.test(className) && /[0-9]/.test(className))
-        return 15;
-    // Unknown — score conservatively
-    return 15;
+function approximateAccessibleName(attrs) {
+  const a = attrs.attributes;
+  const ariaLabel = a["aria-label"];
+  if (ariaLabel) return ariaLabel;
+  if (attrs.textContent) return attrs.textContent;
+  const title = a["title"];
+  if (title) return title;
+  const placeholder = a["placeholder"];
+  if (placeholder) return placeholder;
+  return null;
 }
-// ── Auto-generation detection ────────────────────────────────────────────────
-/**
- * Detects GUID-like, auto-incremented, or hash-suffixed IDs that are
- * likely regenerated on each render and unstable for testing.
- */
-function isAutoGenerated(value) {
-    // GUID / UUID patterns
-    if (/^[a-f0-9]{8}-([a-f0-9]{4}-){3}[a-f0-9]{12}$/i.test(value))
-        return true;
-    // Hash-like (8+ hex chars)
-    if (/^[a-f0-9]{8,}$/i.test(value))
-        return true;
-    // Numeric auto-increment with hash suffix
-    if (/^[a-z]+-\d+$/.test(value))
-        return true;
-    // Random-looking CSS-in-JS IDs
-    if (/^(emotion-|styled-|css-|sc-)/.test(value))
-        return true;
-    // Angular-style generated IDs (ng-xxx-N)
-    if (value.startsWith('ng-'))
-        return true;
-    // Component-library generated ids (Radix, Headless UI, MUI, Mantine, Chakra)
-    if (/^(radix-|headlessui-|mui-|mantine-|chakra-)/i.test(value))
-        return true;
-    // React useId format — `:r1:` (18) / `«r1»` (19)
-    if (/^:r[0-9a-z]+:$/i.test(value) || /^«r[0-9a-z]+»$/i.test(value))
-        return true;
-    return false;
+
+// src/internal/capture/locator-healing.ts
+function dedupeSnapshotsByLocation(snaps) {
+  const lastWithElement = /* @__PURE__ */ new Map();
+  const lastAny = /* @__PURE__ */ new Map();
+  snaps.forEach((s, i) => {
+    if (!s.location) return;
+    lastAny.set(s.location, i);
+    if (s.element) lastWithElement.set(s.location, i);
+  });
+  return snaps.filter((s, i) => {
+    if (!s.location) return true;
+    return (lastWithElement.get(s.location) ?? lastAny.get(s.location)) === i;
+  });
 }
-// ── Accessible name extraction ───────────────────────────────────────────────
-/**
- * Extract the accessible name from a YAML-like ariaSnapshot() output.
- *
- * Format example:
- *   - button "Submit order"
- *   - heading "Welcome, Alice"
- *   - textbox "Email" [ref=e12]
- *   - generic
- *
- * Returns the first quoted string after the role, or null if none found.
- */
+var LOCATOR_METHODS = [...LOCATOR_BUILDER_METHODS];
+var CHAIN_METHODS = [
+  "first",
+  "nth",
+  "last",
+  "filter",
+  "and",
+  "or",
+  "locator",
+  "getByRole",
+  "getByTestId",
+  "getByText",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle"
+];
+var ACTION_METHODS = [
+  "click",
+  "fill",
+  "check",
+  "uncheck",
+  "selectOption",
+  "dblclick",
+  "tap",
+  "hover",
+  "press",
+  "type",
+  "pressSequentially",
+  "clear",
+  "setInputFiles",
+  "dragTo",
+  "focus",
+  "blur",
+  "scrollIntoViewIfNeeded",
+  "dispatchEvent",
+  "selectText",
+  // Not an action, but a successful waitFor proves the element resolved — the
+  // closest capture hook available for assertion-style usage of a locator.
+  "waitFor"
+];
+var LOCATOR_CREATING_CHAINS = new Set(LOCATOR_METHODS);
 function extractAccessibleName(ariaSnapshot) {
-    if (!ariaSnapshot)
-        return null;
-    // Match the role line:  - role "name" [...]
-    // The name is the first double-quoted string after the role keyword.
-    const match = ariaSnapshot.match(/- \w+ "([^"]+)"/);
-    if (match)
-        return match[1];
-    return null;
-}
-/**
- * Approximate the accessible name from HTML attributes when ariaSnapshot()
- * is unavailable. Priority: aria-label > text content > title > placeholder.
- */
-function approximateAccessibleName(attrs) {
-    const a = attrs.attributes;
-    const ariaLabel = a['aria-label'];
-    if (ariaLabel)
-        return ariaLabel;
-    if (attrs.textContent)
-        return attrs.textContent;
-    const title = a['title'];
-    if (title)
-        return title;
-    const placeholder = a['placeholder'];
-    if (placeholder)
-        return placeholder;
-    return null;
+  if (!ariaSnapshot) return null;
+  const match = ariaSnapshot.match(/- \w+ "([^"]+)"/);
+  if (match) return match[1];
+  return null;
 }
-/** Name-based locator methods — the only ones whose target can be re-found by accessible name. */
-const NAME_BASED_METHODS = new Set([
-    'getByText',
-    'getByRole',
-    'getByLabel',
-    'getByPlaceholder',
-    'getByTitle',
-    'getByAltText',
+var NAME_BASED_METHODS = /* @__PURE__ */ new Set([
+  "getByText",
+  "getByRole",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByTitle",
+  "getByAltText"
 ]);
-const escAttr = (s) => s.replaceAll('\\', '\\\\').replaceAll("'", "\\'");
-/**
- * Parse `ariaSnapshot()` lines into role/name pairs (mirrors the server-side
- * `parseAriaCandidates` in application/shared/locator-fingerprint.ts).
- * Exported so the dashboard's drift-guard unit test can compare the two.
- */
-function parseAriaRoleName(ariaSnapshot) {
-    const out = [];
-    for (const line of ariaSnapshot.split('\n')) {
-        const m = /^\s*-\s+([a-z]+)(?:\s+"((?:[^"\\]|\\.)*)")?/i.exec(line);
-        if (!m)
-            continue;
-        const role = m[1];
-        const name = m[2] == null ? null : m[2].replace(/\\(.)/g, '$1');
-        if (!name && (role === 'generic' || role === 'group' || role === 'list' || role === 'paragraph'))
-            continue;
-        // Heading level rides after the name as `[level=N]` (other bracketed
-        // markers like `[ref=eN]` are ignored). Scan only past the matched part so
-        // brackets inside the quoted name can't fake a level.
-        const levelMatch = /\[level=(\d+)\]/.exec(line.slice(m[0].length));
-        const level = levelMatch ? Number(levelMatch[1]) : null;
-        out.push({ role, name, level });
-    }
-    return out;
-}
-/**
- * Token-set (Dice) similarity, 0-1, case- and punctuation-insensitive.
- * Duplicated from `textSimilarity` in application/shared/locator-fingerprint.ts —
- * this package publishes standalone to npm and can't import monorepo-relative
- * shared/ code, so keep the two implementations in sync by hand. Exported so
- * the dashboard's drift-guard unit test can compare the two.
- */
-function nameSimilarity(a, b) {
-    const tok = (s) => new Set((s ?? '')
-        .toLowerCase()
-        .split(/[^a-z0-9]+/i)
-        .filter(Boolean));
-    const sa = tok(a);
-    const sb = tok(b);
-    if (sa.size === 0 && sb.size === 0)
-        return 1;
-    if (sa.size === 0 || sb.size === 0)
-        return 0;
-    let common = 0;
-    for (const t of sa)
-        if (sb.has(t))
-            common++;
-    return (2 * common) / (sa.size + sb.size);
-}
-const SUGG_TEXT_ROLES = new Set([
-    'button',
-    'link',
-    'heading',
-    'menuitem',
-    'tab',
-    'option',
-    'cell',
-    'columnheader',
-    'rowheader',
-    'gridcell',
-    'treeitem',
-    'listitem',
-    'checkbox',
-    'radio',
-    'switch',
+var escAttr = (s) => s.replaceAll("\\", "\\\\").replaceAll("'", "\\'");
+var SUGG_TEXT_ROLES = /* @__PURE__ */ new Set([
+  "button",
+  "link",
+  "heading",
+  "menuitem",
+  "tab",
+  "option",
+  "cell",
+  "columnheader",
+  "rowheader",
+  "gridcell",
+  "treeitem",
+  "listitem",
+  "checkbox",
+  "radio",
+  "switch"
 ]);
-const SUGG_FIELD_ROLES = new Set(['textbox', 'combobox', 'searchbox', 'spinbutton', 'slider']);
-/** Extract the role (for getByRole), targeted accessible name, and heading level from a failed locator's args. */
+var SUGG_FIELD_ROLES = /* @__PURE__ */ new Set(["textbox", "combobox", "searchbox", "spinbutton", "slider"]);
 function failedNameAndRole(failed) {
-    if (failed.method === 'getByRole') {
-        const role = typeof failed.args[0] === 'string' ? failed.args[0] : null;
-        const opts = failed.args[1];
-        const name = opts && typeof opts.name === 'string' ? opts.name : null;
-        const level = opts && typeof opts.level === 'number' ? opts.level : null;
-        return { role, name, level };
-    }
-    const first = failed.args.find((a) => typeof a === 'string');
-    return { role: null, name: typeof first === 'string' ? first : null, level: null };
+  if (failed.method === "getByRole") {
+    const role = typeof failed.args[0] === "string" ? failed.args[0] : null;
+    const opts = failed.args[1];
+    const name = opts && typeof opts.name === "string" ? opts.name : null;
+    const level = opts && typeof opts.level === "number" ? opts.level : null;
+    return { role, name, level };
+  }
+  const first = failed.args.find((a) => typeof a === "string");
+  return { role: null, name: typeof first === "string" ? first : null, level: null };
 }
-/** Render the failed locator back to source for the annotation message. */
 function renderFailing(failed) {
-    const { role, name } = failedNameAndRole(failed);
-    if (failed.method === 'getByRole') {
-        return name
-            ? `getByRole('${escAttr(role ?? '')}', { name: '${escAttr(name)}' })`
-            : `getByRole('${escAttr(role ?? '')}')`;
-    }
-    return `${failed.method}('${escAttr(name ?? '')}')`;
+  const { role, name } = failedNameAndRole(failed);
+  if (failed.method === "getByRole") {
+    return name ? `getByRole('${escAttr(role ?? "")}', { name: '${escAttr(name)}' })` : `getByRole('${escAttr(role ?? "")}')`;
+  }
+  return `${failed.method}('${escAttr(name ?? "")}')`;
 }
-/** Build fresh locator suggestions for a matched candidate, with the failed method's style first. */
 function freshSuggestions(candidate, failedMethod) {
-    const out = [];
-    const role = candidate.role;
-    const name = candidate.name;
-    const push = (s) => {
-        if (!out.includes(s))
-            out.push(s);
-    };
-    const levelPart = candidate.level != null ? `, level: ${candidate.level}` : '';
-    const roleLoc = `getByRole('${escAttr(role)}', { name: '${escAttr(name)}'${levelPart} })`;
-    const textLoc = `getByText('${escAttr(name)}')`;
-    const labelLoc = `getByLabel('${escAttr(name)}')`;
-    // Same-style first: a broken getByText is re-suggested as getByText where viable.
-    if (failedMethod === 'getByText' && SUGG_TEXT_ROLES.has(role))
-        push(textLoc);
-    if (failedMethod === 'getByLabel' && SUGG_FIELD_ROLES.has(role))
-        push(labelLoc);
-    push(roleLoc);
-    if (SUGG_TEXT_ROLES.has(role))
-        push(textLoc);
-    else if (SUGG_FIELD_ROLES.has(role))
-        push(labelLoc);
-    return out;
+  const out = [];
+  const role = candidate.role;
+  const name = candidate.name;
+  const push = (s) => {
+    if (!out.includes(s)) out.push(s);
+  };
+  const levelPart = candidate.level != null ? `, level: ${candidate.level}` : "";
+  const roleLoc = `getByRole('${escAttr(role)}', { name: '${escAttr(name)}'${levelPart} })`;
+  const textLoc = `getByText('${escAttr(name)}')`;
+  const labelLoc = `getByLabel('${escAttr(name)}')`;
+  if (failedMethod === "getByText" && SUGG_TEXT_ROLES.has(role)) push(textLoc);
+  if (failedMethod === "getByLabel" && SUGG_FIELD_ROLES.has(role)) push(labelLoc);
+  push(roleLoc);
+  if (SUGG_TEXT_ROLES.has(role)) push(textLoc);
+  else if (SUGG_FIELD_ROLES.has(role)) push(labelLoc);
+  return out;
 }
-/**
- * Best-effort runtime suggestion for a locator that matched nothing: find the
- * element on the *current* page that the failed locator most likely targeted
- * (by accessible name similarity, restricted to the failed role when given) and
- * return fresh locators for it.
- *
- * Unlike the server lookup this has no pre-captured fingerprint — only the
- * failed locator + the live page — so it's a hint, not a guarantee. Returns null
- * for non-name-based locators (testid/CSS), when the targeted name is still
- * present (so the failure wasn't a rename), or when no candidate is confident.
- */
 function suggestLocatorsFromAria(failed, ariaSnapshot) {
-    if (!ariaSnapshot || !NAME_BASED_METHODS.has(failed.method))
-        return null;
-    const { role, name, level } = failedNameAndRole(failed);
-    if (!name)
-        return null;
-    const candidates = parseAriaRoleName(ariaSnapshot);
-    if (candidates.length === 0)
-        return null;
-    const sameRole = role ? candidates.filter((c) => c.role === role) : [];
-    let pool = sameRole.length > 0 ? sameRole : candidates;
-    // A targeted heading level narrows the pool further — a lone renamed h1
-    // among many h2s becomes the single confident candidate. Fall back to all
-    // same-role candidates when none share the level (it may have changed too).
-    if (level != null && sameRole.length > 0) {
-        const sameLevel = sameRole.filter((c) => c.level === level);
-        if (sameLevel.length > 0)
-            pool = sameLevel;
+  if (!ariaSnapshot || !NAME_BASED_METHODS.has(failed.method)) return null;
+  const { role, name, level } = failedNameAndRole(failed);
+  if (!name) return null;
+  const candidates = parseAriaCandidates(ariaSnapshot);
+  if (candidates.length === 0) return null;
+  const fingerprint = { role, name, level };
+  if (fingerprintPresent(fingerprint, candidates)) return null;
+  const best = matchRenamedElement(fingerprint, candidates)?.candidate;
+  if (!best || !best.name) return null;
+  const suggestions = freshSuggestions({ role: best.role, name: best.name, level: best.level }, failed.method);
+  if (suggestions.length === 0) return null;
+  return { failing: renderFailing(failed), suggestions };
+}
+function captureCallerLocation(stack = new Error().stack ?? "") {
+  const lines = stack.split("\n");
+  let prevWasCaptureModule = false;
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    if (!line.startsWith("at")) continue;
+    const m = line.match(/^at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?$/);
+    if (!m) {
+      prevWasCaptureModule = false;
+      continue;
     }
-    // The targeted name is still on the page → not a rename, nothing to suggest.
-    if (pool.some((c) => nameSimilarity(c.name, name) >= 0.8))
-        return null;
-    let best = null;
-    let bestScore = -1;
-    for (const c of pool) {
-        const s = nameSimilarity(c.name, name);
-        if (s > bestScore) {
-            bestScore = s;
-            best = c;
-        }
+    let file = m[2];
+    if (!file || file.startsWith("node:")) {
+      prevWasCaptureModule = false;
+      continue;
     }
-    if (!best || !best.name)
-        return null;
-    if (bestScore < 0.2 && pool.length !== 1)
-        return null;
-    const suggestions = freshSuggestions({ role: best.role, name: best.name, level: best.level }, failed.method);
-    if (suggestions.length === 0)
-        return null;
-    return { failing: renderFailing(failed), suggestions };
-}
-// ── Call-site capture ────────────────────────────────────────────────────────
-/**
- * Capture the calling test's source location (`file:line:col`) from the current
- * stack, for stamping onto a locator snapshot. The path is made cwd-relative so
- * it matches the location format Playwright embeds in error messages — which is
- * what the server's exact-match healing lookup (`extractErrorLocation`) parses.
- *
- * Stamping at action *call* time (rather than correlating with `pw:api` step
- * indices at step *end* time) avoids three classes of misalignment: `pw:api`
- * steps with no wrapped locator (e.g. `page.keyboard.press`), cross-worker step
- * interleaving, and concurrent actions reordering by end time.
- *
- * Returns null when no user frame can be identified — the snapshot keeps
- * `location: null` and the server falls back to fingerprint / ARIA lookup.
- */
-function captureCallerLocation(stack = new Error().stack ?? '') {
-    const lines = stack.split('\n');
-    // The capture machinery's own frames sit at the top of the stack: this module
-    // (locator-healing) then the single fixtures-proxy frame that called it. Skip
-    // exactly those, so the first remaining frame is the real test call site. A
-    // USER file named `fixtures.*` further down the stack must be kept, so the
-    // fixtures-proxy frame is only skipped when it directly follows this module.
-    let prevWasCaptureModule = false;
-    for (let i = 1; i < lines.length; i++) {
-        const line = lines[i].trim();
-        if (!line.startsWith('at'))
-            continue;
-        const m = line.match(/^at\s+(?:(.+?)\s+\()?(.+?):(\d+):(\d+)\)?$/);
-        if (!m) {
-            prevWasCaptureModule = false;
-            continue;
-        }
-        let file = m[2];
-        if (!file || file.startsWith('node:')) {
-            prevWasCaptureModule = false;
-            continue;
-        }
-        file = file.replace(/^file:\/\/\/?/, '');
-        // Must look like a source file (has an extension).
-        if (!/\.[a-z]+$/i.test(file)) {
-            prevWasCaptureModule = false;
-            continue;
-        }
-        // This module — always an internal frame; remember it so the immediately
-        // following fixtures-proxy frame can be skipped too.
-        if (/[\\/]locator-healing\.[a-z]+$/i.test(file)) {
-            prevWasCaptureModule = true;
-            continue;
-        }
-        // The fixtures proxy that called us — `capture-fixtures.*` in this
-        // package, `fixtures.*` in the dogfood mirror. Skip only when it directly
-        // follows this module, so a user's own `fixtures.*` deeper down is kept.
-        if (prevWasCaptureModule && /[\\/](?:capture-)?fixtures\.[a-z]+$/i.test(file)) {
-            prevWasCaptureModule = false;
-            continue;
-        }
-        if (/[\\/]node_modules[\\/]/.test(file)) {
-            prevWasCaptureModule = false;
-            continue;
-        }
-        let rel = file;
-        try {
-            rel = path.relative(process.cwd(), file);
-        }
-        catch {
-            /* keep absolute if relative fails */
-        }
-        rel = rel.split(path.sep).join('/');
-        if (rel.startsWith('./'))
-            rel = rel.slice(2);
-        return `${rel}:${m[3]}:${m[4]}`;
+    file = file.replace(/^file:\/\/\/?/, "");
+    if (!/\.[a-z]+$/i.test(file)) {
+      prevWasCaptureModule = false;
+      continue;
+    }
+    if (/[\\/]locator-healing\.[a-z]+$/i.test(file)) {
+      prevWasCaptureModule = true;
+      continue;
     }
-    return null;
+    if (prevWasCaptureModule && /[\\/](?:capture-)?fixtures\.[a-z]+$/i.test(file)) {
+      prevWasCaptureModule = false;
+      continue;
+    }
+    if (/[\\/]node_modules[\\/]/.test(file)) {
+      prevWasCaptureModule = false;
+      continue;
+    }
+    let rel = file;
+    try {
+      rel = path.relative(process.cwd(), file);
+    } catch {
+    }
+    rel = rel.split(path.sep).join("/");
+    if (rel.startsWith("./")) rel = rel.slice(2);
+    return `${rel}:${m[3]}:${m[4]}`;
+  }
+  return null;
 }
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ACTION_METHODS,
+  CAPTURED_ATTRIBUTES,
+  CHAIN_METHODS,
+  INPUT_TYPE_TO_ROLE,
+  LOCATOR_CREATING_CHAINS,
+  LOCATOR_METHODS,
+  TAG_TO_ROLE,
+  approximateAccessibleName,
+  captureCallerLocation,
+  classifyCssStability,
+  dedupeSnapshotsByLocation,
+  extractAccessibleName,
+  generateAlternatives,
+  headingLevel,
+  isAutoGenerated,
+  renderFailing,
+  resolveAriaRole,
+  suggestLocatorsFromAria
+});