fix: apply skill-creator review feedback to webperf-core-web-vitals

Scripts:
- fix(LCP-Video-Candidate): apply activationStart correction to LCP value
  (bfcache navigations returned inflated values without this)
- fix(LCP): use getComputedStyle for background image detection
  (inline style check missed CSS-driven backgrounds)
- fix(CLS): add message field to synchronous return so agent knows to call getCLS()
- fix(INP): remove misleading rating:"good" from no-interactions error case;
  preserve getDataFn so agent can retry after user interacts
- feat(LCP, LCP-Sub-Parts, LCP-Trail): add window.__cwvHighlight flag
  to allow disabling visual element outlines without changing scripts

Documentation:
- docs(schema): document getINPDetails() with return schema and example
- docs(schema): add INP error case (no interactions) to schema examples
- docs(SKILL): add Error Recovery section with per-script guidance
- docs(SKILL): add cross-skill fork note — cross-skill triggers are
  recommendations to report, not direct calls from the forked subagent
- docs(SKILL): add Visual Highlighting section documenting __cwvHighlight
- docs(SKILL): prefix cross-skill script references with skill name
- docs(SKILL): document getINPDetails() step in INP debugging workflow

Author: nucliweb

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

@@ -36,6 +36,8 @@ INP requires real user interactions to measure. The workflow is:
 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."
 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.
+6. For a full breakdown of all interactions, call `evaluate_script("getINPDetails()")` — returns all recorded interactions sorted by duration.
 
 > The agent cannot interact with the page on behalf of the user for INP measurement. Real user interactions are required.
 
@@ -66,7 +68,7 @@ When LCP is slow or the user asks "debug LCP" or "why is LCP slow":
 When layout shifts are detected or the user asks "debug CLS" or "layout shift issues":
 
 1. **CLS.js** - Measure overall CLS score
-2. **Layout-Shift-Loading-and-Interaction.js** (from Interaction skill) - Separate loading vs interaction shifts
+2. **Layout-Shift-Loading-and-Interaction.js** (from `webperf-interaction` skill) - Separate loading vs interaction shifts
 3. Cross-reference with **webperf-loading** skill:
    - Find-Above-The-Fold-Lazy-Loaded-Images.js (lazy images causing shifts)
    - Fonts-Preloaded-Loaded-and-used-above-the-fold.js (font swap causing shifts)
@@ -77,10 +79,11 @@ 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.
 2. Call `getINP()` to collect results once the user confirms.
-3. **Interactions.js** (from Interaction skill) - List all interactions with timing
-4. **Input-Latency-Breakdown.js** (from Interaction skill) - Break down input delay, processing, presentation
-5. **Long-Animation-Frames.js** (from Interaction skill) - Identify blocking animation frames
-6. **Long-Animation-Frames-Script-Attribution.js** (from Interaction skill) - Find scripts causing delays
+3. Call `getINPDetails()` to see all interactions ranked by duration.
+4. **Interactions.js** (from `webperf-interaction` skill) - List all interactions with timing
+5. **Input-Latency-Breakdown.js** (from `webperf-interaction` skill) - Break down input delay, processing, presentation
+6. **Long-Animation-Frames.js** (from `webperf-interaction` skill) - Identify blocking animation frames
+7. **Long-Animation-Frames-Script-Attribution.js** (from `webperf-interaction` skill) - Find scripts causing delays
 
 ### Video as LCP Investigation
 
@@ -212,3 +215,25 @@ These triggers recommend using snippets from other skills:
 
 - **If render delay or interaction delay is high** → Use **webperf-interaction** skill:
   - Long-Animation-Frames.js (main thread blocking)
