@reportforge/playwright-pdf 0.12.0 → 0.13.1

package/README.md

@@ -1,6 +1,6 @@
 # @reportforge/playwright-pdf
 
-> Playwright PDF reporter — generate branded PDF reports from [Playwright Test](https://playwright.dev/) results. Three templates (minimal, detailed, executive) for developers, QA teams, and stakeholders. CI-ready, self-contained, with embedded screenshots and charts.
+> Playwright PDF reporter: generate branded PDF reports from [Playwright Test](https://playwright.dev/) results. Three templates (minimal, detailed, executive) for developers, QA teams, and stakeholders. CI-ready, self-contained, with embedded screenshots and charts.
 
 Drop it into any Playwright project and get a PDF report on every CI run. No changes to your tests.
 
@@ -21,7 +21,7 @@ Drop it into any Playwright project and get a PDF report on every CI run. No cha
 
 ## Report Gallery
 
-Three templates, one reporter. Every PDF is fully offline — fonts, charts, and screenshots are embedded.
+Three templates, one reporter. Every PDF is fully offline: fonts, charts, and screenshots are embedded.
 
 <table>
   <tr>
@@ -45,23 +45,23 @@ Three templates, one reporter. Every PDF is fully offline — fonts, charts, and
 
 ## Features
 
-- **3 templates** — `minimal` (developer), `detailed` (QA team), `executive` (stakeholders)
-- **Detailed reports** — KPI dashboard, suite breakdown with inline failure detail (error, screenshot, root-cause chip) under each failed test, CI/CD environment
-- **Embedded Chart.js** — pass-rate doughnut + per-suite bar chart, bundled inline (no CDN)
-- **Self-contained PDFs** — screenshots, fonts, logos all embedded; share or archive with confidence
-- **Custom branding** — logo, primary/accent colours, watermark, PDF password encryption
-- **Dynamic filenames** — `{date}`, `{branch}`, `{status}` tokens in the output path
-- **Instant demo report** — `npx @reportforge/playwright-pdf demo` generates a realistic sample PDF before subscribing — no license key required
-- **CI/CD snippets** — GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins, Azure DevOps
-- **Live runs** — opt-in `live` streams per-test progress to an unguessable watch link printed at run start; all shards of one CI run converge on a single live dashboard while tests execute. The PDF is still produced at the end, unchanged
-- **Shard merging** — combine N Playwright JSON shard reports into one PDF via `shardResults`; accepts glob patterns or explicit paths
-- **Notifications** — post pass/fail summaries to Slack, Teams, Discord, or email after each run; configurable trigger (`always` / `failure` / `success`) per channel; email supports optional PDF attachment via `attachPdf`
-- **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)
-- **Offline failure analysis** — sorts each failure into one of 7 root-cause buckets and renders a per-test root-cause chip inline under the failed test in the `detailed` PDF (dominant-cause one-liner in `executive`). No network, no AI service — a small embedded classifier that updates itself safely over your existing license refresh; pin it any time. Full details at [reportforge.org/docs/advanced/failure-analysis](https://reportforge.org/docs/advanced/failure-analysis).
-- `npx @reportforge/playwright-pdf export-feedback` — exports locally-collected unrecognized failures (tokenized, local-only) for optional manual sharing.
-- **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 action 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.
-- **Configurable sections** — add or remove any report section per template via `sections`.
-- **Hybrid licensing** — one short key unlocks it; reports keep rendering offline via a cached JWT between refreshes
+- **3 templates**: `minimal` (developer), `detailed` (QA team), `executive` (stakeholders)
+- **Detailed reports**: KPI dashboard, suite breakdown with inline failure detail (error, screenshot, root-cause chip) under each failed test, CI/CD environment
+- **Embedded Chart.js**: pass-rate doughnut + per-suite bar chart, bundled inline (no CDN)
+- **Self-contained PDFs**: screenshots, fonts, logos all embedded; share or archive with confidence
+- **Custom branding**: logo, primary/accent colours, watermark, PDF password encryption
+- **Dynamic filenames**: `{date}`, `{branch}`, `{status}` tokens in the output path
+- **Instant demo report**: `npx @reportforge/playwright-pdf demo` generates a realistic sample PDF before subscribing, no license key required
+- **CI/CD snippets**: GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins, Azure DevOps
+- **Live runs**: opt-in `live` streams per-test progress to an unguessable watch link printed at run start; all shards of one CI run converge on a single live dashboard while tests execute. The PDF is still produced at the end, unchanged
+- **Shard merging**: combine N Playwright JSON shard reports into one PDF via `shardResults`; accepts glob patterns or explicit paths
+- **Notifications**: post pass/fail summaries to Slack, Teams, Discord, or email after each run; configurable trigger (`always` / `failure` / `success`) per channel; email and Discord support optional PDF attachment via `attachPdf`
+- **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)
+- **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 that updates over your existing license refresh; pin it any time. Full details at [reportforge.org/docs/advanced/failure-analysis](https://reportforge.org/docs/advanced/failure-analysis).
+- `npx @reportforge/playwright-pdf export-feedback`: exports locally-collected unrecognized failures (tokenized, local-only) for optional manual sharing.
+- **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.
+- **Configurable sections**: add or remove any report section per template via `sections`.
+- **Hybrid licensing**: one short key unlocks it; reports keep rendering offline via a cached JWT between refreshes
 
 ---
 
@@ -87,16 +87,16 @@ export default defineConfig({
 });
 ```
 
-`defineReporterConfig` is an optional typed identity helper — it gives you IntelliSense and type-checking on the options object without a separate `ReporterOptions` import. You can also pass a plain object literal if you prefer.
+`defineReporterConfig` is an optional typed identity helper: it gives you IntelliSense and type-checking on the options object without a separate `ReporterOptions` import. You can also pass a plain object literal if you prefer.
 
 ```bash
 npx playwright test
 # → reports/2026-05-01-main-failed.pdf
 ```
 
-> **See it first.** Run `npx @reportforge/playwright-pdf demo` to generate a realistic sample PDF in under 60 seconds — no license key required. Supports `--template=minimal|detailed|executive` and `--output=<path>`.
+> **See it first.** Run `npx @reportforge/playwright-pdf demo` to generate a realistic sample PDF in under 60 seconds, no license key required. Supports `--template=minimal|detailed|executive` and `--output=<path>`.
 
-> **License required.** Start a **[7-day free trial at reportforge.org/pricing](https://reportforge.org/pricing)** — card required, no charge until day 8. Paste the resulting `RFSU-…` key into `RF_LICENSE_KEY`. Without a valid license the reporter logs a warning and skips PDF generation; your Playwright tests still run normally.
+> **License required.** Start a **[7-day free trial at reportforge.org/pricing](https://reportforge.org/pricing)**: card required, no charge until day 8. Paste the resulting `RFSU-…` key into `RF_LICENSE_KEY`. Without a valid license the reporter logs a warning and skips PDF generation; your Playwright tests still run normally.
 
 ---
 
@@ -132,7 +132,7 @@ sudo apt-get update -qq && sudo apt-get install -y google-chrome-stable
 export PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome-stable
 ```
 
-> **Note:** Do not use the `chromium-browser` apt package — it installs as a snap on Ubuntu and Puppeteer cannot drive it.
+> **Note:** Do not use the `chromium-browser` apt package: it installs as a snap on Ubuntu and Puppeteer cannot drive it.
 
 **macOS**
 
@@ -173,37 +173,37 @@ Currency is auto-detected by region; toggle on the pricing page.
 
 All options are the second element of the reporter tuple.
 
-<!-- AUTOGEN:options-table START — edit scripts/docs/options-meta.ts, then run npm run docs:gen -->
+<!-- AUTOGEN:options-table START: edit scripts/docs/options-meta.ts, then run npm run docs:gen -->
 | Option | Type | Default | Description |
 |---|---|---|---|
 | `outputFile` | `string` | `'playwright-report/{date}-report.pdf'` | Output path. Supports tokens: `{date}`, `{datetime}`, `{branch}`, `{status}`, `{total}`, `{passed}`, `{failed}`, `{project}`. Directory is created if absent. |
-| `template` | `'minimal' \| 'detailed' \| 'executive'` or array | `'minimal'` | Template(s) to generate. Pass an array to produce one PDF per template in one run — the template name is appended to each output filename automatically (e.g. `report-detailed.pdf`). |
+| `template` | `'minimal' \| 'detailed' \| 'executive'` or array | `'minimal'` | Template(s) to generate. Pass an array to produce one PDF per template in one run: the template name is appended to each output filename automatically (e.g. `report-detailed.pdf`). |
 | `licenseKey` | `string` | env `RF_LICENSE_KEY` | Subscription key (format `RFSU-…`). Falls back to the `RF_LICENSE_KEY` environment variable. PDF generation is skipped when absent or invalid. |
-| `logo` | `string` | — | Path to a logo image (PNG, JPG, or SVG) to embed in the report header. Supports absolute and relative paths. |
+| `logo` | `string` | n/a | Path to a logo image (PNG, JPG, or SVG) to embed in the report header. Supports absolute and relative paths. |
 | `primaryColor` | `string` | `'#CC785C'` | Primary brand colour (3-, 6-, or 8-digit hex). Used for headers and accent bars. |
 | `accentColor` | `string` | `'#3F7D58'` | Accent brand colour (hex). Used for highlights and badges. |
-| `watermark` | `string` | — | Text to render as a diagonal watermark overlay on every page — e.g. `'CONFIDENTIAL'`, `'DRAFT'`. |
-| `pdfPassword` | `string` | — | Password-protect the generated PDF. Requires `qpdf` installed on the system. |
+| `watermark` | `string` | n/a | Text to render as a diagonal watermark overlay on every page, e.g. `'CONFIDENTIAL'` or `'DRAFT'`. |
+| `pdfPassword` | `string` | n/a | Password-protect the generated PDF. Requires `qpdf` installed on the system. |
 | `reportTitle` | `string` | `'Playwright Test Report'` | Custom title for the report cover page and running header. |
 | `projectName` | `string` | from `package.json` | Project or application name. Inferred from the `package.json` `name` field if absent. |
-| `open` | `boolean` | `false` | Open the generated PDF automatically after generation. For local use only — ignored in CI. |
+| `open` | `boolean` | `false` | Open the generated PDF automatically after generation. For local use only; ignored in CI. |
 | `puppeteerExecutablePath` | `string` | auto-detect | Full path to a Chrome or Chromium binary. Falls back to `PUPPETEER_EXECUTABLE_PATH` env, then system Chrome discovery. |
 | `serverUrl` | `string` | `'https://reportforge.org'` | Base URL for the ReportForge licensing server. Override only for self-hosting or local development. |
 | `compressionLevel` | `'auto' \| 'none' \| 'balanced' \| 'max'` | `'auto'` | Screenshot JPEG quality preset. `'auto'` picks based on failure volume; `'none'` keeps original PNGs; `'balanced'` uses JPEG q85; `'max'` uses JPEG q70. |
-| `includeScreenshots` | `boolean` | `true` | Embed Playwright screenshots in the PDF. Set to `false` to omit images — useful for exec-audience reports or reducing file size. |
+| `includeScreenshots` | `boolean` | `true` | Embed Playwright screenshots in the PDF. Set to `false` to omit images; useful for exec-audience reports or reducing file size. |
 | `maxInlineFailures` | `number` | derived from `compressionLevel` | Cap on failure entries rendered inline in the PDF. Overflow is written to a sibling `{basename}-failures.json` sidecar file. |
 | `maxFileSizeMb` | `number` | `8` | Soft cap on the final PDF size in MB. If exceeded, the report is re-rendered once with the `'max'` compression preset. |
-| `shardResults` | `string \| string[]` | — | Glob or path array of Playwright JSON shard report files to merge into one PDF. See the Shard Merging docs. |
-| `notify` | `object` | — | Notification channels: `slack`, `teams`, `discord` (each `{ url, enabled, on }`), `email` (`{ to, enabled, on, attachPdf }`). See the Notifications docs. |
+| `shardResults` | `string \| string[]` | n/a | Glob or path array of Playwright JSON shard report files to merge into one PDF. See the Shard Merging docs. |
+| `notify` | `object` | n/a | Notification channels: `slack`, `teams` (each `{ url, enabled, on }`), `discord` (`{ url, enabled, on, attachPdf }`), `email` (`{ to, enabled, on, attachPdf }`). See the Notifications docs. |
 | `failureAnalysis` | `object` | `{ enabled: true }` | Offline failure root-cause analysis (embedded Naive Bayes; no runtime network). Fields: `enabled` (default `true`), `maxClusters` (default `10`), `minStrength` (`weak`\|`moderate`\|`strong`, default `weak`), `maxFailuresToAnalyse` (default `500`), `collectUnclassified` (default `true`), `autoUpdateModel` (default `true`). See the Failure Analysis docs. |
-| `capture` | `object` | `{}` (off) | Opt-in rich execution capture for the defect log (reporter-side; no fixtures, no test-code changes). Fields: `steps` (a copy-pasteable "Steps to Reproduce" outline built from the Playwright step tree — each row a Markdown list line indented under its parent `test.step`, default `false`), `apiSteps` (include every top-level `pw:api` action (click/fill/check/goto) in the outline for a full action trail; off by default the outline shows only `test.step` intent + `expect` assertions, default `false`), `console` (Node stdout/stderr tail, default `false`), `evidence` (trace/video file links, default `false`), `maxSteps` (default `50`), `maxConsoleLines` (default `50`). Renders in the Defect Log section of the `detailed` template. |
-| `live` | `object` | `{}` (off) | Opt-in live test-execution streaming. When `enabled`, the reporter prints an unguessable watch link to the CI logs at run start and streams per-test progress to the hosted dashboard while tests run — all shards of one CI run converge on a single live view. Fields: `enabled` (default `false`), `runId` (override the auto-derived run id), `serverUrl` (override the streaming server), `steps` (`none`\|`failed`\|`intent`\|`all`, default `failed`; `intent` shows only your `test.step` names plus any failing step), `console` (stream stdout/stderr tails, default `false`), `flushMs` (batch debounce 500–10000, default `2000`). The PDF at the end of the run is unaffected. Requires an active subscription with the `live` entitlement. See the Live Runs docs. |
+| `capture` | `object` | `{}` (off) | Opt-in rich execution capture for the defect log (reporter-side; no fixtures, no test-code changes). Fields: `steps` (a copy-pasteable "Steps to Reproduce" outline built from the Playwright step tree; each row is a Markdown list line indented under its parent `test.step`, default `false`), `apiSteps` (include every top-level `pw:api` action (click/fill/check/goto) in the outline for a full action trail; without it the outline shows only `test.step` intent + `expect` assertions, default `false`), `console` (Node stdout/stderr tail, default `false`), `evidence` (trace/video file links, default `false`), `maxSteps` (default `50`), `maxConsoleLines` (default `50`). Renders in the Defect Log section of the `detailed` template. |
+| `live` | `object` | `{}` (off) | Opt-in live test-execution streaming. When `enabled`, the reporter prints an unguessable watch link to the CI logs at run start and streams per-test progress to the hosted dashboard while tests run; all shards of one CI run converge on a single live view. Fields: `enabled` (default `false`), `runId` (override the auto-derived run id), `serverUrl` (override the streaming server), `steps` (`none`\|`failed`\|`intent`\|`all`, default `failed`; `intent` shows only your `test.step` names plus any failing step), `console` (stream stdout/stderr tails, default `false`), `flushMs` (batch debounce 500–10000, default `2000`). The PDF at the end of the run is unaffected. Requires an active subscription with the `live` entitlement. See the Live Runs docs. |
 | `historyFile` | `string` | `~/.reportforge/{key}/history.json` | Path to the history JSON file. Relative paths resolve from `cwd`. Enables pass-rate trending charts in the `detailed` template. |
 | `historySize` | `number` | `10` | Maximum number of test runs to keep in the history file (integer ≥ 2). Older runs are pruned on append. |
 | `showTrend` | `boolean` | `true` | Show the pass-rate sparkline and delta badge in the `detailed` template. Set to `false` to disable history tracking entirely. |
 | `flakinessTopN` | `number` | `5` | Maximum flaky tests to show in the flakiness table (`detailed` template). Set to `0` to disable the table entirely. |
-| `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). |
-| `templatePath` | `string \| string[]` | — | 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. |
+| `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). |
+| `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. Block toggles: `coverPage`, `analysisOneliner`, `releaseGate`, `summary`, `charts`, `trend`, `requirementsMatrix`, `ciEnvironment`, `suiteBreakdown`, `failureDeepDive`, `failureAnalysis`, `slowTests`, `defectLog`. Display modifiers: `passRate`, `fullEnvironment`, `retries`, `fullFailures`, `stackTraces`. See the Report Sections docs. |
 <!-- AUTOGEN:options-table END -->
 
@@ -211,9 +211,9 @@ Full reference: [reportforge.org/docs/configuration](https://reportforge.org/doc
 
 ### Live Runs
 
-Watch a run as it happens. With `live` enabled, the reporter prints an unguessable watch link — boxed under a `Live Tracker` heading — to your CI logs at run start and streams per-test progress to a hosted dashboard while tests execute. All shards of one CI run converge on a single live view, each test shows its own steps and assertions as sub-lines beneath its row — each step once, as it settles, indented under its parent `test.step` and read in source order (Playwright's hooks, fixtures, and teardown are filtered out) — and the PDF is still generated at the end, unchanged.
+Watch a run as it happens. With `live` enabled, the reporter prints an unguessable watch link (boxed under a `Live Tracker` heading) to your CI logs at run start and streams per-test progress to a hosted dashboard while tests execute. All shards of one CI run converge on a single live view. Each test shows its steps and assertions as sub-lines beneath its row: each step once, as it settles, indented under its parent `test.step` in source order (Playwright's hooks, fixtures, and teardown are filtered out). The PDF is still generated at the end, unchanged.
 
-> The watch link is entitlement-gated. If you enable `live` but see no `Live Tracker` line, the reporter logs why (missing `RF_LICENSE_KEY`, or a cached token without the `live` entitlement — delete `~/.reportforge/license.json` to force re-activation).
+> The watch link is entitlement-gated. If you enable `live` but see no `Live Tracker` line, the reporter logs why (missing `RF_LICENSE_KEY`, or a cached token without the `live` entitlement; delete `~/.reportforge/license.json` to force re-activation).
 
 ```typescript
 // playwright.config.ts
@@ -223,20 +223,20 @@ reporter: [
     live: {
       enabled: true,
       steps: 'failed',   // 'none' | 'failed' | 'intent' | 'all'
-      // console: false,  // stream stdout/stderr tails (off by default — see note)
+      // console: false,  // stream stdout/stderr tails (off by default; see note)
       // flushMs: 2000,   // batch debounce (500–10000)
     },
   }],
 ],
 ```
 
-`steps: 'intent'` shows only your `test.step` names (plus any failing step) — the cleanest, most readable trail; `'all'` adds every action and assertion beneath its parent step, `'failed'` (default) keeps intent + assertions + failures.
+`steps: 'intent'` shows only your `test.step` names (plus any failing step): the cleanest, most readable trail. `'all'` adds every action and assertion beneath its parent step; `'failed'` (default) keeps intent + assertions + failures.
 
-Sharded runs need no extra config — the run id is derived from the run-shared CI identifier (e.g. `GITHUB_RUN_ID`), identical across every matrix shard. Set `RF_LIVE_RUN_ID` to override when your CI is not auto-detected.
+Sharded runs need no extra config: the run id is derived from the run-shared CI identifier (e.g. `GITHUB_RUN_ID`), identical across every matrix shard. Set `RF_LIVE_RUN_ID` to override when your CI is not auto-detected.
 
 Live streaming is best-effort and entitlement-gated: if the server is unreachable the run is unaffected, and an active subscription with the `live` feature is required. If you've configured Slack/Teams/Discord notifications, the watch link is also posted to those channels when the run starts.
 
-> **Security:** the watch link exposes test titles + statuses (and step titles when `steps` is on). Leaving `console: false` is recommended — enabling it streams your tests' stdout/stderr to anyone holding the link. Full details at [reportforge.org/docs/advanced/live](https://reportforge.org/docs/advanced/live).
+> **Security:** the watch link exposes test titles + statuses (and step titles when `steps` is on). Leaving `console: false` is recommended: enabling it streams your tests' stdout/stderr to anyone holding the link. Full details at [reportforge.org/docs/advanced/live](https://reportforge.org/docs/advanced/live).
 
 ### Shard Merging
 
@@ -245,7 +245,7 @@ Combine parallel Playwright shards into one PDF without re-running any tests.
 **Workflow:**
 
 1. Run each shard with `--reporter=json` to produce a JSON output file.
-2. In a separate step, point `shardResults` at those files — accepts a glob or an explicit array.
+2. In a separate step, point `shardResults` at those files; it accepts a glob or an explicit array.
 
 ```typescript
 // playwright.config.ts (merge step)
