@elench/testkit 0.1.61 → 0.1.63

package/lib/coverage/shared.mjs

@@ -9,6 +9,7 @@ export const HTTP_WRAPPER_METHODS = {
   patchJson: "PATCH",
   deleteJson: "DELETE",
 };
+export const DYNAMIC_SEGMENT_TOKEN = "__TESTKIT_DYNAMIC_SEGMENT__";
 
 export function createEmptyGraph() {
   return {
@@ -16,6 +17,7 @@ export function createEmptyGraph() {
     nodes: [],
     edges: [],
     evidence: [],
+    diagnostics: [],
   };
 }
 
@@ -195,3 +197,69 @@ export function dedupeDataImports(entries) {
     return true;
   });
 }
+
+export function findMatchingApiRouteEntry(method, candidatePath, routeEntries = []) {
+  const normalizedMethod = String(method || "").trim().toUpperCase();
+  const normalizedCandidate = normalizeRequestPathCandidate(candidatePath);
+  if (!normalizedMethod || !normalizedCandidate) return null;
+
+  return [...routeEntries]
+    .filter((entry) => entry.method === normalizedMethod)
+    .sort(compareRouteSpecificity)
+    .find((entry) => routePatternMatchesCandidate(entry.requestPath, normalizedCandidate)) || null;
+}
+
+export function findMatchingRouteValue(candidateRoute, routeValues = []) {
+  const normalizedCandidate = normalizeRequestPathCandidate(candidateRoute);
+  if (!normalizedCandidate) return null;
+
+  return [...routeValues]
+    .sort((left, right) => compareRouteSpecificity({ requestPath: left }, { requestPath: right }))
+    .find((routeValue) => routePatternMatchesCandidate(routeValue, normalizedCandidate)) || null;
+}
+
+export function normalizeRequestPathCandidate(value) {
+  if (typeof value !== "string") return null;
+  const [withoutHash] = value.split("#");
+  const [withoutQuery] = withoutHash.split("?");
+  return normalizeRoute(withoutQuery || "/");
+}
+
+export function routePatternMatchesCandidate(patternPath, candidatePath) {
+  const normalizedPattern = normalizeRequestPathCandidate(patternPath);
+  const normalizedCandidate = normalizeRequestPathCandidate(candidatePath);
+  if (!normalizedPattern || !normalizedCandidate) return false;
+
+  const patternSegments = splitRouteSegments(normalizedPattern);
+  const candidateSegments = splitRouteSegments(normalizedCandidate);
+  if (patternSegments.length !== candidateSegments.length) return false;
+
+  for (let index = 0; index < patternSegments.length; index += 1) {
+    const patternSegment = patternSegments[index];
+    const candidateSegment = candidateSegments[index];
+    if (patternSegment === candidateSegment) continue;
+    if (isDynamicRouteSegment(patternSegment) && candidateSegment.length > 0) continue;
+    if (candidateSegment === DYNAMIC_SEGMENT_TOKEN && isDynamicRouteSegment(patternSegment)) continue;
+    return false;
+  }
+
+  return true;
+}
+
+export function isDynamicRouteSegment(segment) {
+  return /^\[[^/]+\]$/u.test(segment) || /^\[\.\.\.[^/]+\]$/u.test(segment) || /^\[\[\.\.\.[^/]+\]\]$/u.test(segment);
+}
+
+function splitRouteSegments(value) {
+  if (value === "/") return [];
+  return value.split("/").filter(Boolean);
+}
+
+function compareRouteSpecificity(left, right) {
+  const leftSegments = splitRouteSegments(left.requestPath || "");
+  const rightSegments = splitRouteSegments(right.requestPath || "");
+  const leftStaticSegments = leftSegments.filter((segment) => !isDynamicRouteSegment(segment)).length;
+  const rightStaticSegments = rightSegments.filter((segment) => !isDynamicRouteSegment(segment)).length;
+  if (leftStaticSegments !== rightStaticSegments) return rightStaticSegments - leftStaticSegments;
+  return rightSegments.length - leftSegments.length;
+}

