webperf-snippets 0.4.0 → 0.4.1

package/README.md

@@ -77,6 +77,8 @@ npx webperf-snippets https://web.dev --snippet Interaction/Interactions --intera
 
 The Interaction snippets (`Interactions`, `Input-Latency-Breakdown`, `LongTask`, `Forced-Synchronous-Layout`...) are installed before the first step and read after the last one, so their result holds what the steps caused.
 
+The CLI waits for the browser to report the timing of the last interaction before it reads the snippets. A script that ends right after a click still reads the page before anything the click sets in motion later has happened, such as a request or an animation, so end it with a `wait` step when you want to measure that.
+
 Interaction audit (long tasks, long animation frames, scroll, layout shifts, forced layouts, interaction latency). It scrolls the page, or runs your `--interact-script`; the steps that need a click are skipped when the script has none:
 
 ```bash
@@ -132,7 +134,7 @@ 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": "0.4.0" }
+  "meta": { "viewport": "mobile", "waitMs": 3000, "cli_version": "0.4.1" }
 }
 ```
 

package/package.json

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

package/src/interactions.js

@@ -38,3 +38,30 @@ export async function runInteractions(page, source) {
     await executeStep(page, step);
   }
 }
+
+// The browser reports the timing of an event after the frame that follows it, and an observer gets it
+// in a task after that frame. Reading a snippet right after the last step can miss that step, so this
+// waits for two frames and a task, which takes a few milliseconds on a page that renders. A page that
+// never renders a frame stops the wait at `limitMs`, and a page that is gone is not an error here: the
+// evaluation that follows reports it.
+export async function settle(page, limitMs = 1000) {
+  try {
+    await page.evaluate(
+      (limit) =>
+        new Promise((resolve) => {
+          const timer = setTimeout(resolve, limit);
+          requestAnimationFrame(() =>
+            requestAnimationFrame(() =>
+              setTimeout(() => {
+                clearTimeout(timer);
+                resolve();
+              }, 0)
+            )
+          );
+        }),
+      limitMs
+    );
+  } catch {
+    // the page navigated or closed
+  }
+}

package/src/runner.js

@@ -1,6 +1,6 @@
 import { chromium } from "playwright";
 import { loadSnippet } from "./load-snippet.js";
-import { runInteractions, loadInteractionSteps, isInputStep } from "./interactions.js";
+import { runInteractions, loadInteractionSteps, isInputStep, settle } from "./interactions.js";
 import { isTrackingSnippet } from "./tracking.js";
 import { nextSteps } from "./decision-tree.js";
 
@@ -42,14 +42,16 @@ async function evaluateItems(page, items) {
 
 // Runs the items around a set of interactions. A tracking snippet is installed first, so it sees
 // the interactions, and answers through its getDataFn afterwards. The other items run after the
-// interactions, as before. Results keep the order of the items. Without interactions every item
-// runs once, as it always did.
+// interactions, as before. The browser reports the timing of an interaction after the frame that
+// follows it, so the runner lets it settle before it reads anything. Results keep the order of the
+// items. Without interactions every item runs once, as it always did.
 async function evaluateAroundInteractions(page, items, interactions) {
   if (!interactions) return evaluateItems(page, items);
 
   const tracking = items.filter((item) => isTrackingSnippet(item.path ?? "", item.source));
   const installed = await evaluateItems(page, tracking);
   await runInteractions(page, interactions);
+  await settle(page);
   const others = await evaluateItems(
     page,
     items.filter((item) => !tracking.includes(item))

package/src/tracking.js

@@ -1,6 +1,6 @@
-// A tracking snippet installs observers and answers later through a window function named in
-// its result (getDataFn). The Interaction snippets work this way. CLS and INP also name a
-// getDataFn but answer with their value in one go, so only the Interaction category counts.
+// A tracking snippet installs observers and answers later through a window function named in its
+// result (getDataFn). The Interaction snippets work this way, and so does INP, whose value only
+// comes out of getINP(). CLS also names a getDataFn but answers with its value in one go.
 export function isTrackingSnippet(path, source) {
-  return path.startsWith("Interaction/") && source.includes("getDataFn");
+  return (path.startsWith("Interaction/") || path === "CoreWebVitals/INP") && source.includes("getDataFn");
 }