@piwitests/reporter 0.11.0 → 0.13.0

package/dist/internal/capture/pick-on-failure.js

@@ -0,0 +1,1203 @@
+"use strict";
+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/pick-on-failure.ts
+var pick_on_failure_exports = {};
+__export(pick_on_failure_exports, {
+  applyPickToSnapshots: () => applyPickToSnapshots,
+  deriveFailedLocator: () => deriveFailedLocator,
+  generateAnchoredAlternatives: () => generateAnchoredAlternatives,
+  installPickerOverlay: () => installPickerOverlay,
+  mergeCandidates: () => mergeCandidates,
+  parseLeafLocatorExpression: () => parseLeafLocatorExpression,
+  runLocatorPicker: () => runLocatorPicker,
+  showAnchorPicker: () => showAnchorPicker,
+  showPickerChoices: () => showPickerChoices
+});
+module.exports = __toCommonJS(pick_on_failure_exports);
+var path2 = __toESM(require("path"));
+
+// src/internal/capture/locator-healing.ts
+var path = __toESM(require("path"));
+
+// ../packages/core/src/locator-methods.ts
+var LOCATOR_BUILDER_METHODS = [
+  "getByRole",
+  "getByTestId",
+  "getByText",
+  "getByLabel",
+  "getByPlaceholder",
+  "getByAltText",
+  "getByTitle",
+  "locator"
+];
+
+// ../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"
+};
+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"
+};
+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 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;
+}
+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;
+}
+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;
+}
+function generateAlternatives(attrs) {
+  const alts = [];
+  const seen = /* @__PURE__ */ 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);
+  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
+      });
+    }
+  }
+  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: `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 || 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
+        });
+      }
+    }
+    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 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);
+}
+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;
+}
+
+// src/internal/capture/locator-healing.ts
+var LOCATOR_METHODS = [...LOCATOR_BUILDER_METHODS];
+var LOCATOR_CREATING_CHAINS = new Set(LOCATOR_METHODS);
+var escAttr = (s) => s.replaceAll("\\", "\\\\").replaceAll("'", "\\'");
+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 };
+}
+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 ?? "")}')`;
+}
+
+// src/internal/capture/pick-on-failure.ts
+var ANSI_RE = /\[[0-9;]*m/g;
+function endOfString(s, start) {
+  const q = s[start];
+  for (let i = start + 1; i < s.length; i++) {
+    if (s[i] === "\\") {
+      i++;
+      continue;
+    }
+    if (s[i] === q) return i;
+  }
+  return s.length - 1;
+}
+function matchBrace(s, start) {
+  let depth = 0;
+  for (let i = start; i < s.length; i++) {
+    if (s[i] === "{") depth++;
+    else if (s[i] === "}" && --depth === 0) return i;
+  }
+  return s.length - 1;
+}
+function parseOptions(src) {
+  const obj = {};
+  const re = /(\w+)\s*:\s*('(?:\\.|[^'])*'|"(?:\\.|[^"])*"|true|false|-?\d+)/g;
+  let m;
+  while ((m = re.exec(src)) !== null) {
+    const key = m[1];
+    const raw = m[2];
+    if (raw === "true") obj[key] = true;
+    else if (raw === "false") obj[key] = false;
+    else if (/^-?\d+$/.test(raw)) obj[key] = Number(raw);
+    else obj[key] = raw.slice(1, -1).replace(/\\(.)/g, "$1");
+  }
+  return obj;
+}
+function parseArgs(inner) {
+  const args = [];
+  let i = 0;
+  while (i < inner.length) {
+    const c = inner[i];
+    if (c === " " || c === ",") {
+      i++;
+      continue;
+    }
+    if (c === "'" || c === '"') {
+      const end = endOfString(inner, i);
+      args.push(inner.slice(i + 1, end).replace(/\\(.)/g, "$1"));
+      i = end + 1;
+      continue;
+    }
+    if (c === "{") {
+      const end = matchBrace(inner, i);
+      args.push(parseOptions(inner.slice(i, end + 1)));
+      i = end + 1;
+      continue;
+    }
+    i++;
+  }
+  return args;
+}
+function leafExpression(expr) {
+  let depth = 0;
+  let leafStart = 0;
+  for (let i = 0; i < expr.length - 1; i++) {
+    const c = expr[i];
+    if (c === "'" || c === '"') {
+      i = endOfString(expr, i);
+      continue;
+    }
+    if (c === "(") depth++;
+    else if (c === ")") {
+      depth--;
+      if (depth === 0 && expr[i + 1] === ".") leafStart = i + 2;
+    }
+  }
+  return expr.slice(leafStart);
+}
+function parseLeafLocatorExpression(rawExpr) {
+  const expr = leafExpression(rawExpr.trim());
+  const m = /^([A-Za-z]+)\((.*)\)$/s.exec(expr);
+  if (!m) return null;
+  return { method: m[1], args: parseArgs(m[2].trim()) };
+}
+function deriveFailedLocator(testInfo) {
+  const info = testInfo;
+  const errors = info.errors && info.errors.length > 0 ? info.errors : info.error ? [info.error] : [];
+  for (const err of errors) {
+    const text = `${err.message ?? ""}
+${err.stack ?? ""}`.replace(ANSI_RE, "");
+    const line = /^\s*Locator:\s*(.+)$/m.exec(text);
+    if (!line) continue;
+    const parsed = parseLeafLocatorExpression(line[1].trim());
+    if (!parsed) continue;
+    const loc = err.location;
+    const location = loc ? `${path2.relative(process.cwd(), loc.file).split(path2.sep).join("/")}:${loc.line}:${loc.column}` : null;
+    return { method: parsed.method, args: parsed.args, location };
+  }
+  return null;
+}
+var escStr = (s) => s.replaceAll("\\", "\\\\").replaceAll("'", "\\'");
+var cssIdSelector = (id) => /^[A-Za-z_][A-Za-z0-9_-]*$/.test(id) ? `#${id}` : `[id="${id.replaceAll("\\", "\\\\").replaceAll('"', '\\"')}"]`;
+var ANCHOR_KIND_SCORES = { testid: 80, id: 74, labeledRole: 68, role: 62 };
+function anchorSegment(a) {
+  if (a.testId && a.testIdCount === 1) {
+    return { code: `getByTestId('${escStr(a.testId)}')`, kind: "testid", flatArgs: { anchorTestId: a.testId } };
+  }
+  if (a.id && !isAutoGenerated(a.id) && a.idCount === 1) {
+    const anchorSelector = cssIdSelector(a.id);
+    return { code: `locator('${escStr(anchorSelector)}')`, kind: "id", flatArgs: { anchorSelector } };
+  }
+  if (a.role && a.ariaLabel && a.labeledRoleCount === 1) {
+    return {
+      code: `getByRole('${escStr(a.role)}', { name: '${escStr(a.ariaLabel)}' })`,
+      kind: "labeledRole",
+      flatArgs: { anchorRole: a.role, anchorName: a.ariaLabel }
+    };
+  }
+  if (a.role && a.roleCount === 1) {
+    return { code: `getByRole('${escStr(a.role)}')`, kind: "role", flatArgs: { anchorRole: a.role } };
+  }
+  return null;
+}
+function generateAnchoredAlternatives(leaf, anchors, chainLeafCount) {
+  if (!leaf.role || anchors.length === 0) return [];
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const rolePart = leaf.level != null ? `'${leaf.role}', { level: ${leaf.level} }` : `'${leaf.role}'`;
+  const leafArgs = leaf.level != null ? { role: leaf.role, level: leaf.level } : { role: leaf.role };
+  const add = (l) => {
+    if (!seen.has(l.locator)) {
+      seen.add(l.locator);
+      out.push(l);
+    }
+  };
+  for (const anchor of anchors) {
+    if (anchor.scopedLeafCount !== 1) continue;
+    const seg = anchorSegment(anchor);
+    if (!seg) continue;
+    add({
+      locator: `${seg.code}.getByRole(${rolePart})`,
+      method: "getByRole",
+      args: { ...leafArgs, ...seg.flatArgs },
+      score: ANCHOR_KIND_SCORES[seg.kind]
+    });
+  }
+  if (anchors.length >= 2 && chainLeafCount === 1) {
+    const ordered = [...anchors].sort((a, b) => b.depth - a.depth);
+    const segments = ordered.map(anchorSegment);
+    if (segments.every((s) => s !== null)) {
+      const innermost = segments[segments.length - 1];
+      const score = Math.min(...segments.map((s) => ANCHOR_KIND_SCORES[s.kind]));
+      add({
+        locator: `${segments.map((s) => s.code).join(".")}.getByRole(${rolePart})`,
+        method: "getByRole",
+        // Flat args describe the innermost anchor (what the healing fingerprint
+        // logic understands); the full chain rides along for transparency.
+        args: { ...leafArgs, ...innermost.flatArgs, anchorChain: segments.map((s) => s.code) },
+        score
+      });
+    }
+  }
+  return out.sort((a, b) => b.score - a.score);
+}
+function mergeCandidates(base, extra) {
+  const seen = new Set(base.map((b) => b.locator));
+  const merged = [...base];
+  for (const e of extra) {
+    if (seen.has(e.locator)) continue;
+    seen.add(e.locator);
+    merged.push(e);
+  }
+  return merged.sort((a, b) => b.score - a.score);
+}
+function installPickerOverlay(arg) {
+  const g = globalThis;
+  const doc = g.document;
+  if (!doc || !doc.body) {
+    g.__piwiPickState = "skipped";
+    return;
+  }
+  const Z = 2147483600;
+  const highlight = doc.createElement("div");
+  highlight.style.cssText = `position:fixed;pointer-events:none;z-index:${Z};display:none;box-sizing:border-box;border:2px solid #7c3aed;background:rgba(124,58,237,.12);border-radius:3px;`;
+  const banner = doc.createElement("div");
+  banner.style.cssText = `position:fixed;top:12px;left:50%;transform:translateX(-50%);z-index:${Z + 2};background:#111827;color:#f9fafb;font:13px/1.5 system-ui,sans-serif;padding:10px 16px;border-radius:8px;box-shadow:0 4px 24px rgba(0,0,0,.4);max-width:80vw;`;
+  const hlLocator = (expr) => {
+    const escHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    const re = /('(?:\\.|[^'])*'|"(?:\\.|[^"])*")|([A-Za-z_$][\w$]*)(?=\s*\()|([A-Za-z_$][\w$]*)(?=\s*:)|(true|false|null|\d+)|([{}(),.])/g;
+    let html = "";
+    let last = 0;
+    let m;
+    while ((m = re.exec(expr)) !== null) {
+      if (m.index > last) html += escHtml(expr.slice(last, m.index));
+      const color = m[1] ? "#4ade80" : m[2] ? "#c084fc" : m[3] ? "#93c5fd" : m[4] ? "#fbbf24" : "#9ca3af";
+      html += `<span style="color:${color}">${escHtml(m[0])}</span>`;
+      last = re.lastIndex;
+    }
+    if (last < expr.length) html += escHtml(expr.slice(last));
+    return `<code style="font-family:ui-monospace,SFMono-Regular,Menlo,monospace">${html}</code>`;
+  };
+  const head = doc.createElement("div");
+  head.innerHTML = arg.failing ? `Piwi locator picker \u2014 click the element that should replace ${hlLocator(arg.failing)}` : "Piwi inspector \u2014 click any element to generate locators for it";
+  const foot = doc.createElement("div");
+  foot.style.cssText = "color:#9ca3af;margin-top:3px;";
+  foot.textContent = "\u2191 parent \xB7 \u2193 child \xB7 Esc skip";
+  banner.appendChild(head);
+  banner.appendChild(foot);
+  doc.body.appendChild(highlight);
+  doc.body.appendChild(banner);
+  const escJs = (s) => s.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+  const describe = (el) => {
+    const tag = (el.tagName || "?").toLowerCase();
+    const testId = el.getAttribute && el.getAttribute("data-testid");
+    if (testId) return `getByTestId('${escJs(testId)}')`;
+    if (el.labels && el.labels.length > 0) {
+      const labelText = (el.labels[0].textContent || "").replace(/\s+/g, " ").trim().slice(0, 80);
+      if (labelText) return `getByLabel('${escJs(labelText)}')`;
+    }
+    const ariaLabel = el.getAttribute && el.getAttribute("aria-label");
+    if (ariaLabel) return `getByLabel('${escJs(ariaLabel)}')`;
+    const placeholder = el.getAttribute && el.getAttribute("placeholder");
+    if (placeholder) return `getByPlaceholder('${escJs(placeholder)}')`;
+    const alt = el.getAttribute && el.getAttribute("alt");
+    if (alt) return `getByAltText('${escJs(alt)}')`;
+    const titleAttr = el.getAttribute && el.getAttribute("title");
+    if (titleAttr) return `getByTitle('${escJs(titleAttr)}')`;
+    if (el.id) return `locator('#${escJs(el.id)}')`;
+    const cls = (el.getAttribute && el.getAttribute("class") || "").split(/\s+/).find((c) => c.length > 1);
+    return cls ? `locator('.${escJs(cls)}')` : tag;
+  };
+  const buildChain = (raw) => {
+    const chain2 = [];
+    let node = raw;
+    while (node && chain2.length < 15) {
+      const tag = (node.tagName || "").toLowerCase();
+      if (tag === "body" || tag === "html") break;
+      chain2.push(node);
+      node = node.parentElement;
+    }
+    return chain2.length ? chain2 : [raw];
+  };
+  const ACTIONABLE_TAGS = ["button", "a", "input", "select", "textarea", "summary", "option"];
+  const snapIndex = (chain2) => {
+    for (let i = 0; i < Math.min(chain2.length, 4); i++) {
+      const el = chain2[i];
+      const tag = (el.tagName || "").toLowerCase();
+      if (ACTIONABLE_TAGS.includes(tag)) return i;
+      if (el.getAttribute && (el.getAttribute("role") || el.getAttribute("data-testid"))) return i;
+    }
+    return 0;
+  };
+  let chain = [];
+  let idx = 0;
+  let lastRaw = null;
+  const current = () => chain[idx] ?? null;
+  const refresh = () => {
+    const el = current();
+    if (!el) {
+      highlight.style.display = "none";
+      return;
+    }
+    const r = el.getBoundingClientRect();
+    highlight.style.display = "block";
+    highlight.style.left = r.left + "px";
+    highlight.style.top = r.top + "px";
+    highlight.style.width = r.width + "px";
+    highlight.style.height = r.height + "px";
+    foot.textContent = `${describe(el)} \u2014 click to pick \xB7 \u2191 parent \xB7 \u2193 child \xB7 Esc skip`;
+  };
+  const stop = (e) => {
+    e.preventDefault();
+    e.stopImmediatePropagation();
+  };
+  const isOwn = (el) => el === banner || el === highlight || banner.contains && banner.contains(el);
+  let bannerDocked = "top";
+  const dockBanner = (side) => {
+    if (bannerDocked === side) return;
+    bannerDocked = side;
+    if (side === "bottom") {
+      banner.style.top = "auto";
+      banner.style.bottom = "12px";
+    } else {
+      banner.style.top = "12px";
+      banner.style.bottom = "auto";
+    }
+  };
+  const onMove = (e) => {
+    const raw = e.target;
+    if (!raw || isOwn(raw)) {
+      highlight.style.display = "none";
+      return;
+    }
+    if (raw !== lastRaw) {
+      lastRaw = raw;
+      chain = buildChain(raw);
+      idx = snapIndex(chain);
+    }
+    refresh();
+    const el = current();
+    if (el) {
+      const r = el.getBoundingClientRect();
+      const br = banner.getBoundingClientRect();
+      const margin = 8;
+      if (r.left < br.right + margin && r.right > br.left - margin && r.top < br.bottom + margin && r.bottom > br.top - margin) {
+        dockBanner(bannerDocked === "top" ? "bottom" : "top");
+      }
+    }
+  };
+  const onClick = (e) => {
+    stop(e);
+    const el = current();
+    if (!el || isOwn(e.target)) return;
+    g.__piwiPickedElement = el;
+    g.__piwiPickState = "picked";
+    removeListeners();
+    highlight.style.display = "none";
+    foot.textContent = "Analyzing element\u2026";
+  };
+  const onKey = (e) => {
+    if (e.key === "Escape") {
+      stop(e);
+      g.__piwiPickState = "skipped";
+      cleanup();
+      return;
+    }
+    if (e.key === "ArrowUp" || e.key === "ArrowDown") {
+      stop(e);
+      if (e.key === "ArrowUp") idx = Math.min(idx + 1, chain.length - 1);
+      else idx = Math.max(idx - 1, 0);
+      refresh();
+    }
+  };
+  const suppressed = ["mousedown", "mouseup", "pointerdown", "pointerup", "auxclick", "dblclick"];
+  const removeListeners = () => {
+    doc.removeEventListener("mousemove", onMove, true);
+    doc.removeEventListener("click", onClick, true);
+    doc.removeEventListener("keydown", onKey, true);
+    for (const t of suppressed) doc.removeEventListener(t, stop, true);
+  };
+  const cleanup = () => {
+    removeListeners();
+    highlight.remove();
+    banner.remove();
+  };
+  g.__piwiPickCleanup = cleanup;
+  doc.addEventListener("mousemove", onMove, true);
+  doc.addEventListener("click", onClick, true);
+  doc.addEventListener("keydown", onKey, true);
+  for (const t of suppressed) doc.addEventListener(t, stop, true);
+}
+function showAnchorPicker(arg) {
+  const g = globalThis;
+  const doc = g.document;
+  const el = g.__piwiPickedElement;
+  if (!doc || !doc.body || !el) {
+    g.__piwiAnchorState = "skipped";
+    return;
+  }
+  const Z = 2147483600;
+  const { tagRoles, inputRoles, roleSources, leafRole, leafLevel, leafTestId } = arg;
+  const roleOf = (n) => {
+    const explicit = n.getAttribute && n.getAttribute("role");
+    if (explicit) return explicit;
+    const tag = (n.tagName || "").toLowerCase();
+    if (tag === "input") return inputRoles[(n.getAttribute("type") || "text").toLowerCase()] ?? "textbox";
+    if (tag === "select") return n.getAttribute("multiple") != null ? "listbox" : "combobox";
+    if (tag === "a") return n.getAttribute("href") != null ? "link" : null;
+    return tagRoles[tag] ?? null;
+  };
+  const levelOf = (n) => {
+    const m = /^h([1-6])$/.exec((n.tagName || "").toLowerCase());
+    if (m) return Number(m[1]);
+    const al = n.getAttribute && n.getAttribute("aria-level");
+    return al && /^\d+$/.test(al) ? Number(al) : null;
+  };
+  const leafMatches = (scope) => {
+    try {
+      if (leafTestId) return scope.querySelectorAll(`[data-testid=${JSON.stringify(leafTestId)}]`).length;
+      const nodes = scope.querySelectorAll(roleSources);
+      if (nodes.length > 2e3) return -1;
+      let matched = 0;
+      for (let i = 0; i < nodes.length; i++) {
+        const n = nodes[i];
+        if (roleOf(n) !== leafRole) continue;
+        if (leafLevel != null && levelOf(n) !== leafLevel) continue;
+        matched++;
+      }
+      return matched;
+    } catch {
+      return -1;
+    }
+  };
+  let roleNodes = [];
+  try {
+    const all = doc.querySelectorAll(roleSources);
+    if (all.length <= 4e3) roleNodes = Array.from(all);
+  } catch {
+    roleNodes = [];
+  }
+  const count = (sel) => {
+    try {
+      return doc.querySelectorAll(sel).length;
+    } catch {
+      return void 0;
+    }
+  };
+  const rows = [];
+  let node = el.parentElement;
+  let depth = 0;
+  while (node && depth < 12) {
+    depth++;
+    const tag = (node.tagName || "").toLowerCase();
+    if (tag === "body" || tag === "html") break;
+    const testId = node.getAttribute("data-testid");
+    const id = node.getAttribute("id");
+    const ariaLabel = node.getAttribute("aria-label");
+    const role = roleOf(node);
+    const info = { tag, depth, testId: testId || null, id: id || null, ariaLabel: ariaLabel || null, role };
+    if (testId) info.testIdCount = count(`[data-testid=${JSON.stringify(testId)}]`);
+    if (id) {
+      try {
+        info.idCount = count(`#${doc.defaultView.CSS.escape(id)}`);
+      } catch {
+      }
+    }
+    if (role) {
+      let roleCount = 0;
+      let labeledCount = 0;
+      for (const n of roleNodes) {
+        if (roleOf(n) !== role) continue;
+        roleCount++;
+        if (ariaLabel && n.getAttribute && n.getAttribute("aria-label") === ariaLabel) labeledCount++;
+      }
+      info.roleCount = roleCount;
+      if (ariaLabel) info.labeledRoleCount = labeledCount;
+    }
+    info.scopedLeafCount = leafMatches(node);
+    const hookLabel = testId ? `data-testid="${testId}"` : id ? `#${id}` : ariaLabel && role ? `${role} "${ariaLabel}"` : role ? `role ${role}` : "no stable hook";
+    rows.push({
+      node,
+      info,
+      hookLabel,
+      selectable: !!(testId || id || role && (ariaLabel || info.roleCount === 1))
+    });
+    node = node.parentElement;
+  }
+  if (rows.length === 0) {
+    g.__piwiAnchorState = "skipped";
+    return;
+  }
+  const outline = doc.createElement("div");
+  outline.style.cssText = `position:fixed;pointer-events:none;z-index:${Z};box-sizing:border-box;border:2px solid #22c55e;border-radius:3px;display:none;`;
+  const pickedOutline = doc.createElement("div");
+  const pr = el.getBoundingClientRect();
+  pickedOutline.style.cssText = `position:fixed;pointer-events:none;z-index:${Z};box-sizing:border-box;border:2px solid #7c3aed;background:rgba(124,58,237,.10);border-radius:3px;left:${pr.left}px;top:${pr.top}px;width:${pr.width}px;height:${pr.height}px;`;
+  const panel = doc.createElement("div");
+  panel.style.cssText = `position:fixed;top:12px;right:12px;z-index:${Z + 3};width:340px;max-height:82vh;overflow:auto;background:#111827;color:#f9fafb;border-radius:10px;padding:16px;font:12px/1.5 system-ui,sans-serif;box-shadow:0 8px 40px rgba(0,0,0,.5);`;
+  const title = doc.createElement("div");
+  title.style.cssText = "font-weight:600;font-size:13px;margin-bottom:2px;";
+  title.textContent = "Scope to stable parents (optional)";
+  const sub = doc.createElement("div");
+  sub.style.cssText = "color:#9ca3af;margin-bottom:10px;";
+  sub.textContent = "Pick one or more parents to anchor the locator to. Hover a row to see the parent.";
+  panel.appendChild(title);
+  panel.appendChild(sub);
+  const selected = /* @__PURE__ */ new Set();
+  const footer = doc.createElement("div");
+  footer.style.cssText = "margin:10px 0;font-weight:600;";
+  const segMatches = (scope, info) => {
+    try {
+      if (info.testId) return Array.from(scope.querySelectorAll(`[data-testid=${JSON.stringify(info.testId)}]`));
+      if (info.id) return Array.from(scope.querySelectorAll(`#${doc.defaultView.CSS.escape(info.id)}`));
+      const nodes = Array.from(scope.querySelectorAll(roleSources));
+      if (nodes.length > 2e3) return [];
+      return nodes.filter(
+        (n) => roleOf(n) === info.role && (!info.ariaLabel || n.getAttribute && n.getAttribute("aria-label") === info.ariaLabel)
+      );
+    } catch {
+      return [];
+    }
+  };
+  const chainCount = () => {
+    const chosen = rows.filter((_, i) => selected.has(i)).sort((a, b) => b.info.depth - a.info.depth);
+    if (chosen.length === 0) return -1;
+    let scopes = [doc];
+    for (const row of chosen) {
+      const next = [];
+      for (const s of scopes) next.push(...segMatches(s, row.info));
+      scopes = next.slice(0, 200);
+      if (scopes.length === 0) return 0;
+    }
+    let total = 0;
+    for (const s of scopes) {
+      const c = leafMatches(s);
+      if (c > 0) total += c;
+      if (total > 50) return total;
+    }
+    return total;
+  };
+  const refreshFooter = () => {
+    if (selected.size === 0) {
+      footer.textContent = "No parents selected \u2014 standard alternatives only.";
+      footer.style.color = "#9ca3af";
+      g.__piwiPickChainCount = void 0;
+      return;
+    }
+    const c = chainCount();
+    g.__piwiPickChainCount = c;
+    if (c === 1) {
+      footer.textContent = "\u2713 Selection matches exactly 1 element";
+      footer.style.color = "#4ade80";
+    } else {
+      footer.textContent = c < 0 ? "Match count unavailable" : `\u2717 Selection matches ${c} elements`;
+      footer.style.color = "#fbbf24";
+    }
+  };
+  rows.forEach((row, i) => {
+    const line = doc.createElement("label");
+    line.style.cssText = `display:flex;align-items:center;gap:8px;padding:6px 8px;border:1px solid #374151;border-radius:6px;margin-bottom:6px;cursor:${row.selectable ? "pointer" : "default"};opacity:${row.selectable ? "1" : ".45"};`;
+    const box = doc.createElement("input");
+    box.type = "checkbox";
+    box.disabled = !row.selectable;
+    const text = doc.createElement("span");
+    text.style.cssText = "flex:1;min-width:0;";
+    const code = doc.createElement("code");
+    code.style.cssText = "display:block;font:11px ui-monospace,monospace;color:#e5e7eb;word-break:break-all;";
+    code.textContent = `<${row.info.tag}> ${row.hookLabel}`;
+    const hint = doc.createElement("span");
+    hint.style.cssText = "color:#9ca3af;";
+    hint.textContent = row.selectable ? row.info.scopedLeafCount === 1 ? "contains exactly 1 matching element" : `contains ${row.info.scopedLeafCount ?? "?"} matching elements` : "add a data-testid to make this usable";
+    text.appendChild(code);
+    text.appendChild(hint);
+    line.appendChild(box);
+    line.appendChild(text);
+    line.addEventListener("mouseenter", () => {
+      const r = row.node.getBoundingClientRect();
+      outline.style.display = "block";
+      outline.style.left = r.left + "px";
+      outline.style.top = r.top + "px";
+      outline.style.width = r.width + "px";
+      outline.style.height = r.height + "px";
+    });
+    line.addEventListener("mouseleave", () => {
+      outline.style.display = "none";
+    });
+    box.addEventListener("change", () => {
+      if (box.checked) selected.add(i);
+      else selected.delete(i);
+      refreshFooter();
+    });
+    panel.appendChild(line);
+  });
+  panel.appendChild(footer);
+  const cleanup = () => {
+    doc.removeEventListener("keydown", onKey, true);
+    panel.remove();
+    outline.remove();
+    pickedOutline.remove();
+  };
+  const done = (state) => {
+    g.__piwiPickAnchors = state === "done" ? rows.filter((_, i) => selected.has(i)).map((r) => r.info) : [];
+    g.__piwiAnchorState = state;
+    cleanup();
+  };
+  const onKey = (e) => {
+    if (e.key !== "Escape") return;
+    e.preventDefault();
+    e.stopImmediatePropagation();
+    done("skipped");
+  };
+  const buttonRow = doc.createElement("div");
+  buttonRow.style.cssText = "display:flex;gap:8px;margin-top:4px;";
+  const useBtn = doc.createElement("button");
+  useBtn.style.cssText = "flex:1;background:#7c3aed;color:#fff;border:none;border-radius:6px;padding:8px;cursor:pointer;font:600 12px system-ui;";
+  useBtn.textContent = "Use selected parents";
+  useBtn.addEventListener("click", (e) => {
+    e.preventDefault();
+    e.stopImmediatePropagation();
+    done(selected.size > 0 ? "done" : "skipped");
+  });
+  const skipBtn = doc.createElement("button");
+  skipBtn.style.cssText = "background:none;border:1px solid #374151;color:#9ca3af;border-radius:6px;padding:8px 10px;cursor:pointer;font:12px system-ui;";
+  skipBtn.textContent = "Skip (Esc)";
+  skipBtn.addEventListener("click", (e) => {
+    e.preventDefault();
+    e.stopImmediatePropagation();
+    done("skipped");
+  });
+  buttonRow.appendChild(useBtn);
+  buttonRow.appendChild(skipBtn);
+  panel.appendChild(buttonRow);
+  refreshFooter();
+  g.__piwiAnchorCleanup = cleanup;
+  doc.addEventListener("keydown", onKey, true);
+  doc.body.appendChild(pickedOutline);
+  doc.body.appendChild(outline);
+  doc.body.appendChild(panel);
+}
+function showPickerChoices(arg) {
+  const g = globalThis;
+  const doc = g.document;
+  if (!doc || !doc.body) {
+    g.__piwiPickChoice = -1;
+    return;
+  }
+  const Z = 2147483600;
+  const wrap = doc.createElement("div");
+  wrap.style.cssText = `position:fixed;inset:0;z-index:${Z + 3};background:rgba(0,0,0,.45);display:flex;align-items:center;justify-content:center;font:13px/1.5 system-ui,sans-serif;`;
+  const panel = doc.createElement("div");
+  panel.style.cssText = "background:#111827;color:#f9fafb;border-radius:10px;padding:20px;max-width:640px;width:90vw;max-height:70vh;overflow:auto;box-shadow:0 8px 40px rgba(0,0,0,.5);";
+  const hlLocator = (expr) => {
+    const escHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+    const re = /('(?:\\.|[^'])*'|"(?:\\.|[^"])*")|([A-Za-z_$][\w$]*)(?=\s*\()|([A-Za-z_$][\w$]*)(?=\s*:)|(true|false|null|\d+)|([{}(),.])/g;
+    let html = "";
+    let last = 0;
+    let m;
+    while ((m = re.exec(expr)) !== null) {
+      if (m.index > last) html += escHtml(expr.slice(last, m.index));
+      const color = m[1] ? "#4ade80" : m[2] ? "#c084fc" : m[3] ? "#93c5fd" : m[4] ? "#fbbf24" : "#9ca3af";
+      html += `<span style="color:${color}">${escHtml(m[0])}</span>`;
+      last = re.lastIndex;
+    }
+    if (last < expr.length) html += escHtml(expr.slice(last));
+    return html;
+  };
+  const title = doc.createElement("div");
+  title.style.cssText = "font-weight:600;margin-bottom:4px;";
+  title.textContent = arg.failing ? "Pick a replacement locator" : "Pick a locator";
+  const sub = doc.createElement("div");
+  sub.style.cssText = "color:#9ca3af;margin-bottom:12px;";
+  if (arg.failing) {
+    sub.innerHTML = `Replaces <code style="font-family:ui-monospace,Menlo,monospace">${hlLocator(arg.failing)}</code> \u2014 ranked by stability score.`;
+  } else {
+    sub.textContent = "For the element you picked \u2014 ranked by stability score.";
+  }
+  panel.appendChild(title);
+  panel.appendChild(sub);
+  const done = (choice) => {
+    g.__piwiPickChoice = choice;
+    doc.removeEventListener("keydown", onKey, true);
+    wrap.remove();
+  };
+  const onKey = (e) => {
+    if (e.key !== "Escape") return;
+    e.preventDefault();
+    e.stopImmediatePropagation();
+    done(-1);
+  };
+  arg.choices.forEach((c, i) => {
+    const btn = doc.createElement("button");
+    btn.style.cssText = "display:flex;justify-content:space-between;align-items:center;gap:12px;width:100%;text-align:left;background:#1f2937;color:#e5e7eb;border:1px solid #374151;border-radius:6px;padding:8px 12px;margin:0 0 8px;cursor:pointer;font:12px/1.5 ui-monospace,SFMono-Regular,Menlo,monospace;";
+    const code = doc.createElement("span");
+    code.innerHTML = hlLocator(c.locator);
+    code.style.cssText = "word-break:break-all;";
+    const score = doc.createElement("span");
+    score.textContent = String(c.score);
+    score.style.cssText = "color:#a78bfa;flex-shrink:0;";
+    btn.appendChild(code);
+    btn.appendChild(score);
+    btn.addEventListener("click", (e) => {
+      e.preventDefault();
+      e.stopImmediatePropagation();
+      done(i);
+    });
+    panel.appendChild(btn);
+  });
+  const skip = doc.createElement("button");
+  skip.style.cssText = "background:none;border:none;color:#9ca3af;cursor:pointer;padding:6px 0 0;font:12px system-ui,sans-serif;";
+  skip.textContent = "Skip \u2014 keep the failure as-is (Esc)";
+  skip.addEventListener("click", (e) => {
+    e.preventDefault();
+    e.stopImmediatePropagation();
+    done(-1);
+  });
+  panel.appendChild(skip);
+  doc.addEventListener("keydown", onKey, true);
+  wrap.appendChild(panel);
+  doc.body.appendChild(wrap);
+}
+async function cleanupPicker(page) {
+  try {
+    await page.evaluate(() => {
+      const g = globalThis;
+      if (typeof g.__piwiPickCleanup === "function") g.__piwiPickCleanup();
+      if (typeof g.__piwiAnchorCleanup === "function") g.__piwiAnchorCleanup();
+      delete g.__piwiPickCleanup;
+      delete g.__piwiAnchorCleanup;
+      delete g.__piwiPickState;
+      delete g.__piwiPickChoice;
+      delete g.__piwiPickedElement;
+      delete g.__piwiAnchorState;
+      delete g.__piwiPickAnchors;
+      delete g.__piwiPickChainCount;
+    });
+  } catch {
+  }
+}
+async function runLocatorPicker(page, testInfo, failed, probe) {
+  try {
+    testInfo.setTimeout(0);
+    const rendered = failed ? renderFailing(failed) : null;
+    console.log(
+      `
+[piwi] "${testInfo.title}" ${testInfo.status} \u2014 ${rendered ? "locator picker" : "inspector"} open in the browser: ${rendered ? `click the element that should replace ${rendered}` : "click any element to generate locators for it"} (\u2191/\u2193 to select a parent/child, Esc to skip).`
+    );
+    await page.evaluate(installPickerOverlay, { failing: rendered });
+    await page.waitForFunction(() => globalThis.__piwiPickState !== void 0, void 0, {
+      timeout: 0,
+      polling: 250
+    });
+    const state = await page.evaluate(() => globalThis.__piwiPickState);
+    if (state !== "picked") {
+      await cleanupPicker(page);
+      return null;
+    }
+    const handle = await page.evaluateHandle(() => globalThis.__piwiPickedElement);
+    const attrs = await handle.evaluate(probe.fn, probe.arg);
+    await handle.dispose();
+    const accessibleName = approximateAccessibleName({ ...attrs, accessibleName: null });
+    const role = resolveAriaRole({ ...attrs, accessibleName });
+    const level = headingLevel({ ...attrs, accessibleName }, role);
+    let anchors = [];
+    let chainLeafCount;
+    if (role) {
+      const probeArg = probe.arg;
+      await page.evaluate(showAnchorPicker, {
+        tagRoles: probeArg.tagRoles,
+        inputRoles: probeArg.inputRoles,
+        roleSources: probeArg.roleSources,
+        leafRole: role,
+        leafLevel: level,
+        leafTestId: attrs.attributes["data-testid"] ?? null
+      });
+      await page.waitForFunction(() => globalThis.__piwiAnchorState !== void 0, void 0, {
+        timeout: 0,
+        polling: 250
+      });
+      const anchorResult = await page.evaluate(() => {
+        const g = globalThis;
+        return { state: g.__piwiAnchorState, anchors: g.__piwiPickAnchors ?? [], chainCount: g.__piwiPickChainCount };
+      });
+      if (anchorResult.state === "done" && anchorResult.anchors.length > 0) {
+        anchors = anchorResult.anchors;
+        chainLeafCount = anchorResult.chainCount;
+      }
+    }
+    const ranked = mergeCandidates(
+      generateAlternatives({ ...attrs, accessibleName }),
+      generateAnchoredAlternatives({ role, level }, anchors, chainLeafCount)
+    );
+    if (ranked.length === 0) {
+      console.log("[piwi] No stable locator could be generated for the picked element \u2014 nothing recorded.");
+      await cleanupPicker(page);
+      return null;
+    }
+    await page.evaluate(showPickerChoices, {
+      failing: rendered,
+      choices: ranked.map((r) => ({ locator: r.locator, score: r.score }))
+    });
+    await page.waitForFunction(() => globalThis.__piwiPickChoice !== void 0, void 0, {
+      timeout: 0,
+      polling: 250
+    });
+    const choice = await page.evaluate(() => globalThis.__piwiPickChoice);
+    await cleanupPicker(page);
+    if (typeof choice !== "number" || choice < 0 || choice >= ranked.length) return null;
+    const picked = { ...ranked[choice], pickedByUser: true };
+    const alternatives = [picked, ...ranked.filter((_, i) => i !== choice)];
+    const element = {
+      tagName: attrs.tagName,
+      attributes: attrs.attributes,
+      textContent: attrs.textContent,
+      accessibleName,
+      center: attrs.center,
+      ...attrs.rolePosition ? { rolePosition: attrs.rolePosition } : {},
+      ...attrs.ancestors && attrs.ancestors.length > 0 ? { ancestors: attrs.ancestors } : {}
+    };
+    const location = failed?.location ?? null;
+    console.log(
+      failed ? `[piwi] Replacement picked for ${rendered}${location ? ` at ${location}` : ""}:
+[piwi]   ${picked.locator}` : `[piwi] Locator picked while inspecting:
+[piwi]   ${picked.locator}`
+    );
+    return {
+      failing: failed ? { method: failed.method, args: failed.args, rendered, location } : null,
+      picked,
+      alternatives,
+      element,
+      ...anchors.length > 0 ? { anchors } : {}
+    };
+  } catch {
+    return null;
+  }
+}
+function applyPickToSnapshots(snapshots, pick) {
+  if (!pick.failing?.location) return false;
+  const failing = pick.failing;
+  for (let i = snapshots.length - 1; i >= 0; i--) {
+    const snap = snapshots[i];
+    if (snap.location !== failing.location || snap.element) continue;
+    snapshots[i] = {
+      location: snap.location,
+      used: snap.used,
+      element: pick.element,
+      alternatives: pick.alternatives.slice(0, 10)
+    };
+    return true;
+  }
+  snapshots.push({
+    location: failing.location,
+    used: {
+      method: failing.method,
+      args: failing.args,
+      raw: `${failing.method}(${JSON.stringify(failing.args)})`
+    },
+    element: pick.element,
+    alternatives: pick.alternatives.slice(0, 10)
+  });
+  return true;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  applyPickToSnapshots,
+  deriveFailedLocator,
+  generateAnchoredAlternatives,
+  installPickerOverlay,
+  mergeCandidates,
+  parseLeafLocatorExpression,
+  runLocatorPicker,
+  showAnchorPicker,
+  showPickerChoices
+});