Web Performance Engine

Complete web performance optimization system. Audit, diagnose, fix, and monitor — no external tools required (but integrates with Lighthouse, WebPageTest, Chrome DevTools when available).

Phase 1: Performance Audit

Quick Health Check

Run these checks in order. Stop when you find the bottleneck tier.

Tier 1 — Critical (blocks rendering):

• [ ] Time to First Byte (TTFB) > 800ms → server problem
• [ ] First Contentful Paint (FCP) > 1.8s → render-blocking resources
• [ ] Largest Contentful Paint (LCP) > 2.5s → hero element problem
• [ ] Total Blocking Time (TBT) > 200ms → JavaScript problem
• [ ] Cumulative Layout Shift (CLS) > 0.1 → layout instability
• [ ] Interaction to Next Paint (INP) > 200ms → event handler problem

Tier 2 — Important (affects experience):

• [ ] Page weight > 2MB
• [ ] Requests > 80
• [ ] JavaScript > 500KB (compressed)
• [ ] Images > 1MB total
• [ ] No compression (gzip/brotli)
• [ ] No caching headers

Tier 3 — Polish (competitive edge):

• [ ] Speed Index > 3.4s
• [ ] Time to Interactive > 3.8s
• [ ] Font loading causes flash
• [ ] Third-party scripts > 30% of JS

Audit Brief Template

audit:
  url: ""
  device: "mobile"  # mobile | desktop | both
  connection: "4G"  # 3G | 4G | fiber
  region: ""        # closest to target users
  
scores:
  performance: null  # 0-100
  fcp_ms: null
  lcp_ms: null
  tbt_ms: null
  cls: null
  inp_ms: null
  ttfb_ms: null
  
page_weight:
  total_kb: null
  html_kb: null
  css_kb: null
  js_kb: null
  images_kb: null
  fonts_kb: null
  other_kb: null
  
requests:
  total: null
  by_type: {}
  third_party_count: null
  third_party_kb: null

Getting Metrics Without Tools

If no Lighthouse/DevTools available, use web-based tools:

1. web_fetch "https://pagespeed.web.dev/analysis?url={encoded_url}" — Google's free tool
2. web_search "webpagetest {url}" — find cached results
3. web_search "site:{domain} core web vitals" — find CrUX data
4. Check for obvious issues: render-blocking CSS/JS, missing preloads, no meta viewport

Phase 2: Diagnosis — The Performance Waterfall

Critical Rendering Path Analysis

DNS → TCP → TLS → TTFB → HTML Parse → CSSOM → Render Tree → FCP → LCP
                                ↓
                         JS Download → Parse → Execute → INP

Bottleneck Decision Tree:

High TTFB (>800ms)?
├─ YES → Phase 3A: Server optimization
└─ NO → High FCP (>1.8s)?
    ├─ YES → Phase 3B: Render-blocking resources
    └─ NO → High LCP (>2.5s)?
        ├─ YES → Phase 3C: Hero element optimization
        └─ NO → High TBT (>200ms)?
            ├─ YES → Phase 3D: JavaScript optimization
            └─ NO → High CLS (>0.1)?
                ├─ YES → Phase 3E: Layout stability
                └─ NO → High INP (>200ms)?
                    ├─ YES → Phase 3F: Interaction optimization
                    └─ NO → ✅ Performance is good!

Resource Impact Scoring

Rate each resource by impact:

| Factor | Weight | Score 1 | Score 3 | Score 5 | |--------|--------|---------|---------|---------| | Size (KB) | 3x | <10 | 10-100 | >100 | | Render-blocking | 5x | No | Partial | Full | | Above-fold impact | 4x | None | Indirect | Direct | | Cacheable | 2x | Long cache | Short cache | No cache | | Compressible | 2x | Already done | Possible | Not compressed |

Priority = Sum(Factor × Weight). Fix highest scores first.

Phase 3: Fix Playbooks

3A: Server Optimization (TTFB)

Quick wins:

# CDN: If no CDN, this is #1 priority
# Check: curl -sI {url} | grep -i 'x-cache\|cf-cache\|x-cdn'

# Compression: Must have brotli or gzip
# Check: curl -sI -H "Accept-Encoding: br,gzip" {url} | grep -i content-encoding

# HTTP/2 or HTTP/3
# Check: curl -sI --http2 {url} | head -1

Server-side checklist:

• [ ] CDN in front (Cloudflare, Fastly, CloudFront)
• [ ] Brotli compression enabled (20-30% smaller than gzip)
• [ ] HTTP/2 minimum, HTTP/3 if possible
• [ ] Server-side caching (Redis, Varnish)
• [ ] Database query optimization (<50ms per query)
• [ ] Connection pooling enabled
• [ ] Edge computing for dynamic content (Workers, Lambda@Edge)

Cache headers template:

# Static assets (CSS, JS, images, fonts)
Cache-Control: public, max-age=31536000, immutable

# HTML pages
Cache-Control: public, max-age=0, must-revalidate

# API responses
Cache-Control: private, max-age=60, stale-while-revalidate=300

3B: Render-Blocking Resources (FCP)

CSS optimization:

<!-- BEFORE: Render-blocking -->
<link rel="stylesheet" href="styles.css">

<!-- AFTER: Critical CSS inline + async load -->
<style>/* Critical above-fold CSS here (< 14KB) */</style>
<link rel="preload" href="styles.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
<noscript><link rel="stylesheet" href="styles.css"></noscript>

Rules:

• Inline critical CSS (above-fold styles, < 14KB)
• Defer non-critical CSS
• Remove unused CSS (typical savings: 60-90%)
• Combine media queries
• Avoid @import (creates sequential loading)

JavaScript optimization:

<!-- BEFORE: Render-blocking -->
<script src="app.js"></script>

<!-- AFTER: Non-blocking -->
<script src="app.js" defer></script>

<!-- OR: Independent scripts -->
<script src="analytics.js" async></script>

Rules:

• defer for app scripts (maintains order, runs after parse)
• async for independent scripts (analytics, ads)
• Never put