cokit-cli 1.0.7 → 1.0.9

package/skills/ck-chrome-devtools/references/performance-guide.md

@@ -1,940 +0,0 @@
-# Performance Analysis Guide
-
-Comprehensive guide to analyzing web performance using Chrome DevTools Protocol, Puppeteer, and chrome-devtools skill.
-
-## Table of Contents
-
-- [Core Web Vitals](#core-web-vitals)
-- [Performance Tracing](#performance-tracing)
-- [Network Analysis](#network-analysis)
-- [JavaScript Performance](#javascript-performance)
-- [Rendering Performance](#rendering-performance)
-- [Memory Analysis](#memory-analysis)
-- [Optimization Strategies](#optimization-strategies)
-
----
-
-## Core Web Vitals
-
-### Overview
-
-Core Web Vitals are Google's standardized metrics for measuring user experience:
-
-- **LCP (Largest Contentful Paint)** - Loading performance (< 2.5s good)
-- **FID (First Input Delay)** - Interactivity (< 100ms good)
-- **CLS (Cumulative Layout Shift)** - Visual stability (< 0.1 good)
-
-### Measuring with chrome-devtools-mcp
-
-```javascript
-// Start performance trace
-await useTool('performance_start_trace', {
-  categories: ['loading', 'rendering', 'scripting']
-});
-
-// Navigate to page
-await useTool('navigate_page', {
-  url: 'https://example.com'
-});
-
-// Wait for complete load
-await useTool('wait_for', {
-  waitUntil: 'networkidle'
-});
-
-// Stop trace and get data
-await useTool('performance_stop_trace');
-
-// Get AI-powered insights
-const insights = await useTool('performance_analyze_insight');
-
-// insights will include:
-// - LCP timing
-// - FID analysis
-// - CLS score
-// - Performance recommendations
-```
-
-### Measuring with Puppeteer
-
-```javascript
-import puppeteer from 'puppeteer';
-
-const browser = await puppeteer.launch();
-const page = await browser.newPage();
-
-// Measure Core Web Vitals
-await page.goto('https://example.com', {
-  waitUntil: 'networkidle2'
-});
-
-const vitals = await page.evaluate(() => {
-  return new Promise((resolve) => {
-    const vitals = {
-      LCP: null,
-      FID: null,
-      CLS: 0
-    };
-
-    // LCP
-    new PerformanceObserver((list) => {
-      const entries = list.getEntries();
-      vitals.LCP = entries[entries.length - 1].renderTime ||
-                   entries[entries.length - 1].loadTime;
-    }).observe({ entryTypes: ['largest-contentful-paint'] });
-
-    // FID
-    new PerformanceObserver((list) => {
-      vitals.FID = list.getEntries()[0].processingStart -
-                   list.getEntries()[0].startTime;
-    }).observe({ entryTypes: ['first-input'] });
-
-    // CLS
-    new PerformanceObserver((list) => {
-      list.getEntries().forEach((entry) => {
-        if (!entry.hadRecentInput) {
-          vitals.CLS += entry.value;
-        }
-      });
-    }).observe({ entryTypes: ['layout-shift'] });
-
-    // Wait 5 seconds for metrics
-    setTimeout(() => resolve(vitals), 5000);
-  });
-});
-
-console.log('Core Web Vitals:', vitals);
-```
-
-### Other Important Metrics
-
-**TTFB (Time to First Byte)**
-```javascript
-const ttfb = await page.evaluate(() => {
-  const [navigationEntry] = performance.getEntriesByType('navigation');
-  return navigationEntry.responseStart - navigationEntry.requestStart;
-});
-```
-
-**FCP (First Contentful Paint)**
-```javascript
-const fcp = await page.evaluate(() => {
-  const paintEntries = performance.getEntriesByType('paint');
-  const fcpEntry = paintEntries.find(e => e.name === 'first-contentful-paint');
-  return fcpEntry ? fcpEntry.startTime : null;
-});
-```
-
-**TTI (Time to Interactive)**
-```javascript
-// Requires lighthouse or manual calculation
-const tti = await page.evaluate(() => {
-  // Complex calculation based on network idle and long tasks
-  // Best to use Lighthouse for accurate TTI
-});
-```
-
----
-
-## Performance Tracing
-
-### Chrome Trace Categories
-
-**Loading:**
-- Page load events
-- Resource loading
-- Parser activity
-
-**Rendering:**
-- Layout calculations
-- Paint operations
-- Compositing
-
-**Scripting:**
-- JavaScript execution
-- V8 compilation
-- Garbage collection
-
-**Network:**
-- HTTP requests
-- WebSocket traffic
-- Resource fetching
-
-**Input:**
-- User input processing
-- Touch/scroll events
-
-**GPU:**
-- GPU operations
-- Compositing work
-
-### Record Performance Trace
-
-**Using chrome-devtools-mcp:**
-```javascript
-// Start trace with specific categories
-await useTool('performance_start_trace', {
-  categories: ['loading', 'rendering', 'scripting', 'network']
-});
-
-// Perform actions
-await useTool('navigate_page', { url: 'https://example.com' });
-await useTool('wait_for', { waitUntil: 'networkidle' });
-
-// Optional: Interact with page
-await useTool('click', { uid: 'button-uid' });
-
-// Stop trace
-const traceData = await useTool('performance_stop_trace');
-
-// Analyze trace
-const insights = await useTool('performance_analyze_insight');
-```
-
-**Using Puppeteer:**
-```javascript
-// Start tracing
-await page.tracing.start({
-  path: 'trace.json',
-  categories: [
-    'devtools.timeline',
-    'disabled-by-default-devtools.timeline',
-    'disabled-by-default-v8.cpu_profiler'
-  ]
-});
-
-// Navigate
-await page.goto('https://example.com', {
-  waitUntil: 'networkidle2'
-});
-
-// Stop tracing
-await page.tracing.stop();
-
-// Analyze in Chrome DevTools (chrome://tracing)
-```
-
-### Analyze Trace Data
-
-**Key Metrics from Trace:**
-
-1. **Main Thread Activity**
-   - JavaScript execution time
-   - Layout/reflow time
-   - Paint time
-   - Long tasks (> 50ms)
-
-2. **Network Waterfall**
-   - Request start times
-   - DNS lookup
-   - Connection time
-   - Download time
-
-3. **Rendering Pipeline**
-   - DOM construction
-   - Style calculation
-   - Layout
-   - Paint
-   - Composite
-
-**Common Issues to Look For:**
-- Long tasks blocking main thread
-- Excessive JavaScript execution
-- Layout thrashing
-- Unnecessary repaints
-- Slow network requests
-- Large bundle sizes
-
----
-
-## Network Analysis
-
-### Monitor Network Requests
-
-**Using chrome-devtools-mcp:**
-```javascript
-// Navigate to page
-await useTool('navigate_page', { url: 'https://example.com' });
-
-// Wait for all requests
-await useTool('wait_for', { waitUntil: 'networkidle' });
-
-// List all requests
-const requests = await useTool('list_network_requests', {
-  resourceTypes: ['Document', 'Script', 'Stylesheet', 'Image', 'XHR', 'Fetch'],
-  pageSize: 100
-});
-
-// Analyze specific request
-for (const req of requests.requests) {
-  const details = await useTool('get_network_request', {
-    requestId: req.id
-  });
-
-  console.log({
-    url: details.url,
-    method: details.method,
-    status: details.status,
-    size: details.encodedDataLength,
-    time: details.timing.receiveHeadersEnd - details.timing.requestTime,
-    cached: details.fromCache
-  });
-}
-```
-
-**Using Puppeteer:**
-```javascript
-const requests = [];
-
-// Capture all requests
-page.on('request', (request) => {
-  requests.push({
-    url: request.url(),
-    method: request.method(),
-    resourceType: request.resourceType(),
-    headers: request.headers()
-  });
-});
-
-// Capture responses
-page.on('response', (response) => {
-  const request = response.request();
-  console.log({
-    url: response.url(),
-    status: response.status(),
-    size: response.headers()['content-length'],
-    cached: response.fromCache(),
-    timing: response.timing()
-  });
-});
-
-await page.goto('https://example.com');
-```
-
-### Network Performance Metrics
-
-**Calculate Total Page Weight:**
-```javascript
-let totalBytes = 0;
-let resourceCounts = {};
-
-page.on('response', async (response) => {
-  const type = response.request().resourceType();
-  const buffer = await response.buffer();
-
-  totalBytes += buffer.length;
-  resourceCounts[type] = (resourceCounts[type] || 0) + 1;
-});
-
-await page.goto('https://example.com');
-
-console.log('Total size:', (totalBytes / 1024 / 1024).toFixed(2), 'MB');
-console.log('Resources:', resourceCounts);
-```
-
-**Identify Slow Requests:**
-```javascript
-page.on('response', (response) => {
-  const timing = response.timing();
-  const totalTime = timing.receiveHeadersEnd - timing.requestTime;
-
-  if (totalTime > 1000) { // Slower than 1 second
-    console.log('Slow request:', {
-      url: response.url(),
-      time: totalTime.toFixed(2) + 'ms',
-      size: response.headers()['content-length']
-    });
-  }
-});
-```
-
-### Network Throttling
-
-**Simulate Slow Connection:**
-```javascript
-// Using chrome-devtools-mcp
-await useTool('emulate_network', {
-  throttlingOption: 'Slow 3G'  // or 'Fast 3G', 'Slow 4G'
-});
-
-// Using Puppeteer
-const client = await page.createCDPSession();
-await client.send('Network.emulateNetworkConditions', {
-  offline: false,
-  downloadThroughput: 400 * 1024 / 8,  // 400 Kbps
-  uploadThroughput: 400 * 1024 / 8,
-  latency: 2000  // 2000ms RTT
-});
-```
-
----
-
-## JavaScript Performance
-
-### Identify Long Tasks
-
-**Using Performance Observer:**
-```javascript
-await page.evaluate(() => {
-  return new Promise((resolve) => {
-    const longTasks = [];
-
-    const observer = new PerformanceObserver((list) => {
-      list.getEntries().forEach((entry) => {
-        longTasks.push({
-          name: entry.name,
-          duration: entry.duration,
-          startTime: entry.startTime
-        });
-      });
-    });
-
-    observer.observe({ entryTypes: ['longtask'] });
-
-    // Collect for 10 seconds
-    setTimeout(() => {
-      observer.disconnect();
-      resolve(longTasks);
-    }, 10000);
-  });
-});
-```
-
-### CPU Profiling
-
-**Using Puppeteer:**
-```javascript
-// Start CPU profiling
-const client = await page.createCDPSession();
-await client.send('Profiler.enable');
-await client.send('Profiler.start');
-
-// Navigate and interact
-await page.goto('https://example.com');
-await page.click('.button');
-
-// Stop profiling
-const { profile } = await client.send('Profiler.stop');
-
-// Analyze profile (flame graph data)
-// Import into Chrome DevTools for visualization
-```
-
-### JavaScript Coverage
-
-**Identify Unused Code:**
-```javascript
-// Start coverage
-await Promise.all([
-  page.coverage.startJSCoverage(),
-  page.coverage.startCSSCoverage()
-]);
-
-// Navigate
-await page.goto('https://example.com');
-
-// Stop coverage
-const [jsCoverage, cssCoverage] = await Promise.all([
-  page.coverage.stopJSCoverage(),
-  page.coverage.stopCSSCoverage()
-]);
-
-// Calculate unused bytes
-function calculateUnusedBytes(coverage) {
-  let usedBytes = 0;
-  let totalBytes = 0;
-
-  for (const entry of coverage) {
-    totalBytes += entry.text.length;
-    for (const range of entry.ranges) {
-      usedBytes += range.end - range.start - 1;
-    }
-  }
-
-  return {
-    usedBytes,
-    totalBytes,
-    unusedBytes: totalBytes - usedBytes,
-    unusedPercentage: ((totalBytes - usedBytes) / totalBytes * 100).toFixed(2)
-  };
-}
-
-console.log('JS Coverage:', calculateUnusedBytes(jsCoverage));
-console.log('CSS Coverage:', calculateUnusedBytes(cssCoverage));
-```
-
-### Bundle Size Analysis
-
-**Analyze JavaScript Bundles:**
-```javascript
-page.on('response', async (response) => {
-  const url = response.url();
-  const type = response.request().resourceType();
-
-  if (type === 'script') {
-    const buffer = await response.buffer();
-    const size = buffer.length;
-
-    console.log({
-      url: url.split('/').pop(),
-      size: (size / 1024).toFixed(2) + ' KB',
-      gzipped: response.headers()['content-encoding'] === 'gzip'
-    });
-  }
-});
-```
-
----
-
-## Rendering Performance
-
-### Layout Thrashing Detection
-
-**Monitor Layout Recalculations:**
-```javascript
-// Using Performance Observer
-await page.evaluate(() => {
-  return new Promise((resolve) => {
-    const measurements = [];
-
-    const observer = new PerformanceObserver((list) => {
-      list.getEntries().forEach((entry) => {
-        if (entry.entryType === 'measure' &&
-            entry.name.includes('layout')) {
-          measurements.push({
-            name: entry.name,
-            duration: entry.duration,
-            startTime: entry.startTime
-          });
-        }
-      });
-    });
-
-    observer.observe({ entryTypes: ['measure'] });
-
-    setTimeout(() => {
-      observer.disconnect();
-      resolve(measurements);
-    }, 5000);
-  });
-});
-```
-
-### Paint and Composite Metrics
-
-**Get Paint Metrics:**
-```javascript
-const paintMetrics = await page.evaluate(() => {
-  const paints = performance.getEntriesByType('paint');
-  return {
-    firstPaint: paints.find(p => p.name === 'first-paint')?.startTime,
-    firstContentfulPaint: paints.find(p => p.name === 'first-contentful-paint')?.startTime
-  };
-});
-```
-
-### Frame Rate Analysis
-
-**Monitor FPS:**
-```javascript
-await page.evaluate(() => {
-  return new Promise((resolve) => {
-    let frames = 0;
-    let lastTime = performance.now();
-
-    function countFrames() {
-      frames++;
-      requestAnimationFrame(countFrames);
-    }
-
-    countFrames();
-
-    setTimeout(() => {
-      const now = performance.now();
-      const elapsed = (now - lastTime) / 1000;
-      const fps = frames / elapsed;
-      resolve(fps);
-    }, 5000);
-  });
-});
-```
-
-### Layout Shifts (CLS)
-
-**Track Individual Shifts:**
-```javascript
-await page.evaluate(() => {
-  return new Promise((resolve) => {
-    const shifts = [];
-    let totalCLS = 0;
-
-    const observer = new PerformanceObserver((list) => {
-      list.getEntries().forEach((entry) => {
-        if (!entry.hadRecentInput) {
-          totalCLS += entry.value;
-          shifts.push({
-            value: entry.value,
-            time: entry.startTime,
-            elements: entry.sources?.map(s => s.node)
-          });
-        }
-      });
-    });
-
-    observer.observe({ entryTypes: ['layout-shift'] });
-
-    setTimeout(() => {
-      observer.disconnect();
-      resolve({ totalCLS, shifts });
-    }, 10000);
-  });
-});
-```
-
----
-
-## Memory Analysis
-
-### Memory Metrics
-
-**Get Memory Usage:**
-```javascript
-// Using chrome-devtools-mcp
-await useTool('evaluate_script', {
-  expression: `
-    ({
-      usedJSHeapSize: performance.memory?.usedJSHeapSize,
-      totalJSHeapSize: performance.memory?.totalJSHeapSize,
-      jsHeapSizeLimit: performance.memory?.jsHeapSizeLimit
-    })
-  `,
-  returnByValue: true
-});
-
-// Using Puppeteer
-const metrics = await page.metrics();
-console.log({
-  jsHeapUsed: (metrics.JSHeapUsedSize / 1024 / 1024).toFixed(2) + ' MB',
-  jsHeapTotal: (metrics.JSHeapTotalSize / 1024 / 1024).toFixed(2) + ' MB',
-  domNodes: metrics.Nodes,
-  documents: metrics.Documents,
-  jsEventListeners: metrics.JSEventListeners
-});
-```
-
-### Memory Leak Detection
-
-**Monitor Memory Over Time:**
-```javascript
-async function detectMemoryLeak(page, duration = 30000) {
-  const samples = [];
-  const interval = 1000; // Sample every second
-  const samples_count = duration / interval;
-
-  for (let i = 0; i < samples_count; i++) {
-    const metrics = await page.metrics();
-    samples.push({
-      time: i,
-      heapUsed: metrics.JSHeapUsedSize
-    });
-
-    await page.waitForTimeout(interval);
-  }
-
-  // Analyze trend
-  const firstSample = samples[0].heapUsed;
-  const lastSample = samples[samples.length - 1].heapUsed;
-  const increase = ((lastSample - firstSample) / firstSample * 100).toFixed(2);
-
-  return {
-    samples,
-    memoryIncrease: increase + '%',
-    possibleLeak: increase > 50 // > 50% increase indicates possible leak
-  };
-}
-
-const leakAnalysis = await detectMemoryLeak(page, 30000);
-console.log('Memory Analysis:', leakAnalysis);
-```
-
-### Heap Snapshot
-
-**Capture Heap Snapshot:**
-```javascript
-const client = await page.createCDPSession();
-
-// Take snapshot
-await client.send('HeapProfiler.enable');
-const { result } = await client.send('HeapProfiler.takeHeapSnapshot');
-
-// Snapshot is streamed in chunks
-// Save to file or analyze programmatically
-```
-
----
-
-## Optimization Strategies
-
-### Image Optimization
-
-**Detect Unoptimized Images:**
-```javascript
-const images = await page.evaluate(() => {
-  const images = Array.from(document.querySelectorAll('img'));
-  return images.map(img => ({
-    src: img.src,
-    naturalWidth: img.naturalWidth,
-    naturalHeight: img.naturalHeight,
-    displayWidth: img.width,
-    displayHeight: img.height,
-    oversized: img.naturalWidth > img.width * 1.5 ||
-               img.naturalHeight > img.height * 1.5
-  }));
-});
-
-const oversizedImages = images.filter(img => img.oversized);
-console.log('Oversized images:', oversizedImages);
-```
-
-### Font Loading
-
-**Detect Render-Blocking Fonts:**
-```javascript
-const fonts = await page.evaluate(() => {
-  return Array.from(document.fonts).map(font => ({
-    family: font.family,
-    weight: font.weight,
-    style: font.style,
-    status: font.status,
-    loaded: font.status === 'loaded'
-  }));
-});
-
-console.log('Fonts:', fonts);
-```
-
-### Third-Party Scripts
-
-**Measure Third-Party Impact:**
-```javascript
-const thirdPartyDomains = ['googletagmanager.com', 'facebook.net', 'doubleclick.net'];
-
-page.on('response', async (response) => {
-  const url = response.url();
-  const isThirdParty = thirdPartyDomains.some(domain => url.includes(domain));
-
-  if (isThirdParty) {
-    const buffer = await response.buffer();
-    console.log({
-      url: url,
-      size: (buffer.length / 1024).toFixed(2) + ' KB',
-      type: response.request().resourceType()
-    });
-  }
-});
-```
-
-### Critical Rendering Path
-
-**Identify Render-Blocking Resources:**
-```javascript
-await page.goto('https://example.com');
-
-const renderBlockingResources = await page.evaluate(() => {
-  const resources = performance.getEntriesByType('resource');
-  return resources.filter(resource => {
-    return (resource.initiatorType === 'link' &&
-            resource.name.includes('.css')) ||
-           (resource.initiatorType === 'script' &&
-            !resource.name.includes('async'));
-  }).map(r => ({
-    url: r.name,
-    duration: r.duration,
-    startTime: r.startTime
-  }));
-});
-
-console.log('Render-blocking resources:', renderBlockingResources);
-```
-
-### Lighthouse Integration
-
-**Run Lighthouse Audit:**
-```javascript
-import lighthouse from 'lighthouse';
-import { launch } from 'chrome-launcher';
-
-// Launch Chrome
-const chrome = await launch({ chromeFlags: ['--headless'] });
-
-// Run Lighthouse
-const { lhr } = await lighthouse('https://example.com', {
-  port: chrome.port,
-  onlyCategories: ['performance']
-});
-
-// Get scores
-console.log({
-  performanceScore: lhr.categories.performance.score * 100,
-  metrics: {
-    FCP: lhr.audits['first-contentful-paint'].displayValue,
-    LCP: lhr.audits['largest-contentful-paint'].displayValue,
-    TBT: lhr.audits['total-blocking-time'].displayValue,
-    CLS: lhr.audits['cumulative-layout-shift'].displayValue,
-    SI: lhr.audits['speed-index'].displayValue
-  },
-  opportunities: lhr.audits['opportunities']
-});
-
-await chrome.kill();
-```
-
----
-
-## Performance Budgets
-
-### Set Performance Budgets
-
-```javascript
-const budgets = {
-  // Core Web Vitals
-  LCP: 2500,        // ms
-  FID: 100,         // ms
-  CLS: 0.1,         // score
-
-  // Other metrics
-  FCP: 1800,        // ms
-  TTI: 3800,        // ms
-  TBT: 300,         // ms
-
-  // Resource budgets
-  totalPageSize: 2 * 1024 * 1024,  // 2 MB
-  jsSize: 500 * 1024,               // 500 KB
-  cssSize: 100 * 1024,              // 100 KB
-  imageSize: 1 * 1024 * 1024,       // 1 MB
-
-  // Request counts
-  totalRequests: 50,
-  jsRequests: 10,
-  cssRequests: 5
-};
-
-async function checkBudgets(page, budgets) {
-  // Measure actual values
-  const vitals = await measureCoreWebVitals(page);
-  const resources = await analyzeResources(page);
-
-  // Compare against budgets
-  const violations = [];
-
-  if (vitals.LCP > budgets.LCP) {
-    violations.push(`LCP: ${vitals.LCP}ms exceeds budget of ${budgets.LCP}ms`);
-  }
-
-  if (resources.totalSize > budgets.totalPageSize) {
-    violations.push(`Page size: ${resources.totalSize} exceeds budget of ${budgets.totalPageSize}`);
-  }
-
-  // ... check other budgets
-
-  return {
-    passed: violations.length === 0,
-    violations
-  };
-}
-```
-
----
-
-## Automated Performance Testing
-
-### CI/CD Integration
-
-```javascript
-// performance-test.js
-import puppeteer from 'puppeteer';
-
-async function performanceTest(url) {
-  const browser = await puppeteer.launch();
-  const page = await browser.newPage();
-
-  // Measure metrics
-  await page.goto(url, { waitUntil: 'networkidle2' });
-  const metrics = await page.metrics();
-  const vitals = await measureCoreWebVitals(page);
-
-  await browser.close();
-
-  // Check against thresholds
-  const thresholds = {
-    LCP: 2500,
-    FID: 100,
-    CLS: 0.1,
-    jsHeapSize: 50 * 1024 * 1024  // 50 MB
-  };
-
-  const failed = [];
-  if (vitals.LCP > thresholds.LCP) failed.push('LCP');
-  if (vitals.FID > thresholds.FID) failed.push('FID');
-  if (vitals.CLS > thresholds.CLS) failed.push('CLS');
-  if (metrics.JSHeapUsedSize > thresholds.jsHeapSize) failed.push('Memory');
-
-  if (failed.length > 0) {
-    console.error('Performance test failed:', failed);
-    process.exit(1);
-  }
-
-  console.log('Performance test passed');
-}
-
-performanceTest(process.env.TEST_URL);
-```
-
----
-
-## Best Practices
-
-### Performance Testing Checklist
-
-1. **Measure Multiple Times**
-   - Run tests 3-5 times
-   - Use median values
-   - Account for variance
-
-2. **Test Different Conditions**
-   - Fast 3G
-   - Slow 3G
-   - Offline
-   - CPU throttling
-
-3. **Test Different Devices**
-   - Mobile (low-end)
-   - Mobile (high-end)
-   - Desktop
-   - Tablet
-
-4. **Monitor Over Time**
-   - Track metrics in CI/CD
-   - Set up alerts for regressions
-   - Create performance dashboards
-
-5. **Focus on User Experience**
-   - Prioritize Core Web Vitals
-   - Test real user journeys
-   - Consider perceived performance
-
-6. **Optimize Critical Path**
-   - Minimize render-blocking resources
-   - Defer non-critical JavaScript
-   - Optimize font loading
-   - Lazy load images
-
----
-
-## Resources
-
-- [Web.dev Performance](https://web.dev/performance/)
-- [Chrome DevTools Performance](https://developer.chrome.com/docs/devtools/performance/)
-- [Core Web Vitals](https://web.dev/vitals/)
-- [Lighthouse](https://developer.chrome.com/docs/lighthouse/)
-- [WebPageTest](https://www.webpagetest.org/)