@molecule/api-ai-tools 1.10.1 → 1.10.3

package/dist/trace-artifacts.js

@@ -203,26 +203,142 @@ function messageOf(value) {
 const FILLING_ACTION = /\\.(?:fill|type|pressSequentially|selectOption)$/
 
 // The text a failing assertion waited for, named by its own error: a \`has-text(…)\` CSS
-// pseudo-class, a \`getByText(…)\` locator, or a \`toContainText(…)\` expectation. A strict-mode
-// violation is not this shape — two elements DID match the text — and neither is a wait on a
-// selector with no text argument. The ANSI colouring Playwright leaves in the message is dropped
-// before the read, or the quotes it wraps around a locator would never parse.
+// pseudo-class, a \`getByText(…)\` locator, or a \`toContainText(…)\` expectation — and only when
+// the failure IS an absence of that text. A strict-mode violation is not this shape (two elements
+// DID match), and neither is a wait on a selector with no text argument.
+//
+// A locator that RESOLVED is not an absent element either: Playwright names the element it matched
+// and then says why the action could not run (m194's disabled button carried the very title the
+// note called missing). A disabled, invisible, unstable, detached or intercepted control is a
+// control problem, not a rendering one, so none of those shapes may produce a missing-text reading.
+// The ANSI colouring Playwright leaves in the message is dropped before the read, or the quotes it
+// wraps around a locator would never parse.
 function waitedTextOf(message) {
   if (!message) return null
   const text = String(message).replace(/\\u001b\\[[0-9;]*m/g, '')
   if (text.indexOf('strict mode violation') !== -1) return null
+  if (text.indexOf('locator resolved to') !== -1) return null
+  if (/element is not (?:enabled|visible|stable|attached)/.test(text)) return null
+  if (/intercepts? pointer events/.test(text)) return null
+  // Playwright's own not-found marker is what an absence assertion leaves behind; a text
+  // expectation that failed on an element it DID find is the other absence shape (its received
+  // text lacks the expected one).
+  const notFound = /element\\(s\\) not found|element is not found/.test(text)
   const quoted = function (pattern) {
     const m = pattern.exec(text)
     return m === null ? null : m[2]
   }
   const hasText = quoted(/has-text\\(\\s*(['"])((?:(?!\\1).)*)\\1/)
-  if (hasText !== null) return hasText
+  if (hasText !== null) return notFound ? hasText : null
   const byText = quoted(/getByText\\(\\s*(['"])((?:(?!\\1).)*)\\1/)
-  if (byText !== null) return byText
+  if (byText !== null) return notFound ? byText : null
   if (text.indexOf('toContainText') === -1) return null
   return quoted(/Expected(?: string)?:\\s*(["'])((?:(?!\\1).)*)\\1/)
 }
 
+// The attributes of one serialized element's opening tag (\`class="a b" id="c"\`). The trace's
+// snapshots carry them as an object already; the ASSERTION's error prints the tag as text.
+function attrsOf(source) {
+  const out = {}
+  const pattern = /([A-Za-z_:][-A-Za-z0-9_:.]*)\\s*=\\s*("([^"]*)"|'([^']*)')/g
+  let match
+  while ((match = pattern.exec(String(source || ''))) !== null)
+    out[match[1].toLowerCase()] = match[3] !== undefined ? match[3] : match[4]
+  return out
+}
+
+// Whether a serialized subtree carries text of its own. A text node is a string; an element is
+// \`[tag, attrs, …children]\`. A reference to an earlier snapshot is not followed here: the caller
+// only makes a claim when every child is readable in place.
+function subtreeText(node) {
+  if (typeof node === 'string') return node.trim() !== ''
+  if (!Array.isArray(node) || Array.isArray(node[0]) || typeof node[0] !== 'string') return false
+  for (let i = 2; i < node.length; i++) if (subtreeText(node[i])) return true
+  return false
+}
+
+// The serialized element children of a node, in document order (references skipped).
+function elementChildren(node) {
+  const out = []
+  if (!Array.isArray(node)) return out
+  for (let i = 2; i < node.length; i++) {
+    const child = node[i]
+    if (typeof child === 'string' || !Array.isArray(child)) continue
+    if (Array.isArray(child[0]) || typeof child[0] !== 'string') continue
+    out.push(child)
+  }
+  return out
+}
+
+// The first element in a serialized DOM tree with this tag and (when given) id or first class.
+// Playwright's snapshot serializes elements as \`[tag, attrs, …children]\`.
+function findElement(node, tag, id, cls) {
+  if (typeof node === 'string' || !Array.isArray(node)) return null
+  if (Array.isArray(node[0]) || typeof node[0] !== 'string') return null
+  if (node[0].toLowerCase() === tag) {
+    const attrs = node[1] && typeof node[1] === 'object' ? node[1] : {}
+    const idMatch = id === '' || String(attrs.id || '') === id
+    const classes = String(attrs.class || attrs.className || '').split(/\\s+/)
+    const classMatch = id !== '' || cls === '' || classes.indexOf(cls) !== -1
+    if (idMatch && classMatch) return node
+  }
+  for (let i = 2; i < node.length; i++) {
+    const deeper = findElement(node[i], tag, id, cls)
+    if (deeper !== null) return deeper
+  }
+  return null
+}
+
+// A locator that RESOLVED whose box Playwright calls hidden. Playwright reports "hidden" for an
+// element with a zero-size box even when it is painted, so the interesting question is why the
+// box is empty — and the trace's own frame snapshot carries the element's children, the only
+// evidence the run would otherwise have to probe for (xr-molecule-flash-m197: \`a.navbar-brand\`
+// was 0x4 px because its only child was an <img> with no CSS size, and the note said only that
+// "the cause is in the page"; the run spent 4.5 minutes rasterising an SVG to PNG).
+// Only what the snapshot proves is reported: an inline display:none/visibility:hidden, a lone
+// <img> child, or a textless element with no children. Anything else says nothing.
+function hiddenBoxOf(message, frames) {
+  if (!message) return null
+  const text = String(message).replace(/\\u001b\\[[0-9;]*m/g, '')
+  if (text.indexOf('strict mode violation') !== -1) return null
+  if (!/Received:\\s*hidden/.test(text) && text.indexOf('element is not visible') === -1) return null
+  const resolved = /locator resolved to <([A-Za-z][\\w:-]*)((?:[^>"']|"[^"]*"|'[^']*')*)>/.exec(text)
+  if (resolved === null) return null
+  const tag = resolved[1].toLowerCase()
+  const attrs = attrsOf(resolved[2])
+  const id = attrs.id || ''
+  const cls = String(attrs.class || attrs.className || '').split(/\\s+/).filter(Boolean)[0] || ''
+  const named = /Locator:\\s*([^\\n]+)/.exec(text)
+  const reading = {
+    locator: named !== null ? named[1].trim() : cls ? tag + '.' + cls : tag,
+    tag: tag,
+  }
+  const snapshot = frames.length > 0 ? frames[frames.length - 1].snapshot : null
+  const node = snapshot === null || snapshot === undefined ? null : findElement(snapshot, tag, id, cls)
+  if (node === null) return null
+  const own = node[1] && typeof node[1] === 'object' ? node[1] : {}
+  if (typeof own.style === 'string' && own.style) reading.style = own.style.slice(0, 160)
+  if (!subtreeText(node)) {
+    const children = elementChildren(node)
+    if (children.length === 1 && children[0][0].toLowerCase() === 'img') {
+      const image = children[0][1] && typeof children[0][1] === 'object' ? children[0][1] : {}
+      reading.image = {}
+      for (const key of ['src', 'width', 'height', 'style', 'alt']) {
+        if (typeof image[key] === 'string' && image[key])
+          reading.image[key] = image[key].slice(0, 120)
+      }
+      if (typeof image.class === 'string' && image.class) reading.image.className = image.class.slice(0, 120)
+    } else if (children.length === 0) {
+      reading.empty = true
+    }
+  }
+  const hiddenStyle = /(?:^|;)\\s*display\\s*:\\s*none|(?:^|;)\\s*visibility\\s*:\\s*hidden/.test(
+    typeof own.style === 'string' ? own.style : '',
+  )
+  if (!reading.image && !reading.empty && !hiddenStyle) return null
+  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.
@@ -479,6 +595,11 @@ for (const one of found.slice(0, MAX_TRACES)) {
         context: ctx.id,
         pageId: typeof snap.pageId === 'string' ? snap.pageId : undefined,
         frameId: typeof snap.frameId === 'string' ? snap.frameId : undefined,
+        // The snapshot's own DOM tree, kept by reference (the trace line already holds it). The
+        // note reads its text only when it has to prove an awaited value was absent from the page
+        // (m194's false "dropped before rendering" lead). Playwright serializes text nodes as
+        // strings and elements as [tag, attrs, ...children].
+        snapshot: snap.html,
       })
     }
     for (const entry of ctx.trace) {
@@ -776,26 +897,108 @@ for (const one of found.slice(0, MAX_TRACES)) {
     if (sent) r.sent = sent
     if (got) r.got = got
   }
+  // 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.
+  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 out = []
+    let visited = 0
+    let readable = true
+    const visit = function (n) {
+      if (++visited > 400000) { readable = false; return }
+      if (typeof n === 'string') { out.push(n); return }
+      if (!Array.isArray(n)) return
+      if (Array.isArray(n[0])) {
+        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)
+        if (node < 0 || node >= nodes.length) { readable = false; return }
+        visit(nodes[node])
+        return
+      }
+      if (typeof n[0] !== 'string') return
+      const name = n[0].toUpperCase()
+      if (name === 'SCRIPT' || name === 'STYLE') return
+      for (let i = 2; i < n.length; i++) visit(n[i])
+    }
+    visit(tree)
+    return readable ? out.join('') : null
+  }
   // The text the failing assertion waited for, and a response the SAME page received that carried
   // it (m169). The assertion's own error names the text; the network log says whether it ever
   // reached the browser. Only an answered fetch/xhr can say the API returned it — a 4xx body is an
   // error message, not data. The most focused response wins (smallest body): an articles list also
   // carries tag names in its \`tagList\`, while the tags response is the collection whose membership
   // the assertion tests.
+  //
+  // The "page drops it before rendering" claim is made only when the trace PROVES it: a successful
+  // GET of the collection that STARTED AFTER the last navigation, and the awaited text absent from
+  // the page's own failure snapshot. A creation POST says nothing about what a collection render
+  // drops — m194's button failure was labelled missing while its title was on the page and the
+  // only carrier was \`POST /api/articles\` — and a snapshot that still shows the text says the
+  // opposite. Without that proof the note only says a response contained the text.
   const waitedText = waitedTextOf(failedError)
   let missingText = null
   if (waitedText !== null && !unattributed) {
+    let lastNavigation = null
+    for (const a of actions) {
+      if (!/\\.(?:goto|reload|goBack|goForward)$/.test(a.api)) continue
+      if (lastNavigation === null || a.start > lastNavigation) lastNavigation = a.start
+    }
     let best = null
+    let bestGet = null
     for (const r of requests) {
       if (r.type !== 'fetch' && r.type !== 'xhr') continue
       if (r.status < 200 || r.status >= 400) continue
       const got = gotText(buf, entries, r)
       if (!got || got.indexOf(waitedText) === -1) continue
       if (best === null || got.length < best.got.length) best = { request: r, got: got }
+      // The collection read the claim may rest on: a GET that started after the last navigation
+      // (a request that started before it belongs to the page load, not to the failure).
+      if (r.method !== 'GET') continue
+      if (lastNavigation === null || typeof r.startedAt !== 'number' || r.startedAt <= lastNavigation) continue
+      if (bestGet === null || got.length < bestGet.got.length) bestGet = { request: r, got: got }
+    }
+    if (best !== null) {
+      const named = bestGet === null ? best : bestGet
+      let dropped = false
+      if (bestGet !== null && frames.length > 0) {
+        const shown = snapshotShowed(frames[frames.length - 1])
+        dropped = shown !== null && shown.indexOf(waitedText) === -1
+      }
+      missingText = {
+        text: waitedText,
+        method: named.request.method,
+        path: named.request.path,
+        ...(dropped ? { dropped: true } : {}),
+      }
     }
-    if (best !== null)
-      missingText = { text: waitedText, method: best.request.method, path: best.request.path }
   }
+  // A visibility failure whose element RESOLVED but has an empty box: the snapshot's own DOM says
+  // 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)
   function wire(r) {
     return {
       method: r.method,
@@ -1016,7 +1219,13 @@ for (const one of found.slice(0, MAX_TRACES)) {
   const specific = consoleErrors.filter(function (text) { return !/^Failed to load resource/.test(text) })
   const keptConsole = specific.concat(consoleSignals, consoleWarnings)
   if (specific.length === 0) keptConsole.push.apply(keptConsole, consoleErrors)
-  if (chosen.length === 0 && keptConsole.length === 0 && actions.length === 0) continue
+  if (
+    chosen.length === 0 &&
+    keptConsole.length === 0 &&
+    actions.length === 0 &&
+    hiddenBox === null
+  )
+    continue
   process.stdout.write('TRACE ' + JSON.stringify({
     dir: path.relative(ROOT, path.dirname(one.file)),
     spec: spec,
@@ -1029,6 +1238,7 @@ for (const one of found.slice(0, MAX_TRACES)) {
     requests: chosen.slice(0, MAX_REQUESTS),
     ...(missingText === null ? {} : { missingText: missingText }),
     ...(readContradiction === null ? {} : { readContradiction: readContradiction }),
+    ...(hiddenBox === null ? {} : { hiddenBox: hiddenBox }),
     console: keptConsole.slice(0, MAX_CONSOLE).map(function (text) { return text.slice(0, 300) }),
     actions: actions.slice(-MAX_ACTIONS),
     ...(unattributed ? { unattributed: true } : {}),
@@ -1081,7 +1291,12 @@ function parseMissingText(value) {
         return null;
     if (typeof raw.path !== 'string' || raw.path === '')
         return null;
-    return { text: raw.text, method: raw.method, path: raw.path };
+    return {
+        text: raw.text,
+        method: raw.method,
+        path: raw.path,
+        ...(raw.dropped === true ? { dropped: true } : {}),
+    };
 }
 /**
  * One `readContradiction` out of a `TRACE` line's json, or null when the value is not one.
@@ -1106,6 +1321,45 @@ function parseReadContradiction(value) {
         return null;
     return { field: raw.field, writeValue: raw.writeValue, readValue: raw.readValue, write, read };
 }
+/**
+ * One `hiddenBox` out of a `TRACE` line's json, or null when the value is not one.
+ *
+ * The locator and tag are required; the image/empty/style detail is optional evidence, kept only
+ * in the shape the script wrote it.
+ *
+ * @param value - The line's `hiddenBox`.
+ * @returns The element the failed locator resolved to, or null.
+ */
+function parseHiddenBox(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const raw = value;
+    if (typeof raw.locator !== 'string' || raw.locator === '')
+        return null;
+    if (typeof raw.tag !== 'string' || raw.tag === '')
+        return null;
+    // An `image` that parses to no attributes is still the fact that the element wraps an <img>:
+    // its presence is the evidence, so an empty object stays.
+    const image = typeof raw.image === 'object' && raw.image !== null
+        ? (() => {
+            const at = raw.image;
+            const out = {};
+            for (const key of ['src', 'width', 'height', 'style', 'className', 'alt']) {
+                const field = at[key];
+                if (typeof field === 'string' && field !== '')
+                    out[key] = field;
+            }
+            return out;
+        })()
+        : null;
+    return {
+        locator: raw.locator,
+        tag: raw.tag,
+        ...(typeof raw.style === 'string' && raw.style ? { style: raw.style } : {}),
+        ...(image === null ? {} : { image }),
+        ...(raw.empty === true ? { empty: true } : {}),
+    };
+}
 /**
  * One `lastAction` out of a `TRACE` line's json, or null when the value is not one.
  *
@@ -1153,6 +1407,7 @@ export function parseTraceArtifacts(stdout) {
             const lastAction = parseLastAction(raw.lastAction);
             const missingText = parseMissingText(raw.missingText);
             const readContradiction = parseReadContradiction(raw.readContradiction);
+            const hiddenBox = parseHiddenBox(raw.hiddenBox);
             const otherContexts = Array.isArray(raw.otherContexts)
                 ? raw.otherContexts
                     .filter((c) => typeof c === 'object' && c !== null)
@@ -1190,6 +1445,7 @@ export function parseTraceArtifacts(stdout) {
                 ...(raw.unattributed === true ? { unattributed: true } : {}),
                 ...(missingText === null ? {} : { missingText }),
                 ...(readContradiction === null ? {} : { readContradiction }),
+                ...(hiddenBox === null ? {} : { hiddenBox }),
             });
         }
         catch (_error) {
@@ -2141,15 +2397,22 @@ function missingApiPrefixSentence(request) {
 /**
  * The sentence for a failing assertion whose awaited text a same-page API response carried.
  *
- * It names the response and the fact the trace proves — the value reached the browser and the page
- * did not render it — and stops there. Which cut drops it (a slice, a filter, a limit) is in the
- * component that maps the response, and the note cannot see that component; naming the mapping
- * step is the whole instruction (xr-molecule-flash-m169).
+ * With proof ({@link TraceMissingText.dropped}) it names the response and the fact the trace
+ * proves — the value reached the browser and the page did not render it — and stops there. Which
+ * cut drops it (a slice, a filter, a limit) is in the component that maps the response, and the
+ * note cannot see that component; naming the mapping step is the whole instruction
+ * (xr-molecule-flash-m169).
+ *
+ * Without that proof the sentence says only what the trace shows — a response contained the text —
+ * and makes no rendering claim: m194's awaited title was on the page, in a disabled button, while
+ * the only response carrying it was the creation POST (a button failure is not a missing article).
  *
  * @param missing - The awaited text and the response that carried it.
  * @returns The sentence the note leads with.
  */
 function missingTextSentence(missing) {
+    if (missing.dropped !== true)
+        return `The response ${missing.method} ${missing.path} contained "${missing.text}".`;
     return (`The API returned "${missing.text}" (in ${missing.method} ${missing.path}), but the page did ` +
         `not render it — the page drops it before rendering (a slice/filter/limit in the component ` +
         `that renders that list); find where that response is mapped.`);
@@ -2344,6 +2607,71 @@ function consoleLine(text) {
     return (`${url} answered the app's index.html, not a font — the file is missing from ` +
         `\`app/public/\` (or the asset import); copy/import it`);
 }
+/** An `<img>` as the failure snapshot recorded it, for the note's sentence. */
+function imageMarkup(image) {
+    const attrs = [
+        image.src === undefined ? '' : `src="${image.src}"`,
+        image.alt === undefined ? '' : `alt="${image.alt}"`,
+        image.width === undefined ? '' : `width="${image.width}"`,
+        image.height === undefined ? '' : `height="${image.height}"`,
+        image.className === undefined ? '' : `class="${image.className}"`,
+        image.style === undefined ? '' : `style="${image.style}"`,
+    ].filter(Boolean);
+    return `<img${attrs.length > 0 ? ` ${attrs.join(' ')}` : ''}>`;
+}
+/** Whether an image's CSS (its class or inline style) declares a width or height. */
+const IMAGE_SIZE_RULE = /(?:^|;)\s*(?:width|height|max-width|max-height)\s*:/;
+const HIDING_RULE = /(?:^|;)\s*(?:display\s*:\s*none|visibility\s*:\s*hidden)/;
+/**
+ * The sentence a "hidden" visibility failure earns when the trace proved WHY the box is empty.
+ *
+ * Playwright calls an element with a zero-size box hidden even when it is painted, so the answer
+ * is in the element's children. `a.navbar-brand` on xr-molecule-flash-m197 was 0×4 px because its
+ * only child was `<img src="/conduit-logo.svg" height="26">`: an SVG with a `viewBox` and no
+ * width/height has no intrinsic size, and the `height` attribute loses to Tailwind's preflight
+ * (`img { max-width: 100%; height: auto }`), which the scaffold's own `index.css` imports. The
+ * note said only "the cause is in the page", and the run spent over four minutes rasterising an
+ * SVG to PNG. Only what the snapshot shows is claimed ({@link TraceHiddenBox}).
+ *
+ * @param items - The traces {@link parseTraceArtifacts} read.
+ * @returns The sentence, or null when no failure carries a hidden-box reading.
+ */
+export function hiddenBoxNote(items) {
+    const box = items.find((item) => item.hiddenBox !== undefined)?.hiddenBox;
+    if (box === undefined)
+        return null;
+    const element = `\`${box.locator}\``;
+    if (box.image !== undefined) {
+        const image = box.image;
+        const shown = imageMarkup(image);
+        const sized = image.className !== undefined ||
+            (image.style !== undefined && IMAGE_SIZE_RULE.test(image.style));
+        if (sized) {
+            const rule = image.className === undefined ? 'its inline size' : `\`${image.className}\``;
+            return (`${element} resolved but Playwright calls it hidden: its box has no size, and its only ` +
+                `content is ${shown}. That image declares a size (${rule}), so the rule is not applying ` +
+                `on this page — check that the stylesheet defining it is actually loaded (a supplied ` +
+                `theme has to be linked in index.html, not only imported) and that the class name is ` +
+                `spelled the way the theme defines it.`);
+        }
+        return (`${element} resolved but Playwright calls it hidden: the element's box is empty, and its ` +
+            `only content is ${shown} — an image with no CSS size. An <img> takes its size from CSS or ` +
+            `from the file; an SVG that declares only a viewBox has no intrinsic size, and a ` +
+            `width/height ATTRIBUTE loses to any stylesheet rule (Tailwind's preflight, which the ` +
+            `scaffold's index.css imports, sets img { max-width: 100%; height: auto }). Give the image a ` +
+            `CSS width/height — a class the supplied theme already defines for it, or ` +
+            `style={{ height: … }} — rather than changing the SVG or rasterising it to PNG.`);
+    }
+    if (box.style !== undefined && HIDING_RULE.test(box.style)) {
+        return (`${element} resolved but Playwright calls it hidden: its own inline style sets ` +
+            `\`${box.style}\`. Remove that declaration (or the rule that sets it) so the element has a box.`);
+    }
+    if (box.empty === true) {
+        return (`${element} resolved but Playwright calls it hidden: the element has no text and no ` +
+            `children, so its box has zero size. Give it content or an explicit width/height.`);
+    }
+    return null;
+}
 /**
  * The note a failed suite run's result carries: what each failing test's page actually sent, and
  * what came back.
@@ -2482,6 +2810,10 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
     const wrapped = traced.some((item) => item.requests.some((request) => request.sent !== undefined && wrappedInData(request.sent)));
     // The "one of these requests failing" answer is only honest when a listed request really failed.
     const anyFailed = traced.some((item) => item.requests.some(failedRequest));
+    // A visibility failure the trace's own snapshot explains: said instead of the generic
+    // "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);
     // 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`.
@@ -2746,14 +3078,19 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
     // first, before any row, is that the value arrived and the page dropped it (m169's missing
     // "trending" came back from GET /api/tags while the sidebar rendered a cut list). Each distinct
     // response is named once; the note makes no claim about which cut did it.
-    const missingTexts = [
-        ...new Map(traced
-            .filter((item) => item.missingText !== undefined)
-            .map((item) => {
-            const missing = item.missingText;
-            return [`${missing.method} ${missing.path}\u0000${missing.text}`, missing];
-        })).values(),
-    ];
+    // One sentence per response; a trace that PROVES the drop upgrades one that only saw the same
+    // response carry the text.
+    const missingByResponse = new Map();
+    for (const item of traced) {
+        if (item.missingText === undefined)
+            continue;
+        const missing = item.missingText;
+        const key = `${missing.method} ${missing.path}\u0000${missing.text}`;
+        const seen = missingByResponse.get(key);
+        if (seen === undefined || (seen.dropped !== true && missing.dropped === true))
+            missingByResponse.set(key, missing);
+    }
+    const missingTexts = [...missingByResponse.values()];
     const missingTextLead = missingTexts.length === 0
         ? ''
         : `${missingTexts.slice(0, 2).map(missingTextSentence).join(' ')}\n\n`;
@@ -2841,13 +3178,17 @@ export function failureTraceNote(items, target, earlierFailures = [], apiPrefixe
                             'action sent no request at all, so there is no response to read. The page changed ' +
                             'route and fetched nothing, which is why it still shows the previous route’s data: ' +
                             'fix how the page reads the route, not the selector.'
-                        : 'No listed request failed — none got a 4xx/5xx or a network error — so the cause is in the ' +
-                            "page, not the API. Start with 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.') +
+                        : hiddenBox !== null
+                            ? // The trace's own snapshot explains why the element Playwright resolved has no box:
+                                // a fact about the element, so it replaces the "look at the page" advice (m197).
+                                hiddenBox
+                            : 'No listed request failed — none got a 4xx/5xx or a network error — so the cause is in the ' +
+                                "page, not the API. Start with 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)` / ' +

package/dist/types.d.ts

@@ -63,14 +63,34 @@ export interface SuiteBudgetPin {
     /**
      * The Playwright flags that carry the suite's own settings onto the command
      * (`--timeout=15000`, `--workers=1`), as the consumer's own scan reads them. Empty when the
-     * difference is in settings no flag carries — the pin is then the sentence alone.
+     * difference is in settings no flag carries.
      */
     flags: string[];
+    /** One sentence for the run's result: which of the suite's own settings this run uses. */
+    note: string;
     /**
-     * One sentence for the run's result: this run uses the suite's own budget, and which settings
-     * a config keeps because Playwright has no flag for them.
+     * A config file the consumer wrote OUTSIDE the supplied suite, which re-imports the config the
+     * run selected and pins the settings no Playwright flag can carry (`expect.timeout`,
+     * `use.actionTimeout`, `use.navigationTimeout`). When present, the run is launched with
+     * `--config <this path>` in place of the config it named, so those settings are the suite's own
+     * rather than the executor's. Absent when the consumer could not write one.
      */
-    note: string;
+    config?: string;
+    /**
+     * Every setting the derived config ({@link config}) pins at the suite's own value, by the scan's
+     * key (`timeout`, `expect.timeout`, `actionTimeout`, `navigationTimeout`), in milliseconds as
+     * digits. Empty when no derived config was placed.
+     */
+    values?: Record<string, string>;
+    /**
+     * Every setting the run's own config makes different from the suite's, as the consumer's scan
+     * read them: the value this run's config writes and the suite's own. The tool reports the ones
+     * its placement did NOT put back, so a result never claims a drift it carried.
+     */
+    drift?: Record<string, {
+        used: string;
+        suite: string;
+    }>;
 }
 /**
  * Configuration for building the tool set.
@@ -188,7 +208,8 @@ export interface ToolBuildConfig {
      * different settings, asked BEFORE the run executes. The consumer knows where the suite and its
      * base config live; this shared package does not, so the reading is the consumer's and the
      * mechanics — putting the flags on the runner's own arguments, before the pipeline and outside
-     * any redirect or group closer — are this tool's.
+     * any redirect or group closer, and pointing `--config` at the derived config that carries the
+     * settings no flag can — are this tool's.
      *
      * Called for a Playwright suite command only, and only the LAST suite step is touched. A run
      * that already keeps the suite's settings, or a sandbox with no supplied suite, answers `null`.
@@ -196,7 +217,7 @@ export interface ToolBuildConfig {
      *
      * @param command - The shell command, as the model sent it.
      * @param cwd - The resolved working directory it will run in.
-     * @returns The flags and the sentence, or null when nothing is put back.
+     * @returns The flags, the derived config and the sentence, or null when nothing is put back.
      */
     suiteBudget?: (command: string, cwd: string) => Promise<SuiteBudgetPin | null | undefined>;
     /** Post-write hook (e.g. auto-format via Prettier/ESLint). Called after every write_file/edit_file. */

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}