webperf-snippets 0.1.0 → 0.2.0

package/README.md

@@ -2,7 +2,10 @@
 
 Run curated [WebPerf Snippets](https://webperf-snippets.nucliweb.net) headlessly via Playwright. Diagnose Core Web Vitals beyond what Lighthouse exposes and gate CI on real performance budgets.
 
-> **Status:** v0.1 (MVP). Core Web Vitals workflow only. See [Roadmap](#roadmap) for what's next.
+<img width="1820" height="1442" alt="webperf-snippets-CLI" src="https://github.com/user-attachments/assets/af7e6b02-8877-407e-87a4-db063468b5fb" />
+
+
+> **Status:** v0.2. Core Web Vitals, loading audit, and structural checks. See [Roadmap](#roadmap) for what's next.
 
 ## Why
 
@@ -35,6 +38,24 @@ Run the default Core Web Vitals workflow (LCP + CLS, plus LCP-Subparts if LCP >
 npx webperf-snippets https://web.dev
 ```
 
+Loading audit (TTFB, FCP, render-blocking, scripts, fonts):
+
+```bash
+npx webperf-snippets https://web.dev --workflow loading
+```
+
+Structural checks for CI (render-blocking, fonts, priority hints, resource hints):
+
+```bash
+npx webperf-snippets https://web.dev --workflow audit
+```
+
+Markdown output for PR comments:
+
+```bash
+npx webperf-snippets https://web.dev --markdown
+```
+
 JSON output (for piping into `jq` or CI):
 
 ```bash
@@ -47,6 +68,12 @@ Single snippet:
 npx webperf-snippets https://web.dev --snippet LCP-Subparts
 ```
 
+Synthetic INP measurement with an interaction script:
+
+```bash
+npx webperf-snippets https://web.dev --snippet INP --interact-script interactions.json
+```
+
 CI gating:
 
 ```bash
@@ -55,16 +82,40 @@ npx webperf-snippets https://web.dev --budget-lcp 2500 --budget-cls 0.1
 
 ### Options
 
-| Option                | Description                                                |
-| --------------------- | ---------------------------------------------------------- |
-| `--workflow <name>`   | Workflow to run. Default: `core-web-vitals`.               |
-| `--snippet <name>`    | Run a single snippet (`LCP`, `CLS`, or `Category/Name`).   |
-| `--json`              | Output JSON instead of formatted text.                     |
-| `--wait <ms>`         | Post-load wait before evaluating snippets. Default: `3000`.|
-| `--budget-lcp <ms>`   | Exit `1` if LCP exceeds this value.                        |
-| `--budget-cls <score>`| Exit `1` if CLS exceeds this value.                        |
-| `--headed`            | Show the browser window (debug).                           |
-| `-h, --help`          | Show help.                                                 |
+| Option                       | Description                                                            |
+| ---------------------------- | ---------------------------------------------------------------------- |
+| `--workflow <name>`          | Workflow to run. Default: `core-web-vitals`. Options: `core-web-vitals`, `loading`, `audit`. |
+| `--snippet <name>`           | Run a single snippet by alias or `Category/Name` path.                 |
+| `--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 snippets. Default: `3000`.            |
+| `--interact-script <path>`   | JSON file with interactions to run before evaluation (for INP).        |
+| `--budget-lcp <ms>`          | Exit `1` if LCP exceeds this value.                                    |
+| `--budget-cls <score>`       | Exit `1` if CLS exceeds this value.                                    |
+| `--verbose`                  | Show all items, including passing checks.                              |
+| `--headed`                   | Show the browser window (debug).                                       |
+| `-h, --help`                 | Show help.                                                             |
+
+### Snippet aliases
+
+| Alias              | Snippet                                        |
+| ------------------ | ---------------------------------------------- |
+| `LCP`              | CoreWebVitals/LCP                              |
+| `CLS`              | CoreWebVitals/CLS                              |
+| `LCP-Subparts`     | CoreWebVitals/LCP-Subparts                     |
+| `fonts`            | Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold |
+| `render-blocking`  | Loading/Find-render-blocking-resources         |
+| `resource-hints`   | Loading/Resource-Hints-Validation              |
+| `preload-scripts`  | Loading/Validate-Preload-Async-Defer-Scripts   |
+| `priority-hints`   | Loading/Priority-Hints-Audit                   |
+| `critical-css`     | Loading/Critical-CSS-Detection                 |
+| `ttfb`             | Loading/TTFB-Sub-Parts                         |
+| `script-parties`   | Loading/First-And-Third-Party-Script-Info      |
+| `script-loading`   | Loading/Script-Loading                         |
+| `lazy-atf`         | Loading/Find-Above-The-Fold-Lazy-Loaded-Images |
+| `lazy-conflict`    | Loading/Find-Images-With-Lazy-and-Fetchpriority |
+| `eager-below-fold` | Loading/Find-non-Lazy-Loaded-Images-outside-of-the-viewport |
 
 ### Exit codes
 
@@ -112,17 +163,16 @@ Tag protection rules restrict who can push `cli-v*` tags. Configure them under *
 
 The `NPM_TOKEN` secret must be set in the repository settings with publish access to the `webperf-snippets` npm package.
 
-## Known limitations (v0.1)
+## Known limitations
 
-- **No INP**: INP requires real user interactions. v0.2 will support synthetic interaction scripts.
 - **CLS in headless is conservative**: layout shifts that only happen on scroll are missed unless you script the scroll.
 - **First navigation only**: each `webperf-snippets` invocation runs one URL. SPAs need the post-route URL passed directly.
-- **Decision-tree follow-ups re-navigate**: when a follow-up snippet fires (e.g. LCP-Subparts), the page is loaded again. v0.2 will share a single page session.
+- **Synthetic INP ≠ field INP**: `--interact-script` measures handler latency for a single scripted event. Real INP reflects the worst interaction across all user sessions — use RUM for field data.
 
 ## Roadmap
 
-- v0.2: Loading workflow (TTFB, FCP, render-blocking, scripts, fonts), shared page session, synthetic interactions for INP.
-- v0.3: Markdown reporter for PR comments, GitHub Action wrapper.
+- ~~v0.2: Loading workflow (TTFB, FCP, render-blocking, scripts, fonts), shared page session, synthetic interactions for INP, markdown reporter for PR comments.~~ ✓ Released
+- v0.3: GitHub Action wrapper.
 - v0.4: Auth flows (login + measure logged-in pages), CrUX field-data enrichment.
 
 ## How it works

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webperf-snippets",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Run curated WebPerf Snippets headlessly via Playwright. Diagnose Core Web Vitals beyond what Lighthouse exposes.",
   "type": "module",
   "bin": "./src/bin.js",

package/snippets/Loading/Find-render-blocking-resources.js

@@ -31,6 +31,15 @@
     })
     .sort((a, b) => b.responseEnd - a.responseEnd);
 
+  const lastBlockingEnd = blockingResources.length
+    ? Math.max(...blockingResources.map((r) => r.responseEnd))
+    : 0;
+  const totalSizeBytes = blockingResources.reduce((sum, r) => sum + r.size, 0);
+  const byType = blockingResources.reduce((acc, r) => {
+    acc[r.type] = (acc[r.type] || 0) + 1;
+    return acc;
+  }, {});
+
   console.group("%c🚧 Render-Blocking Resources", "font-weight: bold; font-size: 14px;");
 
   if (blockingResources.length === 0) {
@@ -45,14 +54,6 @@
     console.log("   • Scripts use async or defer attributes");
     console.log("   • Critical resources are optimized");
   } else {
-    // Calculate metrics
-    const lastBlockingEnd = Math.max(...blockingResources.map((r) => r.responseEnd));
-    const totalSize = blockingResources.reduce((sum, r) => sum + r.size, 0);
-    const byType = blockingResources.reduce((acc, r) => {
-      acc[r.type] = (acc[r.type] || 0) + 1;
-      return acc;
-    }, {});
-
     // Summary
     console.log(
       `%c⚠️ Found ${blockingResources.length} render-blocking resource(s)`,
@@ -63,8 +64,8 @@
     console.log("%c📊 Impact Summary:", "font-weight: bold;");
     console.log(`   Rendering blocked until: ${lastBlockingEnd.toFixed(0)}ms`);
     console.log(`   Total blocking resources: ${blockingResources.length}`);
-    if (totalSize > 0) {
-      const sizeKB = (totalSize / 1024).toFixed(1);
+    if (totalSizeBytes > 0) {
+      const sizeKB = (totalSizeBytes / 1024).toFixed(1);
       console.log(`   Total size: ${sizeKB} KB`);
     }
     console.log(`   By type: ${Object.entries(byType).map(([k, v]) => `${k} (${v})`).join(", ")}`);
@@ -134,9 +135,6 @@
 
   console.groupEnd();
 
-  const lastBlockingEnd = blockingResources.length ? Math.max(...blockingResources.map((r) => r.responseEnd)) : 0;
-  const totalSizeBytes = blockingResources.reduce((sum, r) => sum + r.size, 0);
-  const byType = blockingResources.reduce((acc, r) => { acc[r.type] = (acc[r.type] || 0) + 1; return acc; }, {});
   return {
     script: "Find-render-blocking-resources",
     status: "ok",

package/src/bin.js

@@ -1,16 +1,19 @@
 #!/usr/bin/env node
 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";
 
 const WORKFLOWS = {
   "core-web-vitals": cwvWorkflow,
   audit: auditWorkflow,
+  loading: loadingWorkflow,
 };
 
 const SNIPPET_ALIASES = {
@@ -53,7 +56,7 @@ 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,
                                  render-blocking, resource-hints, preload-scripts,
@@ -61,10 +64,13 @@ Options:
                                  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
   --verbose             Show all items, even for passing checks
   --headed              Show the browser window (debug)
   -h, --help            Show this help
@@ -77,6 +83,7 @@ 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
 `;
 
 function fail(message, code = 2) {
@@ -88,19 +95,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 +125,12 @@ 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" },
         verbose: { type: "boolean" },
         headed: { type: "boolean" },
         help: { type: "boolean", short: "h" },
@@ -155,7 +154,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,48 +161,27 @@ 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 interactScript = values["interact-script"];
 
-  const payload = {
-    url,
-    navMs: initial.navMs,
-    results: [...initial.results, ...followUpRun.results],
-    pageErrors: [...initial.pageErrors, ...(followUpRun.pageErrors ?? [])],
-  };
+  let payload;
+  if (values.snippet) {
+    const items = buildSnippetItem(values);
+    payload = await runSnippets({ url, items, waitMs, headless: !values.headed, viewport, interactScript });
+  } 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 });
+  }
 
-  const output = values.json ? reportJson(payload) : reportHuman({ ...payload, verbose: values.verbose });
+  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");
 
   // Exit codes.

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/reporters/markdown.js

@@ -0,0 +1,82 @@
+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");
+}
+
+export function reportMarkdown({ url, navMs, results, pageErrors }) {
+  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 (pageErrors?.length) {
+    lines.push("");
+    lines.push("### ⚠ Page Errors");
+    for (const err of pageErrors) lines.push(`- ${err}`);
+  }
+
+  return lines.join("\n");
+}

package/src/runner.js

@@ -1,4 +1,6 @@
 import { chromium } from "playwright";
+import { loadSnippet } from "./load-snippet.js";
+import { runInteractions } from "./interactions.js";
 
 export const VIEWPORT_PRESETS = {
   mobile: { width: 375, height: 812 },
@@ -15,6 +17,27 @@ function toExpression(source) {
   return source.trim().replace(/;\s*$/, "");
 }
 
+async function evaluateItems(page, items) {
+  const results = [];
+  for (const item of items) {
+    try {
+      const result = await page.evaluate(toExpression(item.source));
+      if (result && typeof result === "object") {
+        results.push({ id: item.id, ...result });
+      } else {
+        results.push({
+          id: item.id,
+          status: "error",
+          error: "Snippet did not return an object — check the IIFE return statement",
+        });
+      }
+    } catch (err) {
+      results.push({ id: item.id, status: "error", error: err.message });
+    }
+  }
+  return results;
+}
+
 export async function runSnippets({
   url,
   items,
@@ -22,12 +45,40 @@ export async function runSnippets({
   headless = true,
   viewport = VIEWPORT_PRESETS.mobile,
   navTimeout = DEFAULT_NAV_TIMEOUT,
+  interactScript,
 }) {
   const browser = await chromium.launch({ headless });
   try {
     const context = await browser.newContext({ viewport });
     const page = await context.newPage();
+    const pageErrors = [];
+    page.on("pageerror", (err) => pageErrors.push(err.message));
+    const navStart = Date.now();
+    await page.goto(url, { waitUntil: "load", timeout: navTimeout });
+    if (waitMs > 0) await page.waitForTimeout(waitMs);
+    const navMs = Date.now() - navStart;
+    if (interactScript) await runInteractions(page, interactScript);
+    const results = await evaluateItems(page, items);
+    return { url, navMs, results, pageErrors };
+  } finally {
+    await browser.close();
+  }
+}
 
+export async function runMeasurement({
+  url,
+  workflow,
+  rules = [],
+  waitMs = 3000,
+  headless = true,
+  viewport = VIEWPORT_PRESETS.mobile,
+  navTimeout = DEFAULT_NAV_TIMEOUT,
+  interactScript,
+}) {
+  const browser = await chromium.launch({ headless });
+  try {
+    const context = await browser.newContext({ viewport });
+    const page = await context.newPage();
     const pageErrors = [];
     page.on("pageerror", (err) => pageErrors.push(err.message));
 
@@ -35,26 +86,37 @@ export async function runSnippets({
     await page.goto(url, { waitUntil: "load", timeout: navTimeout });
     if (waitMs > 0) await page.waitForTimeout(waitMs);
     const navMs = Date.now() - navStart;
+    if (interactScript) await runInteractions(page, interactScript);
+
+    const items = workflow.steps.map((step) => ({
+      id: step.id,
+      path: step.path,
+      source: loadSnippet(step.path),
+    }));
+    const initialResults = await evaluateItems(page, items);
 
-    const results = [];
-    for (const item of items) {
-      try {
-        const result = await page.evaluate(toExpression(item.source));
-        if (result && typeof result === "object") {
-          results.push({ id: item.id, ...result });
-        } else {
-          results.push({
-            id: item.id,
-            status: "error",
-            error: "Snippet did not return an object — check the IIFE return statement",
-          });
-        }
-      } catch (err) {
-        results.push({ id: item.id, status: "error", error: err.message });
+    const followUps = [];
+    for (const result of initialResults) {
+      for (const rule of rules) {
+        if (rule.when(result)) followUps.push({ ...rule.append, reason: rule.reason });
       }
     }
 
-    return { url, navMs, results, pageErrors };
+    let followUpResults = [];
+    if (followUps.length > 0) {
+      const followItems = followUps.map((f) => ({
+        id: f.id,
+        path: f.path,
+        source: loadSnippet(f.path),
+      }));
+      const raw = await evaluateItems(page, followItems);
+      followUpResults = raw.map((r) => {
+        const f = followUps.find((x) => x.id === r.id);
+        return f ? { ...r, reason: f.reason } : r;
+      });
+    }
+
+    return { url, navMs, results: [...initialResults, ...followUpResults], pageErrors };
   } finally {
     await browser.close();
   }

package/src/workflows/loading.js

@@ -0,0 +1,14 @@
+// Loading performance workflow — timing-sensitive measurements requiring a real page load.
+// Complements the audit workflow (deterministic structural checks) with live metrics.
+export const loadingWorkflow = {
+  id: "loading",
+  title: "Loading Performance",
+  steps: [
+    { id: "TTFB", path: "Loading/TTFB" },
+    { id: "FCP", path: "Loading/FCP" },
+    { id: "render-blocking", path: "Loading/Find-render-blocking-resources" },
+    { id: "resource-hints", path: "Loading/Resource-Hints-Validation" },
+    { id: "scripts", path: "Loading/Script-Loading" },
+    { id: "fonts", path: "Loading/Fonts-Preloaded-Loaded-and-used-above-the-fold" },
+  ],
+};