@reportforge/playwright-pdf 0.14.3 → 0.15.1

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 
+## [0.15.1] - 2026-07-07
+
+### Changed
+
+- **Release Recommendation copy is dash-free and data-driven.** The banner verdict reads `HOLD: N FAILURES` and the detail line now carries the per-run root-cause tally from failure analysis, e.g. "3 of 21 tests failed (2 assertion, 1 timeout). Each failure may be a product defect or an automation script issue. Review and verify manually before shipping." Falls back to the plain count when analysis is off; `flaky-by-retry` is excluded from the tally (flaky tests keep their own suffix). Timed-out variant matches.
+
+---
+
+## [0.15.0] - 2026-07-07
+
+### Changed
+
+- **Suite Breakdown now always opens on a fresh page** in every template (`minimal`, `detailed`, `executive`), instead of starting mid-page after whatever section precedes it.
+- **Watermark now stamps from the Suite Breakdown page to the end of the report.** The cover, summary, and chart pages stay clean — a diagonal stamp behind the doughnut/trend charts hurt readability on exactly the pages built to be glanced at. The copies anchor inside the suite-breakdown section (its forced page break makes the section's top edge an exact page boundary), so every copy stays page-centred without estimating print pagination; custom templates and `sections` overrides without that section fall back to whole-document stamping. Also fixes a latent overshoot where the page-count pad could paint a blank trailing page containing only a watermark.
+- **Watermark opacity raised from 4% to 10%** — visible as a stamp rather than barely-there, still light enough to keep text underneath legible.
+- **Release Recommendation no longer says "fix before shipping."** A failure isn't necessarily a product defect, so the HOLD banner now reads: "Review each failure — it may be a product defect or an automation script issue — and verify manually before shipping." The timed-out variant matches ("often an environment or automation issue").
+
+---
+
 ## [0.14.3] - 2026-07-06
 
 ### Fixed

package/README.md

@@ -183,7 +183,7 @@ All options are the second element of the reporter tuple.
 | `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` | n/a | Text to render as a diagonal watermark overlay on every page, e.g. `'CONFIDENTIAL'` or `'DRAFT'`. |
+| `watermark` | `string` | n/a | Text to render as a diagonal watermark overlay from the Suite Breakdown page onward (summary/chart pages stay clean), 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. |
@@ -668,7 +668,7 @@ Full documentation at [reportforge.org/docs](https://reportforge.org/docs):
 - [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)
+- [Changelog](https://reportforge.org/changelog): version history and release notes
 
 ---
 

package/dist/cli/index.js

@@ -6375,16 +6375,24 @@ var init_duration = __esm({
 });
 
 // src/analysis/SummaryWriter.ts
-function buildOneLiner(clusters) {
-  if (clusters.length === 0) return "";
+function tallyEntries(clusters) {
   const byCategory = /* @__PURE__ */ new Map();
   for (const c of clusters) {
     byCategory.set(c.category, (byCategory.get(c.category) ?? 0) + c.count);
   }
+  return [...byCategory.entries()].sort((a, b) => b[1] - a[1]);
+}
+function buildOneLiner(clusters) {
+  if (clusters.length === 0) return "";
   const head = `${clusters.length} root ${clusters.length === 1 ? "cause" : "causes"}`;
-  const tally = [...byCategory.entries()].sort((a, b) => b[1] - a[1]).map(([cat, count]) => `${count} ${SHORT_LABEL[cat]}`);
+  const tally = tallyEntries(clusters).map(([cat, count]) => `${count} ${SHORT_LABEL[cat]}`);
   return [head, ...tally].join(" \xB7 ");
 }
+function buildFailureTally(analysis) {
+  if (!analysis) return "";
+  const failureClusters = analysis.clusters.filter((c) => c.category !== "flaky-by-retry");
+  return tallyEntries(failureClusters).map(([cat, count]) => `${count} ${SHORT_LABEL[cat]}`).join(", ");
+}
 function dominantCategory(clusters) {
   return clusters[0]?.category ?? "unknown";
 }
@@ -6666,7 +6674,8 @@ var init_engine = __esm({
           baseCSS: this.fontsBundleCss + "\n" + this.readStyle("base.css"),
           templateCSS: "",
           chartjsScript: this.buildChartjsScript(),
-          watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX
+          watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX,
+          releaseGateTally: buildFailureTally(data.analysis)
         };
       }
       buildContext(data, template, userSections, slowTestThreshold) {
@@ -6690,7 +6699,8 @@ var init_engine = __esm({
           baseCSS,
           templateCSS,
           chartjsScript: this.buildChartjsScript(),
-          watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX
+          watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX,
+          releaseGateTally: buildFailureTally(data.analysis)
         };
       }
       buildChartjsScript() {

package/dist/index.d.mts

@@ -67,7 +67,8 @@ interface ReporterOptions {
      */
     accentColor?: string;
     /**
-     * Text to render as a diagonal watermark overlay on every page.
+     * Text to render as a diagonal watermark overlay, stamped from the Suite
+     * Breakdown page to the end of the report (summary and chart pages stay clean).
      * Example: 'CONFIDENTIAL', 'DRAFT'
      */
     watermark?: string;

package/dist/index.d.ts

@@ -67,7 +67,8 @@ interface ReporterOptions {
      */
     accentColor?: string;
     /**
-     * Text to render as a diagonal watermark overlay on every page.
+     * Text to render as a diagonal watermark overlay, stamped from the Suite
+     * Breakdown page to the end of the report (summary and chart pages stay clean).
      * Example: 'CONFIDENTIAL', 'DRAFT'
      */
     watermark?: string;

package/dist/index.js

@@ -11291,16 +11291,24 @@ var SHORT_LABEL = {
   "flaky-by-retry": "flaky",
   unknown: "unclassified"
 };
-function buildOneLiner(clusters) {
-  if (clusters.length === 0) return "";
+function tallyEntries(clusters) {
   const byCategory = /* @__PURE__ */ new Map();
   for (const c of clusters) {
     byCategory.set(c.category, (byCategory.get(c.category) ?? 0) + c.count);
   }
+  return [...byCategory.entries()].sort((a, b) => b[1] - a[1]);
+}
+function buildOneLiner(clusters) {
+  if (clusters.length === 0) return "";
   const head = `${clusters.length} root ${clusters.length === 1 ? "cause" : "causes"}`;
-  const tally = [...byCategory.entries()].sort((a, b) => b[1] - a[1]).map(([cat, count]) => `${count} ${SHORT_LABEL[cat]}`);
+  const tally = tallyEntries(clusters).map(([cat, count]) => `${count} ${SHORT_LABEL[cat]}`);
   return [head, ...tally].join(" \xB7 ");
 }
+function buildFailureTally(analysis) {
+  if (!analysis) return "";
+  const failureClusters = analysis.clusters.filter((c) => c.category !== "flaky-by-retry");
+  return tallyEntries(failureClusters).map(([cat, count]) => `${count} ${SHORT_LABEL[cat]}`).join(", ");
+}
 function dominantCategory(clusters) {
   return clusters[0]?.category ?? "unknown";
 }
@@ -12443,7 +12451,8 @@ var TemplateEngine = class {
       baseCSS: this.fontsBundleCss + "\n" + this.readStyle("base.css"),
       templateCSS: "",
       chartjsScript: this.buildChartjsScript(),
-      watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX
+      watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX,
+      releaseGateTally: buildFailureTally(data.analysis)
     };
   }
   buildContext(data, template, userSections, slowTestThreshold) {
@@ -12467,7 +12476,8 @@ var TemplateEngine = class {
       baseCSS,
       templateCSS,
       chartjsScript: this.buildChartjsScript(),
-      watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX
+      watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX,
+      releaseGateTally: buildFailureTally(data.analysis)
     };
   }
   buildChartjsScript() {
@@ -14062,7 +14072,7 @@ var PdfReporter = class {
     this.liveConsole = false;
     this.options = parseOptions(rawOptions);
     this.dataCollector = new DataCollector(this.options.capture);
-    const version = true ? "0.14.3" : "0.x";
+    const version = true ? "0.15.1" : "0.x";
     logger.info(`@reportforge/playwright-pdf v${version} initialised`);
     this.licenseClient = new LicenseClient({
       licenseKey: this.options.licenseKey,

package/dist/index.mjs

@@ -11292,16 +11292,24 @@ var SHORT_LABEL = {
   "flaky-by-retry": "flaky",
   unknown: "unclassified"
 };
-function buildOneLiner(clusters) {
-  if (clusters.length === 0) return "";
+function tallyEntries(clusters) {
   const byCategory = /* @__PURE__ */ new Map();
   for (const c of clusters) {
     byCategory.set(c.category, (byCategory.get(c.category) ?? 0) + c.count);
   }
+  return [...byCategory.entries()].sort((a, b) => b[1] - a[1]);
+}
+function buildOneLiner(clusters) {
+  if (clusters.length === 0) return "";
   const head = `${clusters.length} root ${clusters.length === 1 ? "cause" : "causes"}`;
-  const tally = [...byCategory.entries()].sort((a, b) => b[1] - a[1]).map(([cat, count]) => `${count} ${SHORT_LABEL[cat]}`);
+  const tally = tallyEntries(clusters).map(([cat, count]) => `${count} ${SHORT_LABEL[cat]}`);
   return [head, ...tally].join(" \xB7 ");
 }
+function buildFailureTally(analysis) {
+  if (!analysis) return "";
+  const failureClusters = analysis.clusters.filter((c) => c.category !== "flaky-by-retry");
+  return tallyEntries(failureClusters).map(([cat, count]) => `${count} ${SHORT_LABEL[cat]}`).join(", ");
+}
 function dominantCategory(clusters) {
   return clusters[0]?.category ?? "unknown";
 }
@@ -12444,7 +12452,8 @@ var TemplateEngine = class {
       baseCSS: this.fontsBundleCss + "\n" + this.readStyle("base.css"),
       templateCSS: "",
       chartjsScript: this.buildChartjsScript(),
-      watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX
+      watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX,
+      releaseGateTally: buildFailureTally(data.analysis)
     };
   }
   buildContext(data, template, userSections, slowTestThreshold) {
@@ -12468,7 +12477,8 @@ var TemplateEngine = class {
       baseCSS,
       templateCSS,
       chartjsScript: this.buildChartjsScript(),
-      watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX
+      watermarkPageHeightPx: PAGE_CONTENT_HEIGHT_PX,
+      releaseGateTally: buildFailureTally(data.analysis)
     };
   }
   buildChartjsScript() {
@@ -14063,7 +14073,7 @@ var PdfReporter = class {
     this.liveConsole = false;
     this.options = parseOptions(rawOptions);
     this.dataCollector = new DataCollector(this.options.capture);
-    const version = true ? "0.14.3" : "0.x";
+    const version = true ? "0.15.1" : "0.x";
     logger.info(`@reportforge/playwright-pdf v${version} initialised`);
     this.licenseClient = new LicenseClient({
       licenseKey: this.options.licenseKey,

package/dist/templates/partials/release-gate.hbs

@@ -4,10 +4,12 @@
   <div class="release-gate__body">
     <div class="release-gate__label">Release Recommendation</div>
     <div class="release-gate__verdict release-gate__verdict--fail">
-      HOLD &mdash; {{stats.failed}} FAILURE{{#if (gt stats.failed 1)}}S{{/if}}
+      HOLD: {{stats.failed}} FAILURE{{#if (gt stats.failed 1)}}S{{/if}}
     </div>
     <div class="release-gate__detail">
-      {{stats.failed}} of {{stats.total}} tests failed. Review and fix before shipping.
+      {{stats.failed}} of {{stats.total}} tests failed{{#if releaseGateTally}} ({{releaseGateTally}}){{/if}}.
+      Each failure may be a product defect or an automation script issue.
+      Review and verify manually before shipping.
       {{#if stats.flaky}} &nbsp;&middot;&nbsp; {{stats.flaky}} flaky (additional risk).{{/if}}
     </div>
   </div>
@@ -23,10 +25,12 @@
     <div class="release-gate__body">
       <div class="release-gate__label">Release Recommendation</div>
       <div class="release-gate__verdict release-gate__verdict--fail">
-        HOLD &mdash; {{stats.timedOut}} TIMED OUT
+        HOLD: {{stats.timedOut}} TIMED OUT
       </div>
       <div class="release-gate__detail">
-        {{stats.timedOut}} tests exceeded timeout. Investigate before shipping.
+        {{stats.timedOut}} test{{#if (gt stats.timedOut 1)}}s{{/if}} exceeded timeout.
+        Timeouts are often environment or automation issues.
+        Review and verify manually before shipping.
       </div>
     </div>
     <div class="release-gate__meta">

package/dist/templates/partials/suite-breakdown.hbs

@@ -1,4 +1,4 @@
-<div class="section">
+<div class="section section--suite-breakdown">
   <h2>Suite Breakdown</h2>
   {{#if (and overflowFailureCount sections.failureDeepDive)}}
   <div class="overflow-banner">

package/dist/templates/partials/watermark.hbs

@@ -5,19 +5,37 @@ document.addEventListener('DOMContentLoaded', function() {
   // single watermark div only ever prints on one page. Instead, measure the fully
   // parsed document (this listener fires after all content above is in the DOM)
   // and stamp one absolutely-positioned copy per page slot.
+  //
+  // Copies start at the suite breakdown, not page 1, so the summary/chart pages
+  // stay clean. That section opens on a forced page break (.section--suite-breakdown
+  // in base.css), which makes its top edge an exact page boundary — appending the
+  // copies INSIDE it keeps each one page-centred even when print pagination pushes
+  // in-flow content down, because the copies travel with the section rather than
+  // being estimated against shifted content. When the section is absent (sections
+  // override, custom templates), fall back to stamping the whole document.
   var text = {{{safeJsonData meta.branding.watermark}}};
   var pageHeightPx = {{watermarkPageHeightPx}};
-  // +1: print pagination avoids breaking cards/rows mid-way, so each physical
-  // page is often a little under pageHeightPx of raw content — that nudges the
-  // real page count above what scrollHeight / pageHeightPx alone predicts.
-  var pageCount = Math.min(500, Math.max(1, Math.ceil(document.body.scrollHeight / pageHeightPx) + 1));
+  var anchor = document.querySelector('.section--suite-breakdown');
+  var host = anchor || document.body;
+  var startPx = anchor ? anchor.offsetTop : 0;
+  // Copy count: ceil() of the measured span, NEVER padded in the anchor case — the
+  // anchor origin is page-aligned, so ceil is exact for unshifted content and every
+  // copy lands inside it (a padded copy would paint a blank trailing page with a
+  // lone watermark). Print pagination can still push content one page further than
+  // the screen measurement predicts (cards/rows refuse to split mid-way); in the
+  // anchor case that at worst leaves the final spill-over page unstamped, which is
+  // the cheaper failure. The body fallback keeps the +1: whole-document slack
+  // (cover break + every section) reliably exceeds a page, so there the pad fills
+  // a real page instead of minting an empty one.
+  var extra = anchor ? 0 : 1;
+  var pageCount = Math.min(500, Math.max(1, Math.ceil((document.body.scrollHeight - startPx) / pageHeightPx) + extra));
   for (var i = 0; i < pageCount; i++) {
     var el = document.createElement('div');
     el.className = 'watermark';
     el.setAttribute('aria-hidden', 'true');
     el.style.top = (i * pageHeightPx + pageHeightPx / 2) + 'px';
     el.textContent = text;
-    document.body.appendChild(el);
+    host.appendChild(el);
   }
 });
 </script>

package/dist/templates/styles/base.css

@@ -44,7 +44,8 @@ html, body {
   background: var(--bg);
 }
 /* Positioned so it's the containing block for the watermark's `position: absolute`
-   copies (see below) — without this they'd position relative to the document root. */
+   fallback copies (see watermark.hbs) — without this they'd position relative to
+   the document root. */
 body { position: relative; z-index: 0; }
 
 /* ── Typography ─────────────────────────────────────────────────────────── */
@@ -145,20 +146,34 @@ tr:last-child td { border-bottom: none; }
 /* `top` is set inline per copy (see watermark.hbs) — Chromium's print-to-PDF
    doesn't repeat `position: fixed` elements per page, so one copy is stamped
    at each page's vertical centre in document-flow coordinates instead.
+   Copies live inside .section--suite-breakdown (its forced page break makes its
+   top edge a page boundary) and run from there to the end of the report — the
+   summary/chart pages stay unstamped. body hosts the copies only as a fallback
+   when that section is absent.
    z-index is high (not negative) so it paints over cards/badges too — at
-   4% opacity it doesn't hurt legibility, and a negative z-index made it
-   invisible on any page dense enough to have no gaps in the content. */
+   10% opacity it stays light enough not to hurt legibility, and a negative
+   z-index made it invisible on any page dense enough to have no gaps in the
+   content. */
 .watermark {
   position: absolute; left: 50%;
   transform: translate(-50%, -50%) rotate(-30deg);
   font-family: 'Source Serif Pro', Georgia, serif; font-size: 60px; font-weight: 700;
-  color: rgba(31,31,28,0.04); pointer-events: none; z-index: 999;
+  color: rgba(31,31,28,0.10); pointer-events: none; z-index: 999;
   white-space: nowrap; letter-spacing: 8px; text-transform: uppercase;
   user-select: none;
 }
 
 /* ── Page breaks ────────────────────────────────────────────────────────── */
 .no-break { page-break-inside: avoid; }
+/* Suite breakdown always opens on a fresh page (every template) — and the forced
+   break puts its top edge exactly on a page boundary, which watermark.hbs relies
+   on to start the per-page watermark copies here. position:relative makes it
+   their containing block; no z-index, so the copies keep painting in the body
+   stacking context (above the sections that follow this one too). */
+.section--suite-breakdown {
+  break-before: page; page-break-before: always;
+  position: relative;
+}
 /* Keep a failed test row glued to the START of its inline failure detail so the
    title never orphans above it. The detail card itself may break internally (its
    small pieces are individually break-protected), so a tall screenshot flows to the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reportforge/playwright-pdf",
-  "version": "0.14.3",
+  "version": "0.15.1",
   "description": "Playwright Test reporter that generates designed PDF reports: minimal, detailed, and executive templates with CI/CD integrations",
   "license": "MIT",
   "author": "ReportForge",