package/lib/coverage/shared.test.mjs

@@ -1,8 +1,12 @@
 import { describe, expect, it } from "vitest";
 import {
+  DYNAMIC_SEGMENT_TOKEN,
   dedupeTargets,
+  findMatchingApiRouteEntry,
+  findMatchingRouteValue,
   modulePathKey,
   pageLabelFromRoute,
+  routePatternMatchesCandidate,
   toApiRequestPath,
   toSelectionType,
 } from "./shared.mjs";
@@ -36,4 +40,33 @@ describe("coverage shared helpers", () => {
     expect(toSelectionType("integration", "http")).toBe("int");
     expect(toSelectionType("ui", "playwright")).toBe("pw");
   });
+
+  it("matches dynamic API route patterns against concrete and template-like request paths", () => {
+    expect(routePatternMatchesCandidate("/api/projects/[projectId]/overview", "/api/projects/123/overview")).toBe(true);
+    expect(
+      routePatternMatchesCandidate(
+        "/api/projects/[projectId]/events",
+        `/api/projects/${DYNAMIC_SEGMENT_TOKEN}/events`
+      )
+    ).toBe(true);
+    expect(routePatternMatchesCandidate("/api/projects/[projectId]/events", "/api/projects/123/stats")).toBe(false);
+  });
+
+  it("prefers the most specific matching API route entry", () => {
+    const routeEntry = findMatchingApiRouteEntry("GET", "/api/projects/123/events", [
+      { method: "GET", requestPath: "/api/projects/[projectId]" },
+      { method: "GET", requestPath: "/api/projects/[projectId]/events" },
+    ]);
+
+    expect(routeEntry).toEqual({
+      method: "GET",
+      requestPath: "/api/projects/[projectId]/events",
+    });
+  });
+
+  it("matches dynamic page routes against discovered route patterns", () => {
+    expect(
+      findMatchingRouteValue(`/projects/${DYNAMIC_SEGMENT_TOKEN}`, ["/projects/[projectId]", "/projects"])
+    ).toBe("/projects/[projectId]");
+  });
 });

package/node_modules/@elench/testkit-bridge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-bridge",
-  "version": "0.1.61",
+  "version": "0.1.63",
   "description": "Browser bridge helpers for testkit",
   "type": "module",
   "main": "./src/index.mjs",
@@ -11,7 +11,7 @@
     "src/"
   ],
   "dependencies": {
-    "@elench/testkit-protocol": "0.1.61"
+    "@elench/testkit-protocol": "0.1.63"
   },
   "private": false
 }

package/node_modules/@elench/testkit-bridge/src/index.mjs

