Apply suggestions from code review

Co-authored-by: Barry Pollard <barrypollard@google.com>

Author: nucliweb

skills/webperf-core-web-vitals/SKILL.md

@@ -28,12 +28,12 @@ Scripts fall into two execution patterns:
 
 Run via `evaluate_script` and return structured JSON immediately from buffered performance data. The page must have already loaded.
 
-### Tracking (INP)
+### Measuring (INP)
 
 INP requires real user interactions to measure. The workflow is:
 
-1. Run `INP.js` via `evaluate_script` → returns `{ status: "tracking", getDataFn: "getINP" }`
-2. **Tell the user:** "INP tracking is now active. Please interact with the page — click buttons, open menus, fill form fields — then let me know when you're done."
+1. Run `INP.js` via `evaluate_script` → returns `{ status: "measuring", getDataFn: "getINP" }`
+2. **Tell the user:** "INP measuring is now active. Please interact with the page — click buttons, open menus, fill form fields — then let me know when you're done."
 3. Wait for the user to confirm they've interacted.
 4. Call `evaluate_script("getINP()")` to collect results.
 5. If `getINP()` returns `status: "error"` → the user has not interacted yet. Remind them and wait.
@@ -50,15 +50,15 @@ When the user asks for a comprehensive Core Web Vitals analysis or "audit CWV":
 1. **LCP.js** - Measure Largest Contentful Paint
 2. **CLS.js** - Measure Cumulative Layout Shift
 3. **INP.js** - Measure Interaction to Next Paint
-4. **LCP-Sub-Parts.js** - Break down LCP timing phases
+4. **LCP-Subparts.js** - Break down LCP timing phases
 5. **LCP-Trail.js** - Track LCP candidate evolution
 
 ### LCP Deep Dive
 
 When LCP is slow or the user asks "debug LCP" or "why is LCP slow":
 
 1. **LCP.js** - Establish baseline LCP value
-2. **LCP-Sub-Parts.js** - Break down into TTFB, resource load, render delay
+2. **LCP-Subparts.js** - Break down into TTFB, resource load, render delay
 3. **LCP-Trail.js** - Identify all LCP candidates and changes
 4. **LCP-Image-Entropy.js** - Check if LCP image has visual complexity issues
 5. **LCP-Video-Candidate.js** - Detect if LCP is a video (poster or video element)
@@ -77,7 +77,7 @@ When layout shifts are detected or the user asks "debug CLS" or "layout shift is
 
 When interactions feel slow or the user asks "debug INP" or "slow interactions":
 
-1. **INP.js** - Start tracking. Tell the user to interact with the page and confirm when done.
+1. **INP.js** - Start measuring. Tell the user to interact with the page and confirm when done.
 2. Call `getINP()` to collect results once the user confirms.
 3. Call `getINPDetails()` to see all interactions ranked by duration.
 4. **Interactions.js** (from `webperf-interaction` skill) - List all interactions with timing
@@ -91,7 +91,7 @@ When LCP is a video element (detected by LCP-Video-Candidate.js):
 
 1. **LCP-Video-Candidate.js** - Identify video as LCP candidate
 2. **Video-Element-Audit.js** (from Media skill) - Audit video loading strategy
-3. **LCP-Sub-Parts.js** - Analyze video loading phases
+3. **LCP-Subparts.js** - Analyze video loading phases
 4. Cross-reference with **webperf-loading** skill:
    - Resource-Hints-Validation.js (check for video preload)
    - Priority-Hints-Audit.js (check for fetchpriority on video)
@@ -101,7 +101,7 @@ When LCP is a video element (detected by LCP-Video-Candidate.js):
 When LCP is an image (most common case):
 
 1. **LCP.js** - Measure LCP timing
-2. **LCP-Sub-Parts.js** - Break down timing phases
+2. **LCP-Subparts.js** - Break down timing phases
 3. **LCP-Image-Entropy.js** - Analyze image complexity
 4. Cross-reference with **webperf-media** skill:
    - Image-Element-Audit.js (check format, dimensions, lazy loading)
@@ -122,7 +122,7 @@ Use this decision tree to automatically run follow-up snippets based on results:
 - **If LCP candidate is a video** → Run **LCP-Video-Candidate.js** and **webperf-media:Video-Element-Audit.js**
 - **Always run** → **LCP-Trail.js** to understand candidate evolution
 