+
+> **Note on cross-skill references:** This skill runs in an isolated subagent (`context: fork`). When a decision tree recommends scripts from another skill (e.g., `webperf-loading`, `webperf-interaction`, `webperf-media`), report the recommendation to the user as a next step — do not attempt to execute those scripts directly. The user or the main agent can activate the appropriate skill to continue the investigation.
+
+## Error Recovery
+
+When a script returns `status: "error"`:
+
+- **LCP/CLS/LCP-Sub-Parts/LCP-Trail** → The page may not have finished loading. Ask the user to wait for full load or reload, then re-run the script.
+- **INP** (`getINP()` returns error) → No interactions have been recorded yet. Remind the user to interact with the page, then call `getINP()` again.
+- **LCP-Image-Entropy** → No images with measurable BPP found. This is normal for text-only pages or pages where all images are data URIs.
+- **LCP-Video-Candidate** → No LCP entries found; see LCP error recovery above.
+
+## Visual Highlighting
+
+By default, scripts highlight the LCP element(s) with colored dashed outlines — useful when the user is watching the browser while the agent runs. To disable:
+
+```js
+window.__cwvHighlight = false;
+// then run any LCP script
+```
+
+Scripts that support this flag: `LCP.js`, `LCP-Sub-Parts.js`, `LCP-Trail.js`.

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

@@ -90,7 +90,7 @@ data = evaluate_script("getCLS()")
 ```json
 { "script": "INP", "status": "tracking", "message": "INP tracking active. Interact with the page then call getINP() for results.", "getDataFn": "getINP" }
 ```
-`getINP()` returns:
+`getINP()` returns (after interactions):
 ```json
 {
   "script": "INP", "status": "ok", "metric": "INP",
@@ -99,6 +99,17 @@ data = evaluate_script("getCLS()")
   "details": { "totalInteractions": 5, "worstEvent": "click → button.submit", "phases": { "inputDelay": 120, "processingTime": 180, "presentationDelay": 50 } }
 }
 ```
