PixelPilot performance-auditor.instructions.md

Performance Auditor 2026

Run → capture → score → fix. Automates Lighthouse audits via MCP (headless Chrome), reports CWV, and maps every failing audit to a concrete, token-aware fix.

---

CORE WEB VITALS TARGETS (2026)

Metric	Good	Needs Improvement	Poor
LCP Largest Contentful Paint	≤ 2.5 s	2.5–4.0 s	> 4.0 s
INP Interaction to Next Paint	≤ 200 ms	200–500 ms	> 500 ms
CLS Cumulative Layout Shift	≤ 0.1	0.1–0.25	> 0.25
FCP First Contentful Paint	≤ 1.8 s	1.8–3.0 s	> 3.0 s
TTFB Time to First Byte	≤ 800 ms	800–1800 ms	> 1800 ms
TBT Total Blocking Time	≤ 200 ms	200–600 ms	> 600 ms

Score targets:

• Performance: ≥ 90
• Accessibility: ≥ 95
• Best Practices: ≥ 95
• SEO: ≥ 90

---

STEP 1 — CHOOSE AUDIT METHOD

Method A — Chrome DevTools MCP (preferred for local dev)

// Navigate to target
await browser_navigate({ url: TARGET_URL });

// Wait for page to fully load
await browser_evaluate({ script: `
  await new Promise(resolve => {
    if (document.readyState === 'complete') return resolve();
    window.addEventListener('load', resolve);
  });
  await new Promise(r => setTimeout(r, 1000));
` });

// Collect Web Vitals via PerformanceObserver
const vitals = await browser_evaluate({ script: `
  const nav = performance.getEntriesByType('navigation')[0];
  const paint = performance.getEntriesByType('paint');
  const lcp  = await new Promise(res => {
    new PerformanceObserver(list => {
      const entries = list.getEntries();
      res(entries[entries.length - 1].startTime);
    }).observe({ type: 'largest-contentful-paint', buffered: true });
    setTimeout(() => res(null), 3000);
  });
  return {
    TTFB:  nav?.responseStart - nav?.requestStart,
    FCP:   paint.find(e => e.name === 'first-contentful-paint')?.startTime,
    LCP:   lcp,
    TBT:   nav?.domComplete - nav?.domInteractive,
    domSize: document.querySelectorAll('*').length,
    scripts: performance.getEntriesByType('resource')
             .filter(r => r.initiatorType === 'script')
             .map(r => ({ url: r.name.split('/').pop(), size: r.transferSize, duration: r.duration }))
             .sort((a,b) => b.size - a.size)
             .slice(0, 10),
    images:  performance.getEntriesByType('resource')
             .filter(r => r.initiatorType === 'img')
             .map(r => ({ url: r.name.split('/').pop(), size: r.transferSize }))
             .sort((a,b) => b.size - a.size)
             .slice(0, 10),
    thirdParty: performance.getEntriesByType('resource')
             .filter(r => !r.name.includes(location.hostname))
             .reduce((acc, r) => acc + r.transferSize, 0),
  };
` });