feat(perf): add CrUX field data and PageSpeed Insights tools

[vibegui]

Summary

Adds real-user performance data to site-diagnostics via two new research tools, closing the gap between what Lighthouse measures in a lab and what actual users experience in the wild. Both share a single Google Cloud API key (GOOGLE_PAGESPEED_API_KEY).

Why

lighthouse_audit gives us a lab simulation — a snapshot from a clean environment on Google's servers. But Core Web Vitals pass/fail (an SEO ranking signal) is decided by real user data from Chrome UX Report. Without CrUX, our Performance health score was inferring user experience from a single synthetic run. Now we have both lenses.

What's new

1. research_crux — Chrome UX Report (real-user field data)

• Returns p75 LCP, INP, CLS, FCP, TTFB as 28-day rolling averages
• Good / needs-improvement / poor histogram distributions
• Optional 25-week history with improving / stable / degrading trend classification per metric
• Origin-level or URL-level queries, phone / desktop / all form factors
• Graceful handling of low-traffic sites (hasData: false)
• Ships cwvAssessment — authoritative CWV pass/fail + per-metric ratings

2. research_pagespeed — Google PageSpeed Insights

• Hosted Lighthouse via Google's infrastructure — no Browserless token required
• Returns 0-100 performance score, lab CWV (LCP, CLS, FCP, TBT, SI, TTI, TTFB), prioritized opportunities with ms / KB savings
• Alternative to lighthouse_audit when Browserless is unavailable or as a second opinion

3. Updated Phase 2 execution

New tools spawned in parallel with existing deep-analysis work (no added latency).

4. Updated Performance health-score rubric (0-20)

• Field CWV (0-10): derived from research_crux — 10 if passes CWV, 7 if 2/3 good, 4 if 1/3 good, 0 if all poor
• Technical (0-10): existing TTFB + weight + caching signals
• Falls back to lab-only scoring (0-20 from Technical alone) for low-traffic sites without CrUX data

Files changed

• api/lib/pagespeed.ts (new) — Shared CrUX + PSI clients, CWV thresholds, rating helpers
• api/tools/research-crux.ts (new) — Tool definition
• api/tools/research-pagespeed.ts (new) — Tool definition
• api/tools/index.ts — Register new tools
• shared/diagnostics.ts — Tool catalog, Phase 2 execution, Performance rubric

Environment

Set one env var:

GOOGLE_PAGESPEED_API_KEY=<google-cloud-api-key>

Enable these APIs on the key: Chrome UX Report API, PageSpeed Insights API.

Test plan

• bun install && bunx tsc --noEmit passes
• Run diagnose on a high-traffic site (e.g. bagaggio.com.br) — verify CrUX data appears and trend analysis shows up
• Run diagnose on a low-traffic site — verify graceful fallback with hasData: false note in the report
• Verify Performance health score reflects field CWV when available, falls back to lab when not
• Verify research_pagespeed works without BROWSERLESS_TOKEN set (uses Google's hosted Lighthouse)

🤖 Generated with Claude Code

---

Summary by cubic

Add real-user performance data with CrUX and a hosted Lighthouse option via PageSpeed Insights, and integrate both into diagnostics and the Performance score. This adds authoritative CWV pass/fail and PSI opportunities without needing BROWSERLESS_TOKEN.

• New Features

  • research_crux: p75 LCP/INP/CLS/FCP/TTFB (28-day), distributions, optional 25-week trends, origin or URL scope, CWV pass/fail; graceful fallback for low-traffic sites.
  • research_pagespeed: hosted Lighthouse via Google; returns 0–100 score, lab CWV, and prioritized opportunities; no BROWSERLESS_TOKEN required.
  • Phase 2 now spawns both tools in parallel with existing analysis.
  • Performance score: Field CWV (0–10) from research_crux + Technical (0–10); falls back to lab-only when CrUX is unavailable.

• Migration

  • Set GOOGLE_PAGESPEED_API_KEY.
  • Enable Chrome UX Report API and PageSpeed Insights API for the key.

^{Written for commit 3c733bd. Summary will update on new commits.}

[cloudflare-workers-and-pages]

Deploying with    Cloudflare Workers

The latest updates on your project. Learn more about integrating Git with Workers.

Status	Name	Latest Commit	Updated (UTC)
✅ Deployment successful! View logs	site-diagnostics	3c733bd	Apr 18 2026, 06:38 PM

[cubic-dev-ai]

1 issue found across 5 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="api/tools/research-crux.ts">

<violation number="1" location="api/tools/research-crux.ts:144">
P2: Guard against `olderAvg === 0` before computing percent change; the current formula can produce `Infinity`/`NaN` trend output.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: Guard against olderAvg === 0 before computing percent change; the current formula can produce Infinity/NaN trend output.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At api/tools/research-crux.ts, line 144:

<comment>Guard against `olderAvg === 0` before computing percent change; the current formula can produce `Infinity`/`NaN` trend output.</comment>

<file context>
@@ -0,0 +1,251 @@
+		if (older.length === 0) continue;
+		const recentAvg = recent.reduce((s, v) => s + v, 0) / recent.length;
+		const olderAvg = older.reduce((s, v) => s + v, 0) / older.length;
+		const change = ((recentAvg - olderAvg) / olderAvg) * 100;
+		let direction: string;
+		if (Math.abs(change) < 3) direction = "stable";
</file context>