-### After LCP-Sub-Parts.js
+### After LCP-Subparts.js
 
 - **If TTFB phase > 600ms** → Switch to **webperf-loading** skill and run TTFB-Sub-Parts.js
 - **If Resource Load Time > 1500ms** → Run:

skills/webperf-core-web-vitals/references/schema.md

@@ -1,14 +1,14 @@
 # Script Return Value Schema
 
-All scripts return a structured JSON object as the IIFE return value. This allows agents using `evaluate_script` to read structured data directly from the return value, rather than parsing human-readable console output.
+All scripts return a structured JSON object as the return value. This allows agents using `evaluate_script` to read structured data directly from the return value, rather than parsing human-readable console output.
 
 ## Base Shape
 
 ```typescript
 {
   script: string;        // Script name, e.g. "LCP", "CLS", "INP"
   status: "ok"           // Script ran, has data
-       | "tracking"      // Observer active, data accumulates over time
+       | "monitoring"      // Observer active, data accumulates over time
        | "error"         // Failed or no data available
        | "unsupported";  // Browser API not supported
 
@@ -25,7 +25,7 @@ All scripts return a structured JSON object as the IIFE return value. This allow
   details?: object;
   issues?: Array<{ severity: "error" | "warning" | "info"; message: string }>;
 
-  // Tracking scripts
+  // Measurement scripts
   message?: string;
   getDataFn?: string;    // window function name: evaluate_script(`${getDataFn}()`)
 
@@ -37,18 +37,18 @@ All scripts return a structured JSON object as the IIFE return value. This allow
 ## Agent Workflow
 
 ```
-// Synchronous scripts (LCP, CLS, LCP-Sub-Parts, LCP-Trail, LCP-Image-Entropy, LCP-Video-Candidate)
+// Synchronous scripts (LCP, CLS, LCP-Subparts, LCP-Trail, LCP-Image-Entropy, LCP-Video-Candidate)
 result = evaluate_script(scriptCode)
 // → { status: "ok", value: 1240, rating: "good", ... }
 
-// Tracking scripts (INP)
+// Measurement scripts (INP)
 result = evaluate_script(INP_js)
-// → { status: "tracking", getDataFn: "getINP" }
+// → { status: "measuring", getDataFn: "getINP" }
 // (user interacts with the page)
 data = evaluate_script("getINP()")
 // → { status: "ok", value: 350, rating: "needs-improvement", ... }
 
-// CLS (hybrid: returns current value immediately, keeps tracking)
+// CLS (hybrid: returns current value immediately, keeps measuring)
 result = evaluate_script(CLS_js)
 // → { status: "ok", value: 0.05, rating: "good", message: "Call getCLS() for updated value" }
 // (after more page interactions)
@@ -58,11 +58,11 @@ data = evaluate_script("getCLS()")
 
 ## Making Decisions from Return Values
 
-- `rating === "good"` → no action needed for this metric
+- `rating === "good"` → metric meets recommended thresholds
 - `rating === "needs-improvement"` → investigate, check `details` and `issues`
 - `rating === "poor"` → high priority fix, check `issues` for specific problems
 - `status === "error"` → page may not have loaded yet, or metric has no data
-- `status === "tracking"` → call `evaluate_script(result.getDataFn + "()")` after interaction
+- `status === "measuring"` → call `evaluate_script(result.getDataFn + "()")` after interaction
 
 ## Script-Specific Schemas
 
@@ -82,13 +82,11 @@ data = evaluate_script("getCLS()")
   "script": "CLS", "status": "ok", "metric": "CLS",
   "value": 0.05, "unit": "score", "rating": "good",
   "thresholds": { "good": 0.1, "needsImprovement": 0.25 },
-  "message": "CLS tracking active. Call getCLS() for updated value after page interactions."
+  "message": "CLS measurement active. Call getCLS() for updated value after page interactions."
 }
 ```
 
-### INP (initial — tracking)
-```json
-{ "script": "INP", "status": "tracking", "message": "INP tracking active. Interact with the page then call getINP() for results.", "getDataFn": "getINP" }
+### INP (initial — measuring)
 ```
 `getINP()` returns (after interactions):
 ```json