@@ -143,6 +143,7 @@ export function buildPageOverlayResponse(context, pageUrl) {
   const projection = buildGraphProjection(context, page, match.service?.name || null);
   const relatedCoverageCount = projection.coverage.length;
   const relatedFailureCount = projection.failures.length;
+  const coverageBreakdown = buildCoverageBreakdown(projection.coverage);
 
   return {
     protocolVersion: TESTKIT_BROWSER_PROTOCOL_VERSION,
@@ -162,6 +163,7 @@ export function buildPageOverlayResponse(context, pageUrl) {
       coverageState: relatedCoverageCount > 0 ? "covered" : "missing",
       relatedFailureCount,
       relatedCoverageCount,
+      coverageBreakdown,
     },
     failures: projection.failures,
     coverage: projection.coverage,
@@ -267,6 +269,11 @@ function buildGraphProjection(context, page, matchedServiceName) {
     .filter((node) => node?.kind === "ui_surface");
   const pageReachableNodeIds = collectReachableNodeIds(pageNode.id, outgoing);
 
+  const surfaceReachableEntries = surfaceNodes.map((surfaceNode) => ({
+    surfaceNode,
+    reachableNodeIds: collectReachableNodeIds(surfaceNode.id, outgoing),
+  }));
+
   if (surfaceNodes.length === 0) {
     const relevantEvidence = evidence.filter((entry) => intersects(entry.coveredNodeIds || [], pageReachableNodeIds));
     return buildPageLevelProjection({
@@ -283,14 +290,16 @@ function buildGraphProjection(context, page, matchedServiceName) {
   const coverage = [];
   const failures = [];
 
-  for (const surfaceNode of surfaceNodes.sort((left, right) => left.id.localeCompare(right.id))) {
-    const surfaceReachableNodeIds = collectReachableNodeIds(surfaceNode.id, outgoing);
+  for (const { surfaceNode, reachableNodeIds: surfaceReachableNodeIds } of surfaceReachableEntries.sort((left, right) =>
+    left.surfaceNode.id.localeCompare(right.surfaceNode.id)
+  )) {
     const relevantEvidence = evidence.filter((entry) => intersects(entry.coveredNodeIds || [], surfaceReachableNodeIds));
     const supportingTests = relevantEvidence
       .map((entry) => buildSupportingTestRef(entry, discoveryByFile, context.runArtifact))
       .filter(Boolean);
 
     if (supportingTests.length > 0) {
+      const supportKind = inferCoverageSupportKind(supportingTests);
       coverage.push({
         id: surfaceNode.id,
         kind: surfaceNode.kind,
@@ -301,6 +310,10 @@ function buildGraphProjection(context, page, matchedServiceName) {
         supportingTests,
         viaNodes: collectViaNodes(relevantEvidence, surfaceReachableNodeIds, nodeById, new Set([pageNode.id, surfaceNode.id])),
         confidence: supportingTests.some((entry) => entry.type === "pw") ? "high" : "medium",
+        importance: inferSurfaceImportance(surfaceNode),
+        surfaceKind: surfaceNode.metadata?.surfaceKind ? String(surfaceNode.metadata.surfaceKind) : null,
+        supportKind,
+        reason: buildCoverageReason(surfaceNode, supportKind, supportingTests, relevantEvidence),
       });
     }
 
@@ -329,7 +342,26 @@ function buildGraphProjection(context, page, matchedServiceName) {
       targets: collectTargetsForEvidence(failedEvidence, surfaceNode.target),
       failedTests,
       viaNodes: collectViaNodes(failedEvidence, surfaceReachableNodeIds, nodeById, new Set([pageNode.id, surfaceNode.id])),
+      importance: inferSurfaceImportance(surfaceNode),
+      surfaceKind: surfaceNode.metadata?.surfaceKind ? String(surfaceNode.metadata.surfaceKind) : null,
+      reason: buildFailureReason(surfaceNode, failedTests),
+    });
+  }
+
+  const routeLevelNodeIds = collectRouteLevelNodeIds(pageReachableNodeIds, surfaceReachableEntries);
+  if (routeLevelNodeIds.size > 0) {
+    const routeRelevantEvidence = evidence.filter((entry) => intersects(entry.coveredNodeIds || [], routeLevelNodeIds));
+    const pageProjection = buildPageLevelProjection({
+      pageNode,
+      nodeById,
+      relevantEvidence: routeRelevantEvidence,
+      pageReachableNodeIds: routeLevelNodeIds,
+      discoveryByFile,
+      failureByFile,
+      runArtifact: context.runArtifact,
     });
+    coverage.unshift(...pageProjection.coverage);
+    failures.unshift(...pageProjection.failures);
   }
 
   return { coverage, failures };
@@ -352,6 +384,10 @@ function buildPageLevelProjection({ pageNode, nodeById, relevantEvidence, pageRe
           supportingTests,
           viaNodes: collectViaNodes(relevantEvidence, pageReachableNodeIds, nodeById, new Set([pageNode.id])),
           confidence: supportingTests.some((entry) => entry.type === "pw") ? "high" : "medium",
+          importance: inferSurfaceImportance(pageNode),
+          surfaceKind: pageNode.kind,
+          supportKind: inferCoverageSupportKind(supportingTests),
+          reason: buildCoverageReason(pageNode, inferCoverageSupportKind(supportingTests), supportingTests, relevantEvidence),
         },
       ]
     : [];
@@ -370,6 +406,9 @@ function buildPageLevelProjection({ pageNode, nodeById, relevantEvidence, pageRe
         targets: collectTargetsForEvidence([entry], pageNode.target),
         failedTests: supporting ? [{ ...supporting, error: failed?.error || supporting.error || null, status: "failed" }] : [],
         viaNodes: collectViaNodes([entry], pageReachableNodeIds, nodeById, new Set([pageNode.id])),
+        importance: inferSurfaceImportance(pageNode),
+        surfaceKind: pageNode.kind,
+        reason: buildFailureReason(pageNode, supporting ? [{ ...supporting, error: failed?.error || supporting.error || null, status: "failed" }] : []),
       };
     });
 
@@ -400,6 +439,16 @@ function collectReachableNodeIds(startNodeId, outgoing) {
   return visited;
 }
 
+function collectRouteLevelNodeIds(pageReachableNodeIds, surfaceReachableEntries) {
+  const routeLevelNodeIds = new Set(pageReachableNodeIds);
+  for (const { reachableNodeIds } of surfaceReachableEntries) {
+    for (const nodeId of reachableNodeIds) {
+      routeLevelNodeIds.delete(nodeId);
+    }
+  }
+  return routeLevelNodeIds;
+}
+
 function collectViaNodes(evidenceEntries, reachableNodeIds, nodeById, excludedNodeIds = new Set()) {
   const nodes = new Map();
   for (const entry of evidenceEntries) {
@@ -475,3 +524,60 @@ function pathBaseName(filePath) {
   const parts = String(filePath || "").split("/");
   return parts[parts.length - 1] || filePath;
 }
+
+function buildCoverageBreakdown(entries) {
+  const breakdown = { direct: 0, indirect: 0, mixed: 0 };
+  for (const entry of entries || []) {
+    if (entry.supportKind === "direct") breakdown.direct += 1;
+    else if (entry.supportKind === "indirect") breakdown.indirect += 1;
+    else breakdown.mixed += 1;
+  }
+  return breakdown;
+}
+
+function inferCoverageSupportKind(supportingTests) {
+  const hasPw = (supportingTests || []).some((entry) => entry.type === "pw");
+  const hasBackend = (supportingTests || []).some((entry) => entry.type !== "pw");
+  if (hasPw && hasBackend) return "mixed";
+  if (hasPw) return "direct";
+  return "indirect";
+}
+
+function inferSurfaceImportance(node) {
+  const label = String(node?.label || "").toLowerCase();
+  const surfaceKind = String(node?.metadata?.surfaceKind || node?.kind || "").toLowerCase();
+
+  if (/\b(pay|purchase|checkout|publish|send|submit|confirm|delete|remove)\b/u.test(label)) {
+    return "critical";
+  }
+  if (/\b(save|create|update|refresh|retry|login|sign in|continue)\b/u.test(label)) {
+    return "high";
+  }
+  if (surfaceKind === "form" || surfaceKind === "button" || surfaceKind === "input") {
+    return "medium";
+  }
+  return "low";
+}
+
+function buildCoverageReason(node, supportKind, supportingTests, evidenceEntries) {
+  const directCount = supportingTests.filter((entry) => entry.type === "pw").length;
+  const backendCount = supportingTests.filter((entry) => entry.type !== "pw").length;
+  const requestPaths = new Set();
+  for (const entry of evidenceEntries || []) {
+    for (const path of entry?.details?.requestPaths || []) requestPaths.add(path);
+  }
+  const requestSummary = requestPaths.size > 0 ? ` via ${[...requestPaths].join(", ")}` : "";
+  if (supportKind === "mixed") {
+    return `${node.label} is covered directly by ${directCount} UI test${directCount === 1 ? "" : "s"} and indirectly by ${backendCount} backend test${backendCount === 1 ? "" : "s"}${requestSummary}.`;
+  }
+  if (supportKind === "direct") {
+    return `${node.label} is covered directly by ${directCount} UI test${directCount === 1 ? "" : "s"}${requestSummary}.`;
+  }
+  return `${node.label} is covered indirectly by ${backendCount} backend test${backendCount === 1 ? "" : "s"}${requestSummary}.`;
+}
+
+function buildFailureReason(node, failedTests) {
+  const count = (failedTests || []).length;
+  if (count === 0) return `${node.label} has a related failing test.`;
+  return `${node.label} is implicated by ${count} failing test${count === 1 ? "" : "s"}.`;
+}

package/node_modules/@elench/testkit-bridge/src/index.test.mjs

@@ -161,6 +161,163 @@ const context = {
   },
 };
 
+const routeLevelContext = {
+  product: {
+    name: "dashboard",
+    directory: "/tmp/dashboard",
+  },
+  services: [
+    {
+      name: "dashboard",
+      baseUrl: "http://localhost:3000",
+      origin: "http://localhost:3000",
+    },
+  ],
+  discovery: {
+    files: [
+      {
+        path: "__testkit__/projects/projects.int.testkit.ts",
+        displayName: "Projects",
+        service: "dashboard",
+        suiteName: "projects",
+        selectionType: "int",
+        framework: "k6",
+        skipped: false,
+      },
+    ],
+    coverageGraph: {
+      schemaVersion: 1,
+      nodes: [
+        {
+          id: "page_view:dashboard:/projects",
+          kind: "page_view",
+          service: "dashboard",
+          label: "Projects",
+          route: "/projects",
+          filePath: "src/app/projects/page.tsx",
+        },
+        {
+          id: "ui_surface:dashboard:/projects:project-create-button",
+          kind: "ui_surface",
+          service: "dashboard",
+          label: "Create Project",
+          route: "/projects",
+          filePath: "src/app/projects/page.tsx",
+          target: { kind: "testId", value: "project-create-button", confidence: "high" },
+        },
+        {
+          id: "ui_action:dashboard:/projects:handleCreate",
+          kind: "ui_action",
+          service: "dashboard",
+          label: "handleCreate",
+          route: "/projects",
+          filePath: "src/app/projects/page.tsx",
+        },
+        {
+          id: "client_request:dashboard:provider:GET:/api/projects",
+          kind: "client_request",
+          service: "dashboard",
+          label: "GET /api/projects",
+          route: "/projects",
+          method: "GET",
+          path: "/api/projects",
+          filePath: "src/components/project-context.tsx",
+        },
+        {
+          id: "client_request:dashboard:projects:POST:/api/projects",
+          kind: "client_request",
+          service: "dashboard",
+          label: "POST /api/projects",
+          route: "/projects",
+          method: "POST",
+          path: "/api/projects",
+          filePath: "src/app/projects/page.tsx",
+        },
+        {
+          id: "api_route:dashboard:GET:/api/projects",
+          kind: "api_route",
+          service: "dashboard",
+          label: "GET /api/projects",
+          route: "/projects",
+          method: "GET",
+          path: "/api/projects",
+          filePath: "src/app/api/projects/route.ts",
+        },
+        {
+          id: "api_route:dashboard:POST:/api/projects",
+          kind: "api_route",
+          service: "dashboard",
+          label: "POST /api/projects",
+          route: "/projects",
+          method: "POST",
+          path: "/api/projects",
+          filePath: "src/app/api/projects/route.ts",
+        },
+      ],
+      edges: [
+        {
+          id: "contains:page_view:dashboard:/projects:ui_surface:dashboard:/projects:project-create-button",
+          kind: "contains",
+          from: "page_view:dashboard:/projects",
+          to: "ui_surface:dashboard:/projects:project-create-button",
+        },
+        {
+          id: "triggers:ui_surface:dashboard:/projects:project-create-button:ui_action:dashboard:/projects:handleCreate",
+          kind: "triggers",
+          from: "ui_surface:dashboard:/projects:project-create-button",
+          to: "ui_action:dashboard:/projects:handleCreate",
+        },
+        {
+          id: "requests:page_view:dashboard:/projects:client_request:dashboard:provider:GET:/api/projects",
+          kind: "requests",
+          from: "page_view:dashboard:/projects",
+          to: "client_request:dashboard:provider:GET:/api/projects",
+        },
+        {
+          id: "requests:ui_action:dashboard:/projects:handleCreate:client_request:dashboard:projects:POST:/api/projects",
+          kind: "requests",
+          from: "ui_action:dashboard:/projects:handleCreate",
+          to: "client_request:dashboard:projects:POST:/api/projects",
+        },
+        {
+          id: "handles:client_request:dashboard:provider:GET:/api/projects:api_route:dashboard:GET:/api/projects",
+          kind: "handles",
+          from: "client_request:dashboard:provider:GET:/api/projects",
+          to: "api_route:dashboard:GET:/api/projects",
+        },
+        {
+          id: "handles:client_request:dashboard:projects:POST:/api/projects:api_route:dashboard:POST:/api/projects",
+          kind: "handles",
+          from: "client_request:dashboard:projects:POST:/api/projects",
+          to: "api_route:dashboard:POST:/api/projects",
+        },
+      ],
+      evidence: [
+        {
+          id: "evidence:dashboard:__testkit__/projects/projects.int.testkit.ts",
+          source: "convention",
+          confidence: "high",
+          service: "dashboard",
+          suiteName: "projects",
+          selectionType: "int",
+          framework: "k6",
+          testFilePath: "__testkit__/projects/projects.int.testkit.ts",
+          coveredNodeIds: [
+            "api_route:dashboard:GET:/api/projects",
+            "api_route:dashboard:POST:/api/projects",
+          ],
+          details: {
+            route: "/projects",
+            requestPaths: ["/api/projects"],
+          },
+        },
+      ],
+      diagnostics: [],
+    },
+  },
+  runArtifact: null,
+};
+
 describe("testkit bridge", () => {
   it("matches pages against service base URLs", () => {
     expect(buildMatchResponse(context, "http://localhost:3000/coverage")).toMatchObject({
@@ -177,37 +334,76 @@ describe("testkit bridge", () => {
       summary: {
         failureState: "failing",
         coverageState: "covered",
-        relatedFailureCount: 1,
-        relatedCoverageCount: 1,
+        relatedFailureCount: 2,
+        relatedCoverageCount: 2,
+        coverageBreakdown: {
+          direct: 1,
+          indirect: 0,
+          mixed: 1,
+        },
       },
-      failures: [
-        {
+      failures: expect.arrayContaining([
+        expect.objectContaining({
+          kind: "page_view",
+          label: "Coverage",
+        }),
+        expect.objectContaining({
           kind: "ui_surface",
           label: "Refresh overlay",
+          importance: "high",
+          reason: "Refresh overlay is implicated by 1 failing test.",
           targets: [{ kind: "testId", value: "coverage-refresh-button", confidence: "high" }],
           failedTests: [
-            {
+            expect.objectContaining({
               filePath: "app/coverage/__testkit__/coverage.pw.testkit.ts",
               type: "pw",
-            },
+            }),
           ],
-        },
-      ],
-      coverage: [
-        {
+        }),
+      ]),
+      coverage: expect.arrayContaining([
+        expect.objectContaining({
+          kind: "page_view",
+          label: "Coverage",
+          supportKind: "direct",
+        }),
+        expect.objectContaining({
           kind: "ui_surface",
           label: "Refresh overlay",
+          importance: "high",
+          supportKind: "mixed",
           targets: [{ kind: "testId", value: "coverage-refresh-button", confidence: "high" }],
           supportingTests: [
-            {
+            expect.objectContaining({
               filePath: "app/coverage/__testkit__/coverage.pw.testkit.ts",
-            },
-            {
+            }),
+            expect.objectContaining({
               filePath: "app/api/coverage/__testkit__/coverage.int.testkit.ts",
-            },
+            }),
           ],
-        },
-      ],
+        }),
+      ]),
+    });
+  });
+
+  it("retains route-level coverage when support comes from page-owned requests outside any surfaced control", () => {
+    expect(buildPageOverlayResponse(routeLevelContext, "http://localhost:3000/projects")).toMatchObject({
+      summary: {
+        coverageState: "covered",
+        relatedCoverageCount: 2,
+      },
+      coverage: expect.arrayContaining([
+        expect.objectContaining({
+          kind: "page_view",
+          label: "Projects",
+          supportKind: "indirect",
+        }),
+        expect.objectContaining({
+          kind: "ui_surface",
+          label: "Create Project",
+          supportKind: "indirect",
+        }),
+      ]),
     });
   });
 });

package/node_modules/@elench/testkit-protocol/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elench/testkit-protocol",
-  "version": "0.1.61",
+  "version": "0.1.63",
   "description": "Shared browser protocol for testkit bridge and extension consumers",
   "type": "module",
   "main": "./src/index.mjs",

package/node_modules/@elench/testkit-protocol/src/index.d.ts

@@ -5,6 +5,8 @@ export type BrowserTargetKind = "testId" | "role" | "text" | "css" | "xpath" | "
 export type BrowserConfidence = "low" | "medium" | "high";
 export type BrowserFailureState = "failing" | "healthy" | "unavailable";
 export type BrowserCoverageState = "covered" | "missing" | "unavailable";
+export type BridgeSurfaceImportance = "critical" | "high" | "medium" | "low";
+export type BridgeCoverageSupportKind = "direct" | "indirect" | "mixed";
 
 export type CoverageNodeKind =
   | "page_view"
@@ -86,11 +88,22 @@ export interface CoverageEvidence {
   };
 }
 
+export type CoverageGraphDiagnosticLevel = "info" | "warn";
+
+export interface CoverageGraphDiagnostic {
+  level: CoverageGraphDiagnosticLevel;
+  code: string;
+  filePath: string;
+  service: string;
+  message: string;
+}
+
 export interface CoverageGraph {
   schemaVersion: number;
   nodes: CoverageGraphNode[];
   edges: CoverageGraphEdge[];
   evidence: CoverageEvidence[];
+  diagnostics: CoverageGraphDiagnostic[];
 }
 
 export interface BridgeProductRef {
@@ -149,6 +162,9 @@ export interface FailureOverlayEntry {
   targets: BrowserTarget[];
   failedTests: BridgeSupportingTestRef[];
   viaNodes: BridgeCoverageViaNodeRef[];
+  importance?: BridgeSurfaceImportance;
+  surfaceKind?: string | null;
+  reason?: string | null;
 }
 
 export interface CoverageOverlayEntry {
@@ -161,6 +177,10 @@ export interface CoverageOverlayEntry {
   supportingTests: BridgeSupportingTestRef[];
   viaNodes: BridgeCoverageViaNodeRef[];
   confidence: BrowserConfidence;
+  importance?: BridgeSurfaceImportance;
+  surfaceKind?: string | null;
+  supportKind?: BridgeCoverageSupportKind;
+  reason?: string | null;
 }
 
 export interface PageOverlayResponse {
@@ -177,6 +197,11 @@ export interface PageOverlayResponse {
     coverageState: BrowserCoverageState;
     relatedFailureCount: number;
     relatedCoverageCount: number;
+    coverageBreakdown?: {
+      direct: number;
+      indirect: number;
+      mixed: number;
+    };
   };
   failures: FailureOverlayEntry[];
   coverage: CoverageOverlayEntry[];
@@ -196,6 +221,7 @@ export declare function normalizeBrowserMetadataDocument(value: unknown): Browse
 export declare function normalizeCoverageGraphNode(value: unknown): CoverageGraphNode | null;
 export declare function normalizeCoverageGraphEdge(value: unknown): CoverageGraphEdge | null;
 export declare function normalizeCoverageEvidence(value: unknown): CoverageEvidence | null;
+export declare function normalizeCoverageGraphDiagnostic(value: unknown): CoverageGraphDiagnostic | null;
 export declare function normalizeCoverageGraph(value: unknown): CoverageGraph | null;
 export declare function normalizePageOverlayResponse(value: unknown): PageOverlayResponse | null;
 export declare function isPageOverlayResponse(value: unknown): value is PageOverlayResponse;