@sentinelqa/playwright-reporter 0.1.53 → 0.1.56

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");
@@ -250,20 +250,30 @@ const toMessage = (result) => {
 };
 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";
     }
@@ -277,20 +287,238 @@ 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 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) ||
@@ -313,6 +541,65 @@ 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 extractStackLocation = (message) => {
     const lines = stripAnsi(message).split(/\r?\n/);
     for (const line of lines) {
@@ -372,6 +659,35 @@ 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) {
@@ -400,6 +716,22 @@ const timeoutState = (failure) => {
         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 {
@@ -422,6 +754,147 @@ const timeoutStateLabel = (state) => {
             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 = [];
@@ -549,6 +1022,25 @@ const flattenFailedCases = (node, titlePath = []) => {
     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;
@@ -613,6 +1105,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":
@@ -632,16 +1126,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 `${compactLocator(failure.locator)} showed "${truncateValue(failure.received, 72)}" instead of "${truncateValue(failure.expected, 40)}".`;
+        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 `${compactLocator(failure.locator)} was not found when the test expected it to be available.`;
     }
     if (failure.signal === "actionability" && failure.locator) {
+        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.`;
@@ -650,6 +1190,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.`;
@@ -658,6 +1204,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") {
@@ -800,15 +1352,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`);
@@ -823,6 +1383,9 @@ 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);
@@ -840,29 +1403,97 @@ 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") {
@@ -873,17 +1504,55 @@ const compactRootCauseSummary = (cluster) => {
 const compactIssueTitle = (cluster) => {
     const failure = cluster.sample;
     const locator = compactLocator(failure.locator);
+    const blockedVerdict = blockedVerdictForCluster(cluster);
+    const navigation = navigationVerdictForFailure(failure);
     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 (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 ? `Network/API failure (${truncateValue(failure.apiHint, 28)})` : "Network/API failure";
+            return failure.apiHint ? `Backend/API failure (${truncateValue(failure.apiHint, 28)})` : "Backend/API failure";
         case "timeout":
-            return failure.locator ? `Timeout waiting on ${locator}` : "Timeout waiting for state change";
+            if (navigation?.kind === "navigation_timeout")
+                return "Navigation timeout";
+            if (navigation?.kind === "blank_page")
+                return "Blank page after navigation";
+            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":
@@ -894,9 +1563,31 @@ const compactIssueTitle = (cluster) => {
 };
 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") {
-        return failure.locator
-            ? `Same assertion mismatch on ${compactLocator(failure.locator)}`
+        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") {
@@ -905,28 +1596,166 @@ const clusterCauseLine = (cluster) => {
             : "Same missing or changed locator across these tests";
     }
     if (failure.signal === "actionability") {
-        return failure.locator
-            ? `${compactLocator(failure.locator)} is present but blocked in each failure`
-            : "Same actionability problem across these tests";
+        const subtype = blockedActionSubtype(failure, blockedVerdict);
+        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 (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 (failure.locator) {
-            return `check ${compactLocator(failure.locator)} or the data source behind it`;
+        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 (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 (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) => {
@@ -934,8 +1763,24 @@ const compactErrorLine = (failure) => {
         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
         ? {
@@ -947,9 +1792,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)
         }
@@ -961,13 +1806,30 @@ 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 || extractFocusLineFromMessage(message) || 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
             ? {
                 ...fallbackCodeContext,
-                focusLine: fallbackCodeContext.focusLine || extractFocusLineFromMessage(message) || null
+                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,
@@ -978,19 +1840,64 @@ const parseFailureFacts = (title, titlePath, message, status, file = null, optio
                 expectedText: null,
                 timeoutMs: null,
                 apiCall: null,
-                assertion: null,
+                assertion: assertionLine,
                 methodName: null,
-                focusLine: extractFocusLineFromMessage(message),
+                focusLine: signal === "assertion_mismatch"
+                    ? assertionLine || extractFocusLineFromMessage(message)
+                    : extractFocusLineFromMessage(message),
                 previousActionLine: null,
-                found: Boolean(fallbackLocation?.file || extractFocusLineFromMessage(message))
+                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 = extractLocator(message) ||
+        codeContext?.locator ||
+        domCapture?.normalizedLocator ||
+        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,
@@ -1056,6 +1963,9 @@ const buildSimilarityKey = (failure) => {
             basename(failure.likelyFile) || "unknown-file"
         ].join("|");
     }
+    if (failure.signal === "setup") {
+        return [failure.signal, normalizeMessageFingerprint(failure.message)].join("|");
+    }
     if (failure.signal === "timeout" || failure.signal === "actionability" || failure.signal === "locator_not_found") {
         return [
             failure.signal,
@@ -1084,6 +1994,8 @@ const buildSimilarityKey = (failure) => {
 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":
@@ -1116,7 +2028,211 @@ 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) => failure.locator);
+};
+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);
+    return {
+        title: `${compactIssueTitle(cluster)} (${cluster.count} test${cluster.count === 1 ? "" : "s"})`,
+        cause: rootCause,
+        affectedTitles: cluster.titles,
+        where: locationValueForCluster(cluster),
+        failingCode: representativeClusterFailingCode(cluster)?.trim() || null,
+        failingStep: representativeClusterFailingStep(cluster)?.trim() || null,
+        selector: representativeClusterSelector(cluster)?.trim() || null,
+        blocker: representativeClusterBlocker(cluster)?.trim() || null,
+        targetState: representativeClusterTargetState(cluster)?.trim() || null,
+        expected: 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;
@@ -1125,29 +2241,13 @@ const buildQuickDiagnosis = (playwrightJsonPath) => {
         const failed = failures[0];
         const suspects = commitWindow.trusted ? rankCommitsForFailure(failed, commitWindow) : [];
         const top = suspects[0];
-        const lines = [`What broke: ${shortenTitle(failed.title)}`, `Why: ${(0, exports.describeFailure)(failed)}`];
-        const primaryLocation = buildLocationLine(failed);
-        const confidence = top ? confidenceLabel(top.score).toLowerCase() : "medium";
-        if (primaryLocation)
-            lines.push(`Where: ${withoutPrefix(withoutPrefix(primaryLocation, "Error location:"), "Likely file:")}`);
-        if (failed.codeContext?.action)
-            lines.push(`Failing step: ${failed.codeContext.action}`);
-        if (failed.expected)
-            lines.push(`Expected: ${truncateValue(failed.expected)}`);
-        if (failed.received)
-            lines.push(`Received: ${truncateValue(failed.received)}`);
-        if (top && top.score >= 0.62) {
-            lines.push(`What changed: "${top.commit.message}"`);
-            if (top.reasons.length) {
-                lines.push(`Reason: ${compactWhyLine(top)}.`);
-            }
-        }
-        lines.push(`Confidence: ${confidence}`);
-        lines.push("Next:");
-        lines.push(`- ${checkFirst(failed)}`);
         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();
@@ -1168,50 +2268,95 @@ const buildQuickDiagnosis = (playwrightJsonPath) => {
     }))
         .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))
-        .slice(0, 2);
+        (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} real issue${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) : clusterCauseLine(cluster);
-        lines.push(`Issue ${index + 1}: ${compactIssueTitle(cluster)} (${cluster.count} test${cluster.count === 1 ? "" : "s"})`);
-        lines.push(`  Cause: ${rootCause}`);
-        if (locationValue) {
-            lines.push(`  Where: ${locationValue}`);
-        }
-        for (const evidenceLine of buildClusterEvidenceLines(cluster)) {
-            lines.push(`  ${evidenceLine}`);
-        }
-        if (cluster.sample.expected) {
-            lines.push(`  Expected: ${truncateValue(cluster.sample.expected)}`);
-        }
-        if (cluster.sample.received) {
-            lines.push(`  Received: ${truncateValue(cluster.sample.received)}`);
-        }
-        if (top && top.score >= 0.62) {
-            lines.push(`  What changed: "${top.commit.message}"`);
-            if (top.reasons.length) {
-                lines.push(`  Reason: ${compactWhyLine(top)}.`);
+    const mergeRelatedIssues = (issues) => {
+        // If multiple clusters share the same actionability blocker, treat them as one root cause.
+        // This matches the user's expectation: the blocker is the canonical evidence, not the target locator.
+        const merged = [];
+        const used = new Set();
+        const norm = (value) => (value || "").replace(/\s+/g, " ").trim().toLowerCase();
+        const isBlockedInteraction = (issue) => issue.title.toLowerCase().startsWith("blocked interaction");
+        const blockerKey = (issue) => {
+            const blocker = norm(issue.blocker);
+            if (!blocker)
+                return null;
+            const state = norm(issue.targetState);
+            return `blocked_interaction::${blocker}::${state}`;
+        };
+        const buildMergedTitle = (blocker, count) => {
+            const b = blocker.toLowerCase();
+            const prefix = b.includes("overlay") ? "Overlay blocked interactions" : "Blocked interaction";
+            return `${prefix} (${count} test${count === 1 ? "" : "s"})`;
+        };
+        for (let i = 0; i < issues.length; i += 1) {
+            if (used.has(i))
+                continue;
+            const base = issues[i];
+            const key = blockerKey(base);
+            if (!key || !isBlockedInteraction(base)) {
+                merged.push(base);
+                used.add(i);
+                continue;
             }
+            const group = [base];
+            used.add(i);
+            for (let j = i + 1; j < issues.length; j += 1) {
+                if (used.has(j))
+                    continue;
+                const candidate = issues[j];
+                if (!isBlockedInteraction(candidate))
+                    continue;
+                if (blockerKey(candidate) !== key)
+                    continue;
+                group.push(candidate);
+                used.add(j);
+            }
+            if (group.length === 1) {
+                merged.push(base);
+                continue;
+            }
+            const allTitles = Array.from(new Set(group.flatMap((issue) => issue.affectedTitles || [])));
+            const count = allTitles.length;
+            const blocker = group.map((issue) => issue.blocker).find(Boolean) || base.blocker || "";
+            const targetState = group.map((issue) => issue.targetState).find(Boolean) || base.targetState || null;
+            const whereParts = group
+                .map((issue) => issue.where)
+                .filter(Boolean)
+                .flatMap((where) => String(where).split(";").map((p) => p.trim()).filter(Boolean));
+            const where = Array.from(new Set(whereParts)).slice(0, 12).join("; ") || null;
+            merged.push({
+                ...base,
+                title: buildMergedTitle(blocker, count),
+                // Canonical, normalized evidence: blocker + state. Avoid sample-selector specificity here.
+                cause: `${blocker} blocked interactions across these tests`,
+                affectedTitles: allTitles,
+                where,
+                selector: null,
+                targetState,
+                impact: `${count} tests failing with same root cause`,
+                clears: `fixing this likely clears ${count} of ${failures.length} failures`
+            });
         }
-        lines.push(`  Next: ${strongerClusterNext(cluster)}.`);
-        lines.push(`  Impact: ${cluster.count} test${cluster.count === 1 ? "" : "s"} failing with ${cluster.count === 1 ? "this" : "same"} root cause`);
-        lines.push(`  Clears: fixing this likely clears ${cluster.count} of ${failures.length} failures`);
-        if (index < clusters.length - 1)
-            lines.push("");
-    }
+        return merged;
+    };
+    const mergedIssues = mergeRelatedIssues(clusters.map((cluster) => buildClusterIssue(cluster, failures.length)));
     return {
-        lines,
+        mode: "failure",
+        headline: null,
+        failureCountLine: clusters.length < failures.length
+            ? `❌ ${failures.length} failures (grouped)`
+            : `❌ ${failures.length} failures`,
+        collapseLine: clusters.length < failures.length
+            ? `Collapsed into ${clusters.length} real issue${clusters.length === 1 ? "" : "s"}`
+            : null,
+        issues: mergedIssues,
         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;