@@ -111,15 +109,7 @@ data = evaluate_script("getCLS()")
 ]
 ```
 
-### LCP-Sub-Parts
-```json
-{
-  "script": "LCP-Sub-Parts", "status": "ok", "metric": "LCP",
-  "value": 2100, "unit": "ms", "rating": "needs-improvement",
-  "thresholds": { "good": 2500, "needsImprovement": 4000 },
-  "details": {
-    "element": "img.hero", "url": "hero.jpg",
-    "subParts": {
+### LCP-Subparts
       "ttfb": { "value": 450, "percent": 21, "overTarget": false },
       "resourceLoadDelay": { "value": 120, "percent": 6, "overTarget": false },
       "resourceLoadTime": { "value": 1200, "percent": 57, "overTarget": true },

skills/webperf-core-web-vitals/references/snippets.md

@@ -15,7 +15,7 @@ Quick check for Largest Contentful Paint, a Core Web Vital that measures loading
 ---
 ## Cumulative Layout Shift (CLS)
 
-Quick check for Cumulative Layout Shift, a Core Web Vital that measures visual stability. CLS tracks how much the page layout shifts unexpectedly during its lifetime, providing a single score that represents the cumulative impact of all unexpected layout shifts.
+Quick check for Cumulative Layout Shift, a Core Web Vital that measures visual stability. CLS tracks how much the page layout shifts unexpectedly during its lifetime, providing a single score that represents the worst batch impact of all unexpected layout shifts.
 
 **Script:** `scripts/CLS.js`
 
@@ -31,33 +31,33 @@ Quick check for Cumulative Layout Shift, a Core Web Vital that measures visual s
 ---
 ## Interaction to Next Paint (INP)
 
-Tracks Interaction to Next Paint, a Core Web Vital that measures responsiveness. INP evaluates how quickly a page responds to user interactions throughout the entire page visit, replacing First Input Delay (FID) as a Core Web Vital in March 2024.
+Tracks Interaction to Next Paint, a Core Web Vital that measures responsiveness. INP evaluates how quickly a page responds to user interactions throughout the entire page visit.
 
 **Script:** `scripts/INP.js`
 
-**Usage:** Run `INP.js` once to start tracking. It returns `status: "tracking"` immediately. After the user interacts with the page, call `getINP()` to retrieve the current INP value.
+**Usage:** Run `INP.js` once to start measuring. It returns `status: "measuring"` immediately. After the user interacts with the page, call `getINP()` to retrieve the current INP value.
 
 **Thresholds:**
 
 | Rating | Time | Meaning |
 |--------|------|---------|
-| 🟢 Good | ≤ 200ms | Responsive, feels instant |
+| 🟢 Good | ≤ 200ms | Responsive, feels responsive |
 | 🟡 Needs Improvement | ≤ 500ms | Noticeable delay |
 | 🔴 Poor | > 500ms | Slow, frustrating experience |
 ---
-## LCP Sub-Parts
+## LCP Subparts
 
 Breaks down Largest Contentful Paint into its four phases to identify optimization opportunities. Understanding which phase is slowest helps focus optimization efforts where they'll have the most impact.
 
-**Script:** `scripts/LCP-Sub-Parts.js`
+**Script:** `scripts/LCP-Subparts.js`
 
-**Sub-parts:**
+**Subparts:**
 
 | Phase | Target | Description |
 |-------|--------|-------------|
 | Time to First Byte (TTFB) | ≤ 800ms | Navigation start → first HTML byte |
 | Resource Load Delay | < 10% of LCP | TTFB → browser starts loading LCP resource |
-| Resource Load Time | ~40% of LCP | Time to download the LCP resource |
+| Resource Load Duration | ~40% of LCP | Time spent waiting for the downloading of the LCP resource |
 | Element Render Delay | < 10% of LCP | Resource downloaded → LCP element rendered |
 ---
 ## LCP Trail

skills/webperf-core-web-vitals/scripts/CLS.js

@@ -39,6 +39,6 @@
     unit: "score",
     rating: valueToRating(clsSync),
     thresholds: { good: 0.1, needsImprovement: 0.25 },
-    message: "CLS tracking active. Call getCLS() for updated value after page interactions.",
+    message: "CLS measurement active. Call getCLS() for updated value after page interactions.",
   };
 })();

skills/webperf-core-web-vitals/scripts/INP.js

