@metamask/client-mcp-core 0.1.0

package/dist/mcp-server/discovery.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.cjs","sourceRoot":"","sources":["../../src/mcp-server/discovery.ts"],"names":[],"mappings":";;AA6CA,sDAoDC;AAuED,wCA0CC;AASD,gEAsFC;AAuBD,sCA0BC;AAYD,sCAUC;AAtXD,kDAAyD;AAOzD,6CAAyC;AACzC,6CAAoC;AAEpC,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAS,sBAAc,CAAC,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,MAAM,YAAY,GAChB,uGAAuG,CAAC;AAE1G;;GAEG;AACH,MAAM,OAAO,GAAG,+CAA+C,CAAC;AAEhE;;;;;;;;;;;GAWG;AACH,SAAgB,qBAAqB,CAAC,IAAY;IAChD,IAAI,CAAC,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;QAClB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAkB,EAAE,CAAC;IAChC,MAAM,KAAK,GAA4C,EAAE,CAAC;IAE1D,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACjB,SAAS;QACX,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;QAE7C,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,SAAS;QACX,CAAC;QAED,MAAM,UAAU,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;QAErC,IAAI,UAAU,CAAC,UAAU,CAAC,OAAO,CAAC,IAAI,UAAU,KAAK,MAAM,EAAE,CAAC;YAC5D,SAAS;QACX,CAAC;QAED,IAAI,UAAU,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC/B,SAAS;QACX,CAAC;QAED,MAAM,IAAI,GAAG,uBAAuB,CAAC,UAAU,CAAC,CAAC;QACjD,IAAI,CAAC,IAAI,EAAE,CAAC;YACV,SAAS;QACX,CAAC;QAED,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,MAAM,IAAI,MAAM,EAAE,CAAC;YACpE,KAAK,CAAC,GAAG,EAAE,CAAC;QACd,CAAC;QAED,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACvB,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACnB,CAAC;aAAM,CAAC;YACN,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;YAC5C,MAAM,CAAC,QAAQ,KAAf,MAAM,CAAC,QAAQ,GAAK,EAAE,EAAC;YACvB,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC7B,CAAC;QAED,KAAK,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC;IAC/B,CAAC;IAED,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,SAAS,uBAAuB,CAAC,UAAkB;IACjD,IAAI,IAAI,GAAG,UAAU,CAAC;IAEtB,0EAA0E;IAC1E,MAAM,kBAAkB,GAAG,IAAI,CAAC,KAAK,CACnC,uFAAuF,CACxF,CAAC;IACF,IAAI,kBAAkB,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QACrC,IAAI,GAAG,kBAAkB,CAAC,MAAM,CAAC,IAAI,CAAC;IACxC,CAAC;IAED,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACtC,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,CAAC;QACnB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,EAAE,IAAI,EAAE,GAAG,KAAK,CAAC,MAAM,CAAC;IAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC;IAElC,MAAM,IAAI,GAAgB,EAAE,IAAI,EAAE,CAAC;IAEnC,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACpE,CAAC;IAED,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC;IACpC,IAAI,QAAQ,EAAE,CAAC;QACb,IAAI,SAAS,CAAC;QACd,OAAO,CAAC,SAAS,GAAG,CAAC,CAAC;QACtB,OAAO,CAAC,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACrD,MAAM,GAAG,GAAG,SAAS,CAAC,MAAM,EAAE,GAAG,CAAC;YAClC,MAAM,KAAK,GAAG,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC;YAEtC,QAAQ,GAAG,EAAE,CAAC;gBACZ,KAAK,UAAU;oBACb,IAAI,CAAC,QAAQ,GAAG,KAAK,KAAK,OAAO,CAAC;oBAClC,MAAM;gBACR,KAAK,SAAS;oBACZ,IAAI,KAAK,KAAK,OAAO,EAAE,CAAC;wBACtB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;oBACzB,CAAC;yBAAM,CAAC;wBACN,IAAI,CAAC,OAAO,GAAG,KAAK,KAAK,OAAO,CAAC;oBACnC,CAAC;oBACD,MAAM;gBACR,KAAK,UAAU;oBACb,IAAI,CAAC,QAAQ,GAAG,KAAK,KAAK,OAAO,CAAC;oBAClC,MAAM;gBACR;oBACE,MAAM;YACV,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,cAAc,CAClC,IAAU,EACV,QAAgB,GAAG;IAEnB,MAAM,IAAI,CAAC,gBAAgB,CAAC,kBAAkB,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;IAEvE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,CAAC,GAAG,EAAE,CAAC;IAC3D,MAAM,OAAO,GAAiB,EAAE,CAAC;IAEjC,KAAK,MAAM,OAAO,IAAI,QAAQ,EAAE,CAAC;QAC/B,IAAI,OAAO,CAAC,MAAM,IAAI,KAAK,EAAE,CAAC;YAC5B,MAAM;QACR,CAAC;QAED,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,YAAY,CAAC,aAAa,CAAC,CAAC;YACzD,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,SAAS;YACX,CAAC;YAED,MAAM,SAAS,GAAG,MAAM,OAAO,CAAC,SAAS,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,CAAC;YAC/D,MAAM,WAAW,GAAG,MAAM,OAAO;iBAC9B,WAAW,EAAE;iBACb,IAAI,CACH,CAAC,IAAI,EAAE,EAAE,CACP,IAAI,EAAE,IAAI,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,sCAAuB,CAAC,IAAI,SAAS,CAClE;iBACA,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;YAE1B,OAAO,CAAC,IAAI,CAAC;gBACX,MAAM;gBACN,GAAG,EAAE,SAAS;gBACd,IAAI,EAAE,WAAW;gBACjB,OAAO,EAAE,SAAS;aACnB,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAA,iBAAS,EAAC,0BAA0B,EAAE,KAAK,CAAC,CAAC;YAC7C,SAAS;QACX,CAAC;IACH,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;GAMG;AACI,KAAK,UAAU,0BAA0B,CAC9C,IAAU,EACV,YAAqB;IAKrB,MAAM,OAAO,GAAG,YAAY;QAC1B,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,KAAK,EAAE;QACpC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC;IAEjC,MAAM,YAAY,GAAW,MAAM,OAAO,CAAC,YAAY,EAAE,CAAC;IAE1D,IAAI,CAAC,YAAY,EAAE,CAAC;QAClB,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;IAC1C,CAAC;IAED,MAAM,WAAW,GAAG,qBAAqB,CAAC,YAAY,CAAC,CAAC;IAExD,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC7B,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,GAAG,EAAE,EAAE,CAAC;IAC1C,CAAC;IAED,MAAM,YAAY,GAAsB,EAAE,CAAC;IAC3C,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB;;;;;OAKG;IACH,SAAS,YAAY,CAAC,IAAiB,EAAE,YAAsB;QAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC;QAC5C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;QAE7B,IAAI,kBAAkB,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACjC,MAAM,GAAG,GAAG,IAAI,UAAU,EAAE,CAAC;YAC7B,UAAU,IAAI,CAAC,CAAC;YAChB,MAAM,WAAW,GAAG,CAAC,GAAG,YAAY,CAAC,CAAC;YAEtC,IAAI,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS,EAAE,CAAC;gBAC5C,WAAW,CAAC,IAAI,CAAC,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC,CAAC;YACtC,CAAC;YAED,MAAM,WAAW,GAAoB;gBACnC,GAAG;gBACH,IAAI;gBACJ,IAAI;gBACJ,IAAI,EAAE,WAAW;aAClB,CAAC;YAEF,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAChC,WAAW,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;YACvC,CAAC;YACD,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;gBAC/B,WAAW,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,KAAK,IAAI,CAAC;YAC9C,CAAC;YACD,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;gBAChC,WAAW,CAAC,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;YACvC,CAAC;YAED,YAAY,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;YAE/B,MAAM,QAAQ,GAAG,iBAAiB,CAAC,IAAoB,EAAE,IAAI,CAAC,CAAC;YAC/D,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;QAC5B,CAAC;QAED,MAAM,WAAW,GACf,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,SAAS;YACrC,CAAC,CAAC,CAAC,GAAG,YAAY,EAAE,GAAG,IAAI,IAAI,IAAI,EAAE,CAAC;YACtC,CAAC,CAAC,YAAY,CAAC;QAEnB,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClB,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAClC,YAAY,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;IACH,CAAC;IAED,KAAK,MAAM,IAAI,IAAI,WAAW,EAAE,CAAC;QAC/B,YAAY,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;IACzB,CAAC;IAED,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC;AACzC,CAAC;AAED;;;;;;GAMG;AACH,SAAS,iBAAiB,CAAC,IAAkB,EAAE,IAAY;IACzD,MAAM,WAAW,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAC/C,OAAO,QAAQ,IAAI,UAAU,WAAW,IAAI,CAAC;AAC/C,CAAC;AAED;;;;;;;;GAQG;AACI,KAAK,UAAU,aAAa,CACjC,IAAU,EACV,UAA6C,EAC7C,WAAmB,EACnB,MAA2B;IAE3B,QAAQ,UAAU,EAAE,CAAC;QACnB,KAAK,SAAS,CAAC,CAAC,CAAC;YACf,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;YACzC,IAAI,CAAC,QAAQ,EAAE,CAAC;gBACd,MAAM,IAAI,KAAK,CACb,oBAAoB,WAAW,IAAI;oBACjC,mBAAmB,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAC5D,CAAC;YACJ,CAAC;YACD,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAChC,CAAC;QACD,KAAK,QAAQ;YACX,OAAO,IAAI,CAAC,OAAO,CAAC,iBAAiB,WAAW,IAAI,CAAC,CAAC;QACxD,KAAK,UAAU;YACb,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC;QACnC,OAAO,CAAC,CAAC,CAAC;YACR,MAAM,eAAe,GAAU,UAAU,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,wBAAwB,eAAyB,EAAE,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;AACH,CAAC;AAED;;;;;;;;;GASG;AACI,KAAK,UAAU,aAAa,CACjC,IAAU,EACV,UAA6C,EAC7C,WAAmB,EACnB,MAA2B,EAC3B,SAAiB;IAEjB,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;IAC3E,MAAM,OAAO,CAAC,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC,CAAC;IAChE,OAAO,OAAO,CAAC;AACjB,CAAC","sourcesContent":["import type { Page, Locator } from '@playwright/test';\n\nimport { TEXT_PREVIEW_MAX_LENGTH } from './constants.js';\nimport type {\n  TestIdItem,\n  A11yNodeTrimmed,\n  RawA11yNode,\n  IncludedRole,\n} from './types';\nimport { INCLUDED_ROLES } from './types';\nimport { debugWarn } from './utils';\n\nconst INCLUDED_ROLES_SET = new Set<string>(INCLUDED_ROLES);\n\n/**\n * Regular expression to parse a single ARIA snapshot line descriptor.\n *\n * Matches: `role` + optional `\"name\"` + optional `[attr]` / `[attr=value]` groups\n *\n * Examples:\n *   - `button \"Submit\"`\n *   - `heading \"Title\" [level=1]`\n *   - `checkbox \"Accept\" [checked]`\n *   - `listitem`\n */\nconst ARIA_LINE_RE =\n  /^(?<role>[a-zA-Z]+)(?:\\s+\"(?<name>(?:[^\"\\\\]|\\\\.)*)\")?(?<attrs>(?:\\s+\\[[^\\]]*\\])*)(?<hasChildren>:?)$/u;\n\n/**\n * Regular expression to match individual `[key]` or `[key=value]` attribute groups.\n */\nconst ATTR_RE = /\\[(?<key>[a-zA-Z]+)(?:=(?<value>[^\\]]*))?\\]/gu;\n\n/**\n * Parse a Playwright ariaSnapshot() YAML string into RawA11yNode[].\n *\n * The YAML format emitted by Playwright's `locator.ariaSnapshot()` (v1.49+)\n * is a line-based, indentation-structured tree where each node line is:\n *   `- role \"name\" [attr=value]:` (children follow indented)\n *   `- role \"name\" [attr=value]`  (leaf node)\n *   `- text: some text content`   (text node, ignored for our purposes)\n *\n * @param yaml The YAML string returned by Playwright's ariaSnapshot()\n * @returns Array of parsed RawA11yNode trees\n */\nexport function parseAriaSnapshotYaml(yaml: string): RawA11yNode[] {\n  if (!yaml?.trim()) {\n    return [];\n  }\n\n  const lines = yaml.split('\\n');\n  const roots: RawA11yNode[] = [];\n  const stack: { node: RawA11yNode; indent: number }[] = [];\n\n  for (const line of lines) {\n    if (!line.trim()) {\n      continue;\n    }\n\n    const stripped = line.replace(/^ */u, '');\n    const indent = line.length - stripped.length;\n\n    if (!stripped.startsWith('- ')) {\n      continue;\n    }\n\n    const descriptor = stripped.slice(2);\n\n    if (descriptor.startsWith('text:') || descriptor === 'text') {\n      continue;\n    }\n\n    if (descriptor.startsWith('/')) {\n      continue;\n    }\n\n    const node = parseAriaNodeDescriptor(descriptor);\n    if (!node) {\n      continue;\n    }\n\n    while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {\n      stack.pop();\n    }\n\n    if (stack.length === 0) {\n      roots.push(node);\n    } else {\n      const parent = stack[stack.length - 1].node;\n      parent.children ??= [];\n      parent.children.push(node);\n    }\n\n    stack.push({ node, indent });\n  }\n\n  return roots;\n}\n\n/**\n * Parse a single ARIA node descriptor string into a RawA11yNode.\n *\n * @param descriptor The descriptor after removing the `- ` prefix, e.g. `button \"Submit\" [disabled]:`\n * @returns A parsed node, or null if the descriptor cannot be parsed\n */\nfunction parseAriaNodeDescriptor(descriptor: string): RawA11yNode | null {\n  let desc = descriptor;\n\n  // Strip trailing `:` (children indicator) or `: text` (inline text value)\n  const trailingColonMatch = desc.match(\n    /^(?<main>(?:[a-zA-Z]+)(?:\\s+\"(?:[^\"\\\\]|\\\\.)*\")?(?:\\s+\\[[^\\]]*\\])*)(?::(?<text>.*))?$/u,\n  );\n  if (trailingColonMatch?.groups?.main) {\n    desc = trailingColonMatch.groups.main;\n  }\n\n  const match = ARIA_LINE_RE.exec(desc);\n  if (!match?.groups) {\n    return null;\n  }\n\n  const { role } = match.groups;\n  const rawName = match.groups.name;\n\n  const node: RawA11yNode = { role };\n\n  if (rawName !== undefined) {\n    node.name = rawName.replace(/\\\\\"/gu, '\"').replace(/\\\\\\\\/gu, '\\\\');\n  }\n\n  const attrsStr = match.groups.attrs;\n  if (attrsStr) {\n    let attrMatch;\n    ATTR_RE.lastIndex = 0;\n    while ((attrMatch = ATTR_RE.exec(attrsStr)) !== null) {\n      const key = attrMatch.groups?.key;\n      const value = attrMatch.groups?.value;\n\n      switch (key) {\n        case 'disabled':\n          node.disabled = value !== 'false';\n          break;\n        case 'checked':\n          if (value === 'mixed') {\n            node.checked = 'mixed';\n          } else {\n            node.checked = value !== 'false';\n          }\n          break;\n        case 'expanded':\n          node.expanded = value !== 'false';\n          break;\n        default:\n          break;\n      }\n    }\n  }\n\n  return node;\n}\n\n/**\n * Collect all visible test IDs from the current page.\n *\n * @param page The Playwright page to scan for test IDs\n * @param limit Maximum number of test IDs to return (default: 150)\n * @returns Array of test ID items with visibility and text content\n */\nexport async function collectTestIds(\n  page: Page,\n  limit: number = 150,\n): Promise<TestIdItem[]> {\n  await page.waitForLoadState('domcontentloaded').catch(() => undefined);\n\n  const locators = await page.locator('[data-testid]').all();\n  const results: TestIdItem[] = [];\n\n  for (const locator of locators) {\n    if (results.length >= limit) {\n      break;\n    }\n\n    try {\n      const testId = await locator.getAttribute('data-testid');\n      if (!testId) {\n        continue;\n      }\n\n      const isVisible = await locator.isVisible().catch(() => false);\n      const textContent = await locator\n        .textContent()\n        .then(\n          (text) =>\n            text?.trim().substring(0, TEXT_PREVIEW_MAX_LENGTH) ?? undefined,\n        )\n        .catch(() => undefined);\n\n      results.push({\n        testId,\n        tag: 'element',\n        text: textContent,\n        visible: isVisible,\n      });\n    } catch (error) {\n      debugWarn('discovery.collectTestIds', error);\n      continue;\n    }\n  }\n\n  return results;\n}\n\n/**\n * Collect a trimmed accessibility tree snapshot with deterministic refs.\n *\n * @param page The Playwright page to snapshot\n * @param rootSelector Optional CSS selector to scope the snapshot to a specific element\n * @returns Object containing trimmed accessibility nodes and a reference map (e1, e2, etc.)\n */\nexport async function collectTrimmedA11ySnapshot(\n  page: Page,\n  rootSelector?: string,\n): Promise<{\n  nodes: A11yNodeTrimmed[];\n  refMap: Map<string, string>;\n}> {\n  const locator = rootSelector\n    ? page.locator(rootSelector).first()\n    : page.locator('body').first();\n\n  const snapshotYaml: string = await locator.ariaSnapshot();\n\n  if (!snapshotYaml) {\n    return { nodes: [], refMap: new Map() };\n  }\n\n  const parsedRoots = parseAriaSnapshotYaml(snapshotYaml);\n\n  if (parsedRoots.length === 0) {\n    return { nodes: [], refMap: new Map() };\n  }\n\n  const trimmedNodes: A11yNodeTrimmed[] = [];\n  const refMap = new Map<string, string>();\n  let refCounter = 1;\n\n  /**\n   * Recursively traverse accessibility tree and collect included roles.\n   *\n   * @param node The current accessibility node to process\n   * @param ancestorPath The path of ancestor nodes for context\n   */\n  function traverseNode(node: RawA11yNode, ancestorPath: string[]): void {\n    const role = node.role?.toLowerCase() ?? '';\n    const name = node.name ?? '';\n\n    if (INCLUDED_ROLES_SET.has(role)) {\n      const ref = `e${refCounter}`;\n      refCounter += 1;\n      const currentPath = [...ancestorPath];\n\n      if (role === 'dialog' || role === 'heading') {\n        currentPath.push(`${role}:${name}`);\n      }\n\n      const trimmedNode: A11yNodeTrimmed = {\n        ref,\n        role,\n        name,\n        path: currentPath,\n      };\n\n      if (node.disabled !== undefined) {\n        trimmedNode.disabled = node.disabled;\n      }\n      if (node.checked !== undefined) {\n        trimmedNode.checked = node.checked === true;\n      }\n      if (node.expanded !== undefined) {\n        trimmedNode.expanded = node.expanded;\n      }\n\n      trimmedNodes.push(trimmedNode);\n\n      const selector = buildA11ySelector(role as IncludedRole, name);\n      refMap.set(ref, selector);\n    }\n\n    const updatedPath =\n      role === 'dialog' || role === 'heading'\n        ? [...ancestorPath, `${role}:${name}`]\n        : ancestorPath;\n\n    if (node.children) {\n      for (const child of node.children) {\n        traverseNode(child, updatedPath);\n      }\n    }\n  }\n\n  for (const root of parsedRoots) {\n    traverseNode(root, []);\n  }\n\n  return { nodes: trimmedNodes, refMap };\n}\n\n/**\n * Build an accessibility selector string from role and name.\n *\n * @param role The ARIA role for the selector\n * @param name The accessible name to match\n * @returns Formatted selector string (e.g., \"role=button[name=\\\"Click me\\\"]\")\n */\nfunction buildA11ySelector(role: IncludedRole, name: string): string {\n  const escapedName = name.replace(/\"/gu, '\\\\\"');\n  return `role=${role}[name=\"${escapedName}\"]`;\n}\n\n/**\n * Resolve a target element to a Playwright Locator.\n *\n * @param page The Playwright page to search\n * @param targetType The type of target identifier (a11yRef, testId, or CSS selector)\n * @param targetValue The target value to resolve\n * @param refMap Map of a11y refs to selectors (used when targetType is 'a11yRef')\n * @returns Playwright Locator for the resolved element\n */\nexport async function resolveTarget(\n  page: Page,\n  targetType: 'a11yRef' | 'testId' | 'selector',\n  targetValue: string,\n  refMap: Map<string, string>,\n): Promise<Locator> {\n  switch (targetType) {\n    case 'a11yRef': {\n      const selector = refMap.get(targetValue);\n      if (!selector) {\n        throw new Error(\n          `Unknown a11yRef: ${targetValue}. ` +\n            `Available refs: ${Array.from(refMap.keys()).join(', ')}`,\n        );\n      }\n      return page.locator(selector);\n    }\n    case 'testId':\n      return page.locator(`[data-testid=\"${targetValue}\"]`);\n    case 'selector':\n      return page.locator(targetValue);\n    default: {\n      const exhaustiveCheck: never = targetType;\n      throw new Error(`Unknown target type: ${exhaustiveCheck as string}`);\n    }\n  }\n}\n\n/**\n * Wait for a target element to become visible.\n *\n * @param page The Playwright page to search\n * @param targetType The type of target identifier (a11yRef, testId, or CSS selector)\n * @param targetValue The target value to resolve\n * @param refMap Map of a11y refs to selectors (used when targetType is 'a11yRef')\n * @param timeoutMs Maximum time to wait in milliseconds\n * @returns Playwright Locator for the visible element\n */\nexport async function waitForTarget(\n  page: Page,\n  targetType: 'a11yRef' | 'testId' | 'selector',\n  targetValue: string,\n  refMap: Map<string, string>,\n  timeoutMs: number,\n): Promise<Locator> {\n  const locator = await resolveTarget(page, targetType, targetValue, refMap);\n  await locator.waitFor({ state: 'visible', timeout: timeoutMs });\n  return locator;\n}\n"]}

package/dist/mcp-server/discovery.d.cts

@@ -0,0 +1,56 @@
+import type { Page, Locator } from "@playwright/test";
+import type { TestIdItem, A11yNodeTrimmed, RawA11yNode } from "./types/index.cjs";
+/**
+ * Parse a Playwright ariaSnapshot() YAML string into RawA11yNode[].
+ *
+ * The YAML format emitted by Playwright's `locator.ariaSnapshot()` (v1.49+)
+ * is a line-based, indentation-structured tree where each node line is:
+ *   `- role "name" [attr=value]:` (children follow indented)
+ *   `- role "name" [attr=value]`  (leaf node)
+ *   `- text: some text content`   (text node, ignored for our purposes)
+ *
+ * @param yaml The YAML string returned by Playwright's ariaSnapshot()
+ * @returns Array of parsed RawA11yNode trees
+ */
+export declare function parseAriaSnapshotYaml(yaml: string): RawA11yNode[];
+/**
+ * Collect all visible test IDs from the current page.
+ *
+ * @param page The Playwright page to scan for test IDs
+ * @param limit Maximum number of test IDs to return (default: 150)
+ * @returns Array of test ID items with visibility and text content
+ */
+export declare function collectTestIds(page: Page, limit?: number): Promise<TestIdItem[]>;
+/**
+ * Collect a trimmed accessibility tree snapshot with deterministic refs.
+ *
+ * @param page The Playwright page to snapshot
+ * @param rootSelector Optional CSS selector to scope the snapshot to a specific element
+ * @returns Object containing trimmed accessibility nodes and a reference map (e1, e2, etc.)
+ */
+export declare function collectTrimmedA11ySnapshot(page: Page, rootSelector?: string): Promise<{
+    nodes: A11yNodeTrimmed[];
+    refMap: Map<string, string>;
+}>;
+/**
+ * Resolve a target element to a Playwright Locator.
+ *
+ * @param page The Playwright page to search
+ * @param targetType The type of target identifier (a11yRef, testId, or CSS selector)
+ * @param targetValue The target value to resolve
+ * @param refMap Map of a11y refs to selectors (used when targetType is 'a11yRef')
+ * @returns Playwright Locator for the resolved element
+ */
+export declare function resolveTarget(page: Page, targetType: 'a11yRef' | 'testId' | 'selector', targetValue: string, refMap: Map<string, string>): Promise<Locator>;
+/**
+ * Wait for a target element to become visible.
+ *
+ * @param page The Playwright page to search
+ * @param targetType The type of target identifier (a11yRef, testId, or CSS selector)
+ * @param targetValue The target value to resolve
+ * @param refMap Map of a11y refs to selectors (used when targetType is 'a11yRef')
+ * @param timeoutMs Maximum time to wait in milliseconds
+ * @returns Playwright Locator for the visible element
+ */
+export declare function waitForTarget(page: Page, targetType: 'a11yRef' | 'testId' | 'selector', targetValue: string, refMap: Map<string, string>, timeoutMs: number): Promise<Locator>;
+//# sourceMappingURL=discovery.d.cts.map

package/dist/mcp-server/discovery.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.cts","sourceRoot":"","sources":["../../src/mcp-server/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,yBAAyB;AAGtD,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,WAAW,EAEZ,0BAAgB;AAyBjB;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAoDjE;AAgED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,IAAI,EACV,KAAK,GAAE,MAAY,GAClB,OAAO,CAAC,UAAU,EAAE,CAAC,CAuCvB;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,IAAI,EACV,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC;IACT,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B,CAAC,CAgFD;AAcD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,EAC7C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC1B,OAAO,CAAC,OAAO,CAAC,CAqBlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,EAC7C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAIlB"}

package/dist/mcp-server/discovery.d.mts

@@ -0,0 +1,56 @@
+import type { Page, Locator } from "@playwright/test";
+import type { TestIdItem, A11yNodeTrimmed, RawA11yNode } from "./types/index.mjs";
+/**
+ * Parse a Playwright ariaSnapshot() YAML string into RawA11yNode[].
+ *
+ * The YAML format emitted by Playwright's `locator.ariaSnapshot()` (v1.49+)
+ * is a line-based, indentation-structured tree where each node line is:
+ *   `- role "name" [attr=value]:` (children follow indented)
+ *   `- role "name" [attr=value]`  (leaf node)
+ *   `- text: some text content`   (text node, ignored for our purposes)
+ *
+ * @param yaml The YAML string returned by Playwright's ariaSnapshot()
+ * @returns Array of parsed RawA11yNode trees
+ */
+export declare function parseAriaSnapshotYaml(yaml: string): RawA11yNode[];
+/**
+ * Collect all visible test IDs from the current page.
+ *
+ * @param page The Playwright page to scan for test IDs
+ * @param limit Maximum number of test IDs to return (default: 150)
+ * @returns Array of test ID items with visibility and text content
+ */
+export declare function collectTestIds(page: Page, limit?: number): Promise<TestIdItem[]>;
+/**
+ * Collect a trimmed accessibility tree snapshot with deterministic refs.
+ *
+ * @param page The Playwright page to snapshot
+ * @param rootSelector Optional CSS selector to scope the snapshot to a specific element
+ * @returns Object containing trimmed accessibility nodes and a reference map (e1, e2, etc.)
+ */
+export declare function collectTrimmedA11ySnapshot(page: Page, rootSelector?: string): Promise<{
+    nodes: A11yNodeTrimmed[];
+    refMap: Map<string, string>;
+}>;
+/**
+ * Resolve a target element to a Playwright Locator.
+ *
+ * @param page The Playwright page to search
+ * @param targetType The type of target identifier (a11yRef, testId, or CSS selector)
+ * @param targetValue The target value to resolve
+ * @param refMap Map of a11y refs to selectors (used when targetType is 'a11yRef')
+ * @returns Playwright Locator for the resolved element
+ */
+export declare function resolveTarget(page: Page, targetType: 'a11yRef' | 'testId' | 'selector', targetValue: string, refMap: Map<string, string>): Promise<Locator>;
+/**
+ * Wait for a target element to become visible.
+ *
+ * @param page The Playwright page to search
+ * @param targetType The type of target identifier (a11yRef, testId, or CSS selector)
+ * @param targetValue The target value to resolve
+ * @param refMap Map of a11y refs to selectors (used when targetType is 'a11yRef')
+ * @param timeoutMs Maximum time to wait in milliseconds
+ * @returns Playwright Locator for the visible element
+ */
+export declare function waitForTarget(page: Page, targetType: 'a11yRef' | 'testId' | 'selector', targetValue: string, refMap: Map<string, string>, timeoutMs: number): Promise<Locator>;
+//# sourceMappingURL=discovery.d.mts.map

package/dist/mcp-server/discovery.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.d.mts","sourceRoot":"","sources":["../../src/mcp-server/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,yBAAyB;AAGtD,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,WAAW,EAEZ,0BAAgB;AAyBjB;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CAoDjE;AAgED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,IAAI,EACV,KAAK,GAAE,MAAY,GAClB,OAAO,CAAC,UAAU,EAAE,CAAC,CAuCvB;AAED;;;;;;GAMG;AACH,wBAAsB,0BAA0B,CAC9C,IAAI,EAAE,IAAI,EACV,YAAY,CAAC,EAAE,MAAM,GACpB,OAAO,CAAC;IACT,KAAK,EAAE,eAAe,EAAE,CAAC;IACzB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B,CAAC,CAgFD;AAcD;;;;;;;;GAQG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,EAC7C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,GAC1B,OAAO,CAAC,OAAO,CAAC,CAqBlB;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,IAAI,EAAE,IAAI,EACV,UAAU,EAAE,SAAS,GAAG,QAAQ,GAAG,UAAU,EAC7C,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC3B,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAIlB"}

package/dist/mcp-server/discovery.mjs

@@ -0,0 +1,292 @@
+import { TEXT_PREVIEW_MAX_LENGTH } from "./constants.mjs";
+import { INCLUDED_ROLES } from "./types/index.mjs";
+import { debugWarn } from "./utils/index.mjs";
+const INCLUDED_ROLES_SET = new Set(INCLUDED_ROLES);
+/**
+ * Regular expression to parse a single ARIA snapshot line descriptor.
+ *
+ * Matches: `role` + optional `"name"` + optional `[attr]` / `[attr=value]` groups
+ *
+ * Examples:
+ *   - `button "Submit"`
+ *   - `heading "Title" [level=1]`
+ *   - `checkbox "Accept" [checked]`
+ *   - `listitem`
+ */
+const ARIA_LINE_RE = /^(?<role>[a-zA-Z]+)(?:\s+"(?<name>(?:[^"\\]|\\.)*)")?(?<attrs>(?:\s+\[[^\]]*\])*)(?<hasChildren>:?)$/u;
+/**
+ * Regular expression to match individual `[key]` or `[key=value]` attribute groups.
+ */
+const ATTR_RE = /\[(?<key>[a-zA-Z]+)(?:=(?<value>[^\]]*))?\]/gu;
+/**
+ * Parse a Playwright ariaSnapshot() YAML string into RawA11yNode[].
+ *
+ * The YAML format emitted by Playwright's `locator.ariaSnapshot()` (v1.49+)
+ * is a line-based, indentation-structured tree where each node line is:
+ *   `- role "name" [attr=value]:` (children follow indented)
+ *   `- role "name" [attr=value]`  (leaf node)
+ *   `- text: some text content`   (text node, ignored for our purposes)
+ *
+ * @param yaml The YAML string returned by Playwright's ariaSnapshot()
+ * @returns Array of parsed RawA11yNode trees
+ */
+export function parseAriaSnapshotYaml(yaml) {
+    if (!yaml?.trim()) {
+        return [];
+    }
+    const lines = yaml.split('\n');
+    const roots = [];
+    const stack = [];
+    for (const line of lines) {
+        if (!line.trim()) {
+            continue;
+        }
+        const stripped = line.replace(/^ */u, '');
+        const indent = line.length - stripped.length;
+        if (!stripped.startsWith('- ')) {
+            continue;
+        }
+        const descriptor = stripped.slice(2);
+        if (descriptor.startsWith('text:') || descriptor === 'text') {
+            continue;
+        }
+        if (descriptor.startsWith('/')) {
+            continue;
+        }
+        const node = parseAriaNodeDescriptor(descriptor);
+        if (!node) {
+            continue;
+        }
+        while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {
+            stack.pop();
+        }
+        if (stack.length === 0) {
+            roots.push(node);
+        }
+        else {
+            const parent = stack[stack.length - 1].node;
+            parent.children ?? (parent.children = []);
+            parent.children.push(node);
+        }
+        stack.push({ node, indent });
+    }
+    return roots;
+}
+/**
+ * Parse a single ARIA node descriptor string into a RawA11yNode.
+ *
+ * @param descriptor The descriptor after removing the `- ` prefix, e.g. `button "Submit" [disabled]:`
+ * @returns A parsed node, or null if the descriptor cannot be parsed
+ */
+function parseAriaNodeDescriptor(descriptor) {
+    let desc = descriptor;
+    // Strip trailing `:` (children indicator) or `: text` (inline text value)
+    const trailingColonMatch = desc.match(/^(?<main>(?:[a-zA-Z]+)(?:\s+"(?:[^"\\]|\\.)*")?(?:\s+\[[^\]]*\])*)(?::(?<text>.*))?$/u);
+    if (trailingColonMatch?.groups?.main) {
+        desc = trailingColonMatch.groups.main;
+    }
+    const match = ARIA_LINE_RE.exec(desc);
+    if (!match?.groups) {
+        return null;
+    }
+    const { role } = match.groups;
+    const rawName = match.groups.name;
+    const node = { role };
+    if (rawName !== undefined) {
+        node.name = rawName.replace(/\\"/gu, '"').replace(/\\\\/gu, '\\');
+    }
+    const attrsStr = match.groups.attrs;
+    if (attrsStr) {
+        let attrMatch;
+        ATTR_RE.lastIndex = 0;
+        while ((attrMatch = ATTR_RE.exec(attrsStr)) !== null) {
+            const key = attrMatch.groups?.key;
+            const value = attrMatch.groups?.value;
+            switch (key) {
+                case 'disabled':
+                    node.disabled = value !== 'false';
+                    break;
+                case 'checked':
+                    if (value === 'mixed') {
+                        node.checked = 'mixed';
+                    }
+                    else {
+                        node.checked = value !== 'false';
+                    }
+                    break;
+                case 'expanded':
+                    node.expanded = value !== 'false';
+                    break;
+                default:
+                    break;
+            }
+        }
+    }
+    return node;
+}
+/**
+ * Collect all visible test IDs from the current page.
+ *
+ * @param page The Playwright page to scan for test IDs
+ * @param limit Maximum number of test IDs to return (default: 150)
+ * @returns Array of test ID items with visibility and text content
+ */
+export async function collectTestIds(page, limit = 150) {
+    await page.waitForLoadState('domcontentloaded').catch(() => undefined);
+    const locators = await page.locator('[data-testid]').all();
+    const results = [];
+    for (const locator of locators) {
+        if (results.length >= limit) {
+            break;
+        }
+        try {
+            const testId = await locator.getAttribute('data-testid');
+            if (!testId) {
+                continue;
+            }
+            const isVisible = await locator.isVisible().catch(() => false);
+            const textContent = await locator
+                .textContent()
+                .then((text) => text?.trim().substring(0, TEXT_PREVIEW_MAX_LENGTH) ?? undefined)
+                .catch(() => undefined);
+            results.push({
+                testId,
+                tag: 'element',
+                text: textContent,
+                visible: isVisible,
+            });
+        }
+        catch (error) {
+            debugWarn('discovery.collectTestIds', error);
+            continue;
+        }
+    }
+    return results;
+}
+/**
+ * Collect a trimmed accessibility tree snapshot with deterministic refs.
+ *
+ * @param page The Playwright page to snapshot
+ * @param rootSelector Optional CSS selector to scope the snapshot to a specific element
+ * @returns Object containing trimmed accessibility nodes and a reference map (e1, e2, etc.)
+ */
+export async function collectTrimmedA11ySnapshot(page, rootSelector) {
+    const locator = rootSelector
+        ? page.locator(rootSelector).first()
+        : page.locator('body').first();
+    const snapshotYaml = await locator.ariaSnapshot();
+    if (!snapshotYaml) {
+        return { nodes: [], refMap: new Map() };
+    }
+    const parsedRoots = parseAriaSnapshotYaml(snapshotYaml);
+    if (parsedRoots.length === 0) {
+        return { nodes: [], refMap: new Map() };
+    }
+    const trimmedNodes = [];
+    const refMap = new Map();
+    let refCounter = 1;
+    /**
+     * Recursively traverse accessibility tree and collect included roles.
+     *
+     * @param node The current accessibility node to process
+     * @param ancestorPath The path of ancestor nodes for context
+     */
+    function traverseNode(node, ancestorPath) {
+        const role = node.role?.toLowerCase() ?? '';
+        const name = node.name ?? '';
+        if (INCLUDED_ROLES_SET.has(role)) {
+            const ref = `e${refCounter}`;
+            refCounter += 1;
+            const currentPath = [...ancestorPath];
+            if (role === 'dialog' || role === 'heading') {
+                currentPath.push(`${role}:${name}`);
+            }
+            const trimmedNode = {
+                ref,
+                role,
+                name,
+                path: currentPath,
+            };
+            if (node.disabled !== undefined) {
+                trimmedNode.disabled = node.disabled;
+            }
+            if (node.checked !== undefined) {
+                trimmedNode.checked = node.checked === true;
+            }
+            if (node.expanded !== undefined) {
+                trimmedNode.expanded = node.expanded;
+            }
+            trimmedNodes.push(trimmedNode);
+            const selector = buildA11ySelector(role, name);
+            refMap.set(ref, selector);
+        }
+        const updatedPath = role === 'dialog' || role === 'heading'
+            ? [...ancestorPath, `${role}:${name}`]
+            : ancestorPath;
+        if (node.children) {
+            for (const child of node.children) {
+                traverseNode(child, updatedPath);
+            }
+        }
+    }
+    for (const root of parsedRoots) {
+        traverseNode(root, []);
+    }
+    return { nodes: trimmedNodes, refMap };
+}
+/**
+ * Build an accessibility selector string from role and name.
+ *
+ * @param role The ARIA role for the selector
+ * @param name The accessible name to match
+ * @returns Formatted selector string (e.g., "role=button[name=\"Click me\"]")
+ */
+function buildA11ySelector(role, name) {
+    const escapedName = name.replace(/"/gu, '\\"');
+    return `role=${role}[name="${escapedName}"]`;
+}
+/**
+ * Resolve a target element to a Playwright Locator.
+ *
+ * @param page The Playwright page to search
+ * @param targetType The type of target identifier (a11yRef, testId, or CSS selector)
+ * @param targetValue The target value to resolve
+ * @param refMap Map of a11y refs to selectors (used when targetType is 'a11yRef')
+ * @returns Playwright Locator for the resolved element
+ */
+export async function resolveTarget(page, targetType, targetValue, refMap) {
+    switch (targetType) {
+        case 'a11yRef': {
+            const selector = refMap.get(targetValue);
+            if (!selector) {
+                throw new Error(`Unknown a11yRef: ${targetValue}. ` +
+                    `Available refs: ${Array.from(refMap.keys()).join(', ')}`);
+            }
+            return page.locator(selector);
+        }
+        case 'testId':
+            return page.locator(`[data-testid="${targetValue}"]`);
+        case 'selector':
+            return page.locator(targetValue);
+        default: {
+            const exhaustiveCheck = targetType;
+            throw new Error(`Unknown target type: ${exhaustiveCheck}`);
+        }
+    }
+}
+/**
+ * Wait for a target element to become visible.
+ *
+ * @param page The Playwright page to search
+ * @param targetType The type of target identifier (a11yRef, testId, or CSS selector)
+ * @param targetValue The target value to resolve
+ * @param refMap Map of a11y refs to selectors (used when targetType is 'a11yRef')
+ * @param timeoutMs Maximum time to wait in milliseconds
+ * @returns Playwright Locator for the visible element
+ */
+export async function waitForTarget(page, targetType, targetValue, refMap, timeoutMs) {
+    const locator = await resolveTarget(page, targetType, targetValue, refMap);
+    await locator.waitFor({ state: 'visible', timeout: timeoutMs });
+    return locator;
+}
+//# sourceMappingURL=discovery.mjs.map

package/dist/mcp-server/discovery.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"discovery.mjs","sourceRoot":"","sources":["../../src/mcp-server/discovery.ts"],"names":[],"mappings":"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","sourcesContent":["import type { Page, Locator } from '@playwright/test';\n\nimport { TEXT_PREVIEW_MAX_LENGTH } from './constants.js';\nimport type {\n  TestIdItem,\n  A11yNodeTrimmed,\n  RawA11yNode,\n  IncludedRole,\n} from './types';\nimport { INCLUDED_ROLES } from './types';\nimport { debugWarn } from './utils';\n\nconst INCLUDED_ROLES_SET = new Set<string>(INCLUDED_ROLES);\n\n/**\n * Regular expression to parse a single ARIA snapshot line descriptor.\n *\n * Matches: `role` + optional `\"name\"` + optional `[attr]` / `[attr=value]` groups\n *\n * Examples:\n *   - `button \"Submit\"`\n *   - `heading \"Title\" [level=1]`\n *   - `checkbox \"Accept\" [checked]`\n *   - `listitem`\n */\nconst ARIA_LINE_RE =\n  /^(?<role>[a-zA-Z]+)(?:\\s+\"(?<name>(?:[^\"\\\\]|\\\\.)*)\")?(?<attrs>(?:\\s+\\[[^\\]]*\\])*)(?<hasChildren>:?)$/u;\n\n/**\n * Regular expression to match individual `[key]` or `[key=value]` attribute groups.\n */\nconst ATTR_RE = /\\[(?<key>[a-zA-Z]+)(?:=(?<value>[^\\]]*))?\\]/gu;\n\n/**\n * Parse a Playwright ariaSnapshot() YAML string into RawA11yNode[].\n *\n * The YAML format emitted by Playwright's `locator.ariaSnapshot()` (v1.49+)\n * is a line-based, indentation-structured tree where each node line is:\n *   `- role \"name\" [attr=value]:` (children follow indented)\n *   `- role \"name\" [attr=value]`  (leaf node)\n *   `- text: some text content`   (text node, ignored for our purposes)\n *\n * @param yaml The YAML string returned by Playwright's ariaSnapshot()\n * @returns Array of parsed RawA11yNode trees\n */\nexport function parseAriaSnapshotYaml(yaml: string): RawA11yNode[] {\n  if (!yaml?.trim()) {\n    return [];\n  }\n\n  const lines = yaml.split('\\n');\n  const roots: RawA11yNode[] = [];\n  const stack: { node: RawA11yNode; indent: number }[] = [];\n\n  for (const line of lines) {\n    if (!line.trim()) {\n      continue;\n    }\n\n    const stripped = line.replace(/^ */u, '');\n    const indent = line.length - stripped.length;\n\n    if (!stripped.startsWith('- ')) {\n      continue;\n    }\n\n    const descriptor = stripped.slice(2);\n\n    if (descriptor.startsWith('text:') || descriptor === 'text') {\n      continue;\n    }\n\n    if (descriptor.startsWith('/')) {\n      continue;\n    }\n\n    const node = parseAriaNodeDescriptor(descriptor);\n    if (!node) {\n      continue;\n    }\n\n    while (stack.length > 0 && stack[stack.length - 1].indent >= indent) {\n      stack.pop();\n    }\n\n    if (stack.length === 0) {\n      roots.push(node);\n    } else {\n      const parent = stack[stack.length - 1].node;\n      parent.children ??= [];\n      parent.children.push(node);\n    }\n\n    stack.push({ node, indent });\n  }\n\n  return roots;\n}\n\n/**\n * Parse a single ARIA node descriptor string into a RawA11yNode.\n *\n * @param descriptor The descriptor after removing the `- ` prefix, e.g. `button \"Submit\" [disabled]:`\n * @returns A parsed node, or null if the descriptor cannot be parsed\n */\nfunction parseAriaNodeDescriptor(descriptor: string): RawA11yNode | null {\n  let desc = descriptor;\n\n  // Strip trailing `:` (children indicator) or `: text` (inline text value)\n  const trailingColonMatch = desc.match(\n    /^(?<main>(?:[a-zA-Z]+)(?:\\s+\"(?:[^\"\\\\]|\\\\.)*\")?(?:\\s+\\[[^\\]]*\\])*)(?::(?<text>.*))?$/u,\n  );\n  if (trailingColonMatch?.groups?.main) {\n    desc = trailingColonMatch.groups.main;\n  }\n\n  const match = ARIA_LINE_RE.exec(desc);\n  if (!match?.groups) {\n    return null;\n  }\n\n  const { role } = match.groups;\n  const rawName = match.groups.name;\n\n  const node: RawA11yNode = { role };\n\n  if (rawName !== undefined) {\n    node.name = rawName.replace(/\\\\\"/gu, '\"').replace(/\\\\\\\\/gu, '\\\\');\n  }\n\n  const attrsStr = match.groups.attrs;\n  if (attrsStr) {\n    let attrMatch;\n    ATTR_RE.lastIndex = 0;\n    while ((attrMatch = ATTR_RE.exec(attrsStr)) !== null) {\n      const key = attrMatch.groups?.key;\n      const value = attrMatch.groups?.value;\n\n      switch (key) {\n        case 'disabled':\n          node.disabled = value !== 'false';\n          break;\n        case 'checked':\n          if (value === 'mixed') {\n            node.checked = 'mixed';\n          } else {\n            node.checked = value !== 'false';\n          }\n          break;\n        case 'expanded':\n          node.expanded = value !== 'false';\n          break;\n        default:\n          break;\n      }\n    }\n  }\n\n  return node;\n}\n\n/**\n * Collect all visible test IDs from the current page.\n *\n * @param page The Playwright page to scan for test IDs\n * @param limit Maximum number of test IDs to return (default: 150)\n * @returns Array of test ID items with visibility and text content\n */\nexport async function collectTestIds(\n  page: Page,\n  limit: number = 150,\n): Promise<TestIdItem[]> {\n  await page.waitForLoadState('domcontentloaded').catch(() => undefined);\n\n  const locators = await page.locator('[data-testid]').all();\n  const results: TestIdItem[] = [];\n\n  for (const locator of locators) {\n    if (results.length >= limit) {\n      break;\n    }\n\n    try {\n      const testId = await locator.getAttribute('data-testid');\n      if (!testId) {\n        continue;\n      }\n\n      const isVisible = await locator.isVisible().catch(() => false);\n      const textContent = await locator\n        .textContent()\n        .then(\n          (text) =>\n            text?.trim().substring(0, TEXT_PREVIEW_MAX_LENGTH) ?? undefined,\n        )\n        .catch(() => undefined);\n\n      results.push({\n        testId,\n        tag: 'element',\n        text: textContent,\n        visible: isVisible,\n      });\n    } catch (error) {\n      debugWarn('discovery.collectTestIds', error);\n      continue;\n    }\n  }\n\n  return results;\n}\n\n/**\n * Collect a trimmed accessibility tree snapshot with deterministic refs.\n *\n * @param page The Playwright page to snapshot\n * @param rootSelector Optional CSS selector to scope the snapshot to a specific element\n * @returns Object containing trimmed accessibility nodes and a reference map (e1, e2, etc.)\n */\nexport async function collectTrimmedA11ySnapshot(\n  page: Page,\n  rootSelector?: string,\n): Promise<{\n  nodes: A11yNodeTrimmed[];\n  refMap: Map<string, string>;\n}> {\n  const locator = rootSelector\n    ? page.locator(rootSelector).first()\n    : page.locator('body').first();\n\n  const snapshotYaml: string = await locator.ariaSnapshot();\n\n  if (!snapshotYaml) {\n    return { nodes: [], refMap: new Map() };\n  }\n\n  const parsedRoots = parseAriaSnapshotYaml(snapshotYaml);\n\n  if (parsedRoots.length === 0) {\n    return { nodes: [], refMap: new Map() };\n  }\n\n  const trimmedNodes: A11yNodeTrimmed[] = [];\n  const refMap = new Map<string, string>();\n  let refCounter = 1;\n\n  /**\n   * Recursively traverse accessibility tree and collect included roles.\n   *\n   * @param node The current accessibility node to process\n   * @param ancestorPath The path of ancestor nodes for context\n   */\n  function traverseNode(node: RawA11yNode, ancestorPath: string[]): void {\n    const role = node.role?.toLowerCase() ?? '';\n    const name = node.name ?? '';\n\n    if (INCLUDED_ROLES_SET.has(role)) {\n      const ref = `e${refCounter}`;\n      refCounter += 1;\n      const currentPath = [...ancestorPath];\n\n      if (role === 'dialog' || role === 'heading') {\n        currentPath.push(`${role}:${name}`);\n      }\n\n      const trimmedNode: A11yNodeTrimmed = {\n        ref,\n        role,\n        name,\n        path: currentPath,\n      };\n\n      if (node.disabled !== undefined) {\n        trimmedNode.disabled = node.disabled;\n      }\n      if (node.checked !== undefined) {\n        trimmedNode.checked = node.checked === true;\n      }\n      if (node.expanded !== undefined) {\n        trimmedNode.expanded = node.expanded;\n      }\n\n      trimmedNodes.push(trimmedNode);\n\n      const selector = buildA11ySelector(role as IncludedRole, name);\n      refMap.set(ref, selector);\n    }\n\n    const updatedPath =\n      role === 'dialog' || role === 'heading'\n        ? [...ancestorPath, `${role}:${name}`]\n        : ancestorPath;\n\n    if (node.children) {\n      for (const child of node.children) {\n        traverseNode(child, updatedPath);\n      }\n    }\n  }\n\n  for (const root of parsedRoots) {\n    traverseNode(root, []);\n  }\n\n  return { nodes: trimmedNodes, refMap };\n}\n\n/**\n * Build an accessibility selector string from role and name.\n *\n * @param role The ARIA role for the selector\n * @param name The accessible name to match\n * @returns Formatted selector string (e.g., \"role=button[name=\\\"Click me\\\"]\")\n */\nfunction buildA11ySelector(role: IncludedRole, name: string): string {\n  const escapedName = name.replace(/\"/gu, '\\\\\"');\n  return `role=${role}[name=\"${escapedName}\"]`;\n}\n\n/**\n * Resolve a target element to a Playwright Locator.\n *\n * @param page The Playwright page to search\n * @param targetType The type of target identifier (a11yRef, testId, or CSS selector)\n * @param targetValue The target value to resolve\n * @param refMap Map of a11y refs to selectors (used when targetType is 'a11yRef')\n * @returns Playwright Locator for the resolved element\n */\nexport async function resolveTarget(\n  page: Page,\n  targetType: 'a11yRef' | 'testId' | 'selector',\n  targetValue: string,\n  refMap: Map<string, string>,\n): Promise<Locator> {\n  switch (targetType) {\n    case 'a11yRef': {\n      const selector = refMap.get(targetValue);\n      if (!selector) {\n        throw new Error(\n          `Unknown a11yRef: ${targetValue}. ` +\n            `Available refs: ${Array.from(refMap.keys()).join(', ')}`,\n        );\n      }\n      return page.locator(selector);\n    }\n    case 'testId':\n      return page.locator(`[data-testid=\"${targetValue}\"]`);\n    case 'selector':\n      return page.locator(targetValue);\n    default: {\n      const exhaustiveCheck: never = targetType;\n      throw new Error(`Unknown target type: ${exhaustiveCheck as string}`);\n    }\n  }\n}\n\n/**\n * Wait for a target element to become visible.\n *\n * @param page The Playwright page to search\n * @param targetType The type of target identifier (a11yRef, testId, or CSS selector)\n * @param targetValue The target value to resolve\n * @param refMap Map of a11y refs to selectors (used when targetType is 'a11yRef')\n * @param timeoutMs Maximum time to wait in milliseconds\n * @returns Playwright Locator for the visible element\n */\nexport async function waitForTarget(\n  page: Page,\n  targetType: 'a11yRef' | 'testId' | 'selector',\n  targetValue: string,\n  refMap: Map<string, string>,\n  timeoutMs: number,\n): Promise<Locator> {\n  const locator = await resolveTarget(page, targetType, targetValue, refMap);\n  await locator.waitFor({ state: 'visible', timeout: timeoutMs });\n  return locator;\n}\n"]}