feat(perf): #22 wire Web Vitals through GoogleAnalytics + consolidate reporters

[TortoiseWolfe]

Summary

Closes #22 (Mobile-First Design perf-test gap) by activating Web Vitals instrumentation that already half-existed in the codebase. Two parallel implementations consolidated onto one consent-aware path. Net −95 LOC (drops ~280 LOC of hand-rolled PerformanceObserver logic in favor of the battle-tested npm package).

Why this is a Phase 0 ticket (GrimGlow ThreeJS prep)

GrimGlow Phase 1a is browser R3F on top of ScriptHammer. Three.js scenes notoriously degrade Core Web Vitals — large LCP from canvas mount, CLS from late-bound geometry, INP from main-thread shader compilation. Landing the measurement infrastructure in template means every fork inherits it for free instead of re-deriving.

What changed

• src/utils/web-vitals.ts is now a thin re-export of onCLS/onFCP/onINP/onLCP/onTTFB/Metric from the npm web-vitals package. Public API unchanged so /status consumer keeps working. Drops ~280 LOC of bespoke timing logic.
• src/utils/performance.ts initWebVitals() was previously dead code; now it actually runs. Subscribes through the re-export and dispatches via consolidated sendToAnalytics, routed through the consent-gated analytics.ts trackWebVital.
• src/lib/analytics/GoogleAnalytics calls initWebVitals() once when consent.analytics flips on. Ref-guarded so consent toggle off-then-on doesn't double-subscribe.
• src/types/analytics.types.ts WebVitalEvent.metric_name drops the 'FID' literal — Chromium replaced FID with INP in 2024; web-vitals ^5 no longer exports onFID.

Wireframe sub-task

The audit also asked to "regenerate wireframes" for this feature. Re-validated both SVGs against the current validator v5.4 — both PASS with no errors. The audit's regen claim was stale (issues files dated Jan 2026 against validator v5.0/v5.2). Updated the issues files to record the re-validation rather than running speculative regeneration.

GA4 acceptance criteria (from features/foundation/004-mobile-first-design/spec.md)

• AC-1: LCP under 2.5s on mobile — measured (not enforced)
• AC-2: FID under 100ms — replaced by INP under 200ms (FID deprecated)
• AC-3: CLS below 0.1 — measured (not enforced)

These are observation thresholds, not fix-it requirements — the deliverable is measurement infrastructure, not optimization.

Tests

7 new tests in src/utils/web-vitals.test.ts:

• Re-exports forward to npm package callbacks
• reportWebVitals subscribes to all 5 metrics
• Regression pin: no onFID re-introduction (web-vitals ^5 dropped it)
• sendToAnalytics consent-gating contract (forwards when enabled, suppresses when disabled)
• sendToAnalytics does NOT pre-scale CLS (the older bespoke implementation did; the consolidated path delegates rounding to trackWebVital to avoid double-scaling)

Verification

• pnpm run type-check: clean
• pnpm run lint: clean
• pnpm test: 3255/3255 pass (7 new tests, full suite green)
• Husky pre-push (lint, type-check, unit, build): all green

Test plan

• CI runs the full Chromium + Firefox + WebKit E2E suite
• Smoke test: open the app in a browser with NEXT_PUBLIC_GA_MEASUREMENT_ID set, accept consent → DevTools Network → filter g/collect → see LCP / INP / CLS event payloads after the first navigation
• Smoke test: localhost without GA ID set → initWebVitals short-circuits gracefully (no errors)

Phase 0 status after this lands

#	Ticket	Status
#24	SetupBanner clarity	✅ Closed (PR #77)
#69	node_modules volume permissions	✅ Closed (PR #70)
#22	Mobile-First perf instrumentation	✅ This PR
#21	WCAG AAA scope upgrade	⚠️ Open — next in plan
#73	Constitution v1.0.2 wireframe gate	⚠️ Open — sequenced before #21

After #73 + #21 close, Phase 0 is closed and Phase 0.5 (#48 Three.js Game) becomes the next real work.

Closes

Closes #22

🤖 Generated with Claude Code