@@ -29,7 +29,7 @@
     const phases = { inputDelay: 0, processingTime: 0, presentationDelay: 0 };
     if (entry.processingStart && entry.processingEnd) {
       phases.inputDelay = entry.processingStart - entry.startTime;
-      phases.processingTime = entry.processingEnd - entry.processingStart;
+      phases.processingDuration = entry.processingEnd - entry.processingStart;
       phases.presentationDelay = entry.duration - phases.inputDelay - phases.processingTime;
     }
     return phases;
@@ -71,7 +71,7 @@
       details.worstEvent = inpEntry.formattedName;
       details.phases = {
         inputDelay: Math.round(inpEntry.phases.inputDelay),
-        processingTime: Math.round(inpEntry.phases.processingTime),
+        processingDuration: Math.round(inpEntry.phases.processingDuration),
         presentationDelay: Math.round(inpEntry.phases.presentationDelay),
       };
     }
@@ -116,8 +116,8 @@
 
   return {
     script: "INP",
-    status: "tracking",
-    message: "INP tracking active. Interact with the page then call getINP() for results.",
+    status: "measuring",
+    message: "INP measurement active. Interact with the page then call getINP() for results.",
     getDataFn: "getINP",
   };
 })();

skills/webperf-core-web-vitals/scripts/LCP-Image-Entropy.js

@@ -39,7 +39,7 @@
   if (lowEntropyCount > 0) {
     issues.push({
       severity: "warning",
-      message: `${lowEntropyCount} image(s) have low entropy and are LCP-ineligible in Chrome 112+`,
+      message: `${lowEntropyCount} image(s) have low entropy and are not considered for LCP`,
     });
   }
   if (lcpImage?.isLowEntropy) {

skills/webperf-core-web-vitals/scripts/LCP-Sub-Parts.js

@@ -7,7 +7,7 @@
   const SUB_PARTS = [
     { name: "Time to First Byte", key: "ttfb", target: 800 },
     { name: "Resource Load Delay", key: "loadDelay", targetPercent: 10 },
-    { name: "Resource Load Time", key: "loadTime", targetPercent: 40 },
+    { name: "Resource Load Duration", key: "loadduration", targetPercent: 40 },
     { name: "Element Render Delay", key: "renderDelay", targetPercent: 10 },
   ];
 
@@ -56,7 +56,7 @@
     const values = {
       ttfb,
       loadDelay: lcpRequestStart - ttfb,
-      loadTime: lcpResponseEnd - lcpRequestStart,
+      loadDuration: lcpResponseEnd - lcpRequestStart,
       renderDelay: total - lcpResponseEnd,
     };
     SUB_PARTS.forEach((part) => {
@@ -83,13 +83,13 @@
   const totalMs = Math.round(total);
   const ttfbVal = Math.round(ttfb);
   const loadDelayVal = Math.round(lcpRequestStart - ttfb);
-  const loadTimeVal = Math.round(lcpResponseEnd - lcpRequestStart);
+  const loadDurationVal = Math.round(lcpResponseEnd - lcpRequestStart);
   const renderDelayVal = Math.round(total - lcpResponseEnd);
 
   const slowestPhase = [
     { key: "ttfb", value: ttfbVal },
     { key: "resourceLoadDelay", value: loadDelayVal },
-    { key: "resourceLoadTime", value: loadTimeVal },
+    { key: "resourceLoadDuration", value: loadDurationVal },
     { key: "elementRenderDelay", value: renderDelayVal },
   ].reduce((a, b) => (a.value > b.value ? a : b)).key;
 
@@ -118,7 +118,7 @@
       subParts: {
         ttfb: { value: ttfbVal, percent: Math.round((ttfbVal / totalMs) * 100), overTarget: ttfbVal > 800 },
         resourceLoadDelay: { value: loadDelayVal, percent: Math.round((loadDelayVal / totalMs) * 100), overTarget: (loadDelayVal / totalMs) * 100 > 10 },
-        resourceLoadTime: { value: loadTimeVal, percent: Math.round((loadTimeVal / totalMs) * 100), overTarget: (loadTimeVal / totalMs) * 100 > 40 },
+        resourceLoadDuration: { value: loadDurationVal, percent: Math.round((loadDurationVal / totalMs) * 100), overTarget: (loadDurationVal / totalMs) * 100 > 40 },
         elementRenderDelay: { value: renderDelayVal, percent: Math.round((renderDelayVal / totalMs) * 100), overTarget: (renderDelayVal / totalMs) * 100 > 10 },
       },
       slowestPhase,