webperf-snippets 0.1.0 → 0.3.0

package/snippets/_shared/helpers.js

@@ -0,0 +1,44 @@
+/* eslint-disable no-unused-vars */
+// Canonical source of the helpers that several snippets copy.
+//
+// Snippets run pasted into the DevTools console, so they cannot import anything. Each snippet
+// that needs a helper carries a copy of it between the same two markers:
+//
+//   // @shared <name>
+//   ...
+//   // @end-shared <name>
+//
+// `npm run check:consistency` fails when a copy differs from the block below (indentation is
+// ignored). Edit the block here first, then paste it into every snippet that carries the marker.
+
+// @shared getRootDomain
+function getRootDomain(hostname) {
+  const host = hostname.replace(/\.$/, "");
+  // An IP address has no registrable domain, so each address is its own root
+  if (/^\d{1,3}(\.\d{1,3}){3}$/.test(host) || host.includes(":")) return host;
+  const parts = host.split(".");
+  if (parts.length <= 2) return host;
+  // Country-code domains with a second-level suffix: example.co.uk, example.com.au, example.ac.jp
+  const secondLevelSuffixes = ["ac", "co", "com", "edu", "go", "gob", "gouv", "gov", "govt", "mil", "ne", "net", "nom", "or", "org", "sch"];
+  const tld = parts[parts.length - 1];
+  const sld = parts[parts.length - 2];
+  if (tld.length === 2 && secondLevelSuffixes.includes(sld)) return parts.slice(-3).join(".");
+  return parts.slice(-2).join(".");
+}
+// @end-shared getRootDomain
+
+// @shared isFirstParty
+function isFirstParty(hostname) {
+  return getRootDomain(hostname) === getRootDomain(location.hostname);
+}
+// @end-shared isFirstParty
+
+// @shared formatBytes
+function formatBytes(bytes) {
+  if (bytes === null || bytes === undefined || Number.isNaN(bytes)) return "-";
+  if (bytes === 0) return "0 B";
+  const units = ["B", "KB", "MB", "GB"];
+  const i = Math.max(0, Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1));
+  return (bytes / Math.pow(1024, i)).toFixed(1) + " " + units[i];
+}
+// @end-shared formatBytes

package/src/bin.js

@@ -1,21 +1,28 @@
 #!/usr/bin/env node
+import { existsSync } from "node:fs";
 import { parseArgs } from "node:util";
 import { loadSnippet } from "./load-snippet.js";
-import { runSnippets, VIEWPORT_PRESETS } from "./runner.js";
+import { runSnippets, runMeasurement, VIEWPORT_PRESETS } from "./runner.js";
 import { cwvWorkflow } from "./workflows/cwv.js";
 import { auditWorkflow } from "./workflows/audit.js";
-import { nextSteps } from "./decision-tree.js";
+import { loadingWorkflow } from "./workflows/loading.js";
+import { RULES } from "./decision-tree.js";
 import { reportHuman } from "./reporters/human.js";
 import { reportJson } from "./reporters/json.js";
