@mmerterden/multi-agent-pipeline 8.6.0

package/pipeline/skills/shared/external/web-performance/SKILL.md

@@ -0,0 +1,345 @@
+---
+description: "Web performance: Core Web Vitals (LCP, INP, CLS), image optimization, code splitting, caching strategies, bundle analysis, Lighthouse"
+tags: [performance, core-web-vitals, lighthouse, optimization, frontend, caching]
+version: "2025.1"
+---
+
+# Web Performance Optimization
+
+## Core Web Vitals (2024-2025)
+
+Google uses Core Web Vitals as ranking signals. All pages should meet the "Good" thresholds.
+
+| Metric | Good | Needs Improvement | Poor | What It Measures |
+|--------|------|-------------------|------|-----------------|
+| **LCP** | <= 2.5s | <= 4.0s | > 4.0s | Largest Contentful Paint — loading speed |
+| **INP** | <= 200ms | <= 500ms | > 500ms | Interaction to Next Paint — responsiveness |
+| **CLS** | <= 0.1 | <= 0.25 | > 0.25 | Cumulative Layout Shift — visual stability |
+
+## Image Optimization
+
+```tsx
+// Next.js Image component (automatic optimization)
+import Image from 'next/image';
+
+function HeroSection() {
+  return (
+    <section>
+      {/* LCP image: priority + eager loading */}
+      <Image
+        src="/hero.jpg"
+        alt="Hero banner showing product lineup"
+        width={1200}
+        height={600}
+        priority  // Preloads — use for above-the-fold LCP images
+        sizes="100vw"
+        quality={85}
+      />
+
+      {/* Below-the-fold: lazy load (default) */}
+      <Image
+        src="/feature.jpg"
+        alt="Product feature"
+        width={600}
+        height={400}
+        sizes="(max-width: 768px) 100vw, 50vw"
+        placeholder="blur"
+        blurDataURL="data:image/jpeg;base64,..."
+      />
+    </section>
+  );
+}
+
+// Native HTML with srcset and sizes
+// <img
+//   src="photo-800.jpg"
+//   srcset="photo-400.jpg 400w, photo-800.jpg 800w, photo-1200.jpg 1200w"
+//   sizes="(max-width: 600px) 100vw, (max-width: 1200px) 50vw, 800px"
+//   alt="Product photo"
+//   loading="lazy"
+//   decoding="async"
+//   width="800"
+//   height="600"
+// />
+```
+
+### Modern Image Formats
+
+```html
+<picture>
+  <source srcset="photo.avif" type="image/avif" />
+  <source srcset="photo.webp" type="image/webp" />
+  <img src="photo.jpg" alt="Fallback for older browsers" loading="lazy" />
+</picture>
+```
+
+## Code Splitting
+
+```tsx
+// React.lazy for route-level splitting
+import { lazy, Suspense } from 'react';
+
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+const Settings = lazy(() => import('./pages/Settings'));
+const Analytics = lazy(() =>
+  import('./pages/Analytics').then((mod) => ({ default: mod.AnalyticsPage }))
+);
+
+function App() {
+  return (
+    <Suspense fallback={<PageSkeleton />}>
+      <Routes>
+        <Route path="/dashboard" element={<Dashboard />} />
+        <Route path="/settings" element={<Settings />} />
+        <Route path="/analytics" element={<Analytics />} />
+      </Routes>
+    </Suspense>
+  );
+}
+
+// Dynamic import for heavy libraries
+async function generateChart(data: ChartData) {
+  const { Chart } = await import('chart.js/auto');
+  const canvas = document.getElementById('chart') as HTMLCanvasElement;
+  new Chart(canvas, { type: 'line', data });
+}
+
+// Next.js: next/dynamic with SSR control
+import dynamic from 'next/dynamic';
+
+const HeavyEditor = dynamic(() => import('@/components/RichTextEditor'), {
+  ssr: false,
+  loading: () => <EditorSkeleton />,
+});
+```
+
+## Tree Shaking
+
+```typescript
+// Import only what you need (tree-shakeable)
+import { debounce, throttle } from 'lodash-es'; // NOT 'lodash'
+import { format, parseISO } from 'date-fns'; // NOT import * as dateFns
+
+// Barrel exports can hurt tree shaking — use direct imports
+import { Button } from '@/components/Button'; // Direct
+// NOT: import { Button } from '@/components'; // Barrel — may pull entire lib
+
+// Mark side-effect-free in package.json
+// {
+//   "sideEffects": false,   // or ["*.css"] for CSS-only side effects
+// }
+```
+
+## Bundle Analysis
+
+```bash
+# Next.js
+ANALYZE=true next build        # with @next/bundle-analyzer
+
+# Vite
+npx vite-bundle-visualizer     # generates stats.html
+
+# Webpack
+npx webpack-bundle-analyzer stats.json
+```
+
+```javascript
+// next.config.js with bundle analyzer
+const withBundleAnalyzer = require('@next/bundle-analyzer')({
+  enabled: process.env.ANALYZE === 'true',
+});
+
+module.exports = withBundleAnalyzer({
+  // next config
+});
+```
+
+## Caching Strategies
+
+```typescript
+// Service Worker caching with Workbox
+import { precacheAndRoute } from 'workbox-precaching';
+import { registerRoute } from 'workbox-routing';
+import { StaleWhileRevalidate, CacheFirst, NetworkFirst } from 'workbox-strategies';
+import { ExpirationPlugin } from 'workbox-expiration';
+
+// Precache static assets
+precacheAndRoute(self.__WB_MANIFEST);
+
+// Cache-first for images (long-lived)
+registerRoute(
+  ({ request }) => request.destination === 'image',
+  new CacheFirst({
+    cacheName: 'images',
+    plugins: [
+      new ExpirationPlugin({ maxEntries: 100, maxAgeSeconds: 30 * 24 * 60 * 60 }),
+    ],
+  })
+);
+
+// Stale-while-revalidate for CSS/JS
+registerRoute(
+  ({ request }) => request.destination === 'style' || request.destination === 'script',
+  new StaleWhileRevalidate({ cacheName: 'static-resources' })
+);
+
+// Network-first for API calls
+registerRoute(
+  ({ url }) => url.pathname.startsWith('/api/'),
+  new NetworkFirst({
+    cacheName: 'api-cache',
+    networkTimeoutSeconds: 3,
+  })
+);
+```
+
+### HTTP Caching Headers
+
+```typescript
+// Next.js API route / middleware
+export async function GET() {
+  return new Response(JSON.stringify(data), {
+    headers: {
+      // Immutable assets (hashed filenames)
+      'Cache-Control': 'public, max-age=31536000, immutable',
+
+      // Dynamic content with revalidation
+      // 'Cache-Control': 'public, max-age=0, s-maxage=60, stale-while-revalidate=300',
+
+      // Private user data
+      // 'Cache-Control': 'private, no-cache, no-store, must-revalidate',
+    },
+  });
+}
+```
+
+## Reducing Layout Shift (CLS)
+
+```html
+<!-- Always set width and height on images -->
+<img src="photo.jpg" alt="..." width="800" height="600" />
+
+<!-- Use aspect-ratio for responsive containers -->
+<style>
+  .video-container {
+    aspect-ratio: 16 / 9;
+    width: 100%;
+    background: #f3f4f6;
+  }
+</style>
+
+<!-- Reserve space for dynamic content -->
+<style>
+  .ad-slot {
+    min-height: 250px; /* Reserve space before ad loads */
+  }
+  .skeleton {
+    min-height: 200px;
+    animation: pulse 2s infinite;
+  }
+</style>
+
+<!-- Prevent FOUT (Flash of Unstyled Text) -->
+<style>
+  @font-face {
+    font-family: 'CustomFont';
+    src: url('/fonts/custom.woff2') format('woff2');
+    font-display: swap; /* or 'optional' for less CLS */
+  }
+</style>
+```
+
+## Reducing INP (Interaction to Next Paint)
+
+```typescript
+// Break up long tasks with scheduler.yield() or setTimeout
+async function processLargeList(items: Item[]) {
+  const CHUNK_SIZE = 50;
+  for (let i = 0; i < items.length; i += CHUNK_SIZE) {
+    const chunk = items.slice(i, i + CHUNK_SIZE);
+    processChunk(chunk);
+
+    // Yield to the browser between chunks
+    if ('scheduler' in globalThis && 'yield' in scheduler) {
+      await scheduler.yield();
+    } else {
+      await new Promise((resolve) => setTimeout(resolve, 0));
+    }
+  }
+}
+
+// Debounce expensive input handlers
+import { useDebouncedCallback } from 'use-debounce';
+
+function SearchInput() {
+  const handleSearch = useDebouncedCallback((term: string) => {
+    performSearch(term); // Expensive operation
+  }, 300);
+
+  return <input onChange={(e) => handleSearch(e.target.value)} />;
+}
+
+// Use CSS containment for complex layouts
+// .card { contain: content; }
+// .sidebar { contain: layout style; }
+```
+
+## Lighthouse Audit Checklist
+
+```bash
+# CLI audit
+npx lighthouse https://mysite.com --output=html --view
+
+# CI integration (Lighthouse CI)
+npx lhci autorun --config=lighthouserc.json
+```
+
+```json
+// lighthouserc.json
+{
+  "ci": {
+    "collect": { "url": ["http://localhost:3000/", "http://localhost:3000/products"] },
+    "assert": {
+      "assertions": {
+        "categories:performance": ["error", { "minScore": 0.9 }],
+        "categories:accessibility": ["error", { "minScore": 0.95 }],
+        "categories:best-practices": ["error", { "minScore": 0.9 }],
+        "categories:seo": ["error", { "minScore": 0.9 }]
+      }
+    }
+  }
+}
+```
+
+## Do's
+
+- Measure before optimizing (use Lighthouse, WebPageTest, CrUX)
+- Set `priority` on LCP images and preload critical fonts
+- Use `loading="lazy"` on below-the-fold images
+- Set explicit width/height on all images and videos to prevent CLS
+- Code-split at the route level and lazy-load heavy components
+- Use modern image formats (AVIF > WebP > JPEG)
+- Implement appropriate caching headers for all responses
+- Use `font-display: swap` or `optional` for web fonts
+
+## Don'ts
+
+- Do not load unused JavaScript (audit with bundle analyzer)
+- Do not block rendering with synchronous scripts in `<head>`
+- Do not use layout-thrashing DOM reads/writes in loops
+- Do not lazy-load above-the-fold content
+- Do not import entire libraries when you need one function
+- Do not ignore CLS from dynamically injected content (ads, banners)
+- Do not use `document.write()` — it blocks parsing
+- Do not serve uncompressed assets (enable gzip/brotli)
+
+## Troubleshooting
+
+| Problem | Cause | Solution |
+|---------|-------|----------|
+| High LCP | Large hero image, render-blocking CSS/JS | Optimize image, preload critical resources, inline critical CSS |
+| High CLS | Images without dimensions, late-injected content | Set explicit sizes, reserve space with skeleton/placeholder |
+| High INP | Long tasks blocking main thread | Break tasks with `scheduler.yield()`, use Web Workers |
+| Large bundle | Importing entire libraries | Use tree-shakeable imports, analyze with bundle visualizer |
+| Slow TTFB | No server caching, slow DB | Add CDN, implement server-side caching, optimize queries |
+| Flash of unstyled text | Web font loading | Use `font-display: swap`, preload font files |