feat(analytics): typed Umami event taxonomy across the funnel

Add lib/analytics.ts with a single typed track() wrapper. SSR-safe,
never throws, no-ops when Umami isn't loaded. Event names form a
fixed union so refactors stay safe.

14 events wired:

  Discovery (3)
    search_submitted          FilterBar submit + near_me path
    near_me_used              all geolocation outcomes
    empty_results             search returns 0 schools

  Engagement (5)
    school_viewed             SchoolDetail + Secondary on mount, with
                              urn / phase / local_authority / from
    section_nav_used          section-nav links on both detail views
    chart_metric_changed      mobile chart chip switch
    metric_compared_in_rankings rankings metric dropdown
    external_link_clicked     Ofsted / school website / DfE (declarative
                              data-umami-event attributes)

  Conversion (5)
    compare_school_added      search/rankings/detail/compare sources
    compare_school_removed    detail toggle and compare page
    compare_viewed            once per session when there's a selection
                              (school_count, phase_mix)
    compare_metric_changed    compare page metric dropdown
    compare_shared            native sheet vs clipboard distinguished

  Operational (1)
    api_error                 caught in handleResponse, includes
                              endpoint / status / route

Suggested Goals to configure in the Umami dashboard for the funnel
report: search_submitted → school_viewed → compare_school_added →
compare_viewed → compare_shared.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

nextjs-app/components/ComparisonView.tsx

@@ -15,6 +15,7 @@ import { LoadingSkeleton } from './LoadingSkeleton';
 import type { ComparisonData, MetricDefinition, School } from '@/lib/types';
 import { formatPercentage, formatProgress, formatAcademicYear, CHART_COLORS, schoolUrl } from '@/lib/utils';
 import { fetchComparison } from '@/lib/api';
+import { track } from '@/lib/analytics';
 import styles from './ComparisonView.module.css';
 
 const PRIMARY_CATEGORIES = ['expected', 'higher', 'progress', 'average', 'gender', 'equity', 'context', 'absence', 'trends'];
@@ -148,12 +149,28 @@ export function ComparisonView({
     setSelectedMetric(defaultMetric);
   };
 
+  // compare_viewed: fire once after the page has its first selection.
+  // We watch `selectedSchools.length` going from 0 → ≥1 so the event is
+  // sent only when there's actual content to view, not for empty arrivals.
+  const compareViewedRef = useRef(false);
+  useEffect(() => {
+    if (compareViewedRef.current) return;
+    if (selectedSchools.length === 0) return;
+    compareViewedRef.current = true;
+    const primaryCount = selectedSchools.filter(s => s.phase?.toLowerCase().includes('primary')).length;
+    const secondaryCount = selectedSchools.length - primaryCount;
+    const phaseMix = primaryCount === 0 ? 'all_secondary' : secondaryCount === 0 ? 'all_primary' : 'mixed';
+    track('compare_viewed', { school_count: selectedSchools.length, phase_mix: phaseMix });
+  }, [selectedSchools]);
+
   const handleMetricChange = (metric: string) => {
+    track('compare_metric_changed', { metric, phase: comparePhase });
     setSelectedMetric(metric);
   };
 
   const handleRemoveSchool = (urn: number) => {
     removeSchool(urn);
+    track('compare_school_removed', { urn, from: 'compare' });
   };
 
   const handleShare = async () => {
@@ -172,6 +189,7 @@ export function ComparisonView({
     if (typeof navigator !== 'undefined' && navigator.share && (!navigator.canShare || navigator.canShare(shareData))) {
       try {
         await navigator.share(shareData);
+        track('compare_shared', { method: 'native', school_count: count });
         return;
       } catch (err) {
         // User cancelled — bail silently. Any other error falls through to clipboard.
@@ -180,6 +198,7 @@ export function ComparisonView({
     }
     try {
       await navigator.clipboard.writeText(url);
+      track('compare_shared', { method: 'clipboard', school_count: count });
       setShareConfirm(true);
       setTimeout(() => setShareConfirm(false), 2000);
     } catch { /* fallback: do nothing */ }