@@ -258,7 +258,7 @@ reporter: [
 ],
 ```
 
-The merge step can run against a dummy test file with zero tests — `shardResults` takes precedence over live results.
+The merge step can run against a dummy test file with zero tests: `shardResults` takes precedence over live results.
 
 > **Note:** Timed-out tests are counted as failures in shard mode (Playwright JSON stats do not distinguish `timedOut` from `failed`).
 
@@ -282,6 +282,7 @@ notify: {
     url: process.env.DISCORD_WEBHOOK_URL,
     enabled: true,
     on: 'failure',
+    attachPdf: true,             // upload the PDF with the message (default: false)
   },
   email: {
     to: ['team@company.com', 'qa@company.com'],
@@ -292,7 +293,7 @@ notify: {
 },
 ```
 
-Each channel is independent. `enabled: false` (the default) lets you store a URL without activating it — useful for staging configs.
+Each channel is independent. `enabled: false` (the default) lets you store a URL without activating it; useful for staging configs.
 
 The `on` trigger controls when the message fires:
 
@@ -302,17 +303,19 @@ The `on` trigger controls when the message fires:
 | `'failure'` | `stats.failed > 0` or run timed out / interrupted |
 | `'success'` | All tests passed |
 
-**Email** requires `RESEND_API_KEY` in the environment (get one at [resend.com](https://resend.com)). Sender defaults to `noreply@reportforge.org`; override with `RESEND_FROM`. Store webhook URLs and API keys as CI secrets — never commit them.
+**Email** requires `RESEND_API_KEY` in the environment (get one at [resend.com](https://resend.com)). Sender defaults to `noreply@reportforge.org`; override with `RESEND_FROM`. Store webhook URLs and API keys as CI secrets; never commit them.
 
-The summary includes pass rate, test counts, duration, and the report filename. Notifications require a valid license and fire after PDF generation (or after a PDF failure — you still get the ping).
+**PDF attachment** (`attachPdf: true`) is available on `email` and `discord`: Slack and Teams webhooks cannot carry file uploads. On Discord the PDF is uploaded with the message; if the upload fails or the PDF exceeds Discord's file-size cap, the summary still posts without the attachment. With multiple templates, the first PDF is attached.
+
+The summary includes pass rate, test counts, duration, and the report filename. Notifications require a valid license and fire after PDF generation (or after a PDF failure; you still get the ping).
 
 ### Test History Trending
 
 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.
 
-**Local dev (zero config)** — history is written automatically to `~/.reportforge/{projectKey}/history.json`. The sparkline appears once two or more runs have been recorded.
+**Local dev (zero config)**: history is written automatically to `~/.reportforge/{projectKey}/history.json`. The sparkline appears once two or more runs have been recorded.
 
-**CI with ephemeral runners** — set `historyFile` to a project-relative path and cache it between runs:
+**CI with ephemeral runners**: set `historyFile` to a project-relative path and cache it between runs:
 
 ```typescript
 // playwright.config.ts
@@ -328,10 +331,10 @@ reporter: [['@reportforge/playwright-pdf', {
   with:
     path: .reportforge/history.json
     key: reportforge-history-${{ github.ref }}
-    # Omit restore-keys — cross-branch fallback causes misleading sparklines on PRs
+    # Omit restore-keys; cross-branch fallback causes misleading sparklines on PRs
 ```
 
-**Monorepo** — each package needs a distinct `historyFile` (e.g. `.reportforge/api-history.json`, `.reportforge/web-history.json`) so runs do not overwrite each other.
+**Monorepo**: each package needs a distinct `historyFile` (e.g. `.reportforge/api-history.json`, `.reportforge/web-history.json`) so runs do not overwrite each other.
 
 ### Flakiness Trend Table
 
@@ -340,11 +343,11 @@ The `detailed` template includes a **Top flaky tests** table showing which tests
 ```typescript
 reporter: [['@reportforge/playwright-pdf', {
   template: 'detailed',
-  flakinessTopN: 5,    // default — show top 5; set 0 to disable
+  flakinessTopN: 5,    // default: show top 5; set 0 to disable
 }]]
 ```
 
-The table is gated behind `showTrend: true` (the default) and appears automatically once history entries are present. Runs written before the flakiness feature was added are excluded from the denominator — the table fills in correctly as newer runs accumulate. Set `flakinessTopN: 0` to hide the table entirely.
+The table is gated behind `showTrend: true` (the default) and appears automatically once history entries are present. Runs written before the flakiness feature was added are excluded from the denominator; the table fills in correctly as newer runs accumulate. Set `flakinessTopN: 0` to hide the table entirely.
 
 ### Filename tokens
 
@@ -358,21 +361,21 @@ The table is gated behind `showTrend: true` (the default) and appears automatica
 
 ## Templates
 
-### `minimal` — Developer-focused
+### `minimal`: Developer-focused
 
 Clean layout, KPI numbers, hierarchical test table, failure details with stack traces and embedded screenshots. Fast to generate. Good for local development and PR checks.
 
-### `detailed` — QA Team
+### `detailed`: QA Team
 
 Everything in `minimal`, **plus** Chart.js pass-rate + suite-results charts, a numbered defect log, a requirements traceability matrix derived from `@TAG` annotations, and the full CI/CD environment table.
 
-### `executive` — Stakeholder presentations
+### `executive`: Stakeholder presentations
 
-Full-page cover with verdict + KPI strip, followed by a compact dashboard with charts and a failures summary (titles only — **no raw stack traces**). Best for sprint reports and management dashboards.
+Full-page cover with verdict + KPI strip, followed by a compact dashboard with charts and a failures summary (titles only, **no raw stack traces**). Best for sprint reports and management dashboards.
 
 ### Shared across all three
 
-Every report leads with a **release-gate** ship/hold banner derived from the run verdict, surfaces **timed-out** tests as their own KPI card and pass-rate chart slice, and lists failures **most-severe first** (with severity-coloured card borders in `minimal` and `detailed`). Pages **pack compactly** — large sections flow and break between rows instead of each starting on a fresh page. The Suite Results chart breaks a single-file run down by **describe block** so it never collapses to one bar. Requirements coverage bars are coloured by threshold (red &lt;50%, amber &lt;80%, green ≥80%).
+Every report leads with a **release-gate** ship/hold banner derived from the run verdict, surfaces **timed-out** tests as their own KPI card and pass-rate chart slice, and lists failures **most-severe first** (with severity-coloured card borders in `minimal` and `detailed`). Pages **pack compactly**: large sections flow and break between rows instead of each starting on a fresh page. The Suite Results chart breaks a single-file run down by **describe block** so it never collapses to one bar. Requirements coverage bars are coloured by threshold (red &lt;50%, amber &lt;80%, green ≥80%).
 
 ### Generating multiple templates in one run
 
@@ -394,11 +397,11 @@ reporter: [
 # → reports/2026-04-28-report-executive.pdf
 ```
 
-One license check, one data-collection pass — faster than multiple reporter instances. Duplicate entries are silently deduplicated.
+One license check, one data-collection pass: faster than multiple reporter instances. Duplicate entries are silently deduplicated.
 
 ### Report Sections
 
-Each built-in template ships a curated set of sections. The `sections` option lets you **add a section a template hides or remove one it shows — per template** — without writing a custom template.
+Each built-in template ships a curated set of sections. The `sections` option lets you **add a section a template hides or remove one it shows, per template**, without writing a custom template.
 
 ```ts
 reporter: [['@reportforge/playwright-pdf', {
@@ -413,7 +416,7 @@ reporter: [['@reportforge/playwright-pdf', {
 
 **Resolution order** (lowest → highest): the template's defaults → flat keys (baseline for all chosen templates) → per-template keys (`minimal` / `detailed` / `executive`). An unknown key throws a configuration error (typo-safe).
 
-#### Block toggles — which sections appear
+#### Block toggles: which sections appear
 
 | Key | Renders |
 |---|---|
@@ -431,7 +434,7 @@ 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`) |
 
-#### Display modifiers — tune a section that's on
+#### Display modifiers: tune a section that's on
 
 | Key | Effect |
 |---|---|
@@ -468,11 +471,11 @@ Omit `sections` entirely and each template renders exactly this (✓ = on):
 
 #### Dependencies & gotchas
 
-- **`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.
-- **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.
+- **`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.
+- **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.
 
 ---
 
@@ -497,7 +500,7 @@ Full workflows for all four CI providers: [reportforge.org/docs/ci-cd](https://r
     path: reports/*.pdf
 ```
 
-### GitHub Actions — Sharded runs
+### GitHub Actions: Sharded runs
 
 Run shards in parallel with `--reporter=json`, then merge all JSON files into one PDF:
 
@@ -540,7 +543,7 @@ jobs:
         with: { name: playwright-pdf-report, path: reports/*.pdf }
 ```
 
-In `playwright.config.ts` set `shardResults: process.env.SHARD_RESULTS_GLOB`. `tests/dummy.spec.ts` can be a single skipped test — live results are ignored when `shardResults` is set.
+In `playwright.config.ts` set `shardResults: process.env.SHARD_RESULTS_GLOB`. `tests/dummy.spec.ts` can be a single skipped test: live results are ignored when `shardResults` is set.
 
 ### GitLab CI
 
@@ -603,11 +606,11 @@ ReportForge ships a **hybrid offline-first** model:
 
 1. Paste your `RFSU-…` key into the config once (or set `RF_LICENSE_KEY`).
 2. On first run the reporter activates against the license server, receives a short-lived **Ed25519-signed JWT**, and caches it at `~/.reportforge/license.json`.
-3. Every subsequent run is **fully offline** — the cached JWT is verified locally against a public key bundled into the npm package. No network call.
+3. Every subsequent run is **fully offline**: the cached JWT is verified locally against a public key bundled into the npm package. No network call.
 4. When the cache has less than 24 hours left, the reporter refreshes it in the background.
 5. Each subscription allows up to **25 active machines** in any rolling 30-day window. Machines that haven't run in 30 days are pruned automatically.
 
-Cancel the subscription and the reporter keeps working until the end of the current billing period, then stops generating PDFs until you restart. **A license issue never aborts your test run** — the reporter logs a warning and skips PDF generation; your Playwright tests still pass.
+Cancel the subscription and the reporter keeps working until the end of the current billing period, then stops generating PDFs until you restart. **A license issue never aborts your test run**: the reporter logs a warning and skips PDF generation; your Playwright tests still pass.
 
 ```bash
 export RF_LICENSE_KEY=RFSU-XXXX-XXXX-XXXX-XXXX
@@ -654,17 +657,17 @@ Full guide: [reportforge.org/docs/troubleshooting](https://reportforge.org/docs/
 
 Full documentation at [reportforge.org/docs](https://reportforge.org/docs):
 
-- [Quick start](https://reportforge.org/docs/quickstart) — install, configure, activate
-- [Chrome setup](https://reportforge.org/docs/running-tests#chrome-setup) — Windows, Linux, macOS
-- [CI/CD integration](https://reportforge.org/docs/ci-cd) — GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins, Azure DevOps
-- [Configuration reference](https://reportforge.org/docs/configuration) — all options
-- [Filename tokens](https://reportforge.org/docs/configuration#tokens) — `{date}`, `{branch}`, `{status}`
-- [Templates](https://reportforge.org/docs/templates) — minimal, detailed, executive
-- [Live runs](https://reportforge.org/docs/advanced/live) — stream per-test progress to a shared watch link
-- [Report Sections](https://reportforge.org/docs/configuration#report-sections) — add or remove sections per template
-- [License & offline behaviour](https://reportforge.org/docs/licensing) — JWT cache, machine cap, cancellation
-- [Troubleshooting](https://reportforge.org/docs/troubleshooting) — common issues and debug flags
-- **Changelog** — [CHANGELOG.md](./CHANGELOG.md)
+- [Quick start](https://reportforge.org/docs/quickstart): install, configure, activate
+- [Chrome setup](https://reportforge.org/docs/running-tests#chrome-setup): Windows, Linux, macOS
+- [CI/CD integration](https://reportforge.org/docs/ci-cd): GitHub Actions, GitLab CI, Bitbucket Pipelines, Jenkins, Azure DevOps
+- [Configuration reference](https://reportforge.org/docs/configuration): all options
+- [Filename tokens](https://reportforge.org/docs/configuration#tokens): `{date}`, `{branch}`, `{status}`
+- [Templates](https://reportforge.org/docs/templates): minimal, detailed, executive
+- [Live runs](https://reportforge.org/docs/advanced/live): stream per-test progress to a shared watch link
+- [Report Sections](https://reportforge.org/docs/configuration#report-sections): add or remove sections per template
+- [License & offline behaviour](https://reportforge.org/docs/licensing): JWT cache, machine cap, cancellation
+- [Troubleshooting](https://reportforge.org/docs/troubleshooting): common issues and debug flags
+- **Changelog**: [CHANGELOG.md](./CHANGELOG.md)
 
 ---
 
@@ -674,4 +677,4 @@ Questions and bug reports: email [support@reportforge.org](mailto:support@report
 
 ## License
 
-MIT — see [LICENSE](./LICENSE).
+MIT. See [LICENSE](./LICENSE).

package/dist/cli/index.js

@@ -11921,7 +11921,7 @@ ${issues}`);
   }
   return result.data;
 }
-var hexColor, channelConfigSchema, emailChannelConfigSchema, notifyConfigSchema, failureAnalysisConfigSchema, captureConfigSchema, liveConfigSchema, sectionFlagsShape, sectionFlagsSchema, sectionsSchema, ReporterOptionsSchema;
+var hexColor, channelConfigSchema, discordChannelConfigSchema, emailChannelConfigSchema, notifyConfigSchema, failureAnalysisConfigSchema, captureConfigSchema, liveConfigSchema, sectionFlagsShape, sectionFlagsSchema, sectionsSchema, ReporterOptionsSchema;
 var init_schema = __esm({
   "src/config/schema.ts"() {
     "use strict";
@@ -11938,6 +11938,9 @@ var init_schema = __esm({
       on: external_exports.enum(["always", "failure", "success"]).default("always"),
       enabled: external_exports.boolean().default(false)
     });
+    discordChannelConfigSchema = channelConfigSchema.extend({
+      attachPdf: external_exports.boolean().default(false)
+    });
     emailChannelConfigSchema = external_exports.object({
       to: external_exports.array(external_exports.string().email('Each "to" entry must be a valid email')).min(1, '"to" must have at least one address'),
       on: external_exports.enum(["always", "failure", "success"]).default("always"),
@@ -11947,7 +11950,7 @@ var init_schema = __esm({
     notifyConfigSchema = external_exports.object({
       slack: channelConfigSchema.optional(),
       teams: channelConfigSchema.optional(),
-      discord: channelConfigSchema.optional(),
+      discord: discordChannelConfigSchema.optional(),
       email: emailChannelConfigSchema.optional()
     }).optional();
     failureAnalysisConfigSchema = external_exports.object({

package/dist/index.d.mts

@@ -158,7 +158,12 @@ interface ReporterOptions {
      * `on` controls the trigger: `'always'` (default), `'failure'`, or `'success'`.
      *
      * - `slack` / `teams` / `discord`: webhook URL channels
+     * - `discord`: `attachPdf: true` uploads the PDF with the message (falls back
+     *   to the summary alone if the upload fails or the PDF exceeds Discord's cap)
      * - `email`: sends via Resend; `to` is required; `attachPdf: true` attaches the PDF
+     *
+     * Slack and Teams webhooks cannot carry file uploads, so `attachPdf` does not
+     * exist on those channels.
      */
     notify?: {
         slack?: {
@@ -175,6 +180,7 @@ interface ReporterOptions {
             url: string;
             on?: 'always' | 'failure' | 'success';
             enabled?: boolean;
+            attachPdf?: boolean;
         };
         email?: {
             to: string[];

package/dist/index.d.ts

@@ -158,7 +158,12 @@ interface ReporterOptions {
      * `on` controls the trigger: `'always'` (default), `'failure'`, or `'success'`.
      *
      * - `slack` / `teams` / `discord`: webhook URL channels
+     * - `discord`: `attachPdf: true` uploads the PDF with the message (falls back
+     *   to the summary alone if the upload fails or the PDF exceeds Discord's cap)
      * - `email`: sends via Resend; `to` is required; `attachPdf: true` attaches the PDF
+     *
+     * Slack and Teams webhooks cannot carry file uploads, so `attachPdf` does not
+     * exist on those channels.
      */
     notify?: {
         slack?: {
@@ -175,6 +180,7 @@ interface ReporterOptions {
             url: string;
             on?: 'always' | 'failure' | 'success';
             enabled?: boolean;
+            attachPdf?: boolean;
         };
         email?: {
             to: string[];

package/dist/index.js

@@ -10454,6 +10454,9 @@ var channelConfigSchema = external_exports.object({
   on: external_exports.enum(["always", "failure", "success"]).default("always"),
   enabled: external_exports.boolean().default(false)
 });
+var discordChannelConfigSchema = channelConfigSchema.extend({
+  attachPdf: external_exports.boolean().default(false)
+});
 var emailChannelConfigSchema = external_exports.object({
   to: external_exports.array(external_exports.string().email('Each "to" entry must be a valid email')).min(1, '"to" must have at least one address'),
   on: external_exports.enum(["always", "failure", "success"]).default("always"),
@@ -10463,7 +10466,7 @@ var emailChannelConfigSchema = external_exports.object({
 var notifyConfigSchema = external_exports.object({
   slack: channelConfigSchema.optional(),
   teams: channelConfigSchema.optional(),
-  discord: channelConfigSchema.optional(),
+  discord: discordChannelConfigSchema.optional(),
   email: emailChannelConfigSchema.optional()
 }).optional();
 var failureAnalysisConfigSchema = external_exports.object({
@@ -13199,7 +13202,7 @@ function fmtMb(bytes) {
 }
 
 // src/reporter.ts
-var import_path12 = __toESM(require("path"));
+var import_path13 = __toESM(require("path"));
 
 // src/history/HistoryManager.ts
 init_cjs_shims();
@@ -13280,6 +13283,8 @@ init_cjs_shims();
 
 // src/notify/NotificationSender.ts
 init_cjs_shims();
+var import_promises2 = require("fs/promises");
+var import_path12 = require("path");
 
 // src/notify/formatters/slack.ts
 init_cjs_shims();
@@ -13529,6 +13534,7 @@ var FORMATTERS = {
   teams: buildTeamsPayload,
   discord: buildDiscordPayload
 };
+var DISCORD_MAX_UPLOAD_BYTES = 25 * 1024 * 1024;
 var NotificationSender = class {
   async sendAll(reportData, notifyConfig, pdfPaths) {
     const result = { sent: [], skipped: [], failed: [] };
@@ -13541,6 +13547,9 @@ var NotificationSender = class {
           return Promise.resolve();
         }
         const payload = FORMATTERS[name](reportData.stats, pdfPaths, reportTitle);
+        if (name === "discord" && notifyConfig.discord?.attachPdf && pdfPaths.length > 0) {
+          return this.postDiscordWithPdf(channel.url, payload, pdfPaths[0], result);
+        }
         return this.post(name, channel.url, payload, result);
       })
     );
@@ -13582,6 +13591,47 @@ var NotificationSender = class {
       })
     );
   }
+  /**
+   * Posts the summary to a Discord webhook with the PDF as a multipart file
+   * upload (`payload_json` + `files[0]`). Any problem — unreadable file, PDF
+   * over Discord's upload cap, or a failed upload — falls back to the plain
+   * JSON summary post so the notification still lands; only the fallback's
+   * outcome is recorded in the result. Attaches the first PDF only (matches
+   * the email channel's multi-template behaviour).
+   */
+  async postDiscordWithPdf(url, payload, pdfPath, result) {
+    let file;
+    try {
+      file = await (0, import_promises2.readFile)(pdfPath);
+      if (file.byteLength > DISCORD_MAX_UPLOAD_BYTES) {
+        const mb = (file.byteLength / 1024 / 1024).toFixed(1);
+        throw new Error(`PDF is ${mb}MB \u2014 over Discord's upload limit`);
+      }
+    } catch (err) {
+      logger.warn(
+        `[notify] discord: ${err instanceof Error ? err.message : String(err)} \u2014 sending summary without the PDF`
+      );
+      return this.post("discord", url, payload, result);
+    }
+    const form = new FormData();
+    form.append("payload_json", JSON.stringify(payload));
+    form.append("files[0]", new Blob([new Uint8Array(file)], { type: "application/pdf" }), (0, import_path12.basename)(pdfPath));
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), 3e4);
+    try {
+      const res = await fetch(url, { method: "POST", body: form, signal: controller.signal });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      logger.info("[notify] discord: sent (PDF attached)");
+      result.sent.push("discord");
+    } catch (err) {
+      logger.warn(
+        `[notify] discord: upload failed (${err instanceof Error ? err.message : String(err)}) \u2014 retrying without the PDF`
+      );
+      return this.post("discord", url, payload, result);
+    } finally {
+      clearTimeout(timeoutId);
+    }
+  }
   async post(name, url, payload, result) {
     const controller = new AbortController();
     const timeoutId = setTimeout(() => controller.abort(), 1e4);
@@ -13951,7 +14001,7 @@ var PdfReporter = class {
     this.liveConsole = false;
     this.options = parseOptions(rawOptions);
     this.dataCollector = new DataCollector(this.options.capture);
-    const version = true ? "0.12.0" : "0.x";
+    const version = true ? "0.13.1" : "0.x";
     logger.info(`@reportforge/playwright-pdf v${version} initialised`);
     this.licenseClient = new LicenseClient({
       licenseKey: this.options.licenseKey,
@@ -14219,7 +14269,7 @@ var PdfReporter = class {
   }
   resolveProjectName() {
     try {
-      const pkgPath = import_path12.default.resolve(process.cwd(), "package.json");
+      const pkgPath = import_path13.default.resolve(process.cwd(), "package.json");
       const pkg = require(pkgPath);
       return pkg.name ?? "Playwright Tests";
     } catch {
@@ -14269,9 +14319,9 @@ function deriveVerdict(stats) {
 }
 function resolveHistoryPath(options, cwd) {
   if (options.historyFile) {
-    return import_path12.default.isAbsolute(options.historyFile) ? options.historyFile : import_path12.default.resolve(cwd, options.historyFile);
+    return import_path13.default.isAbsolute(options.historyFile) ? options.historyFile : import_path13.default.resolve(cwd, options.historyFile);
   }
-  return import_path12.default.join(resolveProjectDir(options, cwd), "history.json");
+  return import_path13.default.join(resolveProjectDir(options, cwd), "history.json");
 }
 function flattenSuiteNodes(suites) {
   return suites.flatMap((s) => [s, ...flattenSuiteNodes(s.suites)]);