+`getINP()` returns (no interactions yet):
+```json
+{ "script": "INP", "status": "error", "error": "No interactions recorded yet. Interact with the page and call getINP() again.", "getDataFn": "getINP" }
+```
+`getINPDetails()` returns all recorded interactions sorted by duration (useful for INP deep-dive):
+```json
+[
+  { "formattedName": "click → button.submit", "duration": 350, "startTime": 4210, "phases": { "inputDelay": 120, "processingTime": 180, "presentationDelay": 50 } },
+  { "formattedName": "keydown → input#search", "duration": 180, "startTime": 8540, "phases": { "inputDelay": 20, "processingTime": 140, "presentationDelay": 20 } }
+]
+```
 
 ### LCP-Sub-Parts
 ```json

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

@@ -39,5 +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.",
   };
 })();

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

@@ -77,9 +77,9 @@
     }
     if (interactions.length === 0) {
       return {
-        script: "INP", status: "error", error: "No interactions recorded yet",
-        metric: "INP", value: 0, unit: "ms", rating: "good",
-        thresholds: { good: 200, needsImprovement: 500 }, details,
+        script: "INP", status: "error",
+        error: "No interactions recorded yet. Interact with the page and call getINP() again.",
+        getDataFn: "getINP",
       };
     }
     return {

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

@@ -1,4 +1,6 @@
 (() => {
+  const HIGHLIGHT = window.__cwvHighlight !== false;
+
   const valueToRating = (ms) =>
     ms <= 2500 ? "good" : ms <= 4000 ? "needs-improvement" : "poor";
 
@@ -44,7 +46,7 @@
 
     const { ttfb, lcpRequestStart, lcpResponseEnd, total } = calcSubParts(lcpEntry, navEntry);
 
-    if (lcpEntry.element) {
+    if (HIGHLIGHT && lcpEntry.element) {
       lcpEntry.element.style.outline = "3px dashed lime";
       lcpEntry.element.style.outlineOffset = "2px";
     }

skills/webperf-core-web-vitals/scripts/LCP-Trail.js

@@ -1,4 +1,6 @@
 (() => {
+  const HIGHLIGHT = window.__cwvHighlight !== false;
+
   const PALETTE = [
     { color: "#EF4444" },
     { color: "#F97316" },
@@ -42,8 +44,10 @@
       const { element } = entry;
       if (!element || seen.has(element)) continue;
       const { color } = PALETTE[colorIndex % PALETTE.length];
-      element.style.outline = `3px dashed ${color}`;
-      element.style.outlineOffset = "2px";
+      if (HIGHLIGHT) {
+        element.style.outline = `3px dashed ${color}`;
+        element.style.outlineOffset = "2px";
+      }
       seen.add(element);
       colorIndex++;
     }

skills/webperf-core-web-vitals/scripts/LCP-Video-Candidate.js

@@ -10,6 +10,11 @@
   const valueToRating = (ms) =>
     ms <= 2500 ? "good" : ms <= 4000 ? "needs-improvement" : "poor";
 
+  const getActivationStart = () => {
+    const navEntry = performance.getEntriesByType("navigation")[0];
+    return navEntry?.activationStart || 0;
+  };
+
   const detectFormat = (url) => {
     if (!url) return "unknown";
     const ext = url.toLowerCase().split("?")[0].match(/\.(avif|webp|jxl|png|gif|jpg|jpeg|svg)(?:[?#]|$)/);
@@ -22,14 +27,16 @@
     catch { return url; }
   };
 
+  const activationStart = getActivationStart();
+
   if (!element || element.tagName !== "VIDEO") {
     return {
       script: "LCP-Video-Candidate",
       status: "ok",
       metric: "LCP",
-      value: Math.round(lcp.startTime),
+      value: Math.round(Math.max(0, lcp.startTime - activationStart)),
       unit: "ms",
-      rating: valueToRating(lcp.startTime),
+      rating: valueToRating(Math.max(0, lcp.startTime - activationStart)),
       thresholds: { good: 2500, needsImprovement: 4000 },
       details: { isVideo: false },
       issues: [],
@@ -76,13 +83,14 @@
     issues.push({ severity: "warning", message: 'preload="none" on a non-autoplay video may delay poster image loading in some browsers' });
   }
 
+  const lcpValue = Math.round(Math.max(0, lcp.startTime - activationStart));
   return {
     script: "LCP-Video-Candidate",
     status: "ok",
     metric: "LCP",
-    value: Math.round(lcp.startTime),
+    value: lcpValue,
     unit: "ms",
-    rating: valueToRating(lcp.startTime),
+    rating: valueToRating(lcpValue),
     thresholds: { good: 2500, needsImprovement: 4000 },
     details: {
       isVideo: true,

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

@@ -1,4 +1,6 @@
 (() => {
+  const HIGHLIGHT = window.__cwvHighlight !== false;
+
   const valueToRating = (ms) =>
     ms <= 2500 ? "good" : ms <= 4000 ? "needs-improvement" : "poor";
 
@@ -7,16 +9,17 @@
     return navEntry?.activationStart || 0;
   };
 
+  const highlightElement = (element, color = "lime") => {
+    if (!HIGHLIGHT || !element) return;
+    element.style.outline = `3px dashed ${color}`;
+    element.style.outlineOffset = "2px";
+  };
+
   // Highlight LCP element as candidates update
   const observer = new PerformanceObserver((list) => {
     const entries = list.getEntries();
     const lastEntry = entries[entries.length - 1];
-    if (!lastEntry) return;
-    const element = lastEntry.element;
-    if (element) {
-      element.style.outline = "3px dashed lime";
-      element.style.outlineOffset = "2px";
-    }
+    if (lastEntry?.element) highlightElement(lastEntry.element);
   });
 
   observer.observe({ type: "largest-contentful-paint", buffered: true });
@@ -42,14 +45,14 @@
       if (classes) selector = `${el.tagName.toLowerCase()}.${classes}`;
     }
     const tag = el.tagName.toLowerCase();
+    const hasCssBackground = window.getComputedStyle(el).backgroundImage !== "none";
     elementType =
       tag === "img" ? "Image" :
       tag === "video" ? "Video poster" :
-      el.style?.backgroundImage ? "Background image" :
+      hasCssBackground ? "Background image" :
       (tag === "h1" || tag === "p" ? "Text block" : tag);
 
-    el.style.outline = "3px dashed lime";
-    el.style.outlineOffset = "2px";
+    highlightElement(el);
   }
 
   return {