webperf-snippets 1.1.0 → 1.2.0

package/README.md

@@ -44,6 +44,14 @@ Loading audit (11 steps: TTFB, FCP, render-blocking, scripts, resource timings,
 npx webperf-snippets https://example.com --workflow loading
 ```
 
+The steps that tell first-party from third-party resources count as first party the root domain of the page and its subdomains (`cdn.example.com` for `example.com`). A site that serves its own assets from another domain, such as its CDN, lists it with `--own-domains`, comma-separated or repeated:
+
+```bash
+npx webperf-snippets https://example.com --workflow loading --own-domains cdn.example.net,static.example.org
+```
+
+Each domain counts with its root domain, so `cdn.example.net` makes every host under `example.net` first party. The CLI writes the list in the `OWN_DOMAINS` constant of each snippet, the same one you edit at the top of the snippet in the console. An empty domain or one with spaces exits with code `2`.
+
 Structural checks for CI (22 checks: render-blocking, compression, fonts, images, hints, DOM size and more; the list is in the [CLI page](https://webperf-snippets.net/CLI)):
 
 ```bash
@@ -97,6 +105,16 @@ npx webperf-snippets https://example.com/dashboard --storage-state auth.json
 
 The file holds live session cookies. Keep it out of version control (add it to `.gitignore`) and use a throwaway account when you run it in CI. The CLI exits with code `2` if the path does not exist.
 
+Pages behind an access proxy that reads a token from every request, such as the service tokens of Cloudflare Access, take the token as request headers with `--header`, once per header:
+
+```bash
+npx webperf-snippets https://review.example.com \
+  --header "CF-Access-Client-Id: $CF_ACCESS_CLIENT_ID" \
+  --header "CF-Access-Client-Secret: $CF_ACCESS_CLIENT_SECRET"
+```
+
+The headers go with every request to the origin of the URL and never to another origin, so third parties do not receive the token and their cross-origin requests need no CORS preflight. Each request to that origin is paused in the browser to add them, which adds a few milliseconds to its timing; when the proxy accepts a session cookie, `--storage-state` measures without that cost. A header without a name or a colon exits with code `2`. Read the values from environment variables, as above, to keep them out of the shell history.
+
 Compare the measured values with CrUX field data (what real users experience at the 75th percentile):
 
 ```bash
@@ -134,16 +152,32 @@ Without `--report-to` the CLI makes no external calls. With it, the results are
   "timestamp": "2026-05-06T10:00:00.000Z",
   "navMs": 1240,
   "results": [],
-  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "1.1.0" }
+  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "1.2.0" }
 }
 ```
 
-For a `--snippet` run, `workflow` is `null` and a `snippet` field carries the name. `results` is the same list the `--json` output contains, so it can include URLs and details of the measured page; send it only to an endpoint you trust.
+For a `--snippet` run, `workflow` is `null` and a `snippet` field carries the name. With `--cpu` or `--network`, `meta` carries the conditions in `throttling`. `results` is the same list the `--json` output contains, so it can include URLs and details of the measured page; send it only to an endpoint you trust.
 
 - The URL must be `https`. `http` is accepted only for `localhost`, so a key is never sent in clear text.
 - `--api-key` is sent as `Authorization: Bearer <key>`. Prefer the `PERF_REVIEWS_API_KEY` environment variable, because a flag ends up in shell history and CI logs. The key is never printed.
 - The exit code never depends on the report. A failed POST (error status, unreachable endpoint, or no answer within 5 seconds) prints a warning and the exit code stays the one the budgets and snippets decide. If the endpoint answers `{ "ok": false, "regressions": [...] }`, the regressions are printed as a warning, again without changing the exit code.
 
+Measure under the conditions of a slower device and network with `--cpu` and `--network`. Without them the CLI runs at the speed of the machine, which on a laptop or a CI runner is faster than most phones:
+
+```bash
+npx webperf-snippets https://example.com --cpu 4 --network slow-4g
+```
+
+`--cpu <factor>` slows the main thread down by that factor. `--network` takes the presets of DevTools, with the same values:
+
+| Preset    | Download    | Upload      | Latency   |
+| --------- | ----------- | ----------- | --------- |
+| `fast-4g` | 8.1 Mbps    | 1.35 Mbps   | 165 ms    |
+| `slow-4g` | 1.44 Mbps   | 675 kbps    | 562.5 ms  |
+| `3g`      | 400 kbps    | 400 kbps    | 2000 ms   |
+
+Chrome adds the latency to the body of each response, not to its headers. The values read from `responseStart`, such as the TTFB and its sub-parts, do not include it; the download of each resource, FCP, LCP and the load event do. The report names the conditions under its header, and the JSON output carries them in `throttling`, such as `{ "cpu": 4, "network": "slow-4g" }`. A CPU factor below `1` or an unknown preset exits with code `2`.
+
 CI gating:
 
 ```bash
@@ -160,8 +194,12 @@ npx webperf-snippets https://example.com --budget-lcp 2500 --budget-cls 0.1
 | `--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`.            |
+| `--cpu <factor>`             | Slow the main thread down by this factor, such as `4`. No throttling by default. |
+| `--network <preset>`         | Throttle the network with a preset of DevTools: `fast-4g`, `slow-4g`, `3g`. No throttling by default. |
 | `--interact-script <path>`   | JSON file with interactions to run after the page loads (`scroll`, `click`, `hover`, `type`, `wait`). The Interaction snippets are installed first and read afterwards. |
 | `--storage-state <path>`     | Playwright storage state (cookies and localStorage) for pages that require authentication. |
+| `--header "Name: value"`     | Request header for the origin of the URL only, such as the token of an access proxy. Repeat it for more headers. |
+| `--own-domains <list>`       | Domains of the site to count as first party, such as its own CDN. Comma-separated or repeated. |
 | `--crux-key <key>`           | Add CrUX field data (p75) next to the measured values. Prefer `CRUX_API_KEY`. |
 | `--report-to <url>`          | POST the results to this `https` URL after the run. No external calls without it. |
 | `--api-key <key>`            | Sent as a Bearer token with `--report-to`. Prefer `PERF_REVIEWS_API_KEY`. |
@@ -212,6 +250,8 @@ The results of a run can add steps on the same page load: LCP over 2.5 s adds `L
 claude mcp add webperf -- npx -y webperf-snippets mcp
 ```
 
+It needs the Chromium of Playwright (`npx playwright install chromium`); without it, the tools answer with that command. The [MCP server documentation](https://webperf-snippets.net/MCP) has the configuration of other clients (Cursor, VS Code, Claude Desktop, Gemini CLI). The server is listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.nucliweb/webperf-snippets`.
+
 | Tool            | What it does                                                                 |
 | --------------- | ---------------------------------------------------------------------------- |
 | `list_snippets` | Lists the snippets with their category, title, short aliases and whether they track interactions. Takes an optional `category`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webperf-snippets",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "mcpName": "io.github.nucliweb/webperf-snippets",
   "description": "Run curated WebPerf Snippets headlessly via Playwright. Diagnose Core Web Vitals beyond what Lighthouse exposes.",
   "type": "module",

package/src/bin.js

@@ -12,6 +12,9 @@ import { reportMarkdown } from "./reporters/markdown.js";
 import { cliVersion, reportTo, validateReportUrl } from "./report-to.js";
 import { fetchCrux, formFactorFor } from "./crux.js";
 import { MissingBrowserError } from "./browser.js";
+import { parseHeader } from "./headers.js";
+import { NETWORK_PRESETS, parseCpuFactor } from "./throttling.js";
+import { parseOwnDomains } from "./own-domains.js";
 
 
 const USAGE = `webperf-snippets <url> [options]
@@ -37,6 +40,8 @@ Options:
   --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)
+  --cpu <factor>        Slow the CPU down by this factor, such as 4 (no throttling by default)
+  --network <preset>    Throttle the network as DevTools does: fast-4g, slow-4g, 3g
   --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 after the load; the
@@ -44,6 +49,10 @@ Options:
                             Actions: scroll, click, hover, type, wait
   --storage-state <path>    Playwright storage state (cookies + localStorage) to
                             measure pages that require authentication
+  --header "Name: value"    Request header for the origin of the URL only, such as
+                            the token of an access proxy. Repeat it for more headers
+  --own-domains <list>      Domains of the site to count as first party, such as its
+                            own CDN, comma-separated or repeated
   --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
@@ -63,8 +72,11 @@ Examples:
   npx webperf-snippets https://example.com --snippet fonts
   npx webperf-snippets https://example.com --snippet Compression-Audit
   npx webperf-snippets https://example.com --budget-lcp 2500
+  npx webperf-snippets https://example.com --cpu 4 --network slow-4g
+  npx webperf-snippets https://example.com --workflow loading --own-domains cdn.example.net
   npx webperf-snippets https://example.com --snippet INP --interact-script interactions.json
   npx webperf-snippets https://example.com/dashboard --storage-state auth.json
+  npx webperf-snippets https://review.example.com --header "CF-Access-Client-Id: $CF_ID" --header "CF-Access-Client-Secret: $CF_SECRET"
 `;
 
 function fail(message, code = 2) {
@@ -119,8 +131,12 @@ async function main() {
         "budget-lcp": { type: "string" },
         "budget-cls": { type: "string" },
         viewport: { type: "string" },
+        cpu: { type: "string" },
+        network: { type: "string" },
         "interact-script": { type: "string" },
         "storage-state": { type: "string" },
+        header: { type: "string", multiple: true },
+        "own-domains": { type: "string", multiple: true },
         "crux-key": { type: "string" },
         "report-to": { type: "string" },
         "api-key": { type: "string" },
@@ -154,6 +170,13 @@ async function main() {
     fail(`Unknown viewport preset: "${viewportName}". Choose from: ${Object.keys(VIEWPORT_PRESETS).join(", ")}`);
   }
 
+  const cpu = values.cpu != null ? parseCpuFactor(values.cpu) : undefined;
+  if (cpu === null) fail(`Invalid CPU factor "${values.cpu}". Use a number of at least 1, such as 4`);
+  const network = values.network;
+  if (network != null && !NETWORK_PRESETS[network]) {
+    fail(`Unknown network preset: "${network}". Choose from: ${Object.keys(NETWORK_PRESETS).join(", ")}`);
+  }
+
   const reportUrl = values["report-to"];
   if (reportUrl) {
     const problem = validateReportUrl(reportUrl);
@@ -166,15 +189,28 @@ async function main() {
     fail(`Storage state file not found: ${storageState}`);
   }
 
+  const headers = {};
+  for (const raw of values.header ?? []) {
+    const header = parseHeader(raw);
+    if (!header) fail(`Invalid header "${raw}". Use --header "Name: value"`);
+    headers[header[0]] = header[1];
+  }
+
+  const invalidOwnDomains = (values["own-domains"] ?? []).find((raw) => !parseOwnDomains([raw]));
+  if (invalidOwnDomains != null) {
+    fail(`Invalid --own-domains "${invalidOwnDomains}". Use domains separated by commas, such as cdn.example.net,static.example.org`);
+  }
+  const ownDomains = values["own-domains"] && parseOwnDomains(values["own-domains"]);
+
   let payload;
   if (values.snippet) {
     const items = buildSnippetItem(values);
-    payload = await runSnippets({ url, items, waitMs, headless: !values.headed, viewport, interactScript, storageState });
+    payload = await runSnippets({ url, items, waitMs, headless: !values.headed, viewport, interactScript, storageState, headers, cpu, network, ownDomains });
   } 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 });
+    payload = await runMeasurement({ url, workflow, rules: RULES, waitMs, headless: !values.headed, viewport, interactScript, storageState, headers, cpu, network, ownDomains });
   }
 
   const cruxKey = values["crux-key"] || process.env.CRUX_API_KEY;
@@ -202,7 +238,7 @@ async function main() {
         timestamp: new Date().toISOString(),
         navMs: payload.navMs,
         results: payload.results,
-        meta: { viewport: viewportName, waitMs, cli_version: cliVersion },
+        meta: { viewport: viewportName, waitMs, ...(payload.throttling ? { throttling: payload.throttling } : {}), cli_version: cliVersion },
       },
     });
     if (!outcome.ok) {

package/src/headers.js

@@ -0,0 +1,35 @@
+// Extra request headers, for pages behind an access proxy that reads a token from each request.
+// They go only to the origin of the measured URL: sent to every origin, as Playwright's
+// extraHTTPHeaders does, they would hand the token to third parties, and a custom header on a
+// cross-origin fetch needs a CORS preflight that most third parties do not answer.
+//
+// The Fetch domain of CDP pauses only the requests that match the pattern, inside the browser,
+// so third-party requests are not intercepted and keep their timings. Each request to the origin
+// waits for the round trip to Node, which adds a few milliseconds to its timing.
+
+const HEADER_NAME = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+
+// "Name: value" as given to --header, or null when it is not a valid header
+export function parseHeader(raw) {
+  const colon = raw.indexOf(":");
+  if (colon === -1) return null;
+  const name = raw.slice(0, colon).trim();
+  if (!HEADER_NAME.test(name)) return null;
+  return [name, raw.slice(colon + 1).trim()];
+}
+
+export async function sendHeadersToOrigin(context, page, url, headers) {
+  if (!headers || Object.keys(headers).length === 0) return;
+  const extra = Object.entries(headers);
+  const replaced = new Set(extra.map(([name]) => name.toLowerCase()));
+  const cdp = await context.newCDPSession(page);
+  cdp.on("Fetch.requestPaused", ({ requestId, request }) => {
+    const kept = Object.entries(request.headers).filter(([name]) => !replaced.has(name.toLowerCase()));
+    const all = [...kept, ...extra].map(([name, value]) => ({ name, value }));
+    // The request is gone when the page navigates away while it is paused
+    cdp.send("Fetch.continueRequest", { requestId, headers: all }).catch(() => {});
+  });
+  await cdp.send("Fetch.enable", {
+    patterns: [{ urlPattern: `${new URL(url).origin}/*`, requestStage: "Request" }],
+  });
+}

package/src/own-domains.js

@@ -0,0 +1,16 @@
+// The domains of the site that differ from the root domain of the page, such as its own CDN,
+// which the snippets that tell first from third parties count as first party. In the console
+// they are written at the top of each snippet; the CLI writes them there before it runs it.
+const DECLARATION = "const OWN_DOMAINS = [];";
+
+export function withOwnDomains(source, ownDomains) {
+  if (!ownDomains?.length) return source;
+  return source.replace(DECLARATION, `const OWN_DOMAINS = ${JSON.stringify(ownDomains)};`);
+}
+
+// The values given to --own-domains, each one a domain or a comma-separated list, or null when
+// one of the domains is empty or has spaces. The snippets accept URLs and any case.
+export function parseOwnDomains(values) {
+  const domains = values.flatMap((value) => value.split(",").map((domain) => domain.trim()));
+  return domains.every((domain) => domain !== "" && !/\s/.test(domain)) ? domains : null;
+}

package/src/reporters/human.js

@@ -1,5 +1,6 @@
 import { styleText } from "node:util";
 import { fieldDataView } from "../crux.js";
+import { describeThrottling } from "../throttling.js";
 
 const RATING_ICON = {
   good: "🟢",
@@ -202,10 +203,11 @@ function renderFieldData(crux, results) {
   return lines;
 }
 
-export function reportHuman({ url, navMs, results, pageErrors, verbose, crux }) {
+export function reportHuman({ url, navMs, results, pageErrors, verbose, crux, throttling }) {
   const lines = [];
   lines.push(styleText(["bold"], `WebPerf Snippets — ${url}`));
   lines.push(styleText("dim", `Navigated in ${navMs}ms`));
+  if (throttling) lines.push(styleText("dim", `Throttling: ${describeThrottling(throttling)}`));
   lines.push("");
   for (const r of results) lines.push(renderResult(r, verbose));
   if (crux) {

package/src/reporters/markdown.js

@@ -1,4 +1,5 @@
 import { fieldDataView } from "../crux.js";
+import { describeThrottling } from "../throttling.js";
 
 const RATING_ICON = {
   good: "✅",
@@ -71,10 +72,11 @@ function renderFieldData(crux, results) {
   ];
 }
 
-export function reportMarkdown({ url, navMs, results, pageErrors, crux }) {
+export function reportMarkdown({ url, navMs, results, pageErrors, crux, throttling }) {
   const lines = [];
   lines.push(`## WebPerf Results — ${url}`);
   lines.push(`> Navigated in ${navMs}ms`);
+  if (throttling) lines.push(">", `> Throttling: ${describeThrottling(throttling)}`);
   lines.push("");
 
   const initial = results.filter((r) => !r.reason);

package/src/runner.js

@@ -3,6 +3,9 @@ import { loadSnippet } from "./load-snippet.js";
 import { runInteractions, loadInteractionSteps, isInputStep, settle } from "./interactions.js";
 import { isTrackingSnippet } from "./tracking.js";
 import { nextSteps } from "./decision-tree.js";
+import { sendHeadersToOrigin } from "./headers.js";
+import { withOwnDomains } from "./own-domains.js";
+import { applyThrottling, throttlingOf } from "./throttling.js";
 
 export const VIEWPORT_PRESETS = {
   mobile: { width: 375, height: 812 },
@@ -97,6 +100,10 @@ export async function runSnippets({
   interactScript,
   interactions = interactScript,
   storageState,
+  headers,
+  cpu,
+  network,
+  ownDomains,
   // Called at each of the three stages of a run, for callers that report progress (the MCP server)
   onProgress = () => {},
 }) {
@@ -105,6 +112,8 @@ export async function runSnippets({
   try {
     const context = await browser.newContext({ viewport, storageState });
     const page = await context.newPage();
+    await sendHeadersToOrigin(context, page, url, headers);
+    await applyThrottling(context, page, { cpu, network });
     const pageErrors = [];
     page.on("pageerror", (err) => pageErrors.push(err.message));
     const navStart = Date.now();
@@ -112,9 +121,10 @@ export async function runSnippets({
     if (waitMs > 0) await page.waitForTimeout(waitMs);
     const navMs = Date.now() - navStart;
     await onProgress(2, "Page loaded, running the snippets");
-    const results = await evaluateAroundInteractions(page, items, interactions);
+    const prepared = items.map((item) => ({ ...item, source: withOwnDomains(item.source, ownDomains) }));
+    const results = await evaluateAroundInteractions(page, prepared, interactions);
     await onProgress(3, "Snippets evaluated");
-    return { url, navMs, results, pageErrors };
+    return { url, navMs, results, pageErrors, throttling: throttlingOf({ cpu, network }) };
   } finally {
     await browser.close();
   }
@@ -131,6 +141,10 @@ export async function runMeasurement({
   interactScript,
   interactions = interactScript,
   storageState,
+  headers,
+  cpu,
+  network,
+  ownDomains,
   onProgress = () => {},
 }) {
   await onProgress(1, "Opening Chromium");
@@ -138,6 +152,8 @@ export async function runMeasurement({
   try {
     const context = await browser.newContext({ viewport, storageState });
     const page = await context.newPage();
+    await sendHeadersToOrigin(context, page, url, headers);
+    await applyThrottling(context, page, { cpu, network });
     const pageErrors = [];
     page.on("pageerror", (err) => pageErrors.push(err.message));
 
@@ -158,7 +174,7 @@ export async function runMeasurement({
       .map((step) => ({
         id: step.id,
         path: step.path,
-        source: loadSnippet(step.path),
+        source: withOwnDomains(loadSnippet(step.path), ownDomains),
       }));
     const measured = await evaluateAroundInteractions(page, items, steps);
     const initialResults = workflow.steps.map(
@@ -181,7 +197,7 @@ export async function runMeasurement({
       const followItems = followUps.map((f) => ({
         id: f.id,
         path: f.path,
-        source: loadSnippet(f.path),
+        source: withOwnDomains(loadSnippet(f.path), ownDomains),
       }));
       const raw = await evaluateItems(page, followItems);
       // A tracking snippet answers through its data function, which is read right away here
@@ -194,7 +210,7 @@ export async function runMeasurement({
     }
 
     await onProgress(3, "Workflow and follow-ups evaluated");
-    return { url, navMs, results: [...initialResults, ...followUpResults], pageErrors };
+    return { url, navMs, results: [...initialResults, ...followUpResults], pageErrors, throttling: throttlingOf({ cpu, network }) };
   } finally {
     await browser.close();
   }

package/src/throttling.js

@@ -0,0 +1,43 @@
+// CPU and network throttling through CDP, as the Performance panel of DevTools applies it. The
+// network presets copy the values of DevTools, so a measurement of the CLI compares with one made
+// there. Throughputs are in bytes per second and latencies in milliseconds.
+export const NETWORK_PRESETS = {
+  "fast-4g": { title: "Fast 4G", download: (9 * 1000 * 1000) / 8 * 0.9, upload: (1.5 * 1000 * 1000) / 8 * 0.9, latency: 60 * 2.75 },
+  "slow-4g": { title: "Slow 4G", download: (1.6 * 1000 * 1000) / 8 * 0.9, upload: (750 * 1000) / 8 * 0.9, latency: 150 * 3.75 },
+  "3g": { title: "3G", download: (500 * 1000) / 8 * 0.8, upload: (500 * 1000) / 8 * 0.8, latency: 400 * 5 },
+};
+
+// The factor given to --cpu, or null when it is not a number of at least 1
+export function parseCpuFactor(raw) {
+  const factor = Number(raw);
+  return raw.trim() !== "" && Number.isFinite(factor) && factor >= 1 ? factor : null;
+}
+
+// The conditions of a run, as the payload reports them, or undefined without throttling
+export function throttlingOf({ cpu, network }) {
+  if (cpu == null && network == null) return undefined;
+  return { ...(cpu != null ? { cpu } : {}), ...(network != null ? { network } : {}) };
+}
+
+// "CPU 4x, Slow 4G", for the header of the reports
+export function describeThrottling({ cpu, network }) {
+  return [cpu != null ? `CPU ${cpu}x` : null, network != null ? (NETWORK_PRESETS[network]?.title ?? network) : null]
+    .filter(Boolean)
+    .join(", ");
+}
+
+export async function applyThrottling(context, page, { cpu, network }) {
+  if (cpu == null && network == null) return;
+  const cdp = await context.newCDPSession(page);
+  if (cpu != null) await cdp.send("Emulation.setCPUThrottlingRate", { rate: cpu });
+  if (network != null) {
+    const { download, upload, latency } = NETWORK_PRESETS[network];
+    await cdp.send("Network.enable");
+    await cdp.send("Network.emulateNetworkConditions", {
+      offline: false,
+      latency,
+      downloadThroughput: download,
+      uploadThroughput: upload,
+    });
+  }
+}