argusqa-os 9.5.3 → 9.5.5

package/glama.json

@@ -1,36 +1,36 @@
-{
-  "$schema": "https://glama.ai/mcp/schemas/server.json",
-  "name": "argus",
-  "description": "AI-powered QA harness that audits web apps via Chrome DevTools Protocol. Catches JS errors, network failures, a11y violations, SEO issues, security headers, CSS regressions, and more — directly from Claude conversations. 7 MCP tools: argus_audit (fast 8-analyzer pass), argus_audit_full (Lighthouse + memory + responsive), argus_compare (dev vs staging diff), argus_last_report (retrieve last JSON report), argus_watch_snapshot (live tab snapshot without navigating), argus_get_context (LLM-optimized context + fix loop with snapshot_id diff), argus_design_audit (Figma design fidelity — 13 finding types). 128 test blocks, 565 hard assertions, 56 detection categories.",
-  "maintainers": ["ironclawdevs27"],
-  "tools": [
-    {
-      "name": "argus_audit",
-      "description": "Fast QA audit — JS errors, network failures (4xx/5xx), API frequency loops, CSS cascade issues, SEO violations, security headers, accessibility, and content. Returns { findings, summary }. Supports cache: true to skip re-crawl on repeat calls."
-    },
-    {
-      "name": "argus_audit_full",
-      "description": "Deep QA audit — extends argus_audit with Lighthouse performance/accessibility scoring, responsive layout checks at 4 viewports, memory leak detection via heap snapshot, and accessibility tree analysis."
-    },
-    {
-      "name": "argus_compare",
-      "description": "Diffs dev vs staging environments side-by-side. Captures screenshots, runs all analyzers on each, and surfaces regressions — findings present in staging but not dev, or with changed severity."
-    },
-    {
-      "name": "argus_last_report",
-      "description": "Returns the most recent Argus JSON report from the reports/ directory without re-running a scan."
-    },
-    {
-      "name": "argus_watch_snapshot",
-      "description": "Snapshots the currently open Chrome tab without navigating — captures console errors, network failures, CORS blocks, and auth failures in one poll. Accepts optional tabId to inspect a specific tab."
-    },
-    {
-      "name": "argus_get_context",
-      "description": "LLM-optimized diagnostic context for the open Chrome tab. Returns snapshot_id for fix-loop diffing: pass it back on the next call to get resolved/new_issues/persisting arrays. Accepts optional tabId for multi-tab workflows."
-    },
-    {
-      "name": "argus_design_audit",
-      "description": "Full Figma design-to-implementation fidelity audit. Fetches design spec from a Figma frame URL (requires FIGMA_API_TOKEN) and compares every extracted property against live DOM computed styles. Detects 13 mismatch finding types: CSS token values, component presence, fill/text color (RGB distance), typography (fontSize/fontWeight/lineHeight/fontFamily/letterSpacing), Auto Layout padding and gap, border-radius (per-corner), bounding-box overflow, absolute position drift (scroll-corrected x/y vs Figma bounds), border stroke (color+weight), box-shadow (offset+blur+spread+color), opacity, and text content. Selector fallback: tries [data-testid], [aria-label], #id, .class per node."
-    }
-  ]
-}
+{
+  "$schema": "https://glama.ai/mcp/schemas/server.json",
+  "name": "argus",
+  "description": "AI-powered QA harness that audits web apps via Chrome DevTools Protocol. Catches JS errors, network failures, a11y violations, SEO issues, security headers, CSS regressions, and more — directly from Claude conversations. 7 MCP tools: argus_audit (fast 8-analyzer pass), argus_audit_full (Lighthouse + memory + responsive), argus_compare (dev vs staging diff), argus_last_report (retrieve last JSON report), argus_watch_snapshot (live tab snapshot without navigating), argus_get_context (LLM-optimized context + fix loop with snapshot_id diff), argus_design_audit (Figma design fidelity — 13 finding types). 130 test blocks, 581 hard assertions, 58 detection categories.",
+  "maintainers": ["ironclawdevs27"],
+  "tools": [
+    {
+      "name": "argus_audit",
+      "description": "Fast QA audit — JS errors, network failures (4xx/5xx), API frequency loops, CSS cascade issues, SEO violations, security headers, accessibility, and content. Returns { findings, summary }. Supports cache: true to skip re-crawl on repeat calls."
+    },
+    {
+      "name": "argus_audit_full",
+      "description": "Deep QA audit — extends argus_audit with Lighthouse performance/accessibility scoring, responsive layout checks at 4 viewports, memory leak detection via heap snapshot, and accessibility tree analysis."
+    },
+    {
+      "name": "argus_compare",
+      "description": "Diffs dev vs staging environments side-by-side. Captures screenshots, runs all analyzers on each, and surfaces regressions — findings present in staging but not dev, or with changed severity."
+    },
+    {
+      "name": "argus_last_report",
+      "description": "Returns the most recent Argus JSON report from the reports/ directory without re-running a scan."
+    },
+    {
+      "name": "argus_watch_snapshot",
+      "description": "Snapshots the currently open Chrome tab without navigating — captures console errors, network failures, CORS blocks, and auth failures in one poll. Accepts optional tabId to inspect a specific tab."
+    },
+    {
+      "name": "argus_get_context",
+      "description": "LLM-optimized diagnostic context for the open Chrome tab. Returns snapshot_id for fix-loop diffing: pass it back on the next call to get resolved/new_issues/persisting arrays. Accepts optional tabId for multi-tab workflows."
+    },
+    {
+      "name": "argus_design_audit",
+      "description": "Full Figma design-to-implementation fidelity audit. Fetches design spec from a Figma frame URL (requires FIGMA_API_TOKEN) and compares every extracted property against live DOM computed styles. Detects 13 mismatch finding types: CSS token values, component presence, fill/text color (RGB distance), typography (fontSize/fontWeight/lineHeight/fontFamily/letterSpacing), Auto Layout padding and gap, border-radius (per-corner), bounding-box overflow, absolute position drift (scroll-corrected x/y vs Figma bounds), border stroke (color+weight), box-shadow (offset+blur+spread+color), opacity, and text content. Selector fallback: tries [data-testid], [aria-label], #id, .class per node."
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "argusqa-os",
-  "version": "9.5.3",
+  "version": "9.5.5",
   "mcpName": "io.github.ironclawdevs27/argus",
   "description": "Argus — AI-powered automated dev-testing platform using Chrome DevTools MCP and Claude Code",
   "keywords": [

package/src/config/targets.js

@@ -64,6 +64,10 @@ export const thresholds = {
     seo:              { critical: 50, warning: 90 },
     'best-practices': { critical: 50, warning: 90 },
   },
+  visual: {
+    warnPercent: parseFloat(process.env.VISUAL_WARN_PERCENT ?? '0.1'),  // % pixels changed → warning
+    critPercent: parseFloat(process.env.VISUAL_CRIT_PERCENT ?? '5.0'),  // % pixels changed → critical
+  },
 };
 
 /**

package/src/mcp-server.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 /**
- * Argus MCP Server (v9.5.3)
+ * Argus MCP Server (v9.5.5)
  *
  * Exposes Argus as an MCP server so Claude (or any MCP client) can call
  * argus_audit, argus_audit_full, argus_compare, argus_last_report, and
@@ -336,7 +336,7 @@ async function handleLastReport() {
 // ── Server bootstrap ──────────────────────────────────────────────────────────
 
 const server = new Server(
-  { name: 'argus', version: '9.5.3' },
+  { name: 'argus', version: '9.5.5' },
   { capabilities: { tools: {} } },
 );
 

package/src/orchestration/orchestrator.js

@@ -43,6 +43,8 @@ import '../utils/snapshot-analyzer.js';
 import '../utils/keyboard-analyzer.js';
 import '../utils/theme-analyzer.js';
 import '../utils/design-fidelity-analyzer.js';
+import '../utils/web-vitals-analyzer.js';
+import '../utils/visual-diff-analyzer.js';
 
 import { getExpensive }          from '../registry.js';
 import { deduplicateFindings as deduplicateErrors } from './report-processor.js';

package/src/utils/visual-diff-analyzer.js

@@ -0,0 +1,207 @@
+/**
+ * ARGUS Visual Regression Analyzer (Sprint 3 — A8)
+ *
+ * Per-route visual regression detection via screenshot baseline comparison.
+ * Takes a PNG screenshot, compares it pixel-by-pixel against a stored baseline,
+ * and emits a finding when the diff exceeds the configured threshold.
+ *
+ * Works in headless Chrome — uses the Performance API screenshot path, not Lighthouse.
+ *
+ * Findings emitted:
+ *   visual_baseline_created — info, first run for a URL (baseline saved, no prior exists)
+ *   visual_regression       — warning ≥0.1%, critical ≥5% pixels changed
+ *   visual_diff_summary     — info, always emitted with full diff metrics
+ *
+ * Baseline storage: {config.outputDir}/baselines/screenshots/{slug}.png
+ * Override via opts.baselineDir for testing.
+ */
+
+import fs   from 'fs';
+import path from 'path';
+import os   from 'os';
+import { PNG }        from 'pngjs';
+import pixelmatch     from 'pixelmatch';
+import { registerExpensive } from '../registry.js';
+import { childLogger }       from './logger.js';
+import { slugify }           from './slug.js';
+import { config, thresholds } from '../config/targets.js';
+
+const logger = childLogger('visual-diff');
+
+// ── Thresholds ─────────────────────────────────────────────────────────────────
+const WARN_PERCENT = thresholds.visual?.warnPercent ?? 0.1;  // %
+const CRIT_PERCENT = thresholds.visual?.critPercent ?? 5.0;  // %
+
+// ── PNG helpers ────────────────────────────────────────────────────────────────
+
+function cropPng(img, width, height) {
+  if (img.width === width && img.height === height) return img;
+  const out = new PNG({ width, height });
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const src = (y * img.width + x) * 4;
+      const dst = (y * width + x) * 4;
+      out.data[dst]     = img.data[src];
+      out.data[dst + 1] = img.data[src + 1];
+      out.data[dst + 2] = img.data[src + 2];
+      out.data[dst + 3] = img.data[src + 3];
+    }
+  }
+  return out;
+}
+
+/**
+ * Compare two PNG Buffers pixel-by-pixel using pixelmatch.
+ *
+ * @param {Buffer} bufA
+ * @param {Buffer} bufB
+ * @returns {{ diffPixels: number, totalPixels: number, diffPercent: number }}
+ */
+function comparePngBuffers(bufA, bufB) {
+  const imgA = PNG.sync.read(bufA);
+  const imgB = PNG.sync.read(bufB);
+
+  const width  = Math.min(imgA.width, imgB.width);
+  const height = Math.min(imgA.height, imgB.height);
+
+  if (width === 0 || height === 0) {
+    throw new Error(`visual-diff: zero-dimension PNG (${imgA.width}×${imgA.height} vs ${imgB.width}×${imgB.height})`);
+  }
+
+  const croppedA = cropPng(imgA, width, height);
+  const croppedB = cropPng(imgB, width, height);
+  const diff     = new PNG({ width, height });
+
+  const diffPixels  = pixelmatch(croppedA.data, croppedB.data, diff.data, width, height, { threshold: 0.1 });
+  const totalPixels = width * height;
+  const diffPercent = (diffPixels / totalPixels) * 100;
+
+  return { diffPixels, totalPixels, diffPercent };
+}
+
+// ── Public API ─────────────────────────────────────────────────────────────────
+
+/**
+ * Capture a screenshot of `url` and compare against the stored baseline.
+ *
+ * First run (no baseline): saves the screenshot as the new baseline and returns
+ * a `visual_baseline_created` info finding.
+ *
+ * Subsequent runs: compares pixel-by-pixel and emits `visual_regression` when
+ * the diff exceeds the threshold, plus always emits `visual_diff_summary`.
+ *
+ * @param {object}  browser          - CdpBrowserAdapter
+ * @param {string}  url              - Page URL (already loaded)
+ * @param {object}  [opts]
+ * @param {string}  [opts.baselineDir] - Override baseline storage directory
+ * @returns {Promise<object[]>}
+ */
+export async function analyzeVisualRegression(browser, url, opts = {}) {
+  const findings = [];
+
+  // ── 1. Take screenshot ──────────────────────────────────────────────────────
+  // Use filePath so the MCP server writes the PNG to disk — take_screenshot
+  // returns an image content block, not { data: base64 }, so the filePath
+  // approach is the only reliable way to get raw PNG bytes in headless mode.
+  const tmpPath = path.join(os.tmpdir(), `argus-visual-${Date.now()}-${slugify(url)}.png`);
+  try {
+    await browser.screenshot({ format: 'png', filePath: tmpPath });
+  } catch (err) {
+    logger.warn(`[ARGUS] visual-diff: screenshot failed for ${url}: ${err.message}`);
+    return findings;
+  }
+
+  let currentBuf;
+  try {
+    currentBuf = fs.readFileSync(tmpPath);
+  } catch (err) {
+    logger.warn(`[ARGUS] visual-diff: could not read screenshot from ${tmpPath}: ${err.message}`);
+    return findings;
+  } finally {
+    try { fs.unlinkSync(tmpPath); } catch {}
+  }
+
+  if (!currentBuf || currentBuf.length === 0) {
+    logger.warn(`[ARGUS] visual-diff: empty screenshot for ${url}`);
+    return findings;
+  }
+
+  // ── 2. Resolve baseline path ────────────────────────────────────────────────
+  const baselineDir = opts.baselineDir ??
+    path.join(config.outputDir, 'baselines', 'screenshots');
+
+  try {
+    fs.mkdirSync(baselineDir, { recursive: true });
+  } catch (err) {
+    logger.warn(`[ARGUS] visual-diff: could not create baseline dir ${baselineDir}: ${err.message}`);
+    return findings;
+  }
+
+  const slug         = slugify(url);
+  const baselinePath = path.join(baselineDir, `${slug}.png`);
+
+  // ── 3. First run: save baseline ─────────────────────────────────────────────
+  if (!fs.existsSync(baselinePath)) {
+    try {
+      fs.writeFileSync(baselinePath, currentBuf);
+    } catch (err) {
+      logger.warn(`[ARGUS] visual-diff: could not write baseline ${baselinePath}: ${err.message}`);
+      return findings;
+    }
+
+    findings.push({
+      type:     'visual_baseline_created',
+      message:  `Visual baseline saved for ${url} — next run will compare against this snapshot`,
+      severity: 'info',
+      url,
+      baselinePath,
+    });
+    return findings;
+  }
+
+  // ── 4. Compare against existing baseline ────────────────────────────────────
+  let result;
+  try {
+    const baselineBuf = fs.readFileSync(baselinePath);
+    result = comparePngBuffers(baselineBuf, currentBuf);
+  } catch (err) {
+    logger.warn(`[ARGUS] visual-diff: comparison failed for ${url}: ${err.message}`);
+    return findings;
+  }
+
+  const { diffPixels, totalPixels, diffPercent } = result;
+
+  // ── 5. Emit regression finding if threshold exceeded ────────────────────────
+  if (diffPercent >= WARN_PERCENT) {
+    const sev = diffPercent >= CRIT_PERCENT ? 'critical' : 'warning';
+    findings.push({
+      type:        'visual_regression',
+      diffPercent: parseFloat(diffPercent.toFixed(3)),
+      diffPixels,
+      totalPixels,
+      threshold:   WARN_PERCENT,
+      message:     `Visual regression: ${diffPercent.toFixed(2)}% pixels changed — threshold ${WARN_PERCENT}% (warning) / ${CRIT_PERCENT}% (critical)`,
+      severity:    sev,
+      url,
+    });
+  }
+
+  // ── 6. Summary — always emitted ─────────────────────────────────────────────
+  findings.push({
+    type:        'visual_diff_summary',
+    diffPercent: parseFloat(diffPercent.toFixed(3)),
+    diffPixels,
+    totalPixels,
+    message:     `Visual diff: ${diffPercent.toFixed(3)}% (${diffPixels}/${totalPixels} pixels changed)`,
+    severity:    'info',
+    url,
+  });
+
+  return findings;
+}
+
+// ── Self-registration ──────────────────────────────────────────────────────────
+registerExpensive({
+  name:    'visual',
+  analyze: (browser, url) => analyzeVisualRegression(browser, url),
+});

package/src/utils/web-vitals-analyzer.js

@@ -0,0 +1,284 @@
+/**
+ * ARGUS Web Vitals Analyzer (Sprint 9 — Advanced Performance Metrics)
+ *
+ * Captures Core Web Vitals and performance metrics directly via the browser
+ * Performance API. Unlike Lighthouse, this works in headless Chrome — metrics
+ * are always available in CI without requiring a non-headless browser.
+ *
+ * Metrics captured:
+ *   LCP  — Largest Contentful Paint (PerformanceObserver, buffered)
+ *   CLS  — Cumulative Layout Shift   (PerformanceObserver, buffered)
+ *   FCP  — First Contentful Paint    (getEntriesByType('paint'))
+ *   TTI  — Time to Interactive       (NavigationTiming.domInteractive)
+ *   TTFB — Time to First Byte        (NavigationTiming.responseStart)
+ *
+ * Bundle / resource monitoring:
+ *   perf_bundle_large     — JS file > 500 KB (warning) or > 2 MB (critical)
+ *   perf_bundle_large_css — CSS file > 150 KB (warning)
+ *
+ * Findings emitted:
+ *   perf_lcp           — warning ≥2500ms, critical ≥4000ms
+ *   perf_cls           — warning ≥0.1,    critical ≥0.25
+ *   perf_fcp           — warning ≥1800ms, critical ≥3000ms
+ *   perf_tti           — warning ≥3500ms, critical ≥7300ms
+ *   perf_bundle_large  — warning / critical per JS/CSS size thresholds
+ *   perf_vitals_summary — info, always emitted when analysis runs
+ */
+
+import { registerExpensive } from '../registry.js';
+import { unwrapEval }        from './mcp-client.js';
+import { childLogger }       from './logger.js';
+import { thresholds }        from '../config/targets.js';
+
+const logger = childLogger('web-vitals');
+
+// ── Thresholds ────────────────────────────────────────────────────────────────
+// Core Web Vitals "Needs Improvement" / "Poor" boundaries (Google 2024)
+const LCP_WARN  = thresholds.perf?.LCP  ?? 2500; // ms
+const LCP_CRIT  = 4000;                           // ms
+const CLS_WARN  = thresholds.perf?.CLS  ?? 0.1;
+const CLS_CRIT  = 0.25;
+const FCP_WARN  = 1800;  // ms
+const FCP_CRIT  = 3000;  // ms
+const TTI_WARN  = 3500;  // ms  (domInteractive)
+const TTI_CRIT  = 7300;  // ms
+
+const JS_WARN_BYTES  = 500  * 1024; // 500 KB
+const JS_CRIT_BYTES  = 2000 * 1024; // 2 MB
+const CSS_WARN_BYTES = 150  * 1024; // 150 KB
+
+// ── In-browser measurement script ────────────────────────────────────────────
+// Async — awaits PerformanceObserver callbacks for LCP/CLS (buffered entries
+// are delivered synchronously on observe(), so the setTimeout fallbacks are
+// safety nets only).
+const VITALS_SCRIPT = `async () => {
+  var result = {
+    lcp: null, cls: null, fcp: null,
+    tti: null, ttfb: null, domComplete: null,
+    resources: [],
+  };
+
+  // ── Navigation Timing ───────────────────────────────────────────────────────
+  var navEntries = performance.getEntriesByType('navigation');
+  if (navEntries.length > 0) {
+    var nav = navEntries[0];
+    result.ttfb        = Math.round(nav.responseStart);
+    result.tti         = Math.round(nav.domInteractive);
+    result.domComplete = Math.round(nav.domComplete);
+  }
+
+  // ── FCP (synchronous — available in paint entries buffer) ──────────────────
+  var paintEntries = performance.getEntriesByType('paint');
+  for (var i = 0; i < paintEntries.length; i++) {
+    if (paintEntries[i].name === 'first-contentful-paint') {
+      result.fcp = Math.round(paintEntries[i].startTime);
+      break;
+    }
+  }
+
+  // ── LCP (PerformanceObserver with buffered:true) ───────────────────────────
+  await new Promise(function(resolve) {
+    try {
+      var lcpObs = new PerformanceObserver(function(list) {
+        var entries = list.getEntries();
+        if (entries.length > 0) {
+          result.lcp = Math.round(entries[entries.length - 1].startTime);
+        }
+        lcpObs.disconnect();
+        resolve();
+      });
+      lcpObs.observe({ type: 'largest-contentful-paint', buffered: true });
+      setTimeout(resolve, 150); // fallback if no LCP entries
+    } catch (e) { resolve(); }
+  });
+
+  // ── CLS (PerformanceObserver with buffered:true) ───────────────────────────
+  var clsScore = 0;
+  await new Promise(function(resolve) {
+    try {
+      var clsObs = new PerformanceObserver(function(list) {
+        var entries = list.getEntries();
+        for (var j = 0; j < entries.length; j++) {
+          if (!entries[j].hadRecentInput) clsScore += entries[j].value;
+        }
+        clsObs.disconnect();
+        resolve();
+      });
+      clsObs.observe({ type: 'layout-shift', buffered: true });
+      setTimeout(resolve, 150);
+    } catch (e) { resolve(); }
+  });
+  result.cls = Math.round(clsScore * 1000) / 1000;
+
+  // ── Resource Timing — JS / CSS bundles ────────────────────────────────────
+  var pageOrigin;
+  try { pageOrigin = new URL(window.location.href).origin; } catch (e) { pageOrigin = ''; }
+  var resEntries = performance.getEntriesByType('resource');
+  for (var k = 0; k < resEntries.length; k++) {
+    var r = resEntries[k];
+    if (!r.name) continue;
+    var pathname = r.name.split('?')[0];
+    var ext = pathname.split('.').pop().toLowerCase();
+    if (ext !== 'js' && ext !== 'css') continue;
+    var size = r.transferSize || r.encodedBodySize || r.decodedBodySize || 0;
+    // BFcache / memory-cache restores set all three size fields to 0.
+    // Fall back to a HEAD request to get Content-Length for same-origin resources.
+    if (size === 0) {
+      try {
+        var isLocal = new URL(r.name).origin === pageOrigin;
+        if (isLocal) {
+          var head = await fetch(r.name, { method: 'HEAD', cache: 'no-store' });
+          var cl = parseInt(head.headers.get('content-length') || '0', 10);
+          if (cl > 0) size = cl;
+        }
+      } catch (e) {}
+    }
+    if (size === 0) continue; // CORS opaque — skip
+    var isThirdParty = false;
+    try { isThirdParty = new URL(r.name).origin !== pageOrigin; } catch (e) {}
+    result.resources.push({
+      url: r.name,
+      ext: ext,
+      sizeBytes: size,
+      durationMs: Math.round(r.duration),
+      isThirdParty: isThirdParty,
+    });
+  }
+
+  return JSON.stringify(result);
+}`;
+
+// ── JSON parse helper ─────────────────────────────────────────────────────────
+function parseJson(raw) {
+  try {
+    const str = unwrapEval(raw);
+    if (typeof str === 'object' && str !== null) return str;
+    return JSON.parse(str);
+  } catch {
+    return null;
+  }
+}
+
+// ── Public API ────────────────────────────────────────────────────────────────
+
+/**
+ * Capture Web Vitals and performance metrics for a single page.
+ *
+ * Navigates fresh so timing data starts from scratch on each run.
+ *
+ * @param {object} browser  - CdpBrowserAdapter
+ * @param {string} url      - Fully-qualified URL to analyse
+ * @returns {Promise<object[]>} Array of performance finding objects
+ */
+export async function analyzeWebVitals(browser, url) {
+  const findings = [];
+
+  // Navigate fresh — timing APIs measure from navigation start
+  try {
+    await browser.navigate(url);
+    await browser.waitFor({ state: 'networkidle' }).catch(() => {});
+    // Let PerformanceObserver callbacks settle after networkidle
+    await new Promise(r => setTimeout(r, 1200));
+  } catch {
+    return findings;
+  }
+
+  let data;
+  try {
+    const raw = await browser.evaluate(VITALS_SCRIPT);
+    data = parseJson(raw);
+  } catch (err) {
+    logger.warn(`[ARGUS] web-vitals: measurement script failed for ${url}: ${err.message}`);
+    return findings;
+  }
+  if (!data) return findings;
+
+  const { lcp, cls, fcp, tti, ttfb, resources = [] } = data;
+
+  // ── LCP ───────────────────────────────────────────────────────────────────
+  if (lcp !== null) {
+    const sev = lcp >= LCP_CRIT ? 'critical' : lcp >= LCP_WARN ? 'warning' : 'info';
+    if (sev !== 'info') {
+      findings.push({
+        type: 'perf_lcp', value: lcp, threshold: LCP_WARN,
+        message: `LCP ${lcp}ms — threshold ${LCP_WARN}ms (warning) / ${LCP_CRIT}ms (critical)`,
+        severity: sev, url,
+      });
+    }
+  }
+
+  // ── CLS ───────────────────────────────────────────────────────────────────
+  if (cls !== null && cls >= CLS_WARN) {
+    const sev = cls >= CLS_CRIT ? 'critical' : 'warning';
+    findings.push({
+      type: 'perf_cls', value: cls, threshold: CLS_WARN,
+      message: `CLS ${cls} — threshold ${CLS_WARN} (warning) / ${CLS_CRIT} (critical)`,
+      severity: sev, url,
+    });
+  }
+
+  // ── FCP ───────────────────────────────────────────────────────────────────
+  if (fcp !== null && fcp >= FCP_WARN) {
+    const sev = fcp >= FCP_CRIT ? 'critical' : 'warning';
+    findings.push({
+      type: 'perf_fcp', value: fcp, threshold: FCP_WARN,
+      message: `FCP ${fcp}ms — threshold ${FCP_WARN}ms (warning) / ${FCP_CRIT}ms (critical)`,
+      severity: sev, url,
+    });
+  }
+
+  // ── TTI ───────────────────────────────────────────────────────────────────
+  if (tti !== null && tti >= TTI_WARN) {
+    const sev = tti >= TTI_CRIT ? 'critical' : 'warning';
+    findings.push({
+      type: 'perf_tti', value: tti, threshold: TTI_WARN,
+      message: `TTI (domInteractive) ${tti}ms — threshold ${TTI_WARN}ms (warning) / ${TTI_CRIT}ms (critical)`,
+      severity: sev, url,
+    });
+  }
+
+  // ── Bundle sizes ──────────────────────────────────────────────────────────
+  for (const r of resources) {
+    const kb = Math.round(r.sizeBytes / 1024);
+    if (r.ext === 'js') {
+      if (r.sizeBytes >= JS_WARN_BYTES) {
+        const sev = r.sizeBytes >= JS_CRIT_BYTES ? 'critical' : 'warning';
+        findings.push({
+          type: 'perf_bundle_large', ext: 'js', sizeKb: kb,
+          resourceUrl: r.url, durationMs: r.durationMs, isThirdParty: r.isThirdParty,
+          message: `JS bundle ${kb}KB — threshold ${JS_WARN_BYTES / 1024}KB (warning) / ${JS_CRIT_BYTES / 1024}KB (critical): ${r.url}`,
+          severity: sev, url,
+        });
+      }
+    } else if (r.ext === 'css' && r.sizeBytes >= CSS_WARN_BYTES) {
+      findings.push({
+        type: 'perf_bundle_large', ext: 'css', sizeKb: kb,
+        resourceUrl: r.url, durationMs: r.durationMs, isThirdParty: r.isThirdParty,
+        message: `CSS bundle ${kb}KB — threshold ${CSS_WARN_BYTES / 1024}KB (warning): ${r.url}`,
+        severity: 'warning', url,
+      });
+    }
+  }
+
+  // ── Summary — always emitted ──────────────────────────────────────────────
+  findings.push({
+    type:          'perf_vitals_summary',
+    lcp:           lcp ?? null,
+    cls:           cls ?? null,
+    fcp:           fcp ?? null,
+    tti:           tti ?? null,
+    ttfb:          ttfb ?? null,
+    bundleCount:   resources.length,
+    message: `Web Vitals: LCP=${lcp ?? 'N/A'}ms CLS=${cls ?? 'N/A'} FCP=${fcp ?? 'N/A'}ms TTI=${tti ?? 'N/A'}ms TTFB=${ttfb ?? 'N/A'}ms`,
+    severity:      'info',
+    url,
+  });
+
+  return findings;
+}
+
+// ── Self-registration ─────────────────────────────────────────────────────────
+registerExpensive({
+  name: 'web-vitals',
+  analyze: (browser, url) => analyzeWebVitals(browser, url),
+});