@sentinelqa/playwright-reporter 0.1.51 → 0.1.54

package/dist/quickDiagnosis.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.buildQuickDiagnosis = exports.summarizeSignal = exports.buildSimilarityKey = exports.buildDebugSummary = exports.collectFailureFacts = exports.parseFailureFacts = exports.describeFailure = void 0;
+exports.buildQuickDiagnosis = exports.buildQuickDiagnosisStructured = exports.summarizeSignal = exports.buildSimilarityKey = exports.buildDebugSummary = exports.collectFailureFacts = exports.parseFailureFacts = exports.describeFailure = void 0;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_child_process_1 = require("node:child_process");
@@ -162,6 +162,23 @@ const extractFocusLineFromSnippet = (snippet) => {
         .replace(/^\s*\d+\s*\|\s*/, "")
         .trim() || null;
 };
+const extractFocusLineFromMessage = (message) => {
+    if (!message)
+        return null;
+    const lines = stripAnsi(message).split(/\r?\n/);
+    const marked = lines.find((line) => /^\s*>\s*\d+\s*\|/.test(line));
+    if (marked) {
+        return marked
+            .replace(/^\s*>\s*/, "")
+            .replace(/^\s*\d+\s*\|\s*/, "")
+            .trim() || null;
+    }
+    const expectLine = lines.find((line) => /\b(await\s+)?expect\(/.test(line));
+    if (expectLine)
+        return expectLine.trim();
+    const stepLine = lines.find((line) => /\b(getBy|locator\(|page\.)/.test(line));
+    return stepLine?.trim() || null;
+};
 const parseCommitLine = (line) => {
     const [sha, author, message] = line.split("\u001f");
     if (!sha)
@@ -208,29 +225,55 @@ const normalizeStatus = (status) => {
         return "passed";
     return "skipped";
 };
+const errorRichness = (error) => {
+    if (!error)
+        return -1;
+    const message = String(error.message || error.stack || error.value || "");
+    let score = message.length;
+    if (error.location?.file)
+        score += 200;
+    if (/locator\.|Call log:|intercepts pointer events|waiting for|getBy|at .*:\d+:\d+/i.test(message))
+        score += 400;
+    if (/Test timeout of \d+ms exceeded\.$/i.test(stripAnsi(message).trim()))
+        score -= 300;
+    return score;
+};
+const selectBestError = (result) => {
+    const candidates = [result.error, ...(result.errors || [])].filter(Boolean);
+    if (!candidates.length)
+        return null;
+    return candidates.sort((a, b) => errorRichness(b) - errorRichness(a))[0] || null;
+};
 const toMessage = (result) => {
-    const direct = result.error?.message || result.error?.stack || result.error?.value || null;
-    if (direct)
-        return stripAnsi(String(direct));
-    const first = result.errors?.find(Boolean);
-    return first ? stripAnsi(String(first.message || first.stack || first.value || "")) : "";
+    const best = selectBestError(result);
+    return best ? stripAnsi(String(best.message || best.stack || best.value || "")) : "";
 };
 const classifySignal = (message) => {
     const lower = message.toLowerCase();
+    if (/playwright test did not expect test\.describe\(\) to be called here/.test(lower) ||
+        /cannot find module ['"]@playwright\/test['"]/.test(lower) ||
+        /cannot find package ['"]@playwright\/test['"]/.test(lower) ||
+        /browsertype\.launch: executable doesn't exist/.test(lower) ||
+        /please run the following command to download new browsers/.test(lower) ||
+        /npx playwright install/.test(lower) ||
+        /error: no tests found/.test(lower) ||
+        /unknown command ['"]test['"]/.test(lower)) {
+        return "setup";
+    }
     if (/browser has been closed|target page, context or browser has been closed|crash|page crashed|browser disconnected/.test(lower)) {
         return "infra";
     }
-    if (/expected substring|expected string|received string|tohavetext|tocontaintext|tohavevalue|tobechecked/.test(lower)) {
-        return "assertion_mismatch";
-    }
-    if (/timeout|timed out|waiting for/.test(lower))
-        return "timeout";
-    if (/resolved to 0 elements|locator.*not found|never appeared|strict mode violation/.test(lower)) {
+    if (/resolved to 0 elements|locator.*not found|never appeared/.test(lower)) {
         return "locator_not_found";
     }
-    if (/not visible|not enabled|not stable|intercepts pointer events|not actionable/.test(lower)) {
+    if (/not visible|not enabled|not stable|intercepts pointer events|not actionable|strict mode violation/.test(lower)) {
         return "actionability";
     }
+    if (/expected substring|expected string|received string|tohavetext|tocontaintext|tohavevalue|tobechecked|showed ".+" instead of ".+"/.test(lower)) {
+        return "assertion_mismatch";
+    }
+    if (/timeout|timed out|waiting for/.test(lower))
+        return "timeout";
     if (/status\s*[45]\d{2}|net::|failed to fetch|network|request failed|socket hang up|econnreset|503|502|500/.test(lower)) {
         return "network";
     }
@@ -244,20 +287,265 @@ const extractLocator = (message) => {
     const locatorLine = message.match(/Locator:\s*(.+)/i);
     if (locatorLine?.[1])
         return locatorLine[1].trim();
-    const callLine = message.match(/(getByTestId|getByRole|getByText|locator)\([^)]+\)/);
+    const callLine = message.match(/(getByTestId|getByRole|getByText|getByLabel|getByPlaceholder|getByTitle|locator)\([^)]+\)/);
     return callLine?.[0] || null;
 };
+const normalizedUrlPath = (value) => {
+    if (!value)
+        return null;
+    try {
+        const parsed = new URL(value);
+        return parsed.pathname || null;
+    }
+    catch {
+        return value.replace(/^https?:\/\/[^/]+/i, "").split("?")[0] || value;
+    }
+};
+const canonicalLocatorForFailure = (failure) => failure.domCapture?.normalizedLocator ||
+    failure.locator ||
+    failure.codeContext?.locator ||
+    null;
+const pageErrorFingerprint = (failure) => normalizeMessageFingerprint(failure.domCapture?.recentPageErrors?.[0] ||
+    failure.domCapture?.recentConsoleErrors?.[0]?.text ||
+    "");
+const requestFingerprint = (failure) => {
+    const request = failedRequestFromDomCapture(failure.domCapture);
+    if (!request)
+        return null;
+    const method = request.method || "REQUEST";
+    const url = normalizedUrlPath(request.url) || request.url || "unknown-request";
+    const status = typeof request.status === "number" ? String(request.status) : request.failure || "failed";
+    return `${method} ${url} ${status}`;
+};
 const extractExpected = (message) => {
     const match = message.match(/Expected substring:\s*"([^"]+)"/i) ||
         message.match(/Expected string:\s*"([^"]+)"/i) ||
-        message.match(/Expected:\s*"([^"]+)"/i);
+        message.match(/Expected:\s*"([^"]+)"/i) ||
+        message.match(/Expected:\s*`([^`]+)`/i) ||
+        message.match(/instead of\s+"([^"]+)"/i);
     return match?.[1] || null;
 };
 const extractReceived = (message) => {
     const match = message.match(/Received string:\s*"([^"]+)"/i) ||
-        message.match(/Received:\s*"([^"]+)"/i);
+        message.match(/Received:\s*"([^"]+)"/i) ||
+        message.match(/Received:\s*`([^`]+)`/i) ||
+        message.match(/showed\s+"([^"]+)"/i);
     return match?.[1] || null;
 };
+const extractExpectedFromAssertionLine = (value) => {
+    if (!value)
+        return null;
+    const line = value.trim();
+    if (/\.toBeHidden\(\s*\)/i.test(line))
+        return "hidden";
+    if (/\.toBeVisible\(\s*\)/i.test(line))
+        return "visible";
+    if (/\.toBeDisabled\(\s*\)/i.test(line))
+        return "disabled";
+    if (/\.toBeEnabled\(\s*\)/i.test(line))
+        return "enabled";
+    if (/\.toBeChecked\(\s*\)/i.test(line))
+        return "checked";
+    if (/\.not\.toBeChecked\(\s*\)/i.test(line))
+        return "unchecked";
+    const countMatch = line.match(/toHaveCount\(\s*(\d+)\s*\)/i);
+    if (countMatch?.[1])
+        return `count ${countMatch[1]}`;
+    const titleMatch = line.match(/toHaveTitle\(\s*["'`]([^"'`]+)["'`]\s*\)/i);
+    if (titleMatch?.[1])
+        return titleMatch[1];
+    const attrMatch = line.match(/toHaveAttribute\(\s*["'`]([^"'`]+)["'`]\s*,\s*["'`]([^"'`]+)["'`]\s*\)/i);
+    if (attrMatch?.[1] && attrMatch?.[2])
+        return `${attrMatch[1]}=${attrMatch[2]}`;
+    const quoted = line.match(/toHaveText\(\s*["'`]([^"'`]+)["'`]\s*\)/) ||
+        line.match(/toContainText\(\s*["'`]([^"'`]+)["'`]\s*\)/) ||
+        line.match(/toHaveValue\(\s*["'`]([^"'`]+)["'`]\s*\)/) ||
+        line.match(/toHaveURL\(\s*["'`]([^"'`]+)["'`]\s*\)/) ||
+        line.match(/toHaveTitle\(\s*["'`]([^"'`]+)["'`]\s*\)/);
+    return quoted?.[1] || null;
+};
+const extractAssertionKind = (value) => {
+    if (!value)
+        return "unknown";
+    const line = value.trim();
+    if (/toBeHidden\(\s*\)|toBeVisible\(\s*\)/i.test(line))
+        return "visibility";
+    if (/toBeDisabled\(\s*\)|toBeEnabled\(\s*\)/i.test(line))
+        return "enabled";
+    if (/toBeChecked\(\s*\)|not\.toBeChecked\(\s*\)/i.test(line))
+        return "checked";
+    if (/toHaveCount\(\s*\d+\s*\)/i.test(line))
+        return "count";
+    if (/toHaveURL\(/i.test(line))
+        return "url";
+    if (/toHaveTitle\(/i.test(line))
+        return "title";
+    if (/toHaveAttribute\(/i.test(line))
+        return "attribute";
+    if (/toHaveText\(|toContainText\(|toHaveValue\(/i.test(line))
+        return "text";
+    return "unknown";
+};
+const extractObservedDomText = (domCapture) => {
+    if (!domCapture)
+        return null;
+    if (domCapture.observedText)
+        return domCapture.observedText;
+    if (domCapture.textContent)
+        return domCapture.textContent;
+    const matchedText = domCapture.matchedElements
+        ?.map((item) => item?.text || null)
+        .find((value) => typeof value === "string" && value.trim().length > 0);
+    return matchedText || null;
+};
+const normalizedAriaSnapshot = (domCapture) => (domCapture?.ariaSnapshot || "").replace(/\s+/g, " ").trim();
+const firstMatchedElement = (domCapture) => domCapture?.matchedElements?.find(Boolean) || null;
+const parseBooleanToken = (value, token) => {
+    if (!value)
+        return null;
+    const normalized = value.toLowerCase();
+    if (new RegExp(`${token}\\s*[:=]\\s*(true|false)`, "i").test(normalized) ||
+        new RegExp(`${token}\\s*=\\s*"(true|false)"`, "i").test(normalized) ||
+        new RegExp(`${token}\\s*=\\s*'(true|false)'`, "i").test(normalized)) {
+        const match = normalized.match(new RegExp(`${token}\\s*[:=]\\s*(true|false)`, "i")) ||
+            normalized.match(new RegExp(`${token}\\s*=\\s*"(true|false)"`, "i")) ||
+            normalized.match(new RegExp(`${token}\\s*=\\s*'(true|false)'`, "i"));
+        if (match?.[1] === "true")
+            return true;
+        if (match?.[1] === "false")
+            return false;
+    }
+    if (new RegExp(`\\[${token}\\]`, "i").test(normalized) || new RegExp(`\\b${token}\\b`, "i").test(normalized)) {
+        return true;
+    }
+    return null;
+};
+const ariaVisibilityState = (domCapture) => {
+    const snapshot = normalizedAriaSnapshot(domCapture);
+    const hidden = parseBooleanToken(snapshot, "aria-hidden") ??
+        parseBooleanToken(snapshot, "hidden");
+    if (hidden === true)
+        return "hidden";
+    if (hidden === false)
+        return "visible";
+    return null;
+};
+const ariaEnabledState = (domCapture) => {
+    const snapshot = normalizedAriaSnapshot(domCapture);
+    const disabled = parseBooleanToken(snapshot, "aria-disabled") ??
+        parseBooleanToken(snapshot, "disabled");
+    if (disabled === true)
+        return "disabled";
+    if (disabled === false)
+        return "enabled";
+    return null;
+};
+const ariaCheckedState = (domCapture) => {
+    const snapshot = normalizedAriaSnapshot(domCapture);
+    const explicit = snapshot.match(/aria-checked\s*[:=]\s*(true|false|mixed)/i) ||
+        snapshot.match(/checked\s*[:=]\s*(true|false|mixed)/i) ||
+        snapshot.match(/aria-checked\s*=\s*"(true|false|mixed)"/i) ||
+        snapshot.match(/aria-checked\s*=\s*'(true|false|mixed)'/i);
+    if (explicit?.[1]) {
+        if (explicit[1].toLowerCase() === "true" || explicit[1].toLowerCase() === "mixed")
+            return "checked";
+        if (explicit[1].toLowerCase() === "false")
+            return "unchecked";
+    }
+    if (/\[checked\]|\bchecked\b/i.test(snapshot) && !/\bunchecked\b/i.test(snapshot))
+        return "checked";
+    if (/\bunchecked\b/i.test(snapshot))
+        return "unchecked";
+    return null;
+};
+const extractObservedAssertionState = (domCapture, expected) => {
+    if (!domCapture || !expected)
+        return null;
+    const matched = firstMatchedElement(domCapture);
+    switch (expected) {
+        case "hidden":
+        case "visible":
+            if (domCapture.visible === true)
+                return "visible";
+            if (domCapture.visible === false)
+                return "hidden";
+            if (matched?.visible === true)
+                return "visible";
+            if (matched?.visible === false)
+                return "hidden";
+            return ariaVisibilityState(domCapture);
+        case "checked":
+        case "unchecked": {
+            const checked = ariaCheckedState(domCapture);
+            if (checked)
+                return checked;
+            return null;
+        }
+        case "enabled":
+        case "disabled":
+            if (domCapture.enabled === true)
+                return "enabled";
+            if (domCapture.enabled === false)
+                return "disabled";
+            if (matched?.enabled === true)
+                return "enabled";
+            if (matched?.enabled === false)
+                return "disabled";
+            return ariaEnabledState(domCapture);
+        default:
+            return null;
+    }
+};
+const extractObservedAssertionValue = (domCapture, expected, assertionKind) => {
+    if (!domCapture)
+        return null;
+    if (assertionKind === "visibility" || assertionKind === "enabled" || assertionKind === "checked") {
+        return extractObservedAssertionState(domCapture, expected);
+    }
+    if (assertionKind === "count" && typeof domCapture.matchedCount === "number") {
+        return `count ${domCapture.matchedCount}`;
+    }
+    return null;
+};
+const isStateExpectation = (value) => value === "hidden" || value === "visible" || value === "enabled" || value === "disabled" || value === "checked" || value === "unchecked";
+const describeAssertionDifference = (selector, expected, received) => {
+    if (isStateExpectation(expected) && isStateExpectation(received)) {
+        return `${selector} was ${truncateValue(received, 24)} instead of ${truncateValue(expected, 24)}`;
+    }
+    if (/^count \d+$/i.test(expected) && /^count \d+$/i.test(received)) {
+        return `${selector} had ${truncateValue(received, 24)} instead of ${truncateValue(expected, 24)}`;
+    }
+    return `${selector} showed "${truncateValue(received, 72)}" instead of "${truncateValue(expected, 40)}"`;
+};
+const describeExpectedState = (expected) => {
+    if (!expected)
+        return null;
+    if (/^count \d+$/i.test(expected))
+        return expected;
+    if (isStateExpectation(expected))
+        return expected;
+    return `"${truncateValue(expected, 40)}"`;
+};
+const assertionWaitCondition = (selector, expected) => {
+    const expectedState = describeExpectedState(expected);
+    if (!expectedState)
+        return `${selector} to reach the expected state`;
+    if (expected === "hidden")
+        return `${selector} to become hidden`;
+    if (expected === "visible")
+        return `${selector} to become visible`;
+    if (expected === "enabled")
+        return `${selector} to become enabled`;
+    if (expected === "disabled")
+        return `${selector} to become disabled`;
+    if (expected === "checked")
+        return `${selector} to become checked`;
+    if (expected === "unchecked")
+        return `${selector} to become unchecked`;
+    if (/^count \d+$/i.test(expected))
+        return `${selector} to reach ${expectedState}`;
+    return `${selector} to show ${expectedState}`;
+};
 const extractTimeoutMs = (message) => {
     const match = message.match(/Timeout:\s*(\d+)\s*ms/i) ||
         message.match(/timeout(?: of)?\s*(\d+)\s*ms/i) ||
@@ -280,6 +568,85 @@ const extractApiHint = (message, codeContext) => {
     const apiMatch = message.match(/\/(api|graphql|rest)\/[^\s)"']+/i);
     return apiMatch?.[0] || null;
 };
+const recentPageErrorHint = (domCapture) => truncateValue(domCapture?.recentPageErrors?.[0], 140);
+const recentConsoleErrorHint = (domCapture) => truncateValue(domCapture?.recentConsoleErrors?.[0]?.text, 140);
+const ariaSnapshotHint = (domCapture) => truncateValue(domCapture?.ariaSnapshot || null, 140);
+const failedRequestFromDomCapture = (domCapture) => {
+    const requests = domCapture?.recentRequests || [];
+    return requests.find((request) => {
+        const status = typeof request.status === "number" ? request.status : null;
+        return Boolean(request.failure) || (status !== null && status >= 400);
+    }) || null;
+};
+const formatRequestLabel = (request) => {
+    const method = request.method || "REQUEST";
+    const url = request.url || "unknown request";
+    const status = typeof request.status === "number" ? ` -> ${request.status}` : request.failure ? ` -> ${request.failure}` : "";
+    return `${method} ${truncateValue(url, 48)}${status}`;
+};
+const isUrlLike = (value) => Boolean(value && (/^https?:\/\//i.test(value) || /^\//.test(value)));
+const navigationVerdictForFailure = (failure) => {
+    const expected = failure.expected || null;
+    const received = failure.received || failure.lastUrl || null;
+    const message = stripAnsi(failure.message).toLowerCase();
+    if (isUrlLike(expected) || isUrlLike(received)) {
+        if ((received || "").toLowerCase().includes("/login") && expected && !expected.toLowerCase().includes("/login")) {
+            return { kind: "auth_redirect", expected, received };
+        }
+        if (expected && received && expected !== received) {
+            return { kind: "wrong_route", expected, received };
+        }
+    }
+    if (/navigation timeout|page\.goto: timeout|waitforurl.*timeout|waiting for navigation/i.test(message)) {
+        return { kind: "navigation_timeout", expected, received };
+    }
+    if (/about:blank|blank page/i.test(message) || ((received || "").toLowerCase() === "about:blank")) {
+        return { kind: "blank_page", expected, received };
+    }
+    if (/cross-origin|popup|new page/i.test(message)) {
+        return { kind: "popup_origin", expected, received };
+    }
+    return null;
+};
+const blockedActionSubtype = (failure, verdict) => {
+    const blocker = verdict?.blocker || "";
+    const message = stripAnsi(failure.message).toLowerCase();
+    if (/strict mode/i.test(blocker) || /strict mode violation/i.test(message))
+        return "strict_mode";
+    if (/detached/i.test(blocker) || /detached from the dom/i.test(message))
+        return "detached";
+    if (/scrolling or viewport issue/i.test(blocker) || /viewport|scrolled into view/.test(message))
+        return "offscreen";
+    if (/focus or editability issue/i.test(blocker) || /not editable|not focused/.test(message))
+        return "focus";
+    if (/intercepts pointer events|overlay|obscures/.test(blocker) || /intercepts pointer events|overlay/.test(message))
+        return "overlay";
+    if (verdict?.targetState === "hidden")
+        return "hidden";
+    if (verdict?.targetState === "disabled")
+        return "disabled";
+    return "generic";
+};
+const blockerGroupingKey = (failure, verdict) => {
+    const subtype = blockedActionSubtype(failure, verdict);
+    const blocker = (verdict?.blocker || "").toLowerCase().replace(/\s+/g, " ").trim();
+    if (!blocker)
+        return null;
+    return `${subtype}|${blocker}`;
+};
+const sharedBlockedClusterSubtype = (cluster) => {
+    const subtypes = cluster.failures
+        .map((failure) => blockedActionSubtype(failure, blockedVerdictForFailure(failure)))
+        .filter(Boolean);
+    return dominantValue(subtypes) || null;
+};
+const isMultiSelectorBlockedCluster = (cluster) => {
+    const selectors = new Set(cluster.failures.map((item) => compactLocator(item.locator)).filter(Boolean));
+    if (selectors.size <= 1)
+        return false;
+    const subtype = sharedBlockedClusterSubtype(cluster);
+    return subtype === "overlay" || subtype === "strict_mode" || subtype === "detached" || subtype === "offscreen" || subtype === "focus";
+};
 const extractStackLocation = (message) => {
     const lines = stripAnsi(message).split(/\r?\n/);
     for (const line of lines) {
@@ -339,6 +706,242 @@ const describeDomState = (failure) => {
     }
     return null;
 };
+const extractBlockerFromMessage = (message) => {
+    const plain = stripAnsi(message);
+    const interceptMatch = plain.match(/-\s*(<[^>]+>|[^.\n]+?)\s+intercepts pointer events/i);
+    if (interceptMatch?.[1]) {
+        const blocker = interceptMatch[1].replace(/\s+/g, " ").trim();
+        return truncateValue(blocker, 72);
+    }
+    const obscuredMatch = plain.match(/(?:another element|element)\s+(.+?)\s+(?:would receive the click|obscures|obscured)/i);
+    if (obscuredMatch?.[1]) {
+        return truncateValue(`${obscuredMatch[1].replace(/\s+/g, " ").trim()} obscures the target`, 72);
+    }
+    const overlayMatch = plain.match(/\b([.#]?[A-Za-z0-9_-]*overlay[A-Za-z0-9_.-]*)\b/i);
+    if (overlayMatch?.[1]) {
+        return overlayMatch[1];
+    }
+    if (/strict mode violation/i.test(plain)) {
+        return "strict mode matched multiple elements";
+    }
+    if (/element is not attached to the dom|detached from dom|detached from the dom/i.test(plain)) {
+        return "element detached from the DOM";
+    }
+    if (/outside of the viewport|scroll(?:ing)? into view|could not be scrolled into view/i.test(plain)) {
+        return "scrolling or viewport issue blocked the target";
+    }
+    if (/not focused|did not receive focus|is not editable|element is not editable/i.test(plain)) {
+        return "focus or editability issue blocked the target";
+    }
+    return null;
+};
+const dominantValue = (values) => {
+    const counts = new Map();
+    for (const value of values) {
+        const normalized = (value || "").trim();
+        if (!normalized)
+            continue;
+        counts.set(normalized, (counts.get(normalized) || 0) + 1);
+    }
+    const sorted = Array.from(counts.entries()).sort((a, b) => b[1] - a[1]);
+    if (!sorted.length)
+        return null;
+    return sorted[0][0];
+};
+const dominantFocusLine = (failures) => dominantValue(failures.map((failure) => failure.codeContext?.focusLine || null));
+const timeoutState = (failure) => {
+    const dom = failure.domCapture;
+    if (!dom)
+        return "unknown";
+    if (dom.targetFound === false || dom.matchedCount === 0)
+        return "missing";
+    if (dom.visible === false)
+        return "hidden";
+    if (dom.enabled === false)
+        return "disabled";
+    if (dom.targetFound === true && dom.visible === true)
+        return "present";
+    return "unknown";
+};
+const inferMissingTargetFromMessage = (failure) => {
+    if (failure.signal !== "timeout")
+        return false;
+    const message = stripAnsi(failure.message);
+    if (!failure.locator || !failure.codeContext?.action)
+        return false;
+    if (!["click", "fill", "press"].includes(failure.codeContext.action))
+        return false;
+    if (/intercepts pointer events|not visible|not enabled|not stable|strict mode violation|detached from the dom|outside of the viewport|not editable|not focused/i.test(message)) {
+        return false;
+    }
+    if (/locator\.(click|fill|press):/i.test(message) && /Call log:\s*[\s\S]*waiting for /i.test(message)) {
+        return true;
+    }
+    return false;
+};
+const sharedTimeoutEvidence = (failures) => {
+    const timeoutFailures = failures.filter((failure) => failure.signal === "timeout");
+    return {
+        action: dominantValue(timeoutFailures.map((failure) => failure.codeContext?.action || null)),
+        locator: dominantValue(timeoutFailures.map((failure) => failure.locator || null)),
+        state: dominantValue(timeoutFailures.map((failure) => timeoutState(failure))) || "unknown"
+    };
+};
+const timeoutStateLabel = (state) => {
+    switch (state) {
+        case "missing":
+            return "locator never appeared";
+        case "hidden":
+            return "found but hidden";
+        case "disabled":
+            return "found but disabled";
+        case "present":
+            return "found and visible before timeout";
+        default:
+            return null;
+    }
+};
+const capitalize = (value) => {
+    if (!value)
+        return null;
+    return value.length > 1 ? `${value[0].toUpperCase()}${value.slice(1)}` : value.toUpperCase();
+};
+const humanizeAction = (value) => {
+    if (!value)
+        return null;
+    switch (value) {
+        case "expect_text":
+            return "expect text";
+        case "expect_visible":
+            return "expect visible";
+        case "assert":
+            return "assert";
+        default:
+            return value.replace(/_/g, " ");
+    }
+};
+const timeoutWaitConditionForFailure = (failure) => {
+    const verdict = blockedVerdictForFailure(failure);
+    const locator = failure.locator ? compactLocator(failure.locator) : "the target";
+    const action = failure.codeContext?.action || null;
+    if ((action === "expect_text" || action === "assert") && failure.expected && failure.locator) {
+        return assertionWaitCondition(locator, failure.expected);
+    }
+    if (verdict?.targetState === "missing")
+        return `${locator} to appear`;
+    if (verdict?.targetState === "hidden")
+        return `${locator} to become visible`;
+    if (verdict?.targetState === "disabled")
+        return `${locator} to become enabled`;
+    if (action === "click" || verdict?.targetState === "visible_blocked")
+        return `${locator} to become clickable`;
+    if (action === "fill")
+        return `${locator} to become editable`;
+    if (action === "press")
+        return `${locator} to become ready for keyboard input`;
+    if (failure.expected && failure.locator) {
+        return assertionWaitCondition(locator, failure.expected);
+    }
+    if (failure.locator)
+        return `${locator} to be ready`;
+    return "the expected state change to complete";
+};
+const timeoutWaitConditionForCluster = (cluster) => {
+    const failure = cluster.sample;
+    const verdict = blockedVerdictForCluster(cluster);
+    const locator = verdict?.locator ? compactLocator(verdict.locator) : failure.locator ? compactLocator(failure.locator) : "the target";
+    const action = verdict?.action || failure.codeContext?.action || null;
+    const expected = representativeClusterExpected(cluster) || failure.expected;
+    if ((action === "expect_text" || action === "assert") && expected && locator !== "the target") {
+        return assertionWaitCondition(locator, expected);
+    }
+    if (verdict?.targetState === "missing")
+        return `${locator} to appear`;
+    if (verdict?.targetState === "hidden")
+        return `${locator} to become visible`;
+    if (verdict?.targetState === "disabled")
+        return `${locator} to become enabled`;
+    if (action === "click" || verdict?.targetState === "visible_blocked")
+        return `${locator} to become clickable`;
+    if (action === "fill")
+        return `${locator} to become editable`;
+    if (action === "press")
+        return `${locator} to become ready for keyboard input`;
+    if (expected && locator !== "the target") {
+        return assertionWaitCondition(locator, expected);
+    }
+    if (locator !== "the target")
+        return `${locator} to be ready`;
+    return "the expected state change to complete";
+};
+const blockedVerdictForFailure = (failure) => {
+    if (!["timeout", "actionability", "locator_not_found"].includes(failure.signal))
+        return null;
+    const blocker = extractBlockerFromMessage(failure.message);
+    const state = timeoutState(failure);
+    if (state === "missing") {
+        return {
+            action: failure.codeContext?.action || null,
+            locator: failure.locator || null,
+            blocker: null,
+            targetState: "missing"
+        };
+    }
+    if (state === "hidden") {
+        return {
+            action: failure.codeContext?.action || null,
+            locator: failure.locator || null,
+            blocker: null,
+            targetState: "hidden"
+        };
+    }
+    if (state === "disabled") {
+        return {
+            action: failure.codeContext?.action || null,
+            locator: failure.locator || null,
+            blocker: null,
+            targetState: "disabled"
+        };
+    }
+    if (blocker || (state === "present" && failure.codeContext?.action)) {
+        return {
+            action: failure.codeContext?.action || null,
+            locator: failure.locator || null,
+            blocker,
+            targetState: "visible_blocked"
+        };
+    }
+    if (inferMissingTargetFromMessage(failure)) {
+        return {
+            action: failure.codeContext?.action || null,
+            locator: failure.locator || null,
+            blocker: null,
+            targetState: "missing"
+        };
+    }
+    return {
+        action: failure.codeContext?.action || null,
+        locator: failure.locator || null,
+        blocker: null,
+        targetState: "unknown"
+    };
+};
+const blockedVerdictForCluster = (cluster) => {
+    if (!["timeout", "actionability", "locator_not_found"].includes(cluster.sample.signal))
+        return null;
+    const verdicts = cluster.failures
+        .map((failure) => blockedVerdictForFailure(failure))
+        .filter((value) => Boolean(value));
+    if (!verdicts.length)
+        return null;
+    const targetState = dominantValue(verdicts.map((verdict) => verdict.targetState)) || "unknown";
+    return {
+        action: dominantValue(verdicts.map((verdict) => verdict.action)),
+        locator: dominantValue(verdicts.map((verdict) => verdict.locator)),
+        blocker: dominantValue(verdicts.map((verdict) => verdict.blocker)),
+        targetState
+    };
+};
 const buildTouchedFileReason = (label, files) => `${label}: ${files.slice(0, 2).map((file) => basename(file)).join(", ")}`;
 const commitTouchedFailure = (commit, failure) => {
     const reasons = [];
@@ -455,13 +1058,36 @@ const flattenFailedCases = (node, titlePath = []) => {
             timeoutBudgetMs: typeof test.timeout === "number" ? test.timeout : null,
             codeContext: loadCodeContext(finalResult),
             domCapture: loadDomCapture(finalResult),
-            errorLocation: finalResult.error?.location || finalResult.errors?.find(Boolean)?.location || null,
-            errorSnippet: finalResult.error?.snippet || null
+            errorLocation: selectBestError(finalResult)?.location ||
+                finalResult.error?.location ||
+                finalResult.errors?.find((item) => item?.location)?.location ||
+                test.location ||
+                null,
+            errorSnippet: selectBestError(finalResult)?.snippet || finalResult.error?.snippet || null
         }));
     }
     return failures;
 };
 const checkFirst = (failure) => {
+    if (failure.signal === "setup") {
+        const lower = failure.message.toLowerCase();
+        if (/browsertype\.launch: executable doesn't exist|please run the following command to download new browsers|npx playwright install/.test(lower)) {
+            return "run npx playwright install before rerunning";
+        }
+        if (/cannot find module ['"]@playwright\/test['"]|cannot find package ['"]@playwright\/test['"]/.test(lower)) {
+            return "install @playwright/test in this project before rerunning";
+        }
+        if (/playwright test did not expect test\.describe\(\) to be called here/.test(lower)) {
+            return "fix the Playwright package or test runner setup before rerunning";
+        }
+        if (/error: no tests found/.test(lower)) {
+            return "fix the Playwright command, grep, or test discovery settings before rerunning";
+        }
+        if (/unknown command ['"]test['"]/.test(lower)) {
+            return "install Playwright or run the local @playwright/test CLI before rerunning";
+        }
+        return "fix the Playwright setup error before rerunning";
+    }
     if (failure.signal === "runtime" && /retry|flaky/i.test(failure.message)) {
         const file = basename(failure.codeContext?.file || failure.likelyFile);
         const line = failure.codeContext?.line;
@@ -526,6 +1152,8 @@ const alternateCommitLine = (match) => {
 };
 const rootCauseLabel = (failure) => {
     switch (failure.signal) {
+        case "setup":
+            return "Playwright setup error";
         case "assertion_mismatch":
             return "UI assertion mismatch";
         case "locator_not_found":
@@ -545,16 +1173,62 @@ const rootCauseLabel = (failure) => {
     }
 };
 const describeFailure = (failure) => {
+    if (failure.signal === "setup") {
+        return `${setupErrorSummary(failure)}.`;
+    }
+    const navigation = navigationVerdictForFailure(failure);
+    const pageError = recentPageErrorHint(failure.domCapture);
+    const consoleError = recentConsoleErrorHint(failure.domCapture);
+    if (navigation?.kind === "auth_redirect" && navigation.received) {
+        return `The app redirected to "${truncateValue(navigation.received, 48)}" instead of continuing to the expected route.`;
+    }
+    if (navigation?.kind === "wrong_route" && navigation.expected && navigation.received) {
+        return `The app opened "${truncateValue(navigation.received, 48)}" instead of "${truncateValue(navigation.expected, 48)}".`;
+    }
+    if (navigation?.kind === "navigation_timeout") {
+        return `Navigation did not complete before timeout.`;
+    }
+    if (navigation?.kind === "blank_page") {
+        return `The page ended on a blank route instead of the expected app screen.`;
+    }
+    const failedRequest = failedRequestFromDomCapture(failure.domCapture);
     if (failure.signal === "assertion_mismatch" && failure.locator && failure.expected && failure.received) {
-        return `${failure.locator} showed "${failure.received}" instead of "${failure.expected}".`;
+        return `${describeAssertionDifference(compactLocator(failure.locator), failure.expected, failure.received)}.`;
+    }
+    if (failure.signal === "assertion_mismatch" && failure.locator && failure.expected) {
+        const actionHint = assertionStateTransitionHint(failure);
+        if (actionHint) {
+            return `${compactLocator(failure.locator)} did not reach ${describeExpectedState(failure.expected) || "the expected state"} after ${actionHint}.`;
+        }
+        return `${compactLocator(failure.locator)} did not reach ${describeExpectedState(failure.expected) || "the expected state"}.`;
     }
     if (failure.signal === "locator_not_found" && failure.locator) {
-        return `${failure.locator} was not found when the test expected it to be available.`;
+        return `${compactLocator(failure.locator)} was not found when the test expected it to be available.`;
     }
     if (failure.signal === "actionability" && failure.locator) {
-        return `${failure.locator} was found but was not actionable when the interaction ran.`;
+        const verdict = blockedVerdictForFailure(failure);
+        const subtype = blockedActionSubtype(failure, verdict);
+        if (subtype === "overlay" && verdict?.blocker) {
+            return `${verdict.blocker} blocked ${failure.codeContext?.action || "the action"} on ${compactLocator(failure.locator)}.`;
+        }
+        if (subtype === "strict_mode") {
+            return `${compactLocator(failure.locator)} matched multiple elements, so Playwright could not pick a single target.`;
+        }
+        if (subtype === "detached") {
+            return `${compactLocator(failure.locator)} detached from the DOM before ${failure.codeContext?.action || "the action"} completed.`;
+        }
+        if (subtype === "offscreen") {
+            return `${compactLocator(failure.locator)} never became reachable in the viewport for ${failure.codeContext?.action || "the action"}.`;
+        }
+        if (subtype === "focus") {
+            return `${compactLocator(failure.locator)} was present but could not receive focus or input when the interaction ran.`;
+        }
+        return `${compactLocator(failure.locator)} was found but was not actionable when the interaction ran.`;
     }
     if (failure.signal === "network") {
+        if (failedRequest) {
+            return `${formatRequestLabel(failedRequest)} blocked the test flow before the expected UI state loaded.`;
+        }
         return failure.apiHint
             ? `A network or API request around ${failure.apiHint} did not complete successfully.`
             : `A network or API request did not complete successfully.`;
@@ -563,6 +1237,12 @@ const describeFailure = (failure) => {
         const domState = describeDomState(failure);
         if (domState)
             return `${domState}.`;
+        const waitCondition = timeoutWaitConditionForFailure(failure);
+        if (waitCondition) {
+            return failure.timeoutMs
+                ? `Playwright timed out after ${failure.timeoutMs}ms while waiting for ${waitCondition}.`
+                : `Playwright timed out while waiting for ${waitCondition}.`;
+        }
         return failure.timeoutMs
             ? `The expected UI or network condition did not complete before the ${failure.timeoutMs}ms timeout.`
             : `The expected UI or network condition did not complete before timeout.`;
@@ -571,6 +1251,12 @@ const describeFailure = (failure) => {
         return `The test code threw a retry or flaky guard error before the app flow completed.`;
     }
     if (failure.signal === "runtime") {
+        if (pageError) {
+            return `Page error "${pageError}" interrupted the flow before the expected state was reached.`;
+        }
+        if (consoleError) {
+            return `Console error "${consoleError}" interrupted the flow before the expected state was reached.`;
+        }
         return `A runtime error interrupted the test flow before the expected state was reached.`;
     }
     if (failure.signal === "infra") {
@@ -593,7 +1279,25 @@ const describeCluster = (cluster) => {
         return `${cluster.count} tests failed behind the same network or API signal.`;
     }
     if (cluster.count > 1 && failure.signal === "timeout") {
-        return `${cluster.count} tests timed out behind the same blocked state transition.`;
+        const evidence = sharedTimeoutEvidence(cluster.failures);
+        const action = evidence.action ? evidence.action.trim() : "the expected interaction";
+        const locator = evidence.locator ? compactLocator(evidence.locator) : "the target element";
+        if (evidence.state === "missing") {
+            return `${cluster.count} tests timed out because ${locator} never appeared before ${action}.`;
+        }
+        if (evidence.state === "hidden") {
+            return `${cluster.count} tests timed out because ${locator} stayed hidden and blocked ${action}.`;
+        }
+        if (evidence.state === "disabled") {
+            return `${cluster.count} tests timed out because ${locator} stayed disabled and blocked ${action}.`;
+        }
+        if (evidence.state === "present" && evidence.action) {
+            return `${cluster.count} tests timed out because ${action} on ${locator} never completed even though the target was present.`;
+        }
+        if (evidence.action && evidence.locator) {
+            return `${cluster.count} tests timed out on the same ${action} step for ${locator}.`;
+        }
+        return `${cluster.count} tests timed out while waiting for the same UI state change to complete.`;
     }
     if (cluster.count > 1 && failure.signal === "infra") {
         return `${cluster.count} tests failed behind the same browser or CI instability signal.`;
@@ -610,8 +1314,57 @@ const clusterCheckFirst = (cluster) => {
         }
         return "inspect the shared retry/flaky helper or intentional throw in these tests before opening the trace";
     }
+    if (failure.signal === "timeout") {
+        const evidence = sharedTimeoutEvidence(cluster.failures);
+        const locator = evidence.locator ? compactLocator(evidence.locator) : "the target element";
+        if (evidence.state === "missing") {
+            return `make ${locator} render before the blocked step`;
+        }
+        if (evidence.state === "hidden") {
+            return `remove the condition keeping ${locator} hidden before the action`;
+        }
+        if (evidence.state === "disabled") {
+            return `enable ${locator} before the action runs`;
+        }
+        if (evidence.state === "present" && evidence.action && evidence.locator) {
+            return `fix what blocks ${evidence.action} on ${compactLocator(evidence.locator)} (overlay or pointer interception is likely)`;
+        }
+        if (failure.codeContext?.focusLine) {
+            return `inspect the waiting assertion or step: ${failure.codeContext.focusLine.trim()}`;
+        }
+        if (failure.likelyFile) {
+            return `inspect the waiting assertion or blocked state transition in ${basename(failure.likelyFile)}`;
+        }
+    }
     return checkFirst(failure);
 };
+const buildClusterEvidenceLines = (cluster) => {
+    const failure = cluster.sample;
+    const lines = [];
+    if (failure.signal === "timeout") {
+        const evidence = sharedTimeoutEvidence(cluster.failures);
+        const focusLine = dominantFocusLine(cluster.failures);
+        if (focusLine)
+            lines.push(`Failing code: ${focusLine.trim()}`);
+        if (evidence.action)
+            lines.push(`Failing step: ${evidence.action}`);
+        if (evidence.locator)
+            lines.push(`Selector: ${compactLocator(evidence.locator)}`);
+        const stateLabel = timeoutStateLabel(evidence.state);
+        if (stateLabel)
+            lines.push(`Target state: ${stateLabel}`);
+        return lines.slice(0, 4);
+    }
+    const focusLine = dominantFocusLine(cluster.failures);
+    if (focusLine)
+        lines.push(`Failing code: ${focusLine.trim()}`);
+    for (const line of buildSecondaryEvidenceLines(failure)) {
+        if (lines.includes(line))
+            continue;
+        lines.push(line);
+    }
+    return lines.slice(0, 4);
+};
 const formatAffectedTests = (titles) => {
     const unique = Array.from(new Set(titles.map((title) => shortenTitle(title)))).slice(0, 3);
     if (!unique.length)
@@ -646,15 +1399,23 @@ const buildClusterLocationLine = (failures) => {
 };
 const buildEvidenceLines = (failure) => {
     const lines = [];
+    const blockedVerdict = blockedVerdictForFailure(failure);
     const locationLine = buildLocationLine(failure);
+    const pageError = recentPageErrorHint(failure.domCapture);
+    const consoleError = recentConsoleErrorHint(failure.domCapture);
+    const ariaHint = ariaSnapshotHint(failure.domCapture);
     if (locationLine)
         lines.push(locationLine);
-    if (failure.codeContext?.focusLine)
-        lines.push(`Failing code: ${failure.codeContext.focusLine.trim()}`);
     if (failure.codeContext?.action)
         lines.push(`Failing step: ${failure.codeContext.action}`);
     if (failure.locator)
         lines.push(`Selector: ${failure.locator}`);
+    if (blockedVerdict?.blocker)
+        lines.push(`Blocker: ${blockedVerdict.blocker}`);
+    if (pageError)
+        lines.push(`Page error: ${pageError}`);
+    else if (consoleError)
+        lines.push(`Console: ${consoleError}`);
     if (failure.signal === "timeout" && failure.domCapture) {
         if (failure.domCapture.targetFound === false || failure.domCapture.matchedCount === 0) {
             lines.push(`Target state: locator never appeared`);
@@ -669,34 +1430,117 @@ const buildEvidenceLines = (failure) => {
             lines.push(`Target state: found and visible before timeout`);
         }
     }
+    if (!pageError && !consoleError && ariaHint && (failure.signal === "assertion_mismatch" || failure.signal === "locator_not_found")) {
+        lines.push(`ARIA: ${ariaHint}`);
+    }
     if (failure.apiHint)
         lines.push(`API: ${failure.apiHint}`);
     return lines.slice(0, 4);
 };
 const withoutPrefix = (value, prefix) => value.startsWith(prefix) ? value.slice(prefix.length).trim() : value;
+const truncateValue = (value, max = 96) => {
+    if (!value)
+        return null;
+    const compact = value.replace(/\s+/g, " ").trim();
+    if (compact.length <= max)
+        return compact;
+    return `${compact.slice(0, max - 1)}…`;
+};
+const compactLocator = (value) => {
+    const compact = truncateValue(value, 40);
+    return compact || "target element";
+};
+const setupErrorSummary = (failure) => {
+    const message = failure.message.toLowerCase();
+    if (/cannot find module ['"]@playwright\/test['"]|cannot find package ['"]@playwright\/test['"]/.test(message)) {
+        return "@playwright/test is not installed";
+    }
+    if (/browsertype\.launch: executable doesn't exist|please run the following command to download new browsers|npx playwright install/.test(message)) {
+        return "Playwright browsers are not installed";
+    }
+    if (/playwright test did not expect test\.describe\(\) to be called here/.test(message)) {
+        return "Playwright loaded the test file outside the expected test runner context";
+    }
+    if (/error: no tests found/.test(message)) {
+        return "No tests were discovered by Playwright";
+    }
+    if (/unknown command ['"]test['"]/.test(message)) {
+        return "The Playwright CLI entrypoint is not available in this environment";
+    }
+    return compactErrorLine(failure) || "Playwright setup error";
+};
 const buildSecondaryEvidenceLines = (failure) => buildEvidenceLines(failure)
     .filter((line) => !line.startsWith("Error location:") && !line.startsWith("Likely file:"))
     .slice(0, 3);
 const compactRootCauseSummary = (cluster) => {
     const failure = cluster.sample;
+    const navigation = navigationVerdictForFailure(failure);
+    const failedRequest = failedRequestFromDomCapture(failure.domCapture);
+    if (failure.signal === "setup") {
+        return "Same Playwright setup error blocked these tests";
+    }
     if (failure.signal === "runtime" && /retry|flaky/i.test(failure.message)) {
         return "Same test-side throw before the app flow completed";
     }
     if (failure.signal === "network") {
+        if (failedRequest) {
+            return `${formatRequestLabel(failedRequest)} broke these tests`;
+        }
         return failure.apiHint
             ? `Same network/API failure around ${failure.apiHint}`
             : "Same network/API failure across these tests";
     }
     if (failure.signal === "timeout") {
-        return "Same blocked state transition timed out across these tests";
+        const verdict = blockedVerdictForCluster(cluster);
+        const locator = verdict?.locator ? compactLocator(verdict.locator) : null;
+        if (verdict?.targetState === "visible_blocked" && verdict.action && locator) {
+            return `Same blocked ${verdict.action} on ${locator}`;
+        }
+        if (verdict?.targetState === "missing" && locator) {
+            return `${locator} never appeared before the waiting step`;
+        }
+        if (verdict?.targetState === "hidden" && locator) {
+            return `${locator} stayed hidden before the action completed`;
+        }
+        if (verdict?.targetState === "disabled" && locator) {
+            return `${locator} stayed disabled before the action completed`;
+        }
+        return `Playwright timed out while waiting for ${timeoutWaitConditionForCluster(cluster)}`;
     }
     if (failure.signal === "assertion_mismatch") {
+        if (navigation?.kind === "auth_redirect" && navigation.received) {
+            return `The app redirected to "${truncateValue(navigation.received, 40)}" instead of the expected route`;
+        }
+        if (navigation?.kind === "wrong_route" && navigation.expected && navigation.received) {
+            return `The app opened "${truncateValue(navigation.received, 40)}" instead of "${truncateValue(navigation.expected, 40)}"`;
+        }
+        const expected = representativeClusterExpected(cluster);
+        const received = representativeClusterReceived(cluster);
+        const selector = representativeClusterSelector(cluster);
+        const actionHint = assertionStateTransitionHint(failure, cluster);
+        if (selector && expected && received) {
+            return `${selector} showed "${truncateValue(received, 56)}" instead of "${truncateValue(expected, 40)}"`;
+        }
+        if (selector && expected && actionHint) {
+            return `${selector} did not reach "${truncateValue(expected, 40)}" after ${actionHint}`;
+        }
         return "Same UI assertion mismatch across these tests";
     }
     if (failure.signal === "locator_not_found") {
         return "Same missing or changed locator across these tests";
     }
     if (failure.signal === "actionability") {
+        const verdict = blockedVerdictForCluster(cluster);
+        const subtype = blockedActionSubtype(failure, verdict);
+        if (subtype === "overlay" && verdict?.blocker && verdict?.locator) {
+            return `${verdict.blocker} blocked ${verdict.action || "the action"} on ${compactLocator(verdict.locator)}`;
+        }
+        if (subtype === "strict_mode" && verdict?.locator) {
+            return `${compactLocator(verdict.locator)} matched multiple elements in each failure`;
+        }
+        if (subtype === "detached" && verdict?.locator) {
+            return `${compactLocator(verdict.locator)} detached before the action completed`;
+        }
         return "Same element actionability problem across these tests";
     }
     if (failure.signal === "infra") {
@@ -704,13 +1548,359 @@ const compactRootCauseSummary = (cluster) => {
     }
     return describeCluster(cluster);
 };
+const compactIssueTitle = (cluster) => {
+    const failure = cluster.sample;
+    const locator = compactLocator(failure.locator);
+    const blockedVerdict = blockedVerdictForCluster(cluster);
+    const navigation = navigationVerdictForFailure(failure);
+    const multiSelectorBlocked = isMultiSelectorBlockedCluster(cluster);
+    switch (failure.signal) {
+        case "setup":
+            return "Playwright setup error";
+        case "assertion_mismatch":
+            if (navigation?.kind === "auth_redirect") {
+                return "Redirected to login";
+            }
+            if (navigation?.kind === "wrong_route") {
+                return "Wrong route opened";
+            }
+            return failure.locator ? `Assertion mismatch (${locator})` : "Assertion mismatch";
+        case "locator_not_found":
+            return failure.locator ? `Missing locator (${locator})` : "Missing locator";
+        case "actionability":
+            if (blockedVerdict?.locator) {
+                const subtype = blockedActionSubtype(failure, blockedVerdict);
+                if (multiSelectorBlocked) {
+                    if (subtype === "overlay")
+                        return "Overlay blocked interactions";
+                    if (subtype === "strict_mode")
+                        return "Strict-mode locator conflicts";
+                    if (subtype === "detached")
+                        return "Detached targets before interaction";
+                    if (subtype === "offscreen")
+                        return "Offscreen targets before interaction";
+                    if (subtype === "focus")
+                        return "Input targets blocked";
+                    return "Blocked interactions";
+                }
+                if (subtype === "strict_mode")
+                    return `Strict-mode locator conflict (${compactLocator(blockedVerdict.locator)})`;
+                if (subtype === "detached")
+                    return `Detached target before ${blockedVerdict.action || "action"} (${compactLocator(blockedVerdict.locator)})`;
+                if (subtype === "offscreen")
+                    return `Offscreen target before ${blockedVerdict.action || "action"} (${compactLocator(blockedVerdict.locator)})`;
+                if (subtype === "focus")
+                    return `Input target blocked (${compactLocator(blockedVerdict.locator)})`;
+                return `Blocked interaction (${compactLocator(blockedVerdict.locator)})`;
+            }
+            return failure.locator ? `Blocked interaction (${locator})` : "Blocked interaction";
+        case "network":
+            return failure.apiHint ? `Backend/API failure (${truncateValue(failure.apiHint, 28)})` : "Backend/API failure";
+        case "timeout":
+            if (navigation?.kind === "navigation_timeout")
+                return "Navigation timeout";
+            if (navigation?.kind === "blank_page")
+                return "Blank page after navigation";
+            if (multiSelectorBlocked) {
+                const subtype = blockedActionSubtype(failure, blockedVerdict);
+                if (subtype === "overlay")
+                    return "Overlay blocked interactions";
+                if (subtype === "strict_mode")
+                    return "Strict-mode locator conflicts";
+            }
+            if (blockedVerdict?.targetState === "visible_blocked" && blockedVerdict.action && blockedVerdict.locator) {
+                return `Blocked ${blockedVerdict.action} on ${compactLocator(blockedVerdict.locator)}`;
+            }
+            if (blockedVerdict?.targetState === "missing" && blockedVerdict.locator) {
+                return `Timeout while waiting for ${compactLocator(blockedVerdict.locator)} to appear`;
+            }
+            if (blockedVerdict?.targetState === "hidden" && blockedVerdict.locator) {
+                return `Timeout while waiting for ${compactLocator(blockedVerdict.locator)} to become visible`;
+            }
+            if (blockedVerdict?.targetState === "disabled" && blockedVerdict.locator) {
+                return `Timeout while waiting for ${compactLocator(blockedVerdict.locator)} to become enabled`;
+            }
+            return `Timeout while waiting for ${timeoutWaitConditionForCluster(cluster)}`;
+        case "runtime":
+            return /retry|flaky/i.test(failure.message) ? "Test-side throw" : "Runtime error";
+        case "infra":
+            return "Browser/CI instability";
+        default:
+            return rootCauseLabel(failure);
+    }
+};
+const clusterCauseLine = (cluster) => {
+    const failure = cluster.sample;
+    const blockedVerdict = blockedVerdictForCluster(cluster);
+    const navigation = navigationVerdictForFailure(failure);
+    const failedRequest = failedRequestFromDomCapture(failure.domCapture);
+    if (failure.signal === "setup") {
+        return setupErrorSummary(failure);
+    }
+    if (failure.signal === "assertion_mismatch") {
+        if (navigation?.kind === "auth_redirect" && navigation.received) {
+            return `The app redirected to "${truncateValue(navigation.received, 48)}" instead of the expected route`;
+        }
+        if (navigation?.kind === "wrong_route" && navigation.expected && navigation.received) {
+            return `The app opened "${truncateValue(navigation.received, 48)}" instead of "${truncateValue(navigation.expected, 48)}"`;
+        }
+        const selector = representativeClusterSelector(cluster) || (failure.locator ? compactLocator(failure.locator) : null);
+        const expected = representativeClusterExpected(cluster) || failure.expected;
+        const received = representativeClusterReceived(cluster) || failure.received;
+        const actionHint = assertionStateTransitionHint(failure, cluster);
+        if (selector && expected && received) {
+            return describeAssertionDifference(selector, expected, received);
+        }
+        if (selector && expected && actionHint) {
+            return `${selector} did not reach ${describeExpectedState(expected) || "the expected state"} after ${actionHint}`;
+        }
+        return selector
+            ? `Same assertion mismatch on ${selector}`
+            : "Same assertion mismatch across these tests";
+    }
+    if (failure.signal === "locator_not_found") {
+        return failure.locator
+            ? `${compactLocator(failure.locator)} is missing or changed in each failure`
+            : "Same missing or changed locator across these tests";
+    }
+    if (failure.signal === "actionability") {
+        const subtype = blockedActionSubtype(failure, blockedVerdict);
+        if (isMultiSelectorBlockedCluster(cluster)) {
+            if (subtype === "overlay" && blockedVerdict?.blocker) {
+                return `${blockedVerdict.blocker} blocked interactions across these tests`;
+            }
+            if (subtype === "strict_mode") {
+                return "The shared locator pattern matched multiple elements across these tests";
+            }
+            if (subtype === "detached") {
+                return "Targets detached from the DOM before the interaction completed across these tests";
+            }
+            if (subtype === "offscreen") {
+                return "Targets never became reachable in the viewport across these tests";
+            }
+            if (subtype === "focus") {
+                return "Targets could not receive focus or input when the interaction ran";
+            }
+        }
+        if (subtype === "overlay" && blockedVerdict?.blocker && blockedVerdict?.locator) {
+            return `${blockedVerdict.blocker} blocked ${blockedVerdict.action || "the action"} on ${compactLocator(blockedVerdict.locator)}`;
+        }
+        if (subtype === "strict_mode" && blockedVerdict?.locator) {
+            return `${compactLocator(blockedVerdict.locator)} matched multiple elements, so Playwright could not pick one target`;
+        }
+        if (subtype === "detached" && blockedVerdict?.locator) {
+            return `${compactLocator(blockedVerdict.locator)} detached from the DOM before the action completed`;
+        }
+        if (subtype === "offscreen" && blockedVerdict?.locator) {
+            return `${compactLocator(blockedVerdict.locator)} never became reachable in the viewport`;
+        }
+        if (subtype === "focus" && blockedVerdict?.locator) {
+            return `${compactLocator(blockedVerdict.locator)} could not receive focus or input when the action ran`;
+        }
+        return blockedVerdict?.locator
+            ? `${compactLocator(blockedVerdict.locator)} is present but blocked in each failure`
+            : failure.locator
+                ? `${compactLocator(failure.locator)} is present but blocked in each failure`
+                : "Same actionability problem across these tests";
+    }
+    if (failure.signal === "network") {
+        if (failedRequest) {
+            return `${formatRequestLabel(failedRequest)} blocked the expected UI flow`;
+        }
+    }
+    if (failure.signal === "timeout") {
+        if (navigation?.kind === "navigation_timeout") {
+            return `The route change or page load never completed before timeout`;
+        }
+        if (navigation?.kind === "blank_page") {
+            return `The app ended on a blank page instead of the expected screen`;
+        }
+        if (isMultiSelectorBlockedCluster(cluster)) {
+            const subtype = blockedActionSubtype(failure, blockedVerdict);
+            if (subtype === "overlay" && blockedVerdict?.blocker) {
+                return `${blockedVerdict.blocker} blocked interactions across these tests before the expected state changed`;
+            }
+            if (subtype === "strict_mode") {
+                return "The shared locator pattern matched multiple elements across these tests";
+            }
+        }
+        if (blockedVerdict?.targetState === "visible_blocked" && blockedVerdict.action && blockedVerdict.locator) {
+            if (blockedVerdict.blocker) {
+                return `${blockedVerdict.blocker} blocked ${blockedVerdict.action} on ${compactLocator(blockedVerdict.locator)}`;
+            }
+            return `${blockedVerdict.action} on ${compactLocator(blockedVerdict.locator)} was blocked before the state changed`;
+        }
+        if (blockedVerdict?.targetState === "missing" && blockedVerdict.locator) {
+            return `Playwright kept waiting for ${compactLocator(blockedVerdict.locator)} to appear, but it never rendered before timeout`;
+        }
+        if (blockedVerdict?.targetState === "hidden" && blockedVerdict.locator) {
+            return `Playwright kept waiting for ${compactLocator(blockedVerdict.locator)} to become visible, but it stayed hidden`;
+        }
+        if (blockedVerdict?.targetState === "disabled" && blockedVerdict.locator) {
+            return `Playwright kept waiting for ${compactLocator(blockedVerdict.locator)} to become enabled, but it stayed disabled`;
+        }
+        return `Playwright timed out while waiting for ${timeoutWaitConditionForCluster(cluster)}`;
+    }
+    return compactRootCauseSummary(cluster);
+};
+const strongerClusterNext = (cluster) => {
+    const failure = cluster.sample;
+    const blockedVerdict = blockedVerdictForCluster(cluster);
+    const navigation = navigationVerdictForFailure(failure);
+    const failedRequest = failedRequestFromDomCapture(failure.domCapture);
+    if (failure.signal === "setup") {
+        return checkFirst(failure);
+    }
+    if (failure.signal === "assertion_mismatch") {
+        if (navigation?.kind === "auth_redirect") {
+            return "check auth/session setup or redirect guards before this route loads";
+        }
+        if (navigation?.kind === "wrong_route" && navigation.expected) {
+            return `check the route change or redirect logic so the app lands on "${truncateValue(navigation.expected, 40)}"`;
+        }
+        const selector = representativeClusterSelector(cluster) || (failure.locator ? compactLocator(failure.locator) : null);
+        const expected = representativeClusterExpected(cluster) || failure.expected;
+        const received = representativeClusterReceived(cluster) || failure.received;
+        const actionHint = assertionStateTransitionHint(failure, cluster);
+        if (failure.locator && failure.apiHint) {
+            return `check ${compactLocator(failure.locator)} or the data returned by ${truncateValue(failure.apiHint, 36)}`;
+        }
+        if (selector && expected && received && actionHint) {
+            if (isStateExpectation(expected) && isStateExpectation(received)) {
+                return `fix the UI state after ${actionHint} so ${selector} is ${truncateValue(expected, 24)} instead of ${truncateValue(received, 24)}`;
+            }
+            if (/^count \d+$/i.test(expected) && /^count \d+$/i.test(received)) {
+                return `fix the UI state after ${actionHint} so ${selector} reaches ${expected} instead of ${received}`;
+            }
+            return `fix the UI state after ${actionHint} so ${selector} shows "${truncateValue(expected, 28)}" instead of "${truncateValue(received, 28)}"`;
+        }
+        if (selector && expected && received) {
+            if (isStateExpectation(expected) && isStateExpectation(received)) {
+                return `fix the UI state behind ${selector} so it is ${truncateValue(expected, 24)} instead of ${truncateValue(received, 24)}`;
+            }
+            if (/^count \d+$/i.test(expected) && /^count \d+$/i.test(received)) {
+                return `fix the UI state behind ${selector} so it reaches ${expected} instead of ${received}`;
+            }
+            return `fix the UI state behind ${selector} so it shows "${truncateValue(expected, 28)}" instead of "${truncateValue(received, 28)}"`;
+        }
+        if (selector && expected && actionHint) {
+            return `fix the UI state after ${actionHint} so ${assertionWaitCondition(selector, expected)}`;
+        }
+        if (selector && received) {
+            return `fix the state update behind ${selector} so it no longer shows "${truncateValue(received, 28)}"`;
+        }
+        if (selector) {
+            return `check ${selector} or the data source behind it`;
+        }
+    }
+    if (failure.signal === "locator_not_found" && failure.locator) {
+        return `check whether ${compactLocator(failure.locator)} changed or no longer renders`;
+    }
+    if (failure.signal === "actionability" && failure.locator) {
+        const subtype = blockedActionSubtype(failure, blockedVerdict);
+        if (isMultiSelectorBlockedCluster(cluster)) {
+            if (subtype === "overlay" && blockedVerdict?.blocker) {
+                return `remove or dismiss ${blockedVerdict.blocker} before these interactions run`;
+            }
+            if (subtype === "strict_mode") {
+                return "narrow the shared locator pattern so each interaction matches exactly one element";
+            }
+            if (subtype === "detached") {
+                return "stabilize the DOM so the targets do not detach before the interactions run";
+            }
+            if (subtype === "offscreen") {
+                return "make the targets reachable in the viewport before the interactions run";
+            }
+            if (subtype === "focus") {
+                return "make the targets focusable/editable before the interactions run";
+            }
+        }
+        if (subtype === "strict_mode" && blockedVerdict?.locator) {
+            return `narrow ${compactLocator(blockedVerdict.locator)} so it matches exactly one element`;
+        }
+        if (subtype === "detached" && blockedVerdict?.locator) {
+            return `stabilize the DOM so ${compactLocator(blockedVerdict.locator)} does not detach before the action runs`;
+        }
+        if (subtype === "offscreen" && blockedVerdict?.locator) {
+            return `make ${compactLocator(blockedVerdict.locator)} reachable in the viewport before the action`;
+        }
+        if (subtype === "focus" && blockedVerdict?.locator) {
+            return `make ${compactLocator(blockedVerdict.locator)} focusable/editable before the action`;
+        }
+        if (blockedVerdict?.targetState === "visible_blocked" && blockedVerdict.locator) {
+            return `remove what blocks ${compactLocator(blockedVerdict.locator)} from becoming actionable`;
+        }
+        return `check what blocks ${compactLocator(failure.locator)} from becoming actionable`;
+    }
+    if (failure.signal === "network") {
+        if (failedRequest?.url) {
+            return `fix the failing response for ${truncateValue(failedRequest.url, 44)} before debugging the UI`;
+        }
+        return failure.apiHint ? `fix the failing backend response around ${truncateValue(failure.apiHint, 44)}` : "fix the failing request or backend response";
+    }
+    if (failure.signal === "timeout") {
+        if (navigation?.kind === "navigation_timeout") {
+            return "check route loading, redirects, or slow backend responses before the page transition";
+        }
+        if (navigation?.kind === "blank_page") {
+            return "check why the app ended on a blank route after navigation";
+        }
+        if (isMultiSelectorBlockedCluster(cluster)) {
+            const subtype = blockedActionSubtype(failure, blockedVerdict);
+            if (subtype === "overlay" && blockedVerdict?.blocker) {
+                return `remove or dismiss ${blockedVerdict.blocker} before these interactions run`;
+            }
+            if (subtype === "strict_mode") {
+                return "narrow the shared locator pattern so each interaction matches exactly one element";
+            }
+        }
+        if (blockedVerdict?.targetState === "visible_blocked" && blockedVerdict.action && blockedVerdict.locator) {
+            return blockedVerdict.blocker
+                ? `remove or dismiss what blocks ${blockedVerdict.action} on ${compactLocator(blockedVerdict.locator)}`
+                : `fix what blocks ${blockedVerdict.action} on ${compactLocator(blockedVerdict.locator)}`;
+        }
+        if (blockedVerdict?.targetState === "missing" && blockedVerdict.locator) {
+            const actionLabel = capitalize(blockedVerdict.action) || "this step";
+            return `make ${compactLocator(blockedVerdict.locator)} render before ${actionLabel.toLowerCase()} runs`;
+        }
+        if (blockedVerdict?.targetState === "hidden" && blockedVerdict.locator) {
+            return `remove the condition keeping ${compactLocator(blockedVerdict.locator)} hidden before the action`;
+        }
+        if (blockedVerdict?.targetState === "disabled" && blockedVerdict.locator) {
+            return `enable ${compactLocator(blockedVerdict.locator)} before the action runs`;
+        }
+        if (failure.locator && failure.codeContext?.action === "click") {
+            return `check why ${compactLocator(failure.locator)} did not become clickable before timeout`;
+        }
+        if (failure.locator && failure.expected) {
+            return `check why ${compactLocator(failure.locator)} did not reach "${truncateValue(failure.expected, 28)}" before timeout`;
+        }
+    }
+    return clusterCheckFirst(cluster);
+};
 const compactErrorLine = (failure) => {
     if (!failure.firstErrorLine)
         return null;
     return withoutPrefix(failure.firstErrorLine, "Error:");
 };
+const extractAssertionLineFromMessage = (message) => {
+    if (!message)
+        return null;
+    const lines = stripAnsi(message).split(/\r?\n/);
+    const markedAssertion = lines.find((line) => /^\s*>\s*\d+\s*\|.*\b(await\s+)?expect\(/.test(line));
+    if (markedAssertion) {
+        return markedAssertion
+            .replace(/^\s*>\s*/, "")
+            .replace(/^\s*\d+\s*\|\s*/, "")
+            .trim() || null;
+    }
+    const assertionLine = lines.find((line) => /\b(await\s+)?expect\(/.test(line));
+    return assertionLine?.trim() || null;
+};
 const parseFailureFacts = (title, titlePath, message, status, file = null, options) => {
-    const signal = classifySignal(message);
+    let signal = classifySignal(message);
+    const assertionLine = extractAssertionLineFromMessage(message);
+    const assertionKind = extractAssertionKind(assertionLine);
     const fallbackLocation = options?.errorLocation || extractStackLocation(message);
     const fallbackCodeContext = fallbackLocation || options?.errorSnippet
         ? {
@@ -722,9 +1912,9 @@ const parseFailureFacts = (title, titlePath, message, status, file = null, optio
             expectedText: null,
             timeoutMs: null,
             apiCall: null,
-            assertion: null,
+            assertion: assertionLine,
             methodName: null,
-            focusLine: extractFocusLineFromSnippet(options?.errorSnippet),
+            focusLine: assertionLine || extractFocusLineFromSnippet(options?.errorSnippet),
             previousActionLine: null,
             found: Boolean(fallbackLocation?.file || options?.errorSnippet)
         }
@@ -736,17 +1926,98 @@ const parseFailureFacts = (title, titlePath, message, status, file = null, optio
             file: options.codeContext.file || fallbackCodeContext?.file || null,
             line: options.codeContext.line ?? fallbackCodeContext?.line ?? null,
             column: options.codeContext.column ?? fallbackCodeContext?.column ?? null,
-            focusLine: options.codeContext.focusLine || fallbackCodeContext?.focusLine || null,
+            assertion: assertionLine || options.codeContext.assertion || fallbackCodeContext?.assertion || null,
+            focusLine: signal === "assertion_mismatch"
+                ? assertionLine ||
+                    options.codeContext.focusLine ||
+                    fallbackCodeContext?.focusLine ||
+                    options.codeContext.assertion ||
+                    fallbackCodeContext?.assertion ||
+                    options.codeContext.focusLine ||
+                    extractFocusLineFromMessage(message) ||
+                    null
+                : options.codeContext.focusLine || fallbackCodeContext?.focusLine || extractFocusLineFromMessage(message) || null,
             found: options.codeContext.found ?? fallbackCodeContext?.found ?? false
         }
-        : fallbackCodeContext || null;
+        : fallbackCodeContext
+            ? {
+                ...fallbackCodeContext,
+                assertion: assertionLine || fallbackCodeContext.assertion || null,
+                focusLine: signal === "assertion_mismatch"
+                    ? assertionLine ||
+                        fallbackCodeContext.focusLine ||
+                        fallbackCodeContext.assertion ||
+                        extractFocusLineFromMessage(message) ||
+                        null
+                    : fallbackCodeContext.focusLine || extractFocusLineFromMessage(message) || null
+            }
+            : {
+                file: fallbackLocation?.file || file || null,
+                line: typeof fallbackLocation?.line === "number" ? fallbackLocation.line : null,
+                column: typeof fallbackLocation?.column === "number" ? fallbackLocation.column : null,
+                action: null,
+                locator: null,
+                expectedText: null,
+                timeoutMs: null,
+                apiCall: null,
+                assertion: assertionLine,
+                methodName: null,
+                focusLine: signal === "assertion_mismatch"
+                    ? assertionLine || extractFocusLineFromMessage(message)
+                    : extractFocusLineFromMessage(message),
+                previousActionLine: null,
+                found: Boolean(fallbackLocation?.file || assertionLine || extractFocusLineFromMessage(message))
+            };
     const domCapture = options?.domCapture || null;
-    const locator = extractLocator(message) || codeContext?.locator || domCapture?.locator || null;
-    const expected = extractExpected(message) || codeContext?.expectedText || domCapture?.expectedText || null;
-    const received = extractReceived(message) || domCapture?.observedText || domCapture?.textContent || null;
+    const locator = domCapture?.normalizedLocator ||
+        extractLocator(message) ||
+        codeContext?.locator ||
+        domCapture?.locator ||
+        null;
+    const extractedExpected = extractExpected(message);
+    const extractedReceived = extractReceived(message);
+    const expected = extractedExpected ||
+        codeContext?.expectedText ||
+        ((signal === "assertion_mismatch" || assertionKind !== "unknown")
+            ? extractExpectedFromAssertionLine(codeContext?.assertion || codeContext?.focusLine || null)
+            : null) ||
+        domCapture?.expectedText ||
+        null;
+    const received = extractedReceived ||
+        extractObservedAssertionValue(domCapture, expected, assertionKind) ||
+        extractObservedDomText(domCapture) ||
+        null;
+    if (signal === "timeout" &&
+        expected &&
+        (received ||
+            codeContext?.action === "expect_text" ||
+            codeContext?.action === "assert" ||
+            Boolean(codeContext?.assertion) ||
+            message.toLowerCase().includes("expect") ||
+            message.toLowerCase().includes("tohavetext") ||
+            message.toLowerCase().includes("tocontaintext") ||
+            message.toLowerCase().includes("received string"))) {
+        signal = "assertion_mismatch";
+    }
     const likelyFile = inferLikelyFile(file, codeContext);
     const likelyModule = inferLikelyModule(file, locator, codeContext);
-    const apiHint = extractApiHint(message, codeContext);
+    const failedRequest = failedRequestFromDomCapture(domCapture);
+    const apiHint = extractApiHint(message, codeContext) || failedRequest?.url || null;
+    if (signal === "timeout" &&
+        /request failed|failed to fetch|socket hang up|econnreset|status\s*[45]\d{2}|net::|response timed out|api/i.test(message.toLowerCase()) &&
+        apiHint) {
+        signal = "network";
+    }
+    if ((signal === "timeout" || signal === "assertion_mismatch") &&
+        failedRequest &&
+        ((typeof failedRequest.status === "number" && failedRequest.status >= 400) || failedRequest.failure)) {
+        signal = "network";
+    }
+    if ((signal === "timeout" || signal === "assertion_mismatch" || signal === "unknown") &&
+        !failedRequest &&
+        (recentPageErrorHint(domCapture) || recentConsoleErrorHint(domCapture))) {
+        signal = "runtime";
+    }
     return {
         title,
         titlePath,
@@ -798,27 +2069,69 @@ const buildDebugSummary = (failure) => {
 exports.buildDebugSummary = buildDebugSummary;
 const buildSimilarityKey = (failure) => {
     const locationKey = failure.codeContext?.line ? `${basename(failure.codeContext.file)}:${failure.codeContext.line}` : basename(failure.likelyFile) || "unknown-file";
+    const canonicalLocator = canonicalLocatorForFailure(failure);
+    const requestKey = requestFingerprint(failure);
+    const pageErrorKey = pageErrorFingerprint(failure);
     if (failure.signal === 'runtime' || failure.signal === 'unknown') {
         return [
             failure.signal,
-            normalizeMessageFingerprint(failure.message),
-            locationKey
+            pageErrorKey || normalizeMessageFingerprint(failure.message),
+            canonicalLocator || locationKey
         ].join('|');
     }
+    if (failure.signal === "assertion_mismatch") {
+        const assertionKind = extractAssertionKind(failure.codeContext?.assertion || failure.codeContext?.focusLine || null);
+        return [
+            failure.signal,
+            canonicalLocator || failure.likelyModule || basename(failure.likelyFile) || "unknown-target",
+            assertionKind,
+            failure.expected || "unknown-expected",
+            failure.received || pageErrorKey || "unknown-received"
+        ].join("|");
+    }
+    if (failure.signal === "setup") {
+        return [failure.signal, normalizeMessageFingerprint(failure.message)].join("|");
+    }
+    if (failure.signal === "timeout" || failure.signal === "actionability" || failure.signal === "locator_not_found") {
+        const verdict = blockedVerdictForFailure(failure);
+        const blockerKey = blockerGroupingKey(failure, verdict);
+        const subtype = blockedActionSubtype(failure, verdict);
+        if (blockerKey && (subtype === "overlay" || subtype === "strict_mode" || subtype === "detached" || subtype === "offscreen" || subtype === "focus")) {
+            return [
+                "blocked_action_family",
+                blockerKey
+            ].join("|");
+        }
+        return [
+            failure.signal,
+            canonicalLocator || failure.codeContext?.action || failure.likelyModule || "unknown-target",
+            failure.codeContext?.action || "unknown-action",
+            pageErrorKey || locationKey
+        ].join("|");
+    }
+    if (failure.signal === "network") {
+        return [
+            failure.signal,
+            requestKey || normalizedUrlPath(failure.apiHint) || failure.likelyModule || "unknown-api",
+            pageErrorKey || basename(failure.likelyFile) || "unknown-file"
+        ].join("|");
+    }
     if (failure.locator || failure.expected || failure.received || failure.apiHint) {
         return [
             failure.signal,
-            failure.locator || failure.apiHint || "unknown-target",
+            canonicalLocator || normalizedUrlPath(failure.apiHint) || "unknown-target",
             failure.expected || "unknown-expected",
-            failure.received || "unknown-received",
-            locationKey
+            failure.received || requestKey || pageErrorKey || "unknown-received",
+            pageErrorKey || locationKey
         ].join("|");
     }
-    return `${failure.signal}|${normalizeMessageFingerprint(failure.message)}|${locationKey}`;
+    return `${failure.signal}|${pageErrorKey || normalizeMessageFingerprint(failure.message)}|${canonicalLocator || locationKey}`;
 };
 exports.buildSimilarityKey = buildSimilarityKey;
 const summarizeSignal = (signal) => {
     switch (signal) {
+        case "setup":
+            return "Playwright setup or bootstrap error";
         case "timeout":
             return "timeout while waiting for UI or network conditions";
         case "assertion_mismatch":
@@ -851,7 +2164,212 @@ const buildClusterSuspects = (clusterFailures, window) => {
         .sort((a, b) => b.score - a.score)
         .slice(0, 2);
 };
-const buildQuickDiagnosis = (playwrightJsonPath) => {
+const locationValueForFailure = (failure) => {
+    const primaryLocation = buildLocationLine(failure);
+    return primaryLocation
+        ? withoutPrefix(withoutPrefix(primaryLocation, "Error location:"), "Likely file:")
+        : null;
+};
+const locationValueForCluster = (cluster) => {
+    const clusterLocation = buildClusterLocationLine(cluster.failures);
+    return clusterLocation
+        ? withoutPrefix(clusterLocation, clusterLocation.startsWith("Error locations:") ? "Error locations:" : "Error location:")
+        : null;
+};
+const representativeClusterValue = (failures, pick) => dominantValue(failures.map((failure) => pick(failure)));
+const representativeClusterExpected = (cluster) => representativeClusterValue(cluster.failures, (failure) => failure.expected);
+const representativeClusterReceived = (cluster) => representativeClusterValue(cluster.failures, (failure) => failure.received);
+const representativeClusterSelector = (cluster) => {
+    const evidenceSelector = buildClusterEvidenceLines(cluster)
+        .find((line) => line.startsWith("Selector:"));
+    if (evidenceSelector)
+        return withoutPrefix(evidenceSelector, "Selector:");
+    return representativeClusterValue(cluster.failures, (failure) => canonicalLocatorForFailure(failure));
+};
+const representativeClusterBlocker = (cluster) => {
+    const evidenceBlocker = buildClusterEvidenceLines(cluster)
+        .find((line) => line.startsWith("Blocker:"));
+    if (evidenceBlocker)
+        return withoutPrefix(evidenceBlocker, "Blocker:");
+    return representativeClusterValue(cluster.failures, (failure) => blockedVerdictForFailure(failure)?.blocker);
+};
+const representativeClusterTargetState = (cluster) => {
+    const evidenceState = buildClusterEvidenceLines(cluster)
+        .find((line) => line.startsWith("Target state:"));
+    if (evidenceState)
+        return withoutPrefix(evidenceState, "Target state:");
+    const verdict = blockedVerdictForCluster(cluster);
+    if (!verdict)
+        return null;
+    switch (verdict.targetState) {
+        case "visible_blocked":
+            return "found and visible before timeout";
+        case "missing":
+            return "locator never appeared";
+        case "hidden":
+            return "found but hidden";
+        case "disabled":
+            return "found but disabled";
+        default:
+            return null;
+    }
+};
+const representativeClusterFailingCode = (cluster) => representativeClusterValue(cluster.failures, (failure) => failure.codeContext?.focusLine || null);
+const representativeClusterFailingStep = (cluster) => representativeClusterValue(cluster.failures, (failure) => failure.codeContext?.action || null);
+const representativeClusterPreviousAction = (cluster) => representativeClusterValue(cluster.failures, (failure) => failure.codeContext?.previousActionLine || null);
+const compactActionLine = (value) => truncateValue(value, 84);
+const assertionStateTransitionHint = (failure, cluster) => {
+    const previousAction = cluster
+        ? representativeClusterPreviousAction(cluster)
+        : failure.codeContext?.previousActionLine || null;
+    if (!previousAction)
+        return null;
+    const compact = compactActionLine(previousAction);
+    if (!compact)
+        return null;
+    return compact;
+};
+const buildSingleFailureIssue = (failed, top) => ({
+    title: (() => {
+        const clusterLike = {
+            key: "single",
+            count: 1,
+            sample: failed,
+            titles: [failed.title],
+            suspects: top ? [top] : [],
+            failures: [failed]
+        };
+        return compactIssueTitle(clusterLike);
+    })(),
+    cause: (() => {
+        const clusterLike = {
+            key: "single",
+            count: 1,
+            sample: failed,
+            titles: [failed.title],
+            suspects: top ? [top] : [],
+            failures: [failed]
+        };
+        return failed.signal === "assertion_mismatch" || failed.signal === "timeout" || failed.signal === "locator_not_found" || failed.signal === "actionability"
+            ? clusterCauseLine(clusterLike)
+            : (0, exports.describeFailure)(failed);
+    })(),
+    affectedTitles: [failed.title],
+    where: locationValueForFailure(failed),
+    failingCode: failed.codeContext?.focusLine?.trim() || null,
+    failingStep: failed.codeContext?.action || null,
+    selector: failed.locator ? compactLocator(failed.locator) : null,
+    blocker: blockedVerdictForFailure(failed)?.blocker || null,
+    targetState: (() => {
+        const verdict = blockedVerdictForFailure(failed);
+        if (!verdict)
+            return null;
+        if (verdict.targetState === "visible_blocked")
+            return "found and visible before timeout";
+        if (verdict.targetState === "missing")
+            return "locator never appeared";
+        if (verdict.targetState === "hidden")
+            return "found but hidden";
+        if (verdict.targetState === "disabled")
+            return "found but disabled";
+        return null;
+    })(),
+    expected: failed.expected ? truncateValue(failed.expected) : null,
+    received: failed.received ? truncateValue(failed.received) : null,
+    whatChanged: top && top.score >= 0.62 ? top.commit.message : null,
+    reason: top && top.score >= 0.62 && top.reasons.length ? `${compactWhyLine(top)}.` : null,
+    next: (() => {
+        const clusterLike = {
+            key: "single",
+            count: 1,
+            sample: failed,
+            titles: [failed.title],
+            suspects: top ? [top] : [],
+            failures: [failed]
+        };
+        return strongerClusterNext(clusterLike);
+    })(),
+    impact: "1 test failing with this root cause",
+    clears: "fixing this likely clears 1 of 1 failures"
+});
+const buildClusterIssue = (cluster, totalFailures) => {
+    const top = cluster.suspects[0];
+    const rootCause = cluster.count === 1 ? (0, exports.describeFailure)(cluster.sample) : clusterCauseLine(cluster);
+    const hideSelectorSpecificEvidence = isMultiSelectorBlockedCluster(cluster);
+    return {
+        title: `${compactIssueTitle(cluster)} (${cluster.count} test${cluster.count === 1 ? "" : "s"})`,
+        cause: rootCause,
+        affectedTitles: cluster.titles,
+        where: locationValueForCluster(cluster),
+        failingCode: hideSelectorSpecificEvidence ? null : representativeClusterFailingCode(cluster)?.trim() || null,
+        failingStep: hideSelectorSpecificEvidence ? null : representativeClusterFailingStep(cluster)?.trim() || null,
+        selector: hideSelectorSpecificEvidence ? null : representativeClusterSelector(cluster)?.trim() || null,
+        blocker: representativeClusterBlocker(cluster)?.trim() || null,
+        targetState: representativeClusterTargetState(cluster)?.trim() || null,
+        expected: hideSelectorSpecificEvidence ? null : representativeClusterExpected(cluster) ? truncateValue(representativeClusterExpected(cluster) || null) : null,
+        received: representativeClusterReceived(cluster) ? truncateValue(representativeClusterReceived(cluster) || null) : null,
+        whatChanged: top && top.score >= 0.62 ? top.commit.message : null,
+        reason: top && top.score >= 0.62 && top.reasons.length ? `${compactWhyLine(top)}.` : null,
+        next: strongerClusterNext(cluster),
+        impact: `${cluster.count} test${cluster.count === 1 ? "" : "s"} failing with ${cluster.count === 1 ? "this" : "same"} root cause`,
+        clears: `fixing this likely clears ${cluster.count} of ${totalFailures} failures`
+    };
+};
+const renderDiagnosisSummary = (summary) => {
+    const lines = [];
+    if (summary.headline)
+        lines.push(summary.headline);
+    if (summary.headline)
+        lines.push("");
+    lines.push(summary.failureCountLine);
+    if (summary.collapseLine)
+        lines.push(summary.collapseLine);
+    if (summary.issues.length)
+        lines.push("");
+    for (const [index, issue] of summary.issues.entries()) {
+        lines.push(`${summary.issues.length === 1 ? "Issue" : `Issue ${index + 1}`}: ${issue.title}`);
+        lines.push(`  Cause: ${issue.cause}`);
+        const isSetupIssue = issue.title.startsWith("Playwright setup error");
+        if (!isSetupIssue) {
+            if (issue.where)
+                lines.push(`  Where: ${issue.where}`);
+            if (issue.failingStep && issue.selector) {
+                const readableStep = humanizeAction(issue.failingStep) || issue.failingStep;
+                const combinedStep = readableStep.length > 1
+                    ? `${readableStep[0].toUpperCase()}${readableStep.slice(1)} on ${issue.selector} selector`
+                    : `${readableStep.toUpperCase()} on ${issue.selector} selector`;
+                lines.push(`  Failing step: ${combinedStep}`);
+            }
+            else {
+                if (issue.failingStep)
+                    lines.push(`  Failing step: ${humanizeAction(issue.failingStep) || issue.failingStep}`);
+                if (issue.selector)
+                    lines.push(`  Selector: ${issue.selector}`);
+            }
+            if (issue.blocker)
+                lines.push(`  Blocker: ${issue.blocker}`);
+            if (issue.targetState)
+                lines.push(`  Target state: ${issue.targetState}`);
+            if (issue.expected)
+                lines.push(`  Expected: ${issue.expected}`);
+            if (issue.received)
+                lines.push(`  Received: ${issue.received}`);
+            if (issue.whatChanged)
+                lines.push(`  Changes since last run: + ${issue.whatChanged}`);
+            if (issue.reason)
+                lines.push(`  Reason: ${issue.reason}`);
+            lines.push(`  Likely fix: ${issue.next}.`);
+            lines.push(`  Impact: ${issue.impact}`);
+        }
+        if (index < summary.issues.length - 1)
+            lines.push("");
+    }
+    return {
+        lines,
+        footer: summary.footer
+    };
+};
+const buildQuickDiagnosisStructured = (playwrightJsonPath) => {
     const failures = (0, exports.collectFailureFacts)(playwrightJsonPath);
     if (!failures.length)
         return null;
@@ -860,25 +2378,13 @@ const buildQuickDiagnosis = (playwrightJsonPath) => {
         const failed = failures[0];
         const suspects = commitWindow.trusted ? rankCommitsForFailure(failed, commitWindow) : [];
         const top = suspects[0];
-        const lines = [`Test: ${shortenTitle(failed.title)}`, `Likely cause: ${(0, exports.describeFailure)(failed)}`];
-        const primaryLocation = buildLocationLine(failed);
-        const confidence = top ? confidenceLabel(top.score).toLowerCase() : "medium";
-        lines.push(`Confidence: ${confidence}`);
-        if (top && top.score >= 0.62) {
-            lines.push(`Likely introduced in: "${top.commit.message}"`);
-            if (top.reasons.length) {
-                lines.push(`Reason: ${compactWhyLine(top)}.`);
-            }
-        }
-        lines.push("Check first:");
-        lines.push(`- ${checkFirst(failed)}`);
-        if (primaryLocation)
-            lines.push(`Where: ${withoutPrefix(withoutPrefix(primaryLocation, "Error location:"), "Likely file:")}`);
-        if (failed.codeContext?.action)
-            lines.push(`Failing step: ${failed.codeContext.action}`);
         return {
-            lines,
-            footer: []
+            mode: "failure",
+            headline: null,
+            failureCountLine: "❌ 1 failure",
+            collapseLine: null,
+            issues: [buildSingleFailureIssue(failed, top)],
+            footer: top ? [`Confidence: ${confidenceLabel(top.score).toLowerCase()}`] : []
         };
     }
     const clusterMap = new Map();
@@ -894,40 +2400,32 @@ const buildQuickDiagnosis = (playwrightJsonPath) => {
         count: clusterFailures.length,
         sample: clusterFailures[0],
         titles: clusterFailures.map((item) => item.title),
-        suspects: commitWindow.trusted ? buildClusterSuspects(clusterFailures, commitWindow) : []
+        suspects: commitWindow.trusted ? buildClusterSuspects(clusterFailures, commitWindow) : [],
+        failures: clusterFailures
     }))
-        .sort((a, b) => b.count - a.count)
-        .slice(0, 2);
+        .sort((a, b) => b.count - a.count ||
+        ((b.suspects[0]?.score || 0) - (a.suspects[0]?.score || 0)) ||
+        (b.sample.signal === "assertion_mismatch" ? 1 : 0) - (a.sample.signal === "assertion_mismatch" ? 1 : 0));
     const topCluster = clusters[0];
-    const lines = [
-        `${failures.length} tests failed.`,
-        `Collapsed into ${clusters.length} likely root cause${clusters.length === 1 ? "" : "s"}:`
-    ];
-    for (const [index, cluster] of clusters.entries()) {
-        const clusterFailures = clusterMap.get(cluster.key) || [cluster.sample];
-        const clusterLocation = buildClusterLocationLine(clusterFailures);
-        const top = cluster.suspects[0];
-        const locationValue = clusterLocation
-            ? withoutPrefix(clusterLocation, clusterLocation.startsWith("Error locations:") ? "Error locations:" : "Error location:")
-            : null;
-        const rootCause = cluster.count === 1 ? (0, exports.describeFailure)(cluster.sample) : compactRootCauseSummary(cluster);
-        lines.push(`[${index + 1}] ${rootCauseLabel(cluster.sample)} (${cluster.count} tests)`);
-        lines.push(`    Likely cause: ${rootCause}`);
-        if (top && top.score >= 0.62) {
-            lines.push(`    Likely introduced in: "${top.commit.message}"`);
-            if (top.reasons.length) {
-                lines.push(`    Reason: ${compactWhyLine(top)}.`);
-            }
-        }
-        lines.push(`    Check first: ${clusterCheckFirst(cluster)}.`);
-        if (locationValue) {
-            lines.push(`    Where: ${locationValue}`);
-        }
-        lines.push(`    Shared impact: ${cluster.count} test${cluster.count === 1 ? "" : "s"} failing with ${cluster.count === 1 ? "this" : "same"} root cause`);
-    }
+    const visibleClusters = clusters.slice(0, 3);
     return {
-        lines,
+        mode: "failure",
+        headline: null,
+        failureCountLine: clusters.length < failures.length
+            ? `❌ ${failures.length} failures (grouped)`
+            : `❌ ${failures.length} failures`,
+        collapseLine: clusters.length < failures.length
+            ? clusters.length > visibleClusters.length
+                ? `Collapsed into ${clusters.length} real issues (showing top ${visibleClusters.length})`
+                : `Collapsed into ${clusters.length} real issue${clusters.length === 1 ? "" : "s"}`
+            : null,
+        issues: visibleClusters.map((cluster) => buildClusterIssue(cluster, failures.length)),
         footer: topCluster?.suspects[0] ? [`Confidence: ${confidenceLabel(topCluster.suspects[0].score).toLowerCase()}`] : []
     };
 };
+exports.buildQuickDiagnosisStructured = buildQuickDiagnosisStructured;
+const buildQuickDiagnosis = (playwrightJsonPath) => {
+    const summary = (0, exports.buildQuickDiagnosisStructured)(playwrightJsonPath);
+    return summary ? renderDiagnosisSummary(summary) : null;
+};
 exports.buildQuickDiagnosis = buildQuickDiagnosis;