+import { reportMarkdown } from "./reporters/markdown.js";
+import { cliVersion, reportTo, validateReportUrl } from "./report-to.js";
+import { fetchCrux, formFactorFor } from "./crux.js";
 
 const WORKFLOWS = {
   "core-web-vitals": cwvWorkflow,
   audit: auditWorkflow,
+  loading: loadingWorkflow,
 };
 
 const SNIPPET_ALIASES = {
   LCP: "CoreWebVitals/LCP",
   CLS: "CoreWebVitals/CLS",
+  INP: "CoreWebVitals/INP",
   "LCP-Subparts": "CoreWebVitals/LCP-Subparts",
   fonts: "Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold",
   "Fonts-Preloaded-Loaded-and-used-above-the-fold":
@@ -53,18 +60,29 @@ Run curated WebPerf Snippets headlessly via Playwright.
 
 Options:
   --workflow <name>     Workflow to run (default: core-web-vitals)
-                        Workflows: core-web-vitals, audit
+                        Workflows: core-web-vitals, audit, loading
   --snippet <name>      Run a single snippet by alias or Category/Name path
-                        Aliases: LCP, CLS, LCP-Subparts, fonts,
+                        Aliases: LCP, CLS, INP, LCP-Subparts, fonts,
                                  render-blocking, resource-hints, preload-scripts,
                                  priority-hints, critical-css, ttfb,
                                  script-parties, script-loading,
                                  lazy-atf, lazy-conflict, eager-below-fold
   --json                Output JSON instead of formatted text
+  --markdown            Output GitHub-renderable markdown (for PR comments)
   --viewport <preset>   Viewport preset: mobile (default), tablet, desktop
   --wait <ms>           Post-load wait before evaluating (default: 3000)
   --budget-lcp <ms>     Exit 1 if LCP exceeds this value
   --budget-cls <score>  Exit 1 if CLS exceeds this value
+  --interact-script <path>  JSON file with interactions to run before evaluation
+                            Actions: scroll, click, hover, type, wait
+  --storage-state <path>    Playwright storage state (cookies + localStorage) to
+                            measure pages that require authentication
+  --crux-key <key>          Add CrUX field data (p75) next to the measured values.
+                            Also read from the CRUX_API_KEY environment variable
+  --report-to <url>         POST the results to this https URL after the run
+                            (without it the CLI makes no external calls)
+  --api-key <key>           Sent as "Authorization: Bearer <key>" with --report-to.
+                            Prefer the PERF_REVIEWS_API_KEY environment variable
   --verbose             Show all items, even for passing checks
   --headed              Show the browser window (debug)
   -h, --help            Show this help
@@ -77,6 +95,8 @@ Examples:
   npx webperf-snippets https://web.dev --snippet render-blocking
   npx webperf-snippets https://web.dev --snippet fonts
   npx webperf-snippets https://web.dev --budget-lcp 2500
+  npx webperf-snippets https://web.dev --snippet INP --interact-script interactions.json
+  npx webperf-snippets https://example.com/dashboard --storage-state auth.json
 `;
 
 function fail(message, code = 2) {
@@ -88,19 +108,9 @@ function resolveSnippetPath(name) {
   return SNIPPET_ALIASES[name] ?? name;
 }
 
-function buildItems(values) {
-  if (values.snippet) {
-    const path = resolveSnippetPath(values.snippet);
-    return [{ id: values.snippet, path, source: loadSnippet(path) }];
-  }
-  const workflowName = values.workflow ?? "core-web-vitals";
-  const workflow = WORKFLOWS[workflowName];
-  if (!workflow) fail(`Unknown workflow: ${workflowName}`);
-  return workflow.steps.map((step) => ({
-    id: step.id,
-    path: step.path,
-    source: loadSnippet(step.path),
-  }));
+function buildSnippetItem(values) {
+  const path = resolveSnippetPath(values.snippet);
+  return [{ id: values.snippet, path, source: loadSnippet(path) }];
 }
 
 function checkBudgets(results, values) {
@@ -128,10 +138,16 @@ async function main() {
         workflow: { type: "string" },
         snippet: { type: "string" },
         json: { type: "boolean" },
+        markdown: { type: "boolean" },
         wait: { type: "string" },
         "budget-lcp": { type: "string" },
         "budget-cls": { type: "string" },
         viewport: { type: "string" },
+        "interact-script": { type: "string" },
+        "storage-state": { type: "string" },
+        "crux-key": { type: "string" },
+        "report-to": { type: "string" },
+        "api-key": { type: "string" },
         verbose: { type: "boolean" },
         headed: { type: "boolean" },
         help: { type: "boolean", short: "h" },
@@ -155,7 +171,6 @@ async function main() {
     process.exit(2);
   }
 
-  const items = buildItems(values);
   const waitMs = values.wait ? Number(values.wait) : 3000;
   const viewportName = values.viewport ?? "mobile";
   const viewport = VIEWPORT_PRESETS[viewportName];
@@ -163,50 +178,64 @@ async function main() {
     fail(`Unknown viewport preset: "${viewportName}". Choose from: ${Object.keys(VIEWPORT_PRESETS).join(", ")}`);
   }
 
-  const initial = await runSnippets({
-    url,
-    items,
-    waitMs,
-    headless: !values.headed,
-    viewport,
-  });
-
-  // Apply decision tree to spawn follow-up steps.
-  const followUps = nextSteps(initial.results);
-  let followUpRun = { results: [], pageErrors: [] };
-  if (followUps.length > 0) {
-    const followItems = followUps.map((f) => ({
-      id: f.id,
-      path: f.path,
-      source: loadSnippet(f.path),
-      reason: f.reason,
-    }));
-    // v0.1 limitation: follow-ups re-navigate. Acceptable for now; consolidate
-    // into a single page session in v0.2 if perf becomes a problem.
-    followUpRun = await runSnippets({
-      url,
-      items: followItems,
-      waitMs,
-      headless: !values.headed,
-      viewport,
-    });
-    // Carry forward the human-readable reason so reporters can show it.
-    followUpRun.results = followUpRun.results.map((r) => {
-      const f = followUps.find((x) => x.id === r.id);
-      return f ? { ...r, reason: f.reason } : r;
-    });
+  const reportUrl = values["report-to"];
+  if (reportUrl) {
+    const problem = validateReportUrl(reportUrl);
+    if (problem) fail(problem);
   }
 
-  const payload = {
-    url,
-    navMs: initial.navMs,
-    results: [...initial.results, ...followUpRun.results],
-    pageErrors: [...initial.pageErrors, ...(followUpRun.pageErrors ?? [])],
-  };
+  const interactScript = values["interact-script"];
+  const storageState = values["storage-state"];
+  if (storageState && !existsSync(storageState)) {
+    fail(`Storage state file not found: ${storageState}`);
+  }
+
+  let payload;
+  if (values.snippet) {
+    const items = buildSnippetItem(values);
+    payload = await runSnippets({ url, items, waitMs, headless: !values.headed, viewport, interactScript, storageState });
+  } else {
+    const workflowName = values.workflow ?? "core-web-vitals";
+    const workflow = WORKFLOWS[workflowName];
+    if (!workflow) fail(`Unknown workflow: ${workflowName}`);
+    payload = await runMeasurement({ url, workflow, rules: RULES, waitMs, headless: !values.headed, viewport, interactScript, storageState });
+  }
 
-  const output = values.json ? reportJson(payload) : reportHuman({ ...payload, verbose: values.verbose });
+  const cruxKey = values["crux-key"] || process.env.CRUX_API_KEY;
+  const crux = cruxKey ? await fetchCrux({ url, apiKey: cruxKey, formFactor: formFactorFor(viewportName) }) : undefined;
+  if (crux) payload.crux = crux;
+
+  let output;
+  if (values.markdown) {
+    output = reportMarkdown(payload);
+  } else if (values.json) {
+    output = reportJson(payload);
+  } else {
+    output = reportHuman({ ...payload, verbose: values.verbose });
+  }
   process.stdout.write(output + "\n");
 
+  if (reportUrl) {
+    const outcome = await reportTo({
+      url: reportUrl,
+      apiKey: values["api-key"] || process.env.PERF_REVIEWS_API_KEY,
+      body: {
+        url,
+        workflow: values.snippet ? null : (values.workflow ?? "core-web-vitals"),
+        ...(values.snippet ? { snippet: values.snippet } : {}),
+        timestamp: new Date().toISOString(),
+        navMs: payload.navMs,
+        results: payload.results,
+        meta: { viewport: viewportName, waitMs, cli_version: cliVersion },
+      },
+    });
+    if (!outcome.ok) {
+      process.stderr.write(`Warning: could not report results to ${new URL(reportUrl).origin} (${outcome.warning})\n`);
+    } else if (outcome.regressions.length > 0) {
+      process.stderr.write(`Regressions detected:\n${outcome.regressions.map((r) => `  - ${typeof r === "string" ? r : JSON.stringify(r)}`).join("\n")}\n`);
+    }
+  }
+
   // Exit codes.
   const violations = checkBudgets(payload.results, values);
   if (violations.length > 0) {

package/src/crux.js

@@ -0,0 +1,84 @@
+const DEFAULT_ENDPOINT = "https://chromeuxreport.googleapis.com/v1/records:queryRecord";
+const CRUX_TIMEOUT_MS = 10000;
+
+// Good / needs-improvement upper bounds from web.dev/articles/vitals.
+const METRICS = [
+  { name: "LCP", key: "largest_contentful_paint", unit: "ms", good: 2500, poor: 4000 },
+  { name: "CLS", key: "cumulative_layout_shift", unit: "score", good: 0.1, poor: 0.25 },
+  { name: "INP", key: "interaction_to_next_paint", unit: "ms", good: 200, poor: 500 },
+];
+
+const FORM_FACTOR_LABEL = { PHONE: "mobile", DESKTOP: "desktop", TABLET: "tablet" };
+
+const rate = (value, { good, poor }) => (value <= good ? "good" : value <= poor ? "needs-improvement" : "poor");
+
+// The viewport preset decides which population the field data describes.
+export function formFactorFor(viewportName) {
+  return viewportName === "desktop" ? "DESKTOP" : "PHONE";
+}
+
+function parseMetrics(record) {
+  const metrics = {};
+  for (const m of METRICS) {
+    // CLS p75 comes as a string ("0.08"); LCP and INP as numbers.
+    const p75 = Number(record?.metrics?.[m.key]?.percentiles?.p75);
+    if (Number.isFinite(p75)) metrics[m.name] = { p75, rating: rate(p75, m), unit: m.unit };
+  }
+  return metrics;
+}
+
+async function query({ endpoint, apiKey, body, timeoutMs }) {
+  const res = await fetch(`${endpoint}?key=${encodeURIComponent(apiKey)}`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (res.status === 404) return { notFound: true };
+  if (!res.ok) return { status: res.status };
+  return { record: (await res.json()).record };
+}
+
+// Never throws, and no message it returns contains the key (it travels in the
+// query string, so the request URL is never logged or put in an error).
+export async function fetchCrux({
+  url,
+  apiKey,
+  formFactor = "PHONE",
+  endpoint = process.env.WEBPERF_CRUX_ENDPOINT ?? DEFAULT_ENDPOINT,
+  timeoutMs = CRUX_TIMEOUT_MS,
+}) {
+  try {
+    let scope = "url";
+    let answer = await query({ endpoint, apiKey, body: { url, formFactor }, timeoutMs });
+    if (answer.notFound) {
+      scope = "origin";
+      answer = await query({ endpoint, apiKey, body: { origin: new URL(url).origin, formFactor }, timeoutMs });
+    }
+    if (answer.notFound) return { unavailable: "not in the CrUX dataset" };
+    if (answer.status) return { unavailable: `the CrUX API answered ${answer.status}` };
+    const metrics = parseMetrics(answer.record);
+    if (Object.keys(metrics).length === 0) return { unavailable: "no Core Web Vitals in the CrUX record" };
+    return { scope, formFactor, metrics };
+  } catch (err) {
+    const reason = err.name === "TimeoutError" ? `no answer within ${timeoutMs}ms` : (err.cause?.code ?? "request failed");
+    return { unavailable: reason };
+  }
+}
+
+// Shared by both reporters: what to show and next to which synthetic value.
+export function fieldDataView(crux, results) {
+  const label = FORM_FACTOR_LABEL[crux.formFactor] ?? crux.formFactor.toLowerCase();
+  const title = `Field data (CrUX p75, ${label}${crux.scope === "origin" ? ", origin-level" : ""})`;
+  const rows = METRICS.filter((m) => crux.metrics[m.name]).map((m) => {
+    const synthetic = results.find((r) => r.status === "ok" && r.metric === m.name);
+    return {
+      metric: m.name,
+      unit: m.unit,
+      p75: crux.metrics[m.name].p75,
+      rating: crux.metrics[m.name].rating,
+      synthetic: synthetic ? synthetic.value : null,
+    };
+  });
+  return { title, rows };
+}

package/src/decision-tree.js

@@ -1,11 +1,21 @@
 // Declarative follow-ups: if a result matches the predicate, append the step.
 // Mirrors the WORKFLOWS.md decision trees from the snippet catalogue.
-const RULES = [
+export const RULES = [
   {
     when: (r) => r.id === "LCP" && r.status === "ok" && r.value > 2500,
     append: { id: "LCP-Subparts", path: "CoreWebVitals/LCP-Subparts" },
     reason: "LCP > 2.5s — drilling into sub-parts",
   },
+  {
+    when: (r) => r.id === "TTFB" && r.status === "ok" && r.value > 600,
+    append: { id: "ttfb-subparts", path: "Loading/TTFB-Sub-Parts" },
+    reason: "TTFB > 600ms — drilling into sub-parts",
+  },
+  {
+    when: (r) => r.id === "FCP" && r.status === "ok" && r.value > 1800,
+    append: { id: "render-blocking", path: "Loading/Find-render-blocking-resources" },
+    reason: "FCP > 1.8s — checking render-blocking resources",
+  },
 ];
 
 export function nextSteps(results) {

package/src/interactions.js

@@ -0,0 +1,30 @@
+import { readFileSync } from "node:fs";
+
+export async function executeStep(page, step) {
+  switch (step.action) {
+    case "scroll":
+      await page.evaluate((y) => window.scrollBy(0, y), step.y ?? 300);
+      break;
+    case "click":
+      await page.click(step.selector);
+      break;
+    case "hover":
+      await page.hover(step.selector);
+      break;
+    case "type":
+      await page.type(step.selector, step.text);
+      break;
+    case "wait":
+      await page.waitForTimeout(step.ms);
+      break;
+    default:
+      throw new Error(`Unknown interaction action: "${step.action}"`);
+  }
+}
+
+export async function runInteractions(page, scriptPath) {
+  const { interactions } = JSON.parse(readFileSync(scriptPath, "utf8"));
+  for (const step of interactions) {
+    await executeStep(page, step);
+  }
+}

package/src/report-to.js

@@ -0,0 +1,46 @@
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const REPORT_TIMEOUT_MS = 5000;
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+export const cliVersion = JSON.parse(readFileSync(join(HERE, "..", "package.json"), "utf8")).version;
+
+// Returns an error message when the URL cannot receive a report, or null.
+// https is required so the API key is never sent in clear text; local hosts
+// are allowed over http for development and tests.
+export function validateReportUrl(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return `--report-to must be an https URL, got "${value}"`;
+  }
+  if (parsed.protocol === "https:") return null;
+  if (parsed.protocol === "http:" && LOCAL_HOSTS.has(parsed.hostname)) return null;
+  return `--report-to must be an https URL (http is allowed only for localhost), got "${value}"`;
+}
+
+// POSTs the results to `url`. Never throws and never touches the exit code:
+// the caller decides what to do with the outcome. The key is only sent in the
+// Authorization header and never appears in a returned message.
+export async function reportTo({ url, apiKey, body, timeoutMs = REPORT_TIMEOUT_MS }) {
+  const headers = { "Content-Type": "application/json" };
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+  try {
+    const res = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) return { ok: false, warning: `the endpoint answered ${res.status}` };
+    const data = await res.json().catch(() => ({}));
+    return { ok: true, regressions: data.ok === false ? (data.regressions ?? []) : [] };
+  } catch (err) {
+    const reason = err.name === "TimeoutError" ? `no answer within ${timeoutMs}ms` : (err.cause?.code ?? err.message);
+    return { ok: false, warning: reason };
+  }
+}

package/src/reporters/human.js

@@ -1,4 +1,5 @@
 import { styleText } from "node:util";
+import { fieldDataView } from "../crux.js";
 
 const RATING_ICON = {
   good: "🟢",
@@ -164,12 +165,30 @@ function renderResult(r, verbose) {
   return out;
 }
 
-export function reportHuman({ url, navMs, results, pageErrors, verbose }) {
+function renderFieldData(crux, results) {
+  if (crux.unavailable) return [styleText("dim", `Field data: not available (${crux.unavailable})`)];
+  const { title, rows } = fieldDataView(crux, results);
+  const lines = [styleText("bold", title)];
+  for (const row of rows) {
+    const icon = RATING_ICON[row.rating] ?? "·";
+    const synthetic = row.synthetic == null ? "n/a" : formatValue(row.synthetic, row.unit);
+    lines.push(
+      `  ${icon} ${pad(row.metric, 6)} ${pad(paint(row.rating, formatValue(row.p75, row.unit)), 10)} ${pad(styleText("dim", row.rating), 20)} ${styleText("dim", `(synthetic: ${synthetic})`)}`
+    );
+  }
+  return lines;
+}
+
+export function reportHuman({ url, navMs, results, pageErrors, verbose, crux }) {
   const lines = [];
   lines.push(styleText(["bold"], `WebPerf Snippets — ${url}`));
   lines.push(styleText("dim", `Navigated in ${navMs}ms`));
   lines.push("");
   for (const r of results) lines.push(renderResult(r, verbose));
+  if (crux) {
+    lines.push("");
+    lines.push(...renderFieldData(crux, results));
+  }
   if (pageErrors?.length) {
     lines.push("");
     lines.push(styleText("yellow", "Page errors during run:"));

package/src/reporters/markdown.js

@@ -0,0 +1,103 @@
+import { fieldDataView } from "../crux.js";
+
+const RATING_ICON = {
+  good: "✅",
+  "needs-improvement": "⚠️",
+  poor: "❌",
+};
+
+function formatValue(value, unit) {
+  if (unit === "ms") return value >= 1000 ? `${(value / 1000).toFixed(2)}s` : `${value}ms`;
+  if (unit === "score") return value.toFixed(4);
+  return String(value);
+}
+
+function renderMetricRow(r) {
+  const value = formatValue(r.value, r.unit);
+  const icon = RATING_ICON[r.rating] ?? "·";
+  return `| ${r.id} | ${value} | ${icon} ${r.rating} |`;
+}
+
+function renderAuditRow(r) {
+  const errors = (r.issues ?? []).filter((i) => i.severity === "error");
+  const warnings = (r.issues ?? []).filter((i) => i.severity === "warning");
+  const icon = errors.length ? "🔴" : warnings.length ? "🟡" : "🟢";
+  const label = errors.length ? "fail" : warnings.length ? "warning" : "pass";
+  const detail = r.issues?.length ? r.issues.map((i) => i.message).join("; ") : "No issues";
+  return `| ${r.id} | ${icon} ${label} | ${detail} |`;
+}
+
+function renderErrorRow(r) {
+  return `| ${r.id} | ❌ error | ${r.error} |`;
+}
+
+function renderRow(r) {
+  if (r.status === "error") return renderErrorRow(r);
+  if (Array.isArray(r.issues)) return renderAuditRow(r);
+  return renderMetricRow(r);
+}
+
+function sectionHeader(results) {
+  if (results.some((r) => Array.isArray(r.issues))) {
+    return ["| Check | Status | Issues |", "|-------|--------|--------|"];
+  }
+  return ["| Metric | Value | Status |", "|--------|-------|--------|"];
+}
+
+function renderSection(title, results) {
+  return [
+    `### ${title}`,
+    ...sectionHeader(results),
+    ...results.map(renderRow),
+  ].join("\n");
+}
+
+function renderFieldData(crux, results) {
+  if (crux.unavailable) return [`> Field data: not available (${crux.unavailable})`];
+  const { title, rows } = fieldDataView(crux, results);
+  return [
+    `### ${title}`,
+    "| Metric | Field p75 | Status | Synthetic |",
+    "|--------|-----------|--------|-----------|",
+    ...rows.map((row) => {
+      const synthetic = row.synthetic == null ? "n/a" : formatValue(row.synthetic, row.unit);
+      return `| ${row.metric} | ${formatValue(row.p75, row.unit)} | ${RATING_ICON[row.rating] ?? "·"} ${row.rating} | ${synthetic} |`;
+    }),
+  ];
+}
+
+export function reportMarkdown({ url, navMs, results, pageErrors, crux }) {
+  const lines = [];
+  lines.push(`## WebPerf Results — ${url}`);
+  lines.push(`> Navigated in ${navMs}ms`);
+  lines.push("");
+
+  const initial = results.filter((r) => !r.reason);
+  if (initial.length > 0) {
+    lines.push(renderSection("Results", initial));
+  }
+
+  // Group follow-ups by their triggering reason.
+  const byReason = new Map();
+  for (const r of results.filter((r) => r.reason)) {
+    if (!byReason.has(r.reason)) byReason.set(r.reason, []);
+    byReason.get(r.reason).push(r);
+  }
+  for (const [reason, group] of byReason) {
+    lines.push("");
+    lines.push(renderSection(`Follow-up *(${reason})*`, group));
+  }
+
+  if (crux) {
+    lines.push("");
+    lines.push(...renderFieldData(crux, results));
+  }
+
+  if (pageErrors?.length) {
+    lines.push("");
+    lines.push("### ⚠ Page Errors");
+    for (const err of pageErrors) lines.push(`- ${err}`);
+  }
+
+  return lines.join("\n");
+}