webperf-snippets 1.11.0 → 1.13.0

package/snippets/SCHEMA.md

@@ -217,6 +217,8 @@ A script wrapped in `void (async () => {...})()` discards its return value. Neve
 
 `details.element` is a CSS selector that matches only the LCP element, so `document.querySelector(details.element)` returns it: the id when it is unique, otherwise a path of tag, classes and `:nth-of-type()` from the nearest ancestor with a unique id, such as `section.intro:nth-of-type(2) > p.copy:nth-of-type(2)`. LCP-Subparts (`details.element`) and LCP-Trail (`finalElement` and each `selector`) build it the same way.
 
+In LCP-Trail, a candidate whose element has left the DOM has `selector: null` and `removed: true`, with its `time`, `sizePixels`, `url` for an image and `id` when the element had one, and `finalElement` is `null` when the LCP element itself was removed. `value` is the time of the last entry either way.
+
 #### CLS
 
 Returns buffered CLS immediately and keeps tracking. Always call `getCLS()` after interactions to get an updated value.
@@ -269,6 +271,24 @@ Returns buffered CLS immediately and keeps tracking. Always call `getCLS()` afte
 
 If no interactions yet, `getINP()` returns `status: "tracking"` with a `message` and `getDataFn: "getINP"`: interact with the page and call it again.
 
+An interaction that paints nothing has no frame to be measured to, so the browser measures it to the end of its handlers, often 0 ms, and gives no `event` entry under 16 ms at any `durationThreshold`. The first interaction of a page always has a `first-input` entry, which is how web-vitals reads it too, so `getINP()` returns it as `status: "ok"` with its value, and an `info` issue when the worst value is under 16 ms:
+
+```json
+{
+  "script": "INP",
+  "status": "ok",
+  "metric": "INP",
+  "value": 0,
+  "unit": "ms",
+  "rating": "good",
+  "thresholds": { "good": 200, "needsImprovement": 500 },
+  "details": { "totalInteractions": 1, "worstEvent": "pointerdown → h1", "phases": { "inputDelay": 0, "processingTime": 0, "presentationDelay": 0 } },
+  "issues": [{ "code": "no-paint-measured", "severity": "info", "message": "Worst interaction: 0 ms, under the 16 ms of a frame, so the page most likely painted nothing after it. If it should respond, check that the click or key press reaches an element that does." }]
+}
+```
+
+Later interactions that short have no entry of any kind: they only count in `performance.interactionCount`, and INP does not depend on them. `tracking` after a click means that the document recorded no interaction at all, as with a click inside an iframe, which records its own; the CLI and the MCP server turn that result into `status: "error"`, with an `error` that says a click or key press was sent, so the CLI exits with code `1`.
+
 The phases describe the whole interaction, not one of its events. A tap fires `pointerdown`, `pointerup` and `click`, and a key press `keydown` and `keyup`, with one `interactionId`. INP, Interactions and Input-Latency-Breakdown group the entries by `interactionId`, also when they arrive in separate observer callbacks, and measure the interaction over its entries painted in the frame of the longest one: `inputDelay` runs from the first `startTime` to the first `processingStart`, `processingTime` to the last `processingEnd`, and `presentationDelay` from there to the paint (`startTime + duration`, never below zero). The interaction is reported under the event whose handler ran longest, or under the `click` or `keydown` when no handler took a millisecond more than theirs; `worstEvent`, the Interactions `type` and the Input-Latency-Breakdown event type follow that rule.
 
 `getINPDetails()` returns the 15 slowest interactions, slowest first, with the total in `count`. `target` is a CSS selector built like `details.element` of LCP, or `null` when the browser reports no target. Use it when `getINP()` shows poor INP and you need to identify patterns across multiple slow interactions. With no interactions yet it returns `status: "tracking"`, a `message`, `count: 0` and no items.
