@reportforge/playwright-pdf 0.28.0 → 0.30.0

package/README.md

@@ -59,10 +59,11 @@ Three templates, one reporter. Every PDF is fully offline: fonts, charts, and sc
 - **Flakiness trend**: top-N flakiest tests table with per-test dot sparkline across stored history runs in the `detailed` template; `flakinessTopN` option (default 5, `0` disables)
 - **Pass-rate trend**: cross-run trend chart from stored history; opt-in `remoteHistory` keeps the trend alive on ephemeral CI runners by storing aggregate numbers only (pass rate, counts, duration, verdict; no test titles or error text, and the branch name never travels in plaintext), with no extra network calls
 - **Run-over-run diff**: every report shows what changed since the previous run on the same branch: new failures, fixed tests, and still-failing tests, and the same summary rides along in Slack, Teams, Discord, and email notifications
+- **Cross-browser comparison**: multi-project runs get a per-test matrix across projects in the `detailed` template — divergent outcomes first (fails-only-in-webkit at a glance), identical tests collapsed to a count; works for Node.js multi-project configs and pytest runs with multiple `--browser` values
 - **Offline failure analysis**: sorts each failure into one of 7 root-cause buckets and renders a root-cause chip under each failed test in the `detailed` PDF (dominant-cause one-liner in `executive`). No network, no AI service: a small embedded classifier with automatic updates; pin it any time. Full details at [reportforge.org/docs/advanced/failure-analysis](https://reportforge.org/docs/advanced/failure-analysis).
 - **On-device training**: teach the classifier your team's failures without any data leaving your machine. Label locally-collected samples (`npx @reportforge/playwright-pdf label-feedback`), then `train-model` trains and cross-validates a personal layer on-device; it activates only when it measurably beats the base model on your own labeled set (`evaluate-model` shows the comparison any time). Commit the model file to your repo via `failureAnalysis.localModelPath` to share it with CI. Training data, the trained model, and evaluation are all local files; the analysis code cannot even name a network primitive (enforced by an automated source audit).
 - `npx @reportforge/playwright-pdf export-feedback`: merges your locally-collected feedback (tokenized + redacted) into one CSV for review or moving between machines. Local file only; there is no upload.
-- **Rich execution capture**: opt-in "Steps to Reproduce" outline (a nested, copy-pasteable Markdown list of your `test.step`s and assertions; add `apiSteps` for the full click/fill/check trail), Node console tail, and trace/video links under each failed test in the defect log. Read straight from the Playwright step tree: no fixtures, no test-code changes. Enable via `capture` (`steps` / `apiSteps` / `console` / `evidence`); off by default.
+- **Rich execution capture**: opt-in "Steps to Reproduce" outline (a nested, copy-pasteable Markdown list of your `test.step`s and assertions; add `apiSteps` for the full click/fill/check trail), Node console tail, and trace/video links under each failed test in the defect log. Read straight from the Playwright step tree: no fixtures, no test-code changes. Enable via `capture` (`steps` / `apiSteps` / `console` / `evidence`); off by default. Set `evidenceUrlTemplate` to turn those trace/video paths into clickable CI artifact links with a QR code beside each one, so even a printed report jumps straight to the trace viewer.
 - **Configurable sections**: add or remove any report section per template via `sections`.
 - **Executive report brief band**: leads with a plain-language brief (trend + root causes) and one hero pass-rate number instead of a flat KPI grid
 - **Data protection**: AES-256 password-protected PDFs (no external tools) and opt-in redaction of credentials/PII in report content and live streams
@@ -179,7 +180,7 @@ template = "detailed"
 outputFile = "reports/{date}-{branch}-report.pdf"
 ```
 
-The plugin reuses the Node runtime and Chromium that Playwright for Python already ships, so there is nothing else to install. pytest-xdist and pytest-rerunfailures are supported; failure screenshots from `--screenshot only-on-failure` are embedded. Live runs and step trees are Node.js-only today. Full guide: [reportforge.org/docs/python](https://reportforge.org/docs/python).
+The plugin reuses the Node runtime and Chromium that Playwright for Python already ships, so there is nothing else to install. pytest-xdist and pytest-rerunfailures are supported; failure screenshots from `--screenshot only-on-failure` are embedded, and trace/video artifacts from `--tracing` / `--video` feed the defect log's evidence links (pair with `evidenceUrlTemplate` for clickable CI links). Passing `--browser` more than once splits the report into one project per browser and unlocks the cross-browser comparison section. Live runs and step trees are Node.js-only today. Full guide: [reportforge.org/docs/python](https://reportforge.org/docs/python).
 
 ---
 
@@ -194,7 +195,7 @@ set RF_LICENSE_KEY=RFSU-XXXX-XXXX-XXXX-XXXX
 dotnet test --logger "reportforge;output=reports/run.pdf;template=detailed"
 ```
 
-Full options come from a JSON file with the same camelCase names as this reporter: `--logger "reportforge;optionsFile=rf-options.json"`. The logger reuses the Node runtime Microsoft.Playwright places in your test output and a Playwright-managed Chromium, so there is nothing else to install. Retried tests render as flaky with their attempt history; categories become tags. Live runs and step trees are Node.js-only today. Full guide: [reportforge.org/docs/dotnet](https://reportforge.org/docs/dotnet).
+Full options come from a JSON file with the same camelCase names as this reporter: `--logger "reportforge;optionsFile=rf-options.json"`. The logger reuses the Node runtime Microsoft.Playwright places in your test output and a Playwright-managed Chromium, so there is nothing else to install. Retried tests render as flaky with their attempt history; categories become tags. Trace archives and videos attached via `TestContext.AddTestAttachment` feed the defect log's evidence links (pair with `evidenceUrlTemplate` for clickable CI links). A `dotnet test` run drives one browser, so the cross-browser comparison section stays hidden here; live runs and step trees are Node.js-only today. Full guide: [reportforge.org/docs/dotnet](https://reportforge.org/docs/dotnet).
 
 ---
 
@@ -252,10 +253,12 @@ All options are the second element of the reporter tuple.
 | `showTrend` | `boolean` | `true` | Show the pass-rate sparkline and delta badge in the `detailed` template. Set to `false` to disable history tracking entirely. |
 | `remoteHistory` | `boolean` | `false` | Opt-in server-side trend store so the pass-rate trend survives ephemeral CI runners (the local history file is wiped with the workspace, leaving the chart stuck at one data point). One small authenticated request per run carrying aggregate numbers only — no test titles, no error text, and the branch name never travels in plaintext. Falls back to the local history file on any failure. See the History docs. |
 | `flakinessTopN` | `number` | `5` | Maximum flaky tests to show in the flakiness table (`detailed` template). Set to `0` to disable the table entirely. |
+| `quarantineThreshold` | `number` | `40` | Flake-rate percentage (0-100) at which a test gets a QUARANTINE chip in the flakiness table, plus a callout with the candidate count. Applies once a test has 3+ history runs with flakiness data. Set to `0` to disable flagging. |
+| `evidenceUrlTemplate` | `string` | n/a | URL template that turns local trace/video artifact paths (from `capture.evidence`) into clickable CI links with a QR code in the defect log. Must contain `{path}`, replaced with the forward-slashed artifact path, e.g. `https://ci.example.com/job/123/artifacts/{path}`. Unset = plain paths as before. |
 | `slowTestThreshold` | `number` | `10` | Minimum timed-test count before `SLOW` badges appear in the suite breakdown: below this, every test is trivially the "slowest" so badges stay hidden. On larger runs only genuine outliers (at least 2× the median test duration) are badged, so the badge stays rare. Set to `0` to drop the run-size gate (outliers still required). |
 | `requirementTagPattern` | `string` | `'^@?[A-Z][A-Z0-9]*-\\d+$'` | Regex deciding which tags count as requirement IDs in the Requirements Traceability section (`detailed` template). Matching tags (ticket shapes like `@ODP-5328`, `REQ-001`) get the traceability matrix; everything else (`@regression`, `@sanity`) collapses into a compact tag summary instead of repeating identical rows. Set to `''` to disable the split and list every tag in the matrix. |
 | `templatePath` | `string \| string[]` | n/a | Path to a custom Handlebars (`.hbs`) template file. Takes precedence over `template`. Pass an array to generate one PDF per custom template. See the Custom Templates docs. |
-| `sections` | `object` | per-template | Override which report sections appear, on top of the chosen template's defaults. Flat keys are the baseline for every chosen template; per-template keys (`minimal`\|`detailed`\|`executive`) override per template. 20 keys total. Block toggles: `coverPage`, `analysisOneliner`, `releaseGate`, `summary`, `charts`, `trend`, `requirementsMatrix`, `ciEnvironment`, `suiteBreakdown`, `failureDeepDive`, `failureAnalysis`, `slowTests`, `defectLog`, `briefBand`, `runDiff`. Display modifiers: `passRate`, `fullEnvironment`, `retries`, `fullFailures`, `stackTraces`. `runDiff` (block toggle, on by default in all three templates) shows new failures, fixed tests, and still-failing tests compared with the previous run on the same branch. See the Report Sections docs. |
+| `sections` | `object` | per-template | Override which report sections appear, on top of the chosen template's defaults. Flat keys are the baseline for every chosen template; per-template keys (`minimal`\|`detailed`\|`executive`) override per template. 21 keys total. Block toggles: `coverPage`, `analysisOneliner`, `releaseGate`, `summary`, `charts`, `trend`, `requirementsMatrix`, `ciEnvironment`, `suiteBreakdown`, `failureDeepDive`, `failureAnalysis`, `slowTests`, `defectLog`, `briefBand`, `runDiff`, `browserMatrix`. Display modifiers: `passRate`, `fullEnvironment`, `retries`, `fullFailures`, `stackTraces`. `runDiff` (block toggle, on by default in all three templates) shows new failures, fixed tests, and still-failing tests compared with the previous run on the same branch. `browserMatrix` (block toggle, on by default in `detailed`) compares per-test outcomes across the run's projects and appears only when the run has 2+ projects. See the Report Sections docs. |
 <!-- AUTOGEN:options-table END -->
 
 Full reference: [reportforge.org/docs/configuration](https://reportforge.org/docs/configuration).
@@ -408,7 +411,9 @@ Full details at [reportforge.org/docs/advanced/security](https://reportforge.org
 
 After each run the reporter appends a summary entry to a local JSON file and renders a pass-rate sparkline + verdict row in the `detailed` template.
 
-**Since Last Run**: every report also gets a section (`runDiff`, on by default in all three templates) comparing the current run against the previous run on the same branch: new failures, fixed tests, and tests still failing, with the same summary line carried into Slack, Teams, Discord, and email notifications. The first run after upgrading has no comparable prior run to diff against, so the section starts appearing from the second run onward. It reads only the local history file, so test names never leave your machine; see the ephemeral-CI note below for keeping that file around between runs. Like the flakiness table, it rides history tracking (`showTrend`, on by default), and the notification line follows history availability rather than the `runDiff` section toggle.
+**Flaky intelligence**: the flakiness table (`detailed` template) flags quarantine candidates — tests whose flake rate reaches `quarantineThreshold` (default 40%) across 3+ recorded runs get a QUARANTINE chip and a callout with the candidate count, and every row shows its current streak (consecutive latest runs flaky). Set `quarantineThreshold: 0` to turn flagging off.
+
+**Since Last Run**: every report also gets a section (`runDiff`, on by default in all three templates) comparing the current run against the previous run on the same branch: new failures, newly flaky tests, fixed tests, and tests still failing, with the same summary line carried into Slack, Teams, Discord, and email notifications. The first run after upgrading has no comparable prior run to diff against, so the section starts appearing from the second run onward. It reads only the local history file, so test names never leave your machine; see the ephemeral-CI note below for keeping that file around between runs. Like the flakiness table, it rides history tracking (`showTrend`, on by default), and the notification line follows history availability rather than the `runDiff` section toggle.
 
 **Local dev (zero config)**: history is written automatically to `~/.reportforge/{projectKey}/history.json`. The sparkline appears once two or more runs have been recorded.
 
@@ -542,6 +547,8 @@ reporter: [['@reportforge/playwright-pdf', {
 | `slowTests` | `SLOW` badge on the duration-ranked slowest tests, shown inline in the breakdown |
 | `defectLog` | `DEF-####` numbered failure table (severity, duration) + opt-in repro detail (`capture`) |
 | `briefBand` | Executive brief band: one plain-language sentence (trend delta + root causes) and a hero pass-rate stat |
+| `runDiff` | Since Last Run: new failures, fixed tests, and still-failing tests vs. the previous run on the same branch |
+| `browserMatrix` | Cross-browser comparison: per-test outcomes side by side across the run's projects — divergent tests first, identical ones collapsed to a count. Appears only when the run has 2+ projects |
 
 #### Display modifiers: tune a section that's on
 
@@ -573,6 +580,8 @@ Omit `sections` entirely and each template renders exactly this (✓ = on):
 | `slowTests` | – | ✓ | ✓ |
 | `defectLog` | – | ✓ | – |
 | `briefBand` | – | – | ✓ |
+| `runDiff` | ✓ | ✓ | ✓ |
+| `browserMatrix` | – | ✓ | – |
 | `passRate` | ✓ | ✓ | ✓ |
 | `fullEnvironment` | – | ✓ | – |
 | `retries` | ✓ | ✓ | – |
@@ -583,7 +592,7 @@ Omit `sections` entirely and each template renders exactly this (✓ = on):
 
 - **`trend` needs `charts`.** The trend line, run-history, and flakiness table live inside the charts block, so `trend: true` does nothing with `charts: false` (it's coerced off). It also needs history data; keep the top-level `showTrend` option on.
 - **Inline failure detail needs `suiteBreakdown`.** `failureDeepDive` (failure detail), `failureAnalysis` (root-cause chip), and `slowTests` (`SLOW` badge) now render *inside* the suite breakdown, so they show nothing when `suiteBreakdown` is off. The chip (`failureAnalysis`) also needs `failureDeepDive`: it lives inside the failure detail, so it's coerced off without it.
-- **Data-gated sections**: `failureAnalysis`, `requirementsMatrix`, `slowTests`, `defectLog` render only when there's matching data (classified failures, tagged tests, a meaningful slow set, failures). Toggling them on with no data shows nothing.
+- **Data-gated sections**: `failureAnalysis`, `requirementsMatrix`, `slowTests`, `defectLog` render only when there's matching data (classified failures, tagged tests, a meaningful slow set, failures). Toggling them on with no data shows nothing. `browserMatrix` is data-gated too: it needs 2+ projects in the run (multiple Playwright projects, or `pytest --browser` given twice), so single-browser runs never show it.
 - **Render-layer only.** `sections` controls what's drawn, never what's collected; the data switches stay separate: `showTrend` (history), `flakinessTopN` (flaky-table size), `failureAnalysis.enabled` (classifier), `includeScreenshots` (images).
 - **Custom templates.** `sections` applies to the built-in templates; a custom `templatePath` controls its own layout (every section available) and ignores `sections`. You'll get a warning if both are set.
 

package/dist/cli/index.js

@@ -293,20 +293,26 @@ function buildDemoCharts(passed, failed, skipped, flaky, total) {
       delta: 71 - 76
       // -5 vs previous run
     },
+    flakinessQuarantineTotal: 1,
+    flakinessQuarantineThreshold: 40,
     flakinessTable: [
       {
         title: "should handle session timeout gracefully",
         flakeRate: 60,
         flakeCount: 3,
         totalRuns: 5,
-        sparkline: [true, false, true, false, true]
+        sparkline: [true, false, true, false, true],
+        streak: 1,
+        quarantine: true
       },
       {
         title: "should apply valid promo code",
         flakeRate: 20,
         flakeCount: 1,
         totalRuns: 5,
-        sparkline: [false, false, false, true, false]
+        sparkline: [false, false, false, true, false],
+        streak: 0,
+        quarantine: false
       }
     ]
   };
@@ -320,6 +326,9 @@ function buildDemoRunDiff() {
     stillFailing: [
       { id: "co-3", title: "should reject expired promo code" }
     ],
+    newlyFlaky: [
+      { id: "auth-4", title: "should handle session timeout gracefully" }
+    ],
     fixed: [
       { id: "co-5", title: "should complete Stripe checkout" }
     ],
@@ -6381,6 +6390,7 @@ var init_defaults = __esm({
       historySize: 10,
       showTrend: true,
       flakinessTopN: 5,
+      quarantineThreshold: 40,
       slowTestThreshold: 10,
       // Ticket-ID shape: @ODP-5328, REQ-001, JIRA-123. Tags matching this land in
       // the Requirements Traceability matrix; the rest fall to the tag summary.
@@ -6518,6 +6528,7 @@ var init_sections = __esm({
       "defectLog",
       "briefBand",
       "runDiff",
+      "browserMatrix",
       // display modifiers
       "passRate",
       "fullEnvironment",
@@ -6542,6 +6553,7 @@ var init_sections = __esm({
         defectLog: false,
         briefBand: false,
         runDiff: true,
+        browserMatrix: false,
         passRate: true,
         fullEnvironment: false,
         retries: true,
@@ -6564,6 +6576,7 @@ var init_sections = __esm({
         defectLog: true,
         briefBand: false,
         runDiff: true,
+        browserMatrix: true,
         passRate: true,
         fullEnvironment: true,
         retries: true,
@@ -6591,6 +6604,7 @@ var init_sections = __esm({
         defectLog: false,
         briefBand: true,
         runDiff: true,
+        browserMatrix: false,
         passRate: true,
         fullEnvironment: false,
         retries: false,
@@ -12246,6 +12260,10 @@ var init_schema = __esm({
       // local history file is wiped every run. Aggregate numbers only.
       remoteHistory: external_exports.boolean().default(false),
       flakinessTopN: external_exports.number().int().min(0, "flakinessTopN must be 0 or greater").optional().default(DEFAULT_OPTIONS.flakinessTopN),
+      quarantineThreshold: external_exports.number().int().min(0, "quarantineThreshold must be between 0 and 100").max(100, "quarantineThreshold must be between 0 and 100").optional().default(DEFAULT_OPTIONS.quarantineThreshold),
+      evidenceUrlTemplate: external_exports.string().refine((s) => s.includes("{path}"), {
+        message: "evidenceUrlTemplate must contain the {path} token"
+      }).optional(),
       slowTestThreshold: external_exports.number().int().min(0, "slowTestThreshold must be 0 or greater").optional().default(DEFAULT_OPTIONS.slowTestThreshold),
       requirementTagPattern: external_exports.string().refine((v) => {
         try {

package/dist/index.d.mts

@@ -1,11 +1,11 @@
 import { Reporter, FullConfig, Suite, TestCase, TestResult, TestStep, FullResult } from '@playwright/test/reporter';
 
 /**
- * Canonical section catalog. 15 block toggles (section present/absent) followed
+ * Canonical section catalog. 16 block toggles (section present/absent) followed
  * by 5 display modifiers (tweak a section that is on). Single source of truth —
  * the Zod schema in src/config/schema.ts builds its flag shape from this array.
  */
-declare const SECTION_KEYS: readonly ["coverPage", "analysisOneliner", "releaseGate", "summary", "charts", "trend", "requirementsMatrix", "ciEnvironment", "suiteBreakdown", "failureDeepDive", "failureAnalysis", "slowTests", "defectLog", "briefBand", "runDiff", "passRate", "fullEnvironment", "retries", "fullFailures", "stackTraces"];
+declare const SECTION_KEYS: readonly ["coverPage", "analysisOneliner", "releaseGate", "summary", "charts", "trend", "requirementsMatrix", "ciEnvironment", "suiteBreakdown", "failureDeepDive", "failureAnalysis", "slowTests", "defectLog", "briefBand", "runDiff", "browserMatrix", "passRate", "fullEnvironment", "retries", "fullFailures", "stackTraces"];
 type SectionKey = (typeof SECTION_KEYS)[number];
 /** A partial map of section flags — used both as the flat baseline and per-template. */
 type SectionFlags = Partial<Record<SectionKey, boolean>>;
@@ -368,6 +368,24 @@ interface ReporterOptions {
      * @default 5
      */
     flakinessTopN?: number;
+    /**
+     * Flake-rate percentage (0-100) at which a test is flagged as a quarantine
+     * candidate in the flakiness table: a QUARANTINE chip on the row plus a
+     * callout with the candidate count. A test qualifies once its flake rate
+     * over the stored history reaches the threshold across at least 3 runs
+     * that carry flakiness data. Set to 0 to disable flagging.
+     * @default 40
+     */
+    quarantineThreshold?: number;
+    /**
+     * URL template that turns local trace/video artifact paths (surfaced by
+     * `capture.evidence`) into clickable CI links with a QR code in the defect
+     * log. Must contain the `{path}` token, replaced with the forward-slashed
+     * artifact path (each segment percent-encoded), e.g.
+     * `https://ci.example.com/job/123/artifacts/{path}`.
+     * Unset = evidence renders as plain paths, exactly as before.
+     */
+    evidenceUrlTemplate?: string;
     /**
      * Minimum number of timed tests before `SLOW` badges appear in the suite
      * breakdown — below this, every test is trivially the "slowest", so badges
@@ -406,18 +424,22 @@ interface ReporterOptions {
      * every chosen template; per-template keys (`minimal` / `detailed` /
      * `executive`) override the baseline for that template only.
      *
-     * 20 keys total: 15 block toggles, 5 display modifiers.
+     * 21 keys total: 16 block toggles, 5 display modifiers.
      *
      * Block toggles: `coverPage`, `analysisOneliner`, `releaseGate`, `summary`,
      * `charts`, `trend`, `requirementsMatrix`, `ciEnvironment`, `suiteBreakdown`,
      * `failureDeepDive`, `failureAnalysis`, `slowTests`, `defectLog`, `briefBand`,
-     * `runDiff`.
+     * `runDiff`, `browserMatrix`.
      * Display modifiers: `passRate`, `fullEnvironment`, `retries`, `fullFailures`,
      * `stackTraces`.
      *
      * `runDiff` shows new failures, fixed tests, and still-failing tests against
      * the previous run on the same branch; on by default in all three templates.
      *
+     * `browserMatrix` compares per-test outcomes across the run's projects
+     * (divergent tests first, identical ones collapsed to a count); on by default
+     * in `detailed` and self-hides when the run has fewer than two projects.
+     *
      * `trend` renders only when `charts` is also on and history data exists (`showTrend` enabled). Sections gated on data
      * (`failureAnalysis`, `requirementsMatrix`, `slowTests`, `defectLog`) appear
      * only when matching data exists — this option never changes data collection.

package/dist/index.d.ts

@@ -1,11 +1,11 @@
 import { Reporter, FullConfig, Suite, TestCase, TestResult, TestStep, FullResult } from '@playwright/test/reporter';
 
 /**
- * Canonical section catalog. 15 block toggles (section present/absent) followed
+ * Canonical section catalog. 16 block toggles (section present/absent) followed
  * by 5 display modifiers (tweak a section that is on). Single source of truth —
  * the Zod schema in src/config/schema.ts builds its flag shape from this array.
  */
-declare const SECTION_KEYS: readonly ["coverPage", "analysisOneliner", "releaseGate", "summary", "charts", "trend", "requirementsMatrix", "ciEnvironment", "suiteBreakdown", "failureDeepDive", "failureAnalysis", "slowTests", "defectLog", "briefBand", "runDiff", "passRate", "fullEnvironment", "retries", "fullFailures", "stackTraces"];
+declare const SECTION_KEYS: readonly ["coverPage", "analysisOneliner", "releaseGate", "summary", "charts", "trend", "requirementsMatrix", "ciEnvironment", "suiteBreakdown", "failureDeepDive", "failureAnalysis", "slowTests", "defectLog", "briefBand", "runDiff", "browserMatrix", "passRate", "fullEnvironment", "retries", "fullFailures", "stackTraces"];
 type SectionKey = (typeof SECTION_KEYS)[number];
 /** A partial map of section flags — used both as the flat baseline and per-template. */
 type SectionFlags = Partial<Record<SectionKey, boolean>>;
@@ -368,6 +368,24 @@ interface ReporterOptions {
      * @default 5
      */
     flakinessTopN?: number;
+    /**
+     * Flake-rate percentage (0-100) at which a test is flagged as a quarantine
+     * candidate in the flakiness table: a QUARANTINE chip on the row plus a
+     * callout with the candidate count. A test qualifies once its flake rate
+     * over the stored history reaches the threshold across at least 3 runs
+     * that carry flakiness data. Set to 0 to disable flagging.
+     * @default 40
+     */
+    quarantineThreshold?: number;
+    /**
+     * URL template that turns local trace/video artifact paths (surfaced by
+     * `capture.evidence`) into clickable CI links with a QR code in the defect
+     * log. Must contain the `{path}` token, replaced with the forward-slashed
+     * artifact path (each segment percent-encoded), e.g.
+     * `https://ci.example.com/job/123/artifacts/{path}`.
+     * Unset = evidence renders as plain paths, exactly as before.
+     */
+    evidenceUrlTemplate?: string;
     /**
      * Minimum number of timed tests before `SLOW` badges appear in the suite
      * breakdown — below this, every test is trivially the "slowest", so badges
@@ -406,18 +424,22 @@ interface ReporterOptions {
      * every chosen template; per-template keys (`minimal` / `detailed` /
      * `executive`) override the baseline for that template only.
      *
-     * 20 keys total: 15 block toggles, 5 display modifiers.
+     * 21 keys total: 16 block toggles, 5 display modifiers.
      *
      * Block toggles: `coverPage`, `analysisOneliner`, `releaseGate`, `summary`,
      * `charts`, `trend`, `requirementsMatrix`, `ciEnvironment`, `suiteBreakdown`,
      * `failureDeepDive`, `failureAnalysis`, `slowTests`, `defectLog`, `briefBand`,
-     * `runDiff`.
+     * `runDiff`, `browserMatrix`.
      * Display modifiers: `passRate`, `fullEnvironment`, `retries`, `fullFailures`,
      * `stackTraces`.
      *
      * `runDiff` shows new failures, fixed tests, and still-failing tests against
      * the previous run on the same branch; on by default in all three templates.
      *
+     * `browserMatrix` compares per-test outcomes across the run's projects
+     * (divergent tests first, identical ones collapsed to a count); on by default
+     * in `detailed` and self-hides when the run has fewer than two projects.
+     *
      * `trend` renders only when `charts` is also on and history data exists (`showTrend` enabled). Sections gated on data
      * (`failureAnalysis`, `requirementsMatrix`, `slowTests`, `defectLog`) appear
      * only when matching data exists — this option never changes data collection.