@molecule/api-ai-tools 1.10.10 → 1.11.1

package/dist/trace-artifacts.js

@@ -18,11 +18,14 @@
  * 401`. So the platform reads it (bounded, per test) and puts it in the run's result
  * ({@link failureTraceNote}), instead of leaving the executor to build its own browser to find out.
  *
- * Everything here is text in, text out: the sandbox runs {@link traceArtifactsScript} (Node, no
- * dependencies — Playwright's zip reader is not importable from a project) and prints one
- * `TRACE <json>` line per trace; the platform parses those lines ({@link parseTraceArtifacts}) and
- * writes the note ({@link failureTraceNote}). Both halves are covered by a test that runs the
- * script against a `trace.zip` produced by a real Playwright run, in the sandbox's own shape.
+ * Everything here is text in, text out: the sandbox runs {@link traceArtifactsScript} (plain Node —
+ * the zip is read without a dependency) and prints one `TRACE <json>` line per trace; the platform
+ * parses those lines ({@link parseTraceArtifacts}) and writes the note ({@link failureTraceNote}).
+ * The one exception is the selector replay behind a `locator.count()` reading: it resolves the
+ * project's own installed Playwright, replays the recorded selector against the recorded snapshot
+ * in that browser's DOM, and reports `browser-unavailable` (naming no elements) when it cannot.
+ * Both halves are covered by a test that runs the script against a `trace.zip` produced by a real
+ * Playwright run, in the sandbox's own shape.
  *
  * @module
  */
@@ -50,6 +53,12 @@ export const MAX_TRACED_BODY_CHARS = 300;
 const MAX_TRACED_WEBSOCKET_CHARS = 600;
 /** How many tests the note in a run's result names. */
 export const MAX_TRACE_NOTE_TESTS = 5;
+/** How many elements a count mismatch's row names, in document order. */
+const MAX_COUNT_MATCHES = 6;
+/** How much of one matched element's text the trace read keeps. */
+const MAX_COUNT_TEXT_CHARS = 90;
+/** How deep one matched element's ancestor chain is named (it and up to three ancestors). */
+const MAX_COUNT_PATH_DEPTH = 4;
 /** How many requests the note names per test. */
 export const MAX_TRACE_NOTE_REQUESTS = 4;
 /**
@@ -123,6 +132,16 @@ const MAX_ACTIONS = ${MAX_TRACED_ACTIONS}
 const MAX_BODY = ${MAX_TRACED_BODY_CHARS}
 const MAX_WS = ${MAX_TRACED_WEBSOCKET_CHARS}
 const LOOP_REPEATS = ${TRACE_NOTE_LOOP_REPEATS}
+const MAX_COUNT_MATCHES = ${MAX_COUNT_MATCHES}
+const MAX_COUNT_TEXT = ${MAX_COUNT_TEXT_CHARS}
+const MAX_COUNT_PATH_DEPTH = ${MAX_COUNT_PATH_DEPTH}
+// The serialized failure snapshot is capped: a page whose DOM exceeds this is not replayed, and the
+// reading reports no readable snapshot instead of a partial page.
+const MAX_SNAPSHOT_HTML = 4000000
+// A locator.count() older than this before the failing assertion is not paired with it: the value
+// match in countMismatchOf() is the strong evidence, this only bounds a trace whose count recorded
+// no result.
+const COUNT_LOOKBACK_MS = 180000
 const MAX_URL = 200
 // A console line that is not an error but still has to reach the note (m148): one a molecule
 // package wrote — it names the package, the \`[molecule/…]\` prefix, or the \`[scope]\` prefix
@@ -408,6 +427,438 @@ function hiddenBoxOf(message, frames) {
   return reading
 }
 
+// --- count assertions (xr-molecule-flash-m321) -------------------------------
+// A count assertion reports only numbers ("Expected: 3 / Received: 4"). The trace holds the rest:
+// \`locator.count()\` is a Frame.queryCount entry carrying params.selector and the result value,
+// \`expect(locator).toHaveCount(n)\` is a Frame.expect entry carrying the selector and the expected
+// number, and the failure snapshot is the page's DOM at that moment. Two things name the matched
+// elements: the \`__playwright_target__\` marks Playwright leaves on an assertion's own matches, and
+// a replay of the recorded selector in the browser's own DOM against the snapshot (resolved from
+// the project's Playwright; no hand-written CSS grammar). Everything else fails closed — a selector
+// the browser rejects, a missing browser, an unreadable snapshot, or a replay whose count disagrees
+// with the recorded one names no elements rather than inventing them.
+
+function stripAnsi(text) {
+  return String(text || '').replace(/\\u001b\\[[0-9;]*m/g, '')
+}
+
+// The two numbers a count assertion prints, when the failure is one. A string assertion's
+// \`Expected: "…"\` and a comparison's \`Expected: > 3\` both parse to null.
+function countNumbersOf(message) {
+  const text = stripAnsi(message)
+  const expected = /Expected:\\s*(\\d+)\\s*(?:\\n|$)/.exec(text)
+  const received = /Received:\\s*(\\d+)\\s*(?:\\n|$)/.exec(text)
+  if (expected === null || received === null) return null
+  return { expected: Number(expected[1]), received: Number(received[1]) }
+}
+
+// The locator a count assertion printed (\`Locator:  locator('.card…')\`), and its inner selector.
+function locatorInError(message) {
+  const text = stripAnsi(message)
+  const named = /Locator:\\s*(locator\\([^\\n]*?\\))\\s*(?:\\n|$)/.exec(text)
+  if (named === null) return null
+  const inner = /^locator\\(\\s*(['"\`])([\\s\\S]*)\\1\\s*\\)$/.exec(named[1])
+  if (inner === null) return { locator: named[1], selector: null }
+  return { locator: named[1], selector: inner[2] }
+}
+
+function cssClassesOf(node) {
+  return String(node.attrs.class || '').split(/\\s+/).filter(Boolean)
+}
+
+// The post-order node list Playwright's own \`snapshotNodes\` builds: text nodes in place, each
+// element pushed after its children. A subtree reference is not a node and is not followed here.
+function snapshotNodesOf(value) {
+  const nodes = []
+  const visit = function (n) {
+    if (typeof n === 'string') { nodes.push(n); return }
+    if (!Array.isArray(n) || typeof n[0] !== 'string') return
+    for (let i = 2; i < n.length; i++) visit(n[i])
+    nodes.push(n)
+  }
+  visit(value)
+  return nodes
+}
+
+// The frame's own snapshots, in recording order — the list Playwright's subtree references index
+// into. Main frames only (the reader drops subframe snapshots), matched by frameId when present.
+function frameSnapshotsOf(frame, allFrames) {
+  if (typeof frame.frameId === 'string' && frame.frameId !== '') {
+    const same = allFrames.filter(function (f) { return f.frameId === frame.frameId })
+    if (same.length > 0) return same
+  }
+  return allFrames.filter(function (f) { return f.context === frame.context && f.pageId === frame.pageId })
+}
+
+// One snapshot's DOM as { tag, attrs, children, parent } nodes, with subtree references expanded
+// against the frame's earlier snapshots (reference \`[delta, nodeIndex]\` = the snapshot \`at - delta\`,
+// exactly as the trace viewer resolves it). Null when any reference cannot be resolved or the tree
+// is too large: an incomplete snapshot is not evidence about the page.
+function resolvedSnapshotTree(frame, allFrames) {
+  if (frame === undefined || frame === null) return null
+  const tree = frame.snapshot
+  if (tree === undefined || tree === null) return null
+  const shown = frameSnapshotsOf(frame, allFrames)
+  const index = shown.indexOf(frame)
+  if (index < 0) return null
+  let budget = 60000
+  let readable = true
+  const build = function (value, at, depth) {
+    if (!readable) return null
+    if (budget-- < 0 || depth > 80) { readable = false; return null }
+    if (typeof value === 'string') return { tag: null, text: value, attrs: {}, children: [], parent: null }
+    if (!Array.isArray(value)) { readable = false; return null }
+    if (Array.isArray(value[0])) {
+      const delta = typeof value[0][0] === 'number' ? value[0][0] : -1
+      const nodeIndex = typeof value[0][1] === 'number' ? value[0][1] : -1
+      const refAt = at - delta
+      if (delta < 0 || refAt < 0 || refAt >= shown.length || nodeIndex < 0) { readable = false; return null }
+      const earlier = shown[refAt].snapshot
+      const nodes = earlier === undefined || earlier === null ? [] : snapshotNodesOf(earlier)
+      if (nodeIndex >= nodes.length) { readable = false; return null }
+      return build(nodes[nodeIndex], refAt, depth + 1)
+    }
+    if (typeof value[0] !== 'string') { readable = false; return null }
+    const node = {
+      tag: String(value[0]).toLowerCase(),
+      attrs: value[1] && typeof value[1] === 'object' ? value[1] : {},
+      children: [],
+      parent: null,
+    }
+    for (let i = 2; i < value.length; i++) {
+      const child = build(value[i], at, depth + 1)
+      if (child === null) { readable = false; return null }
+      child.parent = node
+      node.children.push(child)
+    }
+    return node
+  }
+  const root = build(tree, index, 0)
+  return readable ? root : null
+}
+
+// An element's own text, whitespace-collapsed and bounded. Script and style bodies are skipped, as
+// the trace viewer skips them: code is not what the page showed.
+function elementTextOf(node) {
+  let out = ''
+  const visit = function (n) {
+    if (out.length > MAX_COUNT_TEXT) return
+    if (typeof n.text === 'string') { out += n.text; return }
+    if (n.tag === 'script' || n.tag === 'style') return
+    for (const child of n.children) visit(child)
+  }
+  visit(node)
+  return out.replace(/\\s+/g, ' ').trim().slice(0, MAX_COUNT_TEXT)
+}
+
+// The element's ancestors, outermost first, for the row's "where it sits" (\`body >
+// section.comments > div.card\`).
+function elementPathOf(node) {
+  const parts = []
+  let at = node.parent
+  while (at !== null && at.tag !== null && parts.length < MAX_COUNT_PATH_DEPTH) {
+    const classes = cssClassesOf(at)
+    parts.unshift(at.tag + (classes.length > 0 ? '.' + classes[0] : ''))
+    at = at.parent
+  }
+  return parts.join(' > ').slice(0, 160)
+}
+
+function elementInForm(node) {
+  let at = node.parent
+  while (at !== null) {
+    if (at.tag === 'form') return true
+    at = at.parent
+  }
+  return false
+}
+
+function countMatchOf(node) {
+  const match = { tag: node.tag }
+  const classes = String(node.attrs.class || '').trim()
+  if (classes) match.classes = classes.slice(0, 120)
+  const text = elementTextOf(node)
+  if (text) match.text = text
+  const path = elementPathOf(node)
+  if (path) match.path = path
+  if (elementInForm(node)) match.inForm = true
+  return match
+}
+
+// Every element carrying Playwright's own assertion-target mark, in document order.
+function targetElementsOf(root) {
+  const out = []
+  const visit = function (node) {
+    if (node.tag === null) return
+    if (Object.prototype.hasOwnProperty.call(node.attrs, '__playwright_target__')) out.push(node)
+    for (const child of node.children) visit(child)
+  }
+  visit(root)
+  return out
+}
+
+// The failure snapshot as HTML, so a real browser can parse it and answer the selector with the
+// standard DOMParser/querySelectorAll instead of a hand-written grammar. Each element carries its
+// node index, so a match maps back to the RECORDED element (text, classes, ancestors) rather than a
+// re-derivation. Bounded, and every unsupported shape fails the serialization instead of producing
+// a partial page: an incomplete DOM is not evidence about the page.
+const SNAPSHOT_NODE_ATTR = 'data-mol-snapshot-node'
+const SNAPSHOT_TAG = /^[a-z][a-z0-9-]*$/i
+const SNAPSHOT_ATTR = /^[-_A-Za-z][-_A-Za-z0-9:.]*$/
+const SNAPSHOT_VOID = {
+  area: 1, base: 1, br: 1, col: 1, embed: 1, hr: 1, img: 1, input: 1, link: 1,
+  meta: 1, param: 1, source: 1, track: 1, wbr: 1
+}
+function snapshotHtmlOf(root) {
+  const nodes = []
+  let html = ''
+  let failed = false
+  function append(text) {
+    if (failed) return
+    if (html.length + text.length > MAX_SNAPSHOT_HTML) { failed = true; return }
+    html += text
+  }
+  function escapeText(text) {
+    return String(text).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+  }
+  function escapeAttr(text) {
+    return String(text).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;')
+  }
+  function visit(node) {
+    if (failed) return
+    if (node.tag === null) { append(escapeText(node.text === undefined ? '' : node.text)); return }
+    if (!SNAPSHOT_TAG.test(node.tag)) { failed = true; return }
+    const index = nodes.length
+    nodes.push(node)
+    append('<' + node.tag)
+    for (const name of Object.keys(node.attrs)) {
+      if (!SNAPSHOT_ATTR.test(name) || name.toLowerCase() === SNAPSHOT_NODE_ATTR) continue
+      const value = node.attrs[name]
+      if (typeof value !== 'string') continue
+      // A meta refresh is a navigation, not rendered content. The replay only needs the DOM the
+      // failure snapshot shows, so it is dropped and the isolated context stays inert.
+      if (node.tag === 'meta' && name.toLowerCase() === 'http-equiv' && /refresh/i.test(value)) continue
+      append(' ' + name + '="' + escapeAttr(value) + '"')
+    }
+    append(' ' + SNAPSHOT_NODE_ATTR + '="' + index + '">')
+    if (SNAPSHOT_VOID[node.tag]) {
+      if (node.children.length > 0) { failed = true; return }
+      return
+    }
+    for (const child of node.children) visit(child)
+    append('</' + node.tag + '>')
+  }
+  visit(root)
+  if (failed || html === '') return null
+  // A snapshot rooted at <html> IS the document; anything else is body content.
+  const documentHtml =
+    root.tag === 'html' ? '<!doctype html>' + html
+      : '<!doctype html><html><head></head><body>' + html + '</body></html>'
+  return { nodes: nodes, documentHtml: documentHtml }
+}
+
+// Playwright, resolved from the project whose traces these are (the sandbox installs it for the e2e
+// run the trace came from). The trace reader itself stays dependency-free: when the module or the
+// recorded browser's executable cannot be resolved, the replay says so and names no elements.
+let playwrightModulePromise = null
+function playwrightModule() {
+  if (playwrightModulePromise === null) {
+    playwrightModulePromise = Promise.resolve().then(function () {
+      const paths = []
+      if (ROOT) paths.push(ROOT)
+      paths.push(process.cwd())
+      for (const name of ['playwright', '@playwright/test']) {
+        try {
+          return require(require.resolve(name, { paths: paths }))
+        } catch (_error) {
+          // Not installed under this name at the project root: try the next module.
+        }
+      }
+      return null
+    })
+  }
+  return playwrightModulePromise
+}
+
+// One browser per recorded engine, launched on the first selector replay and reused. A resolution
+// or launch failure is cached as null, so a project without the browser does not pay for it once per
+// trace.
+const replayBrowsers = {}
+function replayBrowserFor(name) {
+  const engineName = name || 'chromium'
+  if (replayBrowsers[engineName] === undefined) {
+    replayBrowsers[engineName] = playwrightModule().then(function (pw) {
+      if (pw === null) return null
+      const engine = pw[engineName]
+      if (!engine || typeof engine.launch !== 'function') return null
+      try {
+        return engine.launch({ headless: true, timeout: 10000 }).catch(function (_error) {
+          // No executable for this engine: the replay reports unavailable, never a guess.
+          return null
+        })
+      } catch (_error) {
+        return null
+      }
+    })
+  }
+  return replayBrowsers[engineName]
+}
+function closeReplayBrowsers() {
+  return Promise.all(Object.keys(replayBrowsers).map(function (name) {
+    return replayBrowsers[name].then(function (browser) {
+      if (browser === null) return null
+      return browser.close().catch(function (_error) { return null })
+    })
+  }))
+}
+
+// Replay one selector against the recorded snapshot with the browser's own DOM. The context is
+// isolated and has JavaScript disabled (nothing in the snapshot can execute), is offline, and
+// aborts every request (nothing it references can be fetched). null = no browser available;
+// { unsupported: true } = the browser rejected the selector (a Playwright engine, chaining).
+async function replaySelector(selector, snapshot, browserName) {
+  const browser = await replayBrowserFor(browserName)
+  if (browser === null) return null
+  let context = null
+  try {
+    context = await browser.newContext({
+      javaScriptEnabled: false,
+      offline: true,
+      serviceWorkers: 'block',
+    })
+    await context.route('**/*', function (route) { return route.abort() })
+    const page = await context.newPage()
+    await page.setContent(snapshot.documentHtml, { waitUntil: 'domcontentloaded', timeout: 10000 })
+    const found = await page.evaluate(function (args) {
+      try {
+        const elements = document.querySelectorAll(args.selector)
+        const indices = []
+        for (let i = 0; i < elements.length; i++) {
+          indices.push(elements[i].getAttribute(args.marker))
+        }
+        return { ok: true, indices: indices }
+      } catch (_error) {
+        return { ok: false }
+      }
+    }, { selector: selector, marker: SNAPSHOT_NODE_ATTR })
+    if (found === null || found === undefined || found.ok !== true || !Array.isArray(found.indices))
+      return { unsupported: true }
+    return { indices: found.indices }
+  } catch (_error) {
+    // The context could not hold the snapshot (launch failure, a malformed serialization): the
+    // replay is unavailable for this assertion, and no element is named.
+    return null
+  } finally {
+    if (context !== null) await context.close().catch(function (_error) { return null })
+  }
+}
+
+// The count assertion this failure is, with the locator the trace recorded and the elements its
+// failure snapshot matched. Null when the failure is not a count, when no locator can be attributed
+// to it, or when both numbers cannot be read.
+async function countMismatchOf(failedError, frames, allFrames, queryCounts, frameExpects, failedStep, browserName) {
+  const numbers = countNumbersOf(failedError)
+  if (numbers === null) return null
+  const assertionStart =
+    failedStep && typeof failedStep.startTime === 'number' ? failedStep.startTime : null
+  const recent = function (entry) {
+    if (assertionStart === null) return true
+    return entry.start <= assertionStart + 1000 && assertionStart - entry.start <= COUNT_LOOKBACK_MS
+  }
+  const named = locatorInError(failedError)
+  let locator = null
+  let selector = null
+  let source = null
+  if (named !== null && named.selector !== null) {
+    locator = named.locator
+    selector = named.selector
+    source = 'assertion'
+  }
+  // expect(locator).toHaveCount(n): the trace records the selector and the expected number.
+  if (locator === null) {
+    const wanted = frameExpects
+      .filter(function (entry) { return entry.expected === numbers.expected && recent(entry) })
+      .sort(function (a, b) { return b.start - a.start })[0]
+    if (wanted !== undefined) {
+      locator = wanted.locator
+      selector = wanted.selector
+      source = 'assertion'
+    }
+  }
+  // locator.count() then expect(count).toBe(n): the value the trace recorded IS the received one.
+  if (locator === null) {
+    const wanted = queryCounts
+      .filter(function (entry) { return entry.value === numbers.received && recent(entry) })
+      .sort(function (a, b) { return b.start - a.start })[0]
+    if (wanted !== undefined) {
+      locator = wanted.locator
+      selector = wanted.selector
+      source = 'locator-count'
+    }
+  }
+  if (locator === null || source === null) return null
+  const reading = {
+    locator: locator.slice(0, 200),
+    ...(selector === null ? {} : { selector: selector.slice(0, 200) }),
+    expected: numbers.expected,
+    received: numbers.received,
+    source: source,
+  }
+  const tree = resolvedSnapshotTree(frames.length > 0 ? frames[frames.length - 1] : null, allFrames)
+  if (tree === null) {
+    reading.unreadable = 'no-snapshot'
+    return reading
+  }
+  // Playwright marks an assertion's own matches in the snapshot recorded with it. Only a mark set
+  // whose count IS the received count belongs to this assertion.
+  const targets = targetElementsOf(tree)
+  if (targets.length === numbers.received) {
+    reading.matched = targets.slice(0, MAX_COUNT_MATCHES).map(countMatchOf)
+    reading.matchedTotal = targets.length
+    reading.matchedFrom = 'snapshot-targets'
+    return reading
+  }
+  if (selector === null) {
+    reading.unreadable = 'unsupported-selector'
+    return reading
+  }
+  // The recorded selector is replayed against the recorded snapshot by the browser's own DOM: no
+  // hand-written CSS grammar, and every standard selector the engine the test ran in supports.
+  const snapshot = snapshotHtmlOf(tree)
+  if (snapshot === null) {
+    reading.unreadable = 'no-snapshot'
+    return reading
+  }
+  const replay = await replaySelector(selector, snapshot, browserName)
+  if (replay === null) {
+    reading.unreadable = 'browser-unavailable'
+    return reading
+  }
+  if (replay.unsupported) {
+    reading.unreadable = 'unsupported-selector'
+    return reading
+  }
+  const elements = []
+  let broken = false
+  for (const index of replay.indices) {
+    const at = typeof index === 'string' ? Number(index) : NaN
+    const node =
+      Number.isInteger(at) && at >= 0 && at < snapshot.nodes.length ? snapshot.nodes[at] : null
+    if (node === null || node.tag === null) { broken = true; break }
+    elements.push(node)
+  }
+  // The replay is evidence only when it agrees, element for element, with the count the run
+  // recorded; a stale or partial snapshot names nothing.
+  if (broken || elements.length !== numbers.received) {
+    reading.unreadable = 'count-mismatch'
+    return reading
+  }
+  reading.matched = elements.slice(0, MAX_COUNT_MATCHES).map(countMatchOf)
+  reading.matchedTotal = elements.length
+  reading.matchedFrom = 'selector-replay'
+  return reading
+}
+
 // A request/response body exactly as Playwright stored it: inline on the value, or in a resource
 // entry the value names. Bounded, and binary is dropped — a JSON body is what this is for, and a
 // multipart upload would print bytes.
@@ -546,6 +997,8 @@ function networkContextOf(name) {
   return m === null ? null : m[1]
 }
 
+// The reading is async only for the browser selector replay; every other fact is plain Node.
+async function main() {
 for (const one of found.slice(0, MAX_TRACES)) {
   let buf
   try { buf = fs.readFileSync(one.file) } catch (e) { continue }
@@ -580,6 +1033,19 @@ for (const one of found.slice(0, MAX_TRACES)) {
       ctx.network.push.apply(ctx.network, ndjson(zipData(buf, entry)))
     }
   }
+  // The browser the test ran in, from the trace's own context-options: a selector replay uses the
+  // same engine's DOM rather than assuming one. A trace that records none defaults to chromium.
+  let browserName = ''
+  for (const ctx of contexts) {
+    for (const entry of ctx.trace) {
+      if (entry && entry.type === 'context-options' && typeof entry.browserName === 'string' &&
+        entry.browserName) {
+        browserName = entry.browserName
+        break
+      }
+    }
+    if (browserName) break
+  }
   const requestsAll = []
   for (const ctx of contexts) {
     for (const line of ctx.network) {
@@ -644,11 +1110,30 @@ for (const one of found.slice(0, MAX_TRACES)) {
   // assertion's own page can be selected below (m160).
   const actionsAll = []
   const framesAll = []
+  // The count entries a failing assertion can be paired with (m321): \`locator.count()\` and
+  // \`expect(locator).toHaveCount(n)\` are the two ways a test compares a selector's match count.
+  const queryCounts = []
+  const frameExpects = []
+  // The readable locator a runner step names (\`getByRole('button', { name: 'Post Comment' })\`),
+  // keyed by the step id the library trace repeats on the entry it recorded for that step.
+  const locatorByStep = {}
+  for (const entry of runner) {
+    if (!entry || entry.type !== 'before') continue
+    const params = entry.params && typeof entry.params === 'object' ? entry.params : {}
+    if (typeof entry.stepId === 'string' && typeof params.locator === 'string' && params.locator)
+      locatorByStep[entry.stepId] = params.locator
+  }
   for (const ctx of contexts) {
     const ended = {}
+    const callValues = {}
     for (const entry of ctx.trace) {
       if (entry && entry.type === 'after' && typeof entry.callId === 'string' && typeof entry.endTime === 'number')
         ended[entry.callId] = entry.endTime
+      // A count's own answer, on the trace's clock: the \`locator.count()\` entry records
+      // \`result.value\`, and that number is the "Received:" the failing assertion printed.
+      if (entry && entry.type === 'after' && typeof entry.callId === 'string' &&
+        entry.result && typeof entry.result.value === 'number')
+        callValues[entry.callId] = entry.result.value
     }
     const pageByCall = {}
     for (const entry of ctx.trace) {
@@ -697,6 +1182,39 @@ for (const one of found.slice(0, MAX_TRACES)) {
         }
       }
       ctx.actions.push(action)
+      // The entries a count assertion can be attributed to (m321). A \`getByRole\`-style locator is
+      // readable only through the runner step's own \`params.locator\`; the library entry's
+      // \`params.selector\` is the internal engine string, kept for the CSS replay.
+      const locator =
+        (typeof entry.stepId === 'string' ? locatorByStep[entry.stepId] : undefined) ||
+        'locator(' + JSON.stringify(params.selector) + ')'
+      const end = typeof ended[entry.callId] === 'number' ? ended[entry.callId] : null
+      if (api === 'Frame.queryCount' && typeof params.selector === 'string') {
+        queryCounts.push({
+          start: entry.startTime,
+          end: end,
+          selector: params.selector,
+          value: typeof callValues[entry.callId] === 'number' ? callValues[entry.callId] : undefined,
+          locator: locator,
+          pageId: action.pageId,
+          stepId: action.stepId,
+        })
+      }
+      if (
+        api === 'Frame.expect' &&
+        /count/i.test(String(params.expression || '')) &&
+        typeof params.selector === 'string'
+      ) {
+        frameExpects.push({
+          start: entry.startTime,
+          end: end,
+          selector: params.selector,
+          expected: typeof params.expectedNumber === 'number' ? params.expectedNumber : undefined,
+          locator: locator,
+          pageId: action.pageId,
+          stepId: action.stepId,
+        })
+      }
     }
     // Monotonic time, not archive order: two contexts interleave in the zip, and one context's
     // own actions still have to be read in the order the page performed them.
@@ -1026,27 +1544,17 @@ for (const one of found.slice(0, MAX_TRACES)) {
   }
   // The text a frame snapshot SHOWED, so a page that still carried the awaited value is never
   // described as having dropped it. Playwright serializes the DOM as strings (text nodes) and
-  // [tag, attrs, ...children] elements, with a subtree reference ([[snapshotIndex, nodeIndex]]) to
-  // a node an earlier snapshot of the same frame carried. \`script\`/\`style\` bodies are skipped,
-  // as the trace viewer skips them: code is not what the page showed. Null when the snapshot is
-  // absent or a reference cannot be resolved — an unreadable snapshot proves nothing.
+  // [tag, attrs, ...children] elements, with a subtree reference ([delta, nodeIndex]) to a node an
+  // EARLIER snapshot of the same frame carried — the reference is relative to this snapshot's own
+  // index in the frame's list, which is how the trace viewer resolves it (\`snapshotIndex - delta\`).
+  // \`script\`/\`style\` bodies are skipped, as the trace viewer skips them: code is not what the page
+  // showed. Null when the snapshot is absent or a reference cannot be resolved — an unreadable
+  // snapshot proves nothing.
   function snapshotShowed(frame) {
     const tree = frame.snapshot
     if (tree === undefined || tree === null) return null
-    const shown = framesAll.filter(function (f) {
-      return f.context === frame.context && f.pageId === frame.pageId
-    })
-    const nodesOf = function (value) {
-      const nodes = []
-      const collect = function (n) {
-        if (typeof n === 'string') { nodes.push(n); return }
-        if (!Array.isArray(n) || typeof n[0] !== 'string') return
-        for (let i = 2; i < n.length; i++) collect(n[i])
-        nodes.push(n)
-      }
-      collect(value)
-      return nodes
-    }
+    const shown = frameSnapshotsOf(frame, framesAll)
+    const index = shown.indexOf(frame)
     const out = []
     let visited = 0
     let readable = true
@@ -1058,8 +1566,9 @@ for (const one of found.slice(0, MAX_TRACES)) {
         const ref = n[0]
         const at = Array.isArray(ref) && typeof ref[0] === 'number' ? ref[0] : -1
         const node = Array.isArray(ref) && typeof ref[1] === 'number' ? ref[1] : -1
-        const earlier = at >= 0 && at < shown.length && shown[at].snapshot != null ? shown[at].snapshot : null
-        const nodes = earlier === null ? [] : nodesOf(earlier)
+        const refAt = index - at
+        const earlier = at >= 0 && refAt >= 0 && refAt < shown.length && shown[refAt].snapshot != null ? shown[refAt].snapshot : null
+        const nodes = earlier === null ? [] : snapshotNodesOf(earlier)
         if (node < 0 || node >= nodes.length) { readable = false; return }
         visit(nodes[node])
         return
@@ -1132,6 +1641,11 @@ for (const one of found.slice(0, MAX_TRACES)) {
   // what the element is made of, so the note names the cause instead of sending the run at the
   // selector (m197 — an <img> with no CSS size collapsed inside its link).
   const hiddenBox = hiddenBoxOf(failedError, frames)
+  // A count assertion whose locator and matched elements the trace itself holds (m321): the
+  // locator from \`locator.count()\`/\`toHaveCount\`, the elements from the failure snapshot.
+  const countMismatch = await countMismatchOf(
+    failedError, frames, framesAll, queryCounts, frameExpects, failedStep, browserName
+  )
   function wire(r) {
     return {
       method: r.method,
@@ -1356,7 +1870,8 @@ for (const one of found.slice(0, MAX_TRACES)) {
     chosen.length === 0 &&
     keptConsole.length === 0 &&
     actions.length === 0 &&
-    hiddenBox === null
+    hiddenBox === null &&
+    countMismatch === null
   )
     continue
   // Counted over the page's EVERY network entry, before the cap and dedupe above (m215).
@@ -1375,12 +1890,19 @@ for (const one of found.slice(0, MAX_TRACES)) {
     ...(missingText === null ? {} : { missingText: missingText }),
     ...(readContradiction === null ? {} : { readContradiction: readContradiction }),
     ...(hiddenBox === null ? {} : { hiddenBox: hiddenBox }),
+    ...(countMismatch === null ? {} : { countMismatch: countMismatch }),
     console: keptConsole.slice(0, MAX_CONSOLE).map(function (text) { return text.slice(0, 300) }),
     actions: actions.slice(-MAX_ACTIONS),
     ...(unattributed ? { unattributed: true } : {}),
     ...(otherContexts.length > 0 ? { otherContexts: otherContexts } : {}),
   }) + '\\n')
 }
+}
+
+main().catch(function (error) {
+  process.stderr.write('trace read failed: ' +
+    String(error && error.message ? error.message : error) + '\\n')
+}).then(closeReplayBrowsers)
 `;
 /**
  * One request out of a `TRACE` line's json, or null when the value is not an object.
@@ -1496,6 +2018,62 @@ function parseHiddenBox(value) {
         ...(raw.empty === true ? { empty: true } : {}),
     };
 }
+/**
+ * One `countMismatch` out of a `TRACE` line's json, or null when the value is not one.
+ *
+ * The locator and both numbers are required; the matched elements are kept only when the script
+ * wrote them, and each needs a tag. A reading whose `unreadable` reason is unknown is dropped —
+ * the note may not present a reason it cannot explain.
+ *
+ * @param value - The line's `countMismatch`.
+ * @returns The count assertion the trace read, or null.
+ */
+function parseCountMismatch(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const raw = value;
+    if (typeof raw.locator !== 'string' || raw.locator === '')
+        return null;
+    if (typeof raw.expected !== 'number' || !Number.isFinite(raw.expected))
+        return null;
+    if (typeof raw.received !== 'number' || !Number.isFinite(raw.received))
+        return null;
+    if (raw.source !== 'assertion' && raw.source !== 'locator-count')
+        return null;
+    const matched = Array.isArray(raw.matched)
+        ? raw.matched
+            .filter((entry) => typeof entry === 'object' && entry !== null)
+            .filter((entry) => typeof entry.tag === 'string' && entry.tag !== '')
+            .map((entry) => ({
+            tag: String(entry.tag),
+            ...(typeof entry.classes === 'string' && entry.classes ? { classes: entry.classes } : {}),
+            ...(typeof entry.text === 'string' && entry.text ? { text: entry.text } : {}),
+            ...(typeof entry.path === 'string' && entry.path ? { path: entry.path } : {}),
+            ...(entry.inForm === true ? { inForm: true } : {}),
+        }))
+        : [];
+    const unreadable = raw.unreadable === 'unsupported-selector' ||
+        raw.unreadable === 'no-snapshot' ||
+        raw.unreadable === 'count-mismatch' ||
+        raw.unreadable === 'browser-unavailable'
+        ? raw.unreadable
+        : null;
+    return {
+        locator: raw.locator,
+        ...(typeof raw.selector === 'string' && raw.selector ? { selector: raw.selector } : {}),
+        expected: raw.expected,
+        received: raw.received,
+        source: raw.source,
+        ...(matched.length === 0 ? {} : { matched }),
+        ...(typeof raw.matchedTotal === 'number' && Number.isFinite(raw.matchedTotal)
+            ? { matchedTotal: raw.matchedTotal }
+            : {}),
+        ...(raw.matchedFrom === 'snapshot-targets' || raw.matchedFrom === 'selector-replay'
+            ? { matchedFrom: raw.matchedFrom }
+            : {}),
+        ...(unreadable === null ? {} : { unreadable }),
+    };
+}
 /**
  * One `lastAction` out of a `TRACE` line's json, or null when the value is not one.
  *
@@ -1576,6 +2154,7 @@ export function parseTraceArtifacts(stdout) {
             const missingText = parseMissingText(raw.missingText);
             const readContradiction = parseReadContradiction(raw.readContradiction);
             const hiddenBox = parseHiddenBox(raw.hiddenBox);
+            const countMismatch = parseCountMismatch(raw.countMismatch);
             const repeated = parseRepeated(raw.repeated);
             const otherContexts = Array.isArray(raw.otherContexts)
                 ? raw.otherContexts
@@ -1615,6 +2194,7 @@ export function parseTraceArtifacts(stdout) {
                 ...(missingText === null ? {} : { missingText }),
                 ...(readContradiction === null ? {} : { readContradiction }),
                 ...(hiddenBox === null ? {} : { hiddenBox }),
+                ...(countMismatch === null ? {} : { countMismatch }),
                 ...(repeated.length === 0 ? {} : { repeated }),
             });
         }
@@ -2150,6 +2730,9 @@ function traceRowEvidence(item, report) {
     // have resolved the locator into an empty box, and that is the whole cause (m197's shape on a
     // static page).
     item.hiddenBox !== undefined ||
+        // A count assertion's own reading is evidence too: the trace names the locator and the
+        // elements that made the count too large, even when every request answered (m321).
+        item.countMismatch !== undefined ||
         item.console.length > 0 ||
         item.requests.some((request) => !isStaticAssetRequest(request) && !unansweredRequest(request)) ||
         // The one shape in which a subresource with no response IS the cause: the navigation the
@@ -3207,6 +3790,75 @@ export function hiddenBoxNote(items) {
     }
     return null;
 }
+/** One matched element as a count row writes it: tag.class, its own text, and where it sits. */
+function countMatchSentence(match) {
+    const classes = match.classes === undefined ? '' : `.${match.classes.trim().split(/\s+/).join('.')}`;
+    const text = match.text === undefined ? '' : ` "${match.text}"`;
+    const where = [
+        match.path === undefined ? '' : `in \`${match.path}\``,
+        match.inForm === true ? 'inside a form' : '',
+    ]
+        .filter(Boolean)
+        .join(', ');
+    return `\`${match.tag}${classes}\`${text}${where === '' ? '' : ` (${where})`}`;
+}
+/**
+ * The row's sentence for a failing count assertion: the locator, both numbers, and the elements
+ * the failure snapshot held.
+ *
+ * xr-molecule-flash-m321's `comments.spec.ts:86` printed only `Expected: 3 / Received: 4`. The
+ * helper counted `.card:not(.comment-form) .card-block`, and the app's comment form was a
+ * `.comment-form` wrapper around a plain `.card`, so the form's own `.card-block` was the fourth
+ * match. The trace held the selector and the four elements; the note held neither.
+ *
+ * @param mismatch - The trace's count reading ({@link TraceCountMismatch}).
+ * @returns The sentence.
+ */
+export function countMismatchSentence(mismatch) {
+    const counted = `the failing assertion counted \`${mismatch.locator}\`: ${mismatch.received} matched where ` +
+        `${mismatch.expected} ${mismatch.expected === 1 ? 'was' : 'were'} expected`;
+    if (mismatch.matched !== undefined && mismatch.matchedTotal !== undefined) {
+        const shown = mismatch.matchedTotal - mismatch.matched.length;
+        const how = mismatch.matchedFrom === 'snapshot-targets'
+            ? `the trace's failure snapshot marks the assertion's ${mismatch.matchedTotal} ` +
+                `${mismatch.matchedTotal === 1 ? 'match' : 'matches'}`
+            : `the selector replayed against the trace's failure snapshot matched ` +
+                `${mismatch.matchedTotal}`;
+        return (`${counted}; ${how}: ${mismatch.matched.map(countMatchSentence).join('; ')}` +
+            (shown > 0 ? `; and ${shown} more` : ''));
+    }
+    if (mismatch.unreadable === 'unsupported-selector')
+        return (`${counted}. The trace records the locator and the count but not the elements it selected ` +
+            `(a browser's own CSS query cannot express that locator for the failure snapshot), ` +
+            `so read that helper's selector against the page yourself`);
+    if (mismatch.unreadable === 'browser-unavailable')
+        return (`${counted}. The failure snapshot could not be replayed because the project's Playwright ` +
+            `module or the recorded browser's executable was not available, so the matched elements ` +
+            `are not named — read that helper's selector against the page yourself`);
+    if (mismatch.unreadable === 'count-mismatch')
+        return (`${counted}. The failure snapshot's DOM replayed to a different count, so it is not ` +
+            `evidence for this assertion and the matched elements are not named`);
+    return (`${counted}. The trace recorded no readable DOM snapshot at the failure, so the matched ` +
+        `elements are not named`);
+}
+/**
+ * The sentence a count assertion earns when every traced failure is one — the next read before
+ * the API or the request is changed.
+ *
+ * @param items - The traces {@link parseTraceArtifacts} read.
+ * @returns The sentence, or null when not every traced failure is a count mismatch.
+ */
+export function countMismatchNote(items) {
+    if (items.length === 0)
+        return null;
+    if (!items.every((item) => item.countMismatch !== undefined))
+        return null;
+    return ('No listed request failed — none got a 4xx/5xx or a network error. Every failure here is a ' +
+        'COUNT over a locator, and each row names the locator the trace recorded and the elements ' +
+        'its failure snapshot held. Read the extra element and the selector before changing the ' +
+        'request or the API: a match that sits inside another element (a form, a wrapper) is the ' +
+        'selector reaching it, not the list rendering it.');
+}
 /**
  * The note a failed suite run's result carries: what each failing test's page actually sent, and
  * what came back.
@@ -3353,6 +4005,9 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
     // "the cause is in the page" sentence, which m197 read as "go look at the page" and then spent
     // four minutes rasterising an SVG ({@link hiddenBoxNote}).
     const hiddenBox = hiddenBoxNote(traced);
+    // Every traced failure a count assertion: the next read is the locator's matches, not a request
+    // or the page's state (m321's 30-minute `Expected: 3 / Received: 4`).
+    const everyCountMismatch = countMismatchNote(traced);
     // m145's shape: the app's HTTP client lost its base URL, so every API call reached the page
     // origin without the prefix the app mounts its routes under. The prefix is READ — the caller's
     // client config plus what the traces show — never assumed to be `/api`.
@@ -3449,6 +4104,10 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
         const budget = stall?.budgetMs ?? null;
         let room = MAX_TRACE_NOTE_REQUESTS;
         const parts = [];
+        // The count reading leads the row: the locator and the extra element are the fact the run
+        // needs first (m321), the requests beside it explain nothing about a count.
+        if (item.countMismatch !== undefined)
+            parts.push(countMismatchSentence(item.countMismatch));
         if (step !== undefined && !stalledNav) {
             const head = `the test's last action was ${step.api} at ${actionClock(item, step.start)}`;
             const pageBefore = step.pageBefore;
@@ -3762,17 +4421,21 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
                                         `${serverSilentReading(silentApiRequests, silentNavigations, false)} ` +
                                         `Re-run only these tests against ${target} (\`--last-failed\`) or inspect the app's ` +
                                         'runtime log for the same window to distinguish the cause.'
-                                : hasPendingRequests
-                                    ? 'No listed request failed with a 4xx/5xx or a network error, but some requests have no ' +
-                                        'recorded response. This does not establish whether the server stalled or the browser cancelled ' +
-                                        'the request. Read the pending paths alongside the failed action and its timeout.'
-                                    : 'No listed request failed with a 4xx/5xx or a network error. That does not establish ' +
-                                        "that its response body or the page state was correct. Read what the test's last action sent (the first line of each " +
-                                        'row) and what the page did next: a request that answered (2xx included) while the page ' +
-                                        'still did not show the state the assertion waited on is the fact to read — its status ' +
-                                        'and response body, not the selector. If the request is not the one the test meant — an ' +
-                                        'unfollow sent where the test clicked follow — the state the action read was stale ' +
-                                        'before it.') +
+                                : everyCountMismatch !== null
+                                    ? // A count assertion's own reading outranks the generic "read the response body"
+                                        // advice, which sends the run at the request the count never depended on (m321).
+                                        everyCountMismatch
+                                    : hasPendingRequests
+                                        ? 'No listed request failed with a 4xx/5xx or a network error, but some requests have no ' +
+                                            'recorded response. This does not establish whether the server stalled or the browser cancelled ' +
+                                            'the request. Read the pending paths alongside the failed action and its timeout.'
+                                        : 'No listed request failed with a 4xx/5xx or a network error. That does not establish ' +
+                                            "that its response body or the page state was correct. Read what the test's last action sent (the first line of each " +
+                                            'row) and what the page did next: a request that answered (2xx included) while the page ' +
+                                            'still did not show the state the assertion waited on is the fact to read — its status ' +
+                                            'and response body, not the selector. If the request is not the one the test meant — an ' +
+                                            'unfollow sent where the test clicked follow — the state the action read was stale ' +
+                                            'before it.') +
         prefixAdvice +
         (wrapped
             ? ' The API received a body wrapped in `data`: app-http’s `post(url, data, config)` / ' +