@@ -806,6 +826,49 @@ Issues keep `{ severity, message }`. The fix is the last sentence of the message
 }
 ```
 
+#### CSS-Complexity
+
+Reads the CSSOM of every stylesheet of the page: of the document, adopted, in open shadow roots and imported with `@import`. One item per stylesheet, the most embedded bytes first, with `read: "cssom"`; `read: "fetched"` for a stylesheet of another origin whose rules the page cannot read and `fetch` can, as with `Access-Control-Allow-Origin` and a `<link>` without `crossorigin`, parsed with the same CSSOM, its `@import` rules included; or `read: "unreadable"` and only its `source` when neither works, which sets `corsLimitedAnalysis: true`. `source` is the URL of the sheet, or a label such as `<style> #1` or `adopted stylesheet #1`. A stylesheet a browser extension links to the page (`chrome-extension:`, `moz-extension:`, `safari-web-extension:`) is left out and counted in `details.extensionCount`; the `<style>` elements and shadow roots an extension injects cannot be told apart from those of the page, so in a browser with extensions, as with Chrome DevTools MCP connected to the user's Chrome, the counts can include them.
+
+`details` counts what the CSSOM keeps of the CSS as written, as [css-analyzer](https://github.com/projectwallace/css-analyzer) counts its text: rules (style rules, nested and inside at-rules), selectors (each one of a list), declarations (also those of `@font-face` and `@keyframes`), embedded content (`data:` URLs, in characters, and by MIME type), `@import` rules, empty rules, `!important` declarations, `@font-face` and `@keyframes` rules. `selectorUniqueness` is unique selectors over all selectors, without their context, so a selector repeated in two `@media` counts as repeated (1 without selectors). `unusedKeyframes` lists the `@keyframes` that no `animation` or `animation-name` of the stylesheets or of a `style` attribute names. `maxSelectorComplexity` and `commonSelectorComplexity` (the mode, or the mean of the tied values) give the complexity of the selectors as css-analyzer computes it, and `complexSelectors` the 5 most complex, as `{ selectorText, complexity }`: `selectorText` is the selector of a rule, not of an element of the page. The CSSOM drops comments, hacks, invalid declarations and rules with unsupported selectors, and writes a few shorthands as longhands, so these counts can differ slightly from those of the text.
+
+```json
+{
+  "script": "CSS-Complexity",
+  "status": "ok",
+  "count": 2,
+  "corsLimitedAnalysis": false,
+  "details": {
+    "stylesheetCount": 2,
+    "extensionCount": 0,
+    "unreadableCount": 0,
+    "fetchedCount": 1,
+    "ruleCount": 812,
+    "selectorCount": 1104,
+    "declarationCount": 2210,
+    "embeddedBytes": 41210,
+    "embeddedCount": 12,
+    "embeddedTypes": [{ "type": "font/woff2", "count": 2, "bytes": 38090 }, { "type": "image/svg+xml", "count": 10, "bytes": 3120 }],
+    "importCount": 1,
+    "emptyRuleCount": 14,
+    "selectorUniqueness": 0.81,
+    "importantCount": 51,
+    "importantPercent": 2.3,
+    "fontFaceCount": 8,
+    "keyframesCount": 9,
+    "unusedKeyframes": ["spin-old"],
+    "maxSelectorComplexity": 18,
+    "commonSelectorComplexity": 1,
+    "complexSelectors": [{ "selectorText": ".nav > ul li:not(.active) a[href^=\"http\"]", "complexity": 11 }]
+  },
+  "items": [
+    { "source": "https://example.com/app.css", "read": "cssom", "ruleCount": 790, "embeddedBytes": 41210, "importCount": 1, "importantCount": 48 },
+    { "source": "https://cdn.example.com/vendor.css", "read": "fetched", "ruleCount": 22, "embeddedBytes": 0, "importCount": 0, "importantCount": 3 }
+  ],
+  "issues": [{ "code": "import", "severity": "warning", "message": "https://example.com/app.css imports https://cdn.example.com/vendor.css with @import: ...", "target": "https://cdn.example.com/vendor.css" }]
+}
+```
+
 #### CSS-Media-Queries-Analysis
 
 One item per distinct media query that targets viewports wider than `details.minWidth`, largest first. `details` gives the totals, `totalUnique` and `uniquenessRatio`, and `bySource` breaks the rules down by stylesheet.
@@ -853,6 +916,8 @@ With no usage the script returns `count: 0`, no items and an `info` issue.
 
 Tracking scripts return `status: "tracking"` first. The function named by `getDataFn` returns the full result. Items are capped at 50 (20 for frames) and sorted by relevance; `count` holds the total.
 
+Interactions and Input-Latency-Breakdown read `first-input` as INP does, so an interaction that paints nothing counts when it is the first one, and the later ones under 16 ms have no entry.
+
 #### Interactions (tracking)
 
 ```json
@@ -1202,6 +1267,12 @@ Every issue has a `code` that says what it is, so a comparison pairs the issues
 
 An issue about one thing among several, one issue per thing, also names it in `target`: the URL of a resource, a CSS selector, or a name such as an event type or a CSS property. Two issues with the same code and different targets are two issues.
 
+### INP
+
+| Code | Severity | When |
+|------|----------|------|
+| `no-paint-measured` | info | The worst interaction took under 16 ms, too short for a frame, so the page most likely painted nothing after it |
+
 ### LCP-Image-Entropy
 
 | Code | Severity | When |
@@ -1237,6 +1308,21 @@ An issue about one thing among several, one issue per thing, also names it in `t
 | `could-defer` | info | Blocking scripts other than the last three of `<body>`, which could try `defer` |
 | `unknown-size` | info | Scripts whose size is hidden by a missing `Timing-Allow-Origin`, so the total is a lower bound |
 
+### CSS-Complexity
+
+| Code | Severity | When |
+|------|----------|------|
+| `embedded-font` | warning | A stylesheet embeds a font as a `data:` URL; `target` is the stylesheet |
+| `embedded-content` | warning | The `data:` URLs of all the CSS add up to more than 36.6 kB, the 90th percentile of homepages in The CSS Selection 2026 |
+| `import` | warning | An `@import` rule, one issue per rule; `target` is the URL it imports |
+| `empty-rules` | info | One or more style rules without declarations |
+| `duplicate-selectors` | info | Fewer than 66% of the selectors are unique, the threshold of css-code-quality |
+| `important-ratio` | info | More than 13% of the declarations use `!important`, the 90th percentile of homepages |
+| `font-face-count` | info | More than 48 `@font-face` rules, the 90th percentile of homepages |
+| `unused-keyframes` | info | A `@keyframes` that no animation of the stylesheets or of a `style` attribute uses, only when every stylesheet could be read; `target` is its name |
+| `selector-complexity` | info | A selector among the 5 most complex with a complexity above 29, the 90th percentile of the most complex selector of homepages; `target` is the selector of the rule |
+| `unreadable-stylesheets` | info | Cross-origin stylesheets whose rules the page cannot read and `fetch` cannot either |
+
 ### CSS-Media-Queries-Analysis
 
 | Code | Severity | When |

package/src/baseline.js

@@ -204,8 +204,32 @@ function machineWarning(base, current) {
   return `the baseline was measured on another machine (${base.cpu}, ${base.cores} cores) than this run (${current.cpu}, ${current.cores} cores); timings can differ for that alone`;
 }
 
-// What differs in how both were measured. The comparison goes on: the warnings say how far to trust it.
-function warningsOf(base, current) {
+const valueCount = (payload, metric) => measured(payload, metric).values?.length ?? 1;
+
+// Why five runs can leave four values, when a run failed; a run that missed a metric alone does not count
+function afterFailedRuns(payload) {
+  const failed = payload.runs?.failed ?? 0;
+  return failed ? ` after ${failed} failed run${failed === 1 ? "" : "s"}` : "";
+}
+
+// The metrics compared on both sides that have no statistics, one line for each set of numbers. A
+// metric that one side lacks has no comparison to back, and its verdict already says "not measured".
+function statisticsWarnings(base, current, metrics) {
+  const metricsByNumbers = new Map();
+  for (const [metric, { stats, verdict }] of Object.entries(metrics)) {
+    if (stats || verdict === "not measured") continue;
+    const inBase = valueCount(base, metric);
+    const numbers = `the baseline has ${inBase} value${inBase === 1 ? "" : "s"}${afterFailedRuns(base)}, and this run ${valueCount(current, metric)}${afterFailedRuns(current)}`;
+    metricsByNumbers.set(numbers, [...(metricsByNumbers.get(numbers) ?? []), metric]);
+  }
+  return [...metricsByNumbers].map(
+    ([numbers, names]) => `no statistics for ${names.join(", ")}: ${numbers}; they need ${RUNS_FOR_STATISTICS} a side, so measure both with ${RUNS_FOR_STATISTICS} runs or more`
+  );
+}
+
+// What differs in how both were measured, and what it cost. The comparison goes on: the warnings say
+// how far to trust it.
+function warningsOf(base, current, metrics) {
   const warnings = [];
   const b = base.conditions;
   const c = current.conditions;
@@ -221,7 +245,10 @@ function warningsOf(base, current) {
   }
   // In words for both: the CLI asks for runs with --runs, and the tools of the MCP server with runs
   if (runCount(base) < 2) warnings.push(`the baseline has 1 run, so only the thresholds apply; measure both with ${RUNS_FOR_STATISTICS} runs or more`);
-  else if (runCount(base) !== runCount(current)) warnings.push(`the baseline has ${runCount(base)} runs, and this run ${runCount(current)}`);
+  else {
+    if (runCount(base) !== runCount(current)) warnings.push(`the baseline has ${runCount(base)} runs, and this run ${runCount(current)}`);
+    warnings.push(...statisticsWarnings(base, current, metrics));
+  }
   const machine = machineWarning(b?.machine, c?.machine);
   if (machine) warnings.push(machine);
   if (b && c && b.cliVersion !== c.cliVersion) {
@@ -235,13 +262,14 @@ function warningsOf(base, current) {
 // A page against its baseline, as the `baseline` field of its JSON. The runs of the baseline say how
 // much to trust its values, in the header of the reports.
 export function compareRun(base, current, { file, thresholds = DEFAULT_THRESHOLDS }) {
+  const metrics = compareMetrics(base, current, thresholds);
   return {
     file,
     url: base.url,
     runs: base.runs ? { count: base.runs.count, medianBy: base.runs.medianBy } : { count: 1 },
-    metrics: compareMetrics(base, current, thresholds),
+    metrics,
     errors: compareErrors(base, current),
-    warnings: warningsOf(base, current),
+    warnings: warningsOf(base, current, metrics),
   };
 }
 

package/src/bin.js

@@ -40,7 +40,7 @@ Options:
   --workflow <name>     Workflow to run (default: core-web-vitals)
                         Workflows: core-web-vitals, audit, loading, interaction
   --snippet <name>      Run a single snippet by name, alias or Category/Name path
-                        Any of the 56 snippets, such as Compression-Audit
+                        Any of the 57 snippets, such as Compression-Audit
                         Aliases: LCP, CLS, INP, LCP-Subparts, fonts,
                                  render-blocking, resource-hints, preload-scripts,
                                  priority-hints, critical-css, ttfb,
@@ -89,6 +89,7 @@ Options:
   --verbose             Show all items, even for passing checks
   --headed              Show the browser window (debug)
   -h, --help            Show this help
+  -v, --version         Show the version
 
 Examples:
   npx webperf-snippets https://example.com
@@ -182,6 +183,7 @@ async function main() {
         verbose: { type: "boolean" },
         headed: { type: "boolean" },
         help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
       },
       allowPositionals: true,
     });
@@ -196,6 +198,11 @@ async function main() {
     return;
   }
 
+  if (values.version) {
+    process.stdout.write(`${cliVersion}\n`);
+    return;
+  }
+
   const url = positionals[0];
   const matrixPath = values.matrix;
   if (url && matrixPath) fail("Use a URL or --matrix, not both");

package/src/mcp/queue.js

@@ -0,0 +1,72 @@
+// The reason of an abort is whatever the client sent, often a string, or nothing: a caller gets an error
+const gaveUp = () => new Error("The caller gave up while it waited for its turn");
+
+// One task at a time, in the order they arrive. A caller that gives up while it waits leaves the line
+// at once, so it never runs and holds up no one. A task that fails passes the turn like any other, and
+// its failure stays with its caller.
+//
+// A waiting caller hears how many tasks are ahead when it starts to wait, whenever the line moves, and
+// every `reportEveryMs` while it does not: a client can restart its timeout on each report, and a task
+// ahead can take minutes.
+export function createQueue({ reportEveryMs = 5000 } = {}) {
+  const waiting = [];
+  let taken = false;
+
+  // A report is a courtesy: one that fails, as one to a client that left, changes nothing
+  const report = async ({ onWait }, ahead) => {
+    try {
+      await onWait?.(ahead);
+    } catch {
+      // nothing to tell, and no one to tell it to
+    }
+  };
+  const reportAll = () => waiting.forEach((waiter, i) => report(waiter, i + 1));
+
+  function take({ signal, onWait }) {
+    if (signal?.aborted) return Promise.reject(gaveUp());
+    if (!taken) {
+      taken = true;
+      return Promise.resolve();
+    }
+    return new Promise((resolve, reject) => {
+      const waiter = { onWait };
+      const leave = () => {
+        waiting.splice(waiting.indexOf(waiter), 1);
+        clearInterval(timer);
+        signal?.removeEventListener("abort", cancel);
+      };
+      const cancel = () => {
+        leave();
+        reject(gaveUp());
+        reportAll();
+      };
+      waiter.enter = () => {
+        leave();
+        resolve();
+      };
+      const timer = setInterval(() => report(waiter, waiting.indexOf(waiter) + 1), reportEveryMs);
+      // The timer alone must not keep the process alive
+      timer.unref?.();
+      signal?.addEventListener("abort", cancel, { once: true });
+      waiting.push(waiter);
+      report(waiter, waiting.length);
+    });
+  }
+
+  function pass() {
+    taken = waiting.length > 0;
+    waiting[0]?.enter();
+    reportAll();
+  }
+
+  async function run(task, options = {}) {
+    await take(options);
+    try {
+      return await task();
+    } finally {
+      pass();
+    }
+  }
+
+  return { run };
+}

package/src/mcp/server.js

@@ -10,6 +10,7 @@ import { RULES } from "../decision-tree.js";
 import { fetchCrux, fetchCruxHistory } from "../crux.js";
 import { runInteractions, isInputStep, settle } from "../interactions.js";
 import { createSessions, SessionError } from "./sessions.js";
+import { createQueue } from "./queue.js";
 import { launchChromium, isMissingBrowser, MISSING_BROWSER } from "../browser.js";
 import { registerResources } from "./documents.js";
 import { registerPrompts } from "./prompts.js";
@@ -24,6 +25,10 @@ import { MAX_RUNS, measureRuns } from "../runs.js";
 const VIEWPORTS = Object.keys(VIEWPORT_PRESETS);
 const STAGES = 3;
 const NAV_TIMEOUT_MS = 30000;
+// How long a page load can keep its turn: far beyond the load and the wait, which have their own limits
+// (30 s and 10 s), because a run that reaches this is not slow. A page whose main thread never yields
+// answers no evaluation, and Playwright has no timeout for one, so it would hold up the queue for ever.
+const CALL_LIMIT_MS = 120000;
 
 const HttpUrl = z
   .string()
@@ -111,6 +116,7 @@ const NextSteps = z
 const DETAIL_NOTE =
   "Large results come as summaries with a runId for get_details; nextSteps, when present, is the call to make next.";
 const BASELINE_NOTE = "With baseline, it also compares the run with an earlier one, as --baseline of the CLI, and says what regressed.";
+const QUEUE_NOTE = "Measurements run one at a time, so several in one turn save no time.";
 
 // A page can put instructions for the agent in what a snippet returns: an alt text, a class in a
 // selector, the URL of a script. The tools that return what a page holds say how to read it, and so
@@ -162,12 +168,44 @@ function progressFor(ctx, runs) {
         });
 }
 
+// The report of a call that waits for its turn, for a client that wants progress: how many calls are
+// ahead. Progress has to grow with each report, and the stages of a run start at 1, so it stays below 1.
+function waitProgressFor(ctx, total) {
+  const progressToken = ctx.mcpReq._meta?.progressToken;
+  if (progressToken === undefined) return undefined;
+  let reports = 0;
+  return (ahead) => {
+    reports++;
+    const message = `Waiting for its turn: ${ahead} ${ahead === 1 ? "call" : "calls"} ahead`;
+    return ctx.mcpReq.notify({ method: "notifications/progress", params: { progressToken, progress: reports / (reports + 1), ...(total ? { total } : {}), message } });
+  };
+}
+
+const stoppedAnswering = (limitMs) => `The page did not answer within ${limitMs / 1000} seconds`;
+
+// A page that stopped answering is closed, and the runs left of the call would only hold up the queue
+class PageStoppedError extends Error {}
+const endsTheCall = (err) => isMissingBrowser(err) || err instanceof PageStoppedError;
+
 // A page load measured once, or `count` times with the median run as the answer, as --runs of the CLI.
-// When the client gives up (a cancel, its timeout, or leaving), the runs left never start.
-async function measurePage(measure, count, ctx) {
+// `measure` gets the signal of its run, which closes its Chromium. When the client gives up (a cancel,
+// its timeout, or leaving), the run in progress ends and the runs left never start.
+async function measurePage(measure, count, ctx, limitMs) {
   const progress = progressFor(ctx, count);
-  if (count === 1) return measure(progress(1));
-  const { payload, runs, errors } = await measureRuns((i) => measure(progress(i)), count, { isFatal: isMissingBrowser, signal: ctx.mcpReq.signal });
+  const measureRun = async (run) => {
+    const limit = AbortSignal.timeout(limitMs);
+    let measured;
+    try {
+      measured = await measure(progress(run), AbortSignal.any([ctx.mcpReq.signal, limit]));
+    } catch (err) {
+      if (!limit.aborted) throw err;
+    }
+    // The runner keeps a failed evaluation as a result, and closing Chromium fails every one
+    if (limit.aborted) throw new PageStoppedError(stoppedAnswering(limitMs));
+    return measured;
+  };
+  if (count === 1) return measureRun(1);
+  const { payload, runs, errors } = await measureRuns(measureRun, count, { isFatal: endsTheCall, signal: ctx.mcpReq.signal });
   if (!payload) throw new Error(`Every run failed: ${[...new Set(errors.map(firstLine))].join("; ")}`);
   return { ...payload, runs };
 }
@@ -224,10 +262,18 @@ function registerRuns(server, runs) {
 
 // The MCP server of the CLI: the same snippets and runner, offered as tools an agent calls by name.
 // serveStdio creates one instance per connection, so the pages it keeps open belong to that client.
-export function createServer({ launchBrowser = () => launchChromium(), maxPages, idleMs, env = process.env, machine = machineOf } = {}) {
+export function createServer({ launchBrowser = () => launchChromium(), maxPages, idleMs, env = process.env, machine = machineOf, callLimitMs = CALL_LIMIT_MS, reportEveryMs } = {}) {
   const server = new McpServer({ name: "webperf-snippets", version: cliVersion }, { instructions: INSTRUCTIONS });
   const sessions = createSessions({ launchBrowser, maxPages, idleMs });
   const runs = createRuns();
+  // An agent sends several calls in one turn and the client runs them at once. The calls that make a page
+  // work take turns (run_snippet, run_workflow, open_page, interact): a load or a click competes for the
+  // CPU with any other, which inflates what each page reports. A call keeps its turn only while it runs,
+  // so it can wait only for something that ends on its own: never for a later call of the agent, and
+  // never for a page left open, which keeps no turn. read_results and close_page take no turn: they ask
+  // little of Chromium, and they are how an agent gets out of a page.
+  const queue = createQueue({ reportEveryMs });
+  const inTurn = (ctx, total, task) => queue.run(task, { signal: ctx.mcpReq.signal, onWait: waitProgressFor(ctx, total) });
   // The client left (end of stdin, or a closed transport): close the pages and Chromium
   server.server.onclose = () => sessions.closeAll();
   registerResources(server);
@@ -235,10 +281,13 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
   registerRuns(server, runs);
 
   // The machine goes in the conditions of every run, as in the JSON of the CLI, so a baseline measured
-  // on another one warns. It is measured once, with the first run, before its Chromium starts.
+  // on another one warns. It is measured once, in the turn of the first run, before its Chromium starts.
   let machineOfServer;
   const conditionsOf = (conditions) => measurementConditions({ ...conditions, machine: (machineOfServer ??= machine()) });
 
+  const measureInTurn = (conditions, measure, count, ctx) =>
+    inTurn(ctx, STAGES * count, async () => ({ conditions: conditionsOf(conditions), run: await measurePage(measure, count, ctx, callLimitMs) }));
+
   // A run of a page load, kept with its page in the shape of the JSON of the CLI: its runId is the
   // baseline of a later run, and the resources list it
   const keepPage = (run, results, conditions) => {
@@ -292,7 +341,7 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
     {
       title: "Run a snippet",
       description:
-        `Opens the URL in a headless Chromium, runs one web performance snippet on the loaded page and returns the object the snippet returns, as defined in snippets/SCHEMA.md. Use list_snippets for the names. The snippets that record interactions (INP, Interactions, Input-Latency-Breakdown) run on a page opened with open_page instead. ${BASELINE_NOTE} ${DETAIL_NOTE} ${PAGE_DATA}`,
+        `Opens the URL in a headless Chromium, runs one web performance snippet on the loaded page and returns the object the snippet returns, as defined in snippets/SCHEMA.md. Use list_snippets for the names. The snippets that record interactions (INP, Interactions, Input-Latency-Breakdown) run on a page opened with open_page instead. ${QUEUE_NOTE} ${BASELINE_NOTE} ${DETAIL_NOTE} ${PAGE_DATA}`,
       inputSchema: z.object({
         url: HttpUrl,
         snippet: z.string().describe("The snippet: its name (LCP-Subparts), an alias (render-blocking) or Category/Name"),
@@ -337,8 +386,12 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
       }
 
       try {
-        const conditions = conditionsOf({ viewport, snippet: path, waitMs });
-        const run = await measurePage((onProgress) => runSnippets({ url, items: [{ id: path, path, source }], waitMs, viewport: VIEWPORT_PRESETS[viewport], onProgress }), count, ctx);
+        const { conditions, run } = await measureInTurn(
+          { viewport, snippet: path, waitMs },
+          (onProgress, signal) => runSnippets({ url, items: [{ id: path, path, source }], waitMs, viewport: VIEWPORT_PRESETS[viewport], onProgress, signal }),
+          count,
+          ctx
+        );
         const shaped = shapeResults(run.results.map(({ id, ...result }) => result), detail);
         const { runId, current } = keepPage(run, run.results, conditions);
         const id = run.results[0].id;
@@ -369,7 +422,7 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
     {
       title: "Run a workflow",
       description:
-        `Opens the URL in a headless Chromium and runs a workflow: a sequence of snippets plus the follow-ups its decision tree adds from the results (for example LCP-Subparts when LCP is over 2.5 s, with the reason). core-web-vitals: LCP and CLS. audit: render-blocking resources, resource hints, critical CSS, TTFB, scripts, images and more. loading: TTFB, FCP, render-blocking, scripts and fonts. interaction: long tasks, animation frames, scroll and layout shifts while it scrolls the page. ${BASELINE_NOTE} ${DETAIL_NOTE} ${PAGE_DATA}`,
+        `Opens the URL in a headless Chromium and runs a workflow: a sequence of snippets plus the follow-ups its decision tree adds from the results (for example LCP-Subparts when LCP is over 2.5 s, with the reason). core-web-vitals: LCP and CLS. audit: render-blocking resources, resource hints, critical CSS, TTFB, scripts, images and more. loading: TTFB, FCP, render-blocking, scripts and fonts. interaction: long tasks, animation frames, scroll and layout shifts while it scrolls the page. ${QUEUE_NOTE} ${BASELINE_NOTE} ${DETAIL_NOTE} ${PAGE_DATA}`,
       inputSchema: z.object({
         url: HttpUrl,
         workflow: z.enum(Object.keys(WORKFLOWS)).default("core-web-vitals"),
@@ -405,9 +458,9 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
         return toolError(err.message);
       }
       try {
-        const conditions = conditionsOf({ viewport, workflow, waitMs });
-        const run = await measurePage(
-          (onProgress) => runMeasurement({ url, workflow: WORKFLOWS[workflow], rules: RULES, waitMs, viewport: VIEWPORT_PRESETS[viewport], onProgress }),
+        const { conditions, run } = await measureInTurn(
+          { viewport, workflow, waitMs },
+          (onProgress, signal) => runMeasurement({ url, workflow: WORKFLOWS[workflow], rules: RULES, waitMs, viewport: VIEWPORT_PRESETS[viewport], onProgress, signal }),
           count,
           ctx
         );
@@ -537,27 +590,33 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
         items.push({ id: path, path, source });
       }
 
-      let session;
-      try {
-        session = await sessions.create({ viewport: VIEWPORT_PRESETS[viewport], signal: ctx.mcpReq.signal });
-      } catch (err) {
-        if (isMissingBrowser(err)) return toolError(MISSING_BROWSER);
-        throw err;
-      }
-      try {
-        const navStart = Date.now();
-        await session.page.goto(url, { waitUntil: "load", timeout: NAV_TIMEOUT_MS });
-        if (waitMs > 0) await session.page.waitForTimeout(waitMs);
-        const navMs = Date.now() - navStart;
-        session.tracking = await evaluateItems(session.page, items);
-        session.stopListening();
-        const tracking = session.tracking.map(({ id, status }) => ({ snippet: id, status }));
-        return toolResult({ sessionId: session.id, url, viewport, navMs, tracking });
-      } catch (err) {
-        await sessions.close(session.id);
-        if (/page\.goto/.test(err.message)) return toolError(`Could not load ${url}: ${firstLine(err.message)}`);
-        return toolError(`Opening the page failed: ${firstLine(err.message)}`);
-      }
+      return inTurn(ctx, undefined, async () => {
+        const limit = AbortSignal.timeout(callLimitMs);
+        let session;
+        try {
+          session = await sessions.create({ viewport: VIEWPORT_PRESETS[viewport], signal: AbortSignal.any([ctx.mcpReq.signal, limit]) });
+        } catch (err) {
+          if (isMissingBrowser(err)) return toolError(MISSING_BROWSER);
+          throw err;
+        }
+        try {
+          const navStart = Date.now();
+          await session.page.goto(url, { waitUntil: "load", timeout: NAV_TIMEOUT_MS });
+          if (waitMs > 0) await session.page.waitForTimeout(waitMs);
+          const navMs = Date.now() - navStart;
+          session.tracking = await evaluateItems(session.page, items);
+          // evaluateItems keeps a failed evaluation as a result, and closing the page fails every one
+          if (limit.aborted) return toolError(`Opening the page failed: ${stoppedAnswering(callLimitMs)}`);
+          session.stopListening();
+          const tracking = session.tracking.map(({ id, status }) => ({ snippet: id, status }));
+          return toolResult({ sessionId: session.id, url, viewport, navMs, tracking });
+        } catch (err) {
+          await sessions.close(session.id);
+          if (limit.aborted) return toolError(`Opening the page failed: ${stoppedAnswering(callLimitMs)}`);
+          if (/page\.goto/.test(err.message)) return toolError(`Could not load ${url}: ${firstLine(err.message)}`);
+          return toolError(`Opening the page failed: ${firstLine(err.message)}`);
+        }
+      });
     })
   );
 
@@ -575,16 +634,28 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
       // A click can submit a form or change data on the site, so this tool is not read-only
       annotations: { readOnlyHint: false, openWorldHint: true },
     },
-    withSession(async ({ sessionId, steps }) => {
-      const session = sessions.get(sessionId);
-      try {
-        await runInteractions(session.page, steps);
-      } catch (err) {
-        return toolError(`A step failed: ${firstLine(err.message)}`);
-      }
-      session.hadInput ||= steps.some(isInputStep);
-      await settle(session.page);
-      return toolResult({ sessionId, steps: steps.length, url: session.page.url() });
+    withSession(async ({ sessionId, steps }, ctx) => {
+      // A page that is not open answers now, not after a turn it does not need
+      sessions.get(sessionId);
+      return inTurn(ctx, undefined, async () => {
+        const session = sessions.get(sessionId);
+        // A wait step is time the agent asked for. Closing the page fails whatever it stopped answering.
+        const limitMs = callLimitMs + steps.reduce((sum, step) => sum + (step.ms ?? 0), 0);
+        const limit = AbortSignal.timeout(limitMs);
+        const closePage = () => sessions.close(sessionId);
+        limit.addEventListener("abort", closePage, { once: true });
+        try {
+          await runInteractions(session.page, steps);
+          session.hadInput ||= steps.some(isInputStep);
+          await settle(session.page);
+          if (!limit.aborted) return toolResult({ sessionId, steps: steps.length, url: session.page.url() });
+        } catch (err) {
+          if (!limit.aborted) return toolError(`A step failed: ${firstLine(err.message)}`);
+        } finally {
+          limit.removeEventListener("abort", closePage);
+        }
+        return toolError(`${stoppedAnswering(limitMs)}, and it was closed. Open it again with open_page.`);
+      });
     })
   );
 
@@ -593,7 +664,7 @@ export function createServer({ launchBrowser = () => launchChromium(), maxPages,
     {
       title: "Read the tracking snippets",
       description:
-        `Returns what the tracking snippets installed by open_page have recorded on the page so far, as the objects they return. A snippet with nothing recorded yet, such as INP before any interaction, answers with status tracking and a message: interact with the page and read again. ${DETAIL_NOTE} ${PAGE_DATA}`,
+        `Returns what the tracking snippets installed by open_page have recorded on the page so far, as the objects they return. A snippet with nothing recorded yet, such as INP before any interaction, answers with status tracking and a message: interact with the page and read again. After a click or key press that the document did not record, as one inside an iframe, it is an error that says so: interact with an element of the page and read again. ${DETAIL_NOTE} ${PAGE_DATA}`,
       inputSchema: z.object({ sessionId: SessionId, detail: Detail }),
       outputSchema: z.object({ sessionId: z.string(), runId: SummaryRunId, detail: DetailOut, pageErrors: z.array(z.string()), results: z.array(SnippetResult) }),
       annotations: { readOnlyHint: true, openWorldHint: false },

package/src/runner.js

@@ -21,6 +21,13 @@ const DEFAULT_NAV_TIMEOUT = 30000;
 const LATE_ENTRIES_MS = 2000;
 const POLL_MS = 100;
 
+// A snippet still tracking after that wait has seen no interaction at all, and the browser agrees: a
+// click that paints nothing is recorded too. The measurement failed, so the result is an error, which
+// exits with 1, instead of the message of the snippet (click on the page, then call the function
+// again), which would ask for what the run has just done.
+const NOTHING_RECORDED =
+  "A click or key press was sent, and this document recorded no interaction. Check that it reaches an element of this document: an interaction inside an iframe is recorded by the iframe.";
+
 // Snippets are IIFEs. Playwright evaluates a string as an expression, so we
 // trim trailing semicolons to keep the IIFE call as a single expression and
 // recover its return value in Node.
@@ -83,13 +90,28 @@ export async function collectTrackingData(page, result, hasInput) {
       await page.waitForTimeout(POLL_MS);
       data = await read();
     }
-    if (data && typeof data === "object") return { id: result.id, ...data };
+    if (data && typeof data === "object") {
+      if (hasInput && data.status === "tracking") {
+        return { id: result.id, script: data.script, status: "error", error: NOTHING_RECORDED };
+      }
+      return { id: result.id, ...data };
+    }
     return { id: result.id, status: "error", error: `${result.getDataFn}() did not return an object` };
   } catch (err) {
     return { id: result.id, status: "error", error: `${result.getDataFn}() failed: ${err.message}` };
   }
 }
 
+// An aborted signal closes Chromium, which fails whatever the run is waiting for, a page that stopped
+// answering included: Playwright has no timeout for an evaluation. Returns what stops listening.
+function closeOnAbort(browser, signal) {
+  if (!signal) return () => {};
+  const close = () => browser.close().catch(() => {});
+  if (signal.aborted) close();
+  signal.addEventListener("abort", close, { once: true });
+  return () => signal.removeEventListener("abort", close);
+}
+
 export async function runSnippets({
   url,
   items,
@@ -106,9 +128,11 @@ export async function runSnippets({
   ownDomains,
   // Called at each of the three stages of a run, for callers that report progress (the MCP server)
   onProgress = () => {},
+  signal,
 }) {
   await onProgress(1, "Opening Chromium");
   const browser = await launchChromium({ headless });
+  const stopListening = closeOnAbort(browser, signal);
   try {
     const context = await browser.newContext({ viewport, storageState });
     const page = await context.newPage();
@@ -126,6 +150,7 @@ export async function runSnippets({
     await onProgress(3, "Snippets evaluated");
     return { url, navMs, results, pageErrors, throttling: throttlingOf({ cpu, network }) };
   } finally {
+    stopListening();
     await browser.close();
   }
 }
@@ -146,9 +171,11 @@ export async function runMeasurement({
   network,
   ownDomains,
   onProgress = () => {},
+  signal,
 }) {
   await onProgress(1, "Opening Chromium");
   const browser = await launchChromium({ headless });
+  const stopListening = closeOnAbort(browser, signal);
   try {
     const context = await browser.newContext({ viewport, storageState });
     const page = await context.newPage();
@@ -212,6 +239,7 @@ export async function runMeasurement({
     await onProgress(3, "Workflow and follow-ups evaluated");
     return { url, navMs, results: [...initialResults, ...followUpResults], pageErrors, throttling: throttlingOf({ cpu, network }) };
   } finally {
+    stopListening();
     await browser.close();
   }
 }