fix(compare): keep chart data when a client refetch fails

The compare view refetches /api/compare on the client after SSR; on any
failure the catch nulled comparisonData, destroying the working
SSR-provided chart. A transient error (or staging's broken external /api
proxy) should not blank a comparison the user is already viewing — keep
the existing data instead.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

e2e/tests/journeys.spec.ts

@@ -50,6 +50,31 @@ test('school detail page renders name and performance data', async ({ page }) =>
   await expect(page.locator('canvas:visible').first()).toBeVisible({ timeout: 15_000 });
 });
 
+test('school hero map opens fullscreen on mobile without the Fullscreen API', async ({ page }) => {
+  // iOS Safari has no Element.requestFullscreen; the map must fall back to a
+  // CSS overlay. Simulate that by removing the API before any page script runs.
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.addInitScript(() => {
+    // @ts-expect-error deliberate API removal
+    delete Element.prototype.requestFullscreen;
+  });
+
+  await searchByName(page, 'primary');
+  const firstSchool = schoolLinks(page).first();
+  await expect(firstSchool).toBeVisible({ timeout: 15_000 });
+  await firstSchool.click();
+  await page.waitForURL(/\/school\//);
+
+  const openMap = page.getByRole('button', { name: 'Open full map' });
+  await expect(openMap).toBeVisible({ timeout: 15_000 });
+  await openMap.click();
+
+  const closeMap = page.getByRole('button', { name: 'Close map' });
+  await expect(closeMap).toBeVisible();
+  await closeMap.click();
+  await expect(openMap).toBeVisible();
+});
+
 test('comparing two schools shows both side by side', async ({ page }) => {
   // Collect two school URNs from search results, then load the share URL
   await searchByName(page, 'primary');
@@ -66,6 +91,32 @@ test('comparing two schools shows both side by side', async ({ page }) => {
   await expect(page.locator(`a[href*="${urns[1]}"]`).first()).toBeVisible();
 });
 
+test('compare chart on mobile shows school chips with tap-to-focus', async ({ page }) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+
+  await searchByName(page, 'primary');
+  await expect(schoolLinks(page).first()).toBeVisible({ timeout: 15_000 });
+  const hrefs = await schoolLinks(page).evaluateAll((links) =>
+    links.map((l) => (l as HTMLAnchorElement).getAttribute('href') || '')
+  );
+  const urns = [...new Set(hrefs.map((h) => h.match(/\/school\/(\d+)/)?.[1]).filter(Boolean))];
+  expect(urns.length).toBeGreaterThanOrEqual(2);
+
+  await page.goto(`/compare?urns=${urns[0]},${urns[1]}`);
+  await expect(page.locator('canvas:visible').first()).toBeVisible({ timeout: 15_000 });
+
+  // The mobile chart legend renders one chip per school inside the chart card.
+  const chipGroup = page.getByRole('group', { name: /highlight a school/i });
+  const chips = chipGroup.getByRole('button');
+  await expect(chips).toHaveCount(2);
+
+  // Tapping a chip focuses that school's line; tapping again releases it.
+  await chips.first().click();
+  await expect(chips.first()).toHaveAttribute('aria-pressed', 'true');
+  await chips.first().click();
+  await expect(chips.first()).toHaveAttribute('aria-pressed', 'false');
+});
+
 test('rankings page loads a populated table', async ({ page }) => {
   await page.goto('/rankings');
   await expect(page.getByRole('heading', { name: /rankings/i }).first()).toBeVisible();

nextjs-app/__tests__/lib/utils.test.ts

@@ -9,6 +9,8 @@ import {
   isValidPostcode,
   debounce,
   buildOfstedListBadge,
+  metricKind,
+  computeYBounds,
 } from '@/lib/utils';
 
 describe('formatPercentage', () => {
@@ -159,3 +161,54 @@ describe('buildOfstedListBadge', () => {
     expect(badge.cssClass).toBe('ofstedPending');
   });
 });
+
+describe('metricKind', () => {
+  it('classifies metrics by key', () => {
+    expect(metricKind('rwm_expected_pct')).toBe('percentage');
+    expect(metricKind('absence_rate')).toBe('percentage');
+    expect(metricKind('reading_progress')).toBe('progress');
+    expect(metricKind('progress_8_score')).toBe('progress');
+    expect(metricKind('attainment_8_score')).toBe('score');
+    expect(metricKind('reading_avg_score')).toBe('score');
+  });
+});
+
+describe('computeYBounds', () => {
+  it('tightens clustered percentages instead of framing 0-100', () => {
+    const b = computeYBounds([86, 86, 86, 80, 96], 'percentage');
+    expect(b.min).toBeGreaterThanOrEqual(0);
+    expect(b.max).toBeLessThanOrEqual(100);
+    expect(b.min).toBeGreaterThan(50);
+    expect(b.max! - b.min!).toBeGreaterThanOrEqual(10);
+  });
+
+  it('never widens percentages beyond 0-100 for non-negative data', () => {
+    const b = computeYBounds([2, 5, 98], 'percentage');
+    expect(b.min).toBe(0);
+    expect(b.max).toBe(100);
+  });
+
+  it('does not clamp to zero when pct-named trend data is negative', () => {
+    const b = computeYBounds([-12, -3, 4], 'percentage');
+    expect(b.min).toBeLessThan(-12);
+  });
+
+  it('keeps progress bounds symmetric around zero', () => {
+    const b = computeYBounds([-1.2, 0.4, 2.1], 'progress');
+    expect(b.min).toBe(-b.max!);
+    expect(b.min).toBeLessThanOrEqual(-1.2);
+    expect(b.max).toBeGreaterThanOrEqual(2.1);
+  });
+
+  it('fits score metrics without a fixed frame', () => {
+    const b = computeYBounds([42.3, 48.9, 51.2], 'score');
+    expect(b.min).toBeGreaterThanOrEqual(0);
+    expect(b.min).toBeLessThanOrEqual(42.3);
+    expect(b.max).toBeGreaterThanOrEqual(51.2);
+  });
+
+  it('returns empty bounds when there is no numeric data', () => {
+    expect(computeYBounds([null, undefined, NaN], 'percentage')).toEqual({});
+    expect(computeYBounds([], 'progress')).toEqual({});
+  });
+});

nextjs-app/components/ComparisonChart.module.css

@@ -0,0 +1,63 @@
+/* Chart wrapper: chips (mobile) above, canvas filling the rest of the
+   parent .chartContainer, whose fixed height drives Chart.js sizing via
+   maintainAspectRatio: false. */
+.wrapper {
+    display: flex;
+    flex-direction: column;
+    height: 100%;
+}
+
+.canvasBox {
+    position: relative;
+    flex: 1 1 auto;
+    min-height: 0;
+}
+
+/* School chips: mobile-only legend + tap-to-focus control. Desktop keeps
+   Chart.js's built-in legend (with per-school point shapes). */
+.chips {
+    display: none;
+}
+
+@media (max-width: 640px) {
+    .chips {
+        display: flex;
+        flex-wrap: wrap;
+        gap: 6px;
+        padding-bottom: 8px;
+    }
+
+    .chip {
+        display: inline-flex;
+        align-items: center;
+        gap: 6px;
+        min-height: 44px;
+        max-width: 100%;
+        padding: 4px 10px;
+        border: 1px solid rgba(0, 0, 0, .12);
+        border-radius: 999px;
+        background: transparent;
+        cursor: pointer;
+        font-size: 12px;
+        font-weight: 600;
+    }
+
+    .chip[aria-pressed="true"] {
+        background: rgba(0, 0, 0, .06);
+        border-color: rgba(0, 0, 0, .35);
+    }
+
+    .chipDot {
+        flex: 0 0 auto;
+        width: 10px;
+        height: 10px;
+        border-radius: 50%;
+    }
+
+    .chipName {
+        overflow: hidden;
+        text-overflow: ellipsis;
+        white-space: nowrap;
+        max-width: 9rem;
+    }
+}

nextjs-app/components/ComparisonChart.tsx

@@ -1,47 +1,82 @@
 /**
  * ComparisonChart Component
- * Multi-school comparison chart using Chart.js
+ * Multi-school comparison chart using Chart.js.
+ *
+ * Desktop: built-in legend (point-style markers double as per-school shapes).
+ * Mobile (≤640px): the in-chart legend and axis titles are dropped in favour
+ *   of a chip row above the canvas; tapping a chip highlights that school's
+ *   line and dims the rest. The y-axis auto-fits the data on all viewports so
+ *   clustered schools stay distinguishable.
  */
 
 'use client';
 
+import { useEffect, useState } from 'react';
 import { Line } from 'react-chartjs-2';
-import { ChartOptions } from 'chart.js';
+import { ChartOptions, ChartDataset, PointStyle } from 'chart.js';
 import '@/lib/chartSetup';
 import type { ComparisonData } from '@/lib/types';
-import { CHART_COLORS, formatAcademicYear } from '@/lib/utils';
+import {
+  CHART_COLORS,
+  CHART_TEXT_COLORS,
+  computeYBounds,
+  formatAcademicYear,
+  metricKind,
+  rgbToRgba,
+} from '@/lib/utils';
+import { useIsMobile } from '@/hooks/useIsMobile';
+import { track } from '@/lib/analytics';
+import styles from './ComparisonChart.module.css';
 
 interface ComparisonChartProps {
   comparisonData: Record<string, ComparisonData>;
+  /** Ordered as displayed in the school cards, so colours match by index. */
+  schools: Array<{ urn: number; school_name: string }>;
   metric: string;
   metricLabel: string;
 }
 
-export function ComparisonChart({ comparisonData, metric, metricLabel }: ComparisonChartProps) {
+// One shape per basket slot (MAX_SCHOOLS = 5) — secondary encoding so
-  // Get all schools and their data
+// converging lines stay tellable apart without relying on hue alone.
-  const schools = Object.entries(comparisonData);
+const POINT_STYLES: PointStyle[] = ['circle', 'triangle', 'rect', 'rectRot', 'star'];
+
+export function ComparisonChart({ comparisonData, schools, metric, metricLabel }: ComparisonChartProps) {
+  const isMobile = useIsMobile();
+  const [focusedUrn, setFocusedUrn] = useState<number | null>(null);
+
+  // A focused school that leaves the basket must not linger.
+  const urnKey = schools.map((s) => s.urn).join(',');
+  useEffect(() => {
+    setFocusedUrn(null);
+  }, [urnKey]);
 
   if (schools.length === 0) {
     return <div>No data available</div>;
   }
 
-  // Get years from first school (assuming all schools have same years)
+  // Union of years across all schools — coverage differs between them.
-  const years = schools[0][1].yearly_data.map((d) => d.year).sort((a, b) => a - b);
+  const years = [
+    ...new Set(schools.flatMap((s) => comparisonData[String(s.urn)]?.yearly_data.map((d) => d.year) ?? [])),
+  ].sort((a, b) => a - b);
 
-  // Create datasets for each school
+  const datasets: ChartDataset<'line'>[] = schools.map((school, index) => {
-  const datasets = schools.map(([urn, data], index) => {
+    const data = comparisonData[String(school.urn)];
-    const schoolInfo = data.school_info;
     const color = CHART_COLORS[index % CHART_COLORS.length];
+    const dimmed = focusedUrn !== null && focusedUrn !== school.urn;
 
     return {
-      label: schoolInfo.school_name,
+      label: school.school_name,
       data: years.map((year) => {
-        const yearData = data.yearly_data.find((d) => d.year === year);
+        const yearData = data?.yearly_data.find((d) => d.year === year);
         if (!yearData) return null;
         return yearData[metric as keyof typeof yearData] as number | null;
       }),
-      borderColor: color,
+      borderColor: dimmed ? rgbToRgba(color, 0.2) : color,
-      backgroundColor: color.replace('rgb', 'rgba').replace(')', ', 0.1)'),
+      backgroundColor: dimmed ? 'transparent' : rgbToRgba(color, 0.1),
+      borderWidth: focusedUrn === school.urn ? 3 : dimmed ? 1.5 : 2,
+      pointStyle: POINT_STYLES[index % POINT_STYLES.length],
+      pointRadius: dimmed ? 2 : isMobile ? 3 : 4,
+      pointHoverRadius: isMobile ? 5 : 6,
       tension: 0.3,
       spanGaps: true,
     };
@@ -52,9 +87,11 @@ export function ComparisonChart({ comparisonData, metric, metricLabel }: Compari
     datasets,
   };
 
-  // Determine if metric is a progress score or percentage
+  const kind = metricKind(metric);
-  const isProgressScore = metric.includes('progress');
+  const yBounds = computeYBounds(
-  const isPercentage = metric.includes('pct') || metric.includes('rate');
+    datasets.flatMap((ds) => ds.data as Array<number | null>),
+    kind,
+  );
 
   const options: ChartOptions<'line'> = {
     responsive: true,
@@ -65,6 +102,7 @@ export function ComparisonChart({ comparisonData, metric, metricLabel }: Compari
     },
     plugins: {
       legend: {
+        display: !isMobile,
         position: 'top' as const,
         labels: {
           usePointStyle: true,
@@ -74,26 +112,22 @@ export function ComparisonChart({ comparisonData, metric, metricLabel }: Compari
           },
         },
       },
+      // No in-chart title: the section heading and metric selector above the
+      // chart already state the metric.
       title: {
-        display: true,
+        display: false,
-        text: `${metricLabel} - Comparison`,
-        font: {
-          size: 16,
-          weight: 'bold',
-        },
-        padding: {
-          bottom: 20,
-        },
       },
       tooltip: {
         backgroundColor: 'rgba(0, 0, 0, 0.8)',
-        padding: 12,
+        padding: isMobile ? 10 : 12,
         titleFont: {
-          size: 14,
+          size: isMobile ? 12 : 14,
         },
         bodyFont: {
-          size: 13,
+          size: isMobile ? 11 : 13,
         },
+        usePointStyle: true,
+        itemSort: (a, b) => (b.parsed.y ?? -Infinity) - (a.parsed.y ?? -Infinity),
         callbacks: {
           label: function (context) {
             let label = context.dataset.label || '';
@@ -101,13 +135,7 @@ export function ComparisonChart({ comparisonData, metric, metricLabel }: Compari
               label += ': ';
             }
             if (context.parsed.y !== null) {
-              if (isProgressScore) {
+              label += context.parsed.y.toFixed(1) + (kind === 'percentage' ? '%' : '');
-                label += context.parsed.y.toFixed(1);
-              } else if (isPercentage) {
-                label += context.parsed.y.toFixed(1) + '%';
-              } else {
-                label += context.parsed.y.toFixed(1);
-              }
             } else {
               label += 'N/A';
             }
@@ -121,17 +149,18 @@ export function ComparisonChart({ comparisonData, metric, metricLabel }: Compari
         type: 'linear' as const,
         display: true,
         title: {
-          display: true,
+          display: !isMobile,
-          text: isPercentage ? 'Percentage (%)' : isProgressScore ? 'Progress Score' : 'Value',
+          text: kind === 'percentage' ? 'Percentage (%)' : kind === 'progress' ? 'Progress Score' : 'Value',
           font: {
             size: 12,
             weight: 'bold',
           },
         },
-        ...(isPercentage && {
+        ...yBounds,
-          min: 0,
+        ticks: {
-          max: 100,
+          font: { size: isMobile ? 10 : 12 },
-        }),
+          ...(isMobile && { maxTicksLimit: 5 }),
+        },
         grid: {
           color: 'rgba(0, 0, 0, 0.05)',
         },
@@ -141,16 +170,58 @@ export function ComparisonChart({ comparisonData, metric, metricLabel }: Compari
           display: false,
         },
         title: {
-          display: true,
+          display: !isMobile,
           text: 'Year',
           font: {
             size: 12,
             weight: 'bold',
           },
         },
+        ticks: {
+          font: { size: isMobile ? 10 : 12 },
+          ...(isMobile && { maxRotation: 0, autoSkip: true, maxTicksLimit: 4 }),
+        },
       },
     },
   };
 
-  return <Line data={chartData} options={options} />;
+  const toggleFocus = (urn: number) => {
+    const next = focusedUrn === urn ? null : urn;
+    setFocusedUrn(next);
+    if (next !== null) track('compare_focus_school', { urn: next });
+  };
+
+  return (
+    <div className={styles.wrapper}>
+      {/* Mobile legend + focus control; a single series needs no legend. */}
+      {schools.length > 1 && (
+        <div className={styles.chips} role="group" aria-label="Highlight a school on the chart">
+          {schools.map((school, index) => (
+            <button
+              key={school.urn}
+              type="button"
+              className={styles.chip}
+              aria-pressed={focusedUrn === school.urn}
+              onClick={() => toggleFocus(school.urn)}
+            >
+              <span
+                className={styles.chipDot}
+                style={{ background: CHART_COLORS[index % CHART_COLORS.length] }}
+                aria-hidden="true"
+              />
+              <span
+                className={styles.chipName}
+                style={{ color: CHART_TEXT_COLORS[index % CHART_TEXT_COLORS.length] }}
+              >
+                {school.school_name}
+              </span>
+            </button>
+          ))}
+        </div>
+      )}
+      <div className={styles.canvasBox}>
+        <Line data={chartData} options={options} aria-label={`${metricLabel} comparison chart`} />
+      </div>
+    </div>
+  );
 }

nextjs-app/components/ComparisonView.module.css

@@ -454,7 +454,10 @@
   }
 
   .chartContainer {
-    height: 300px;
+    /* Taller than desktop's proportion would suggest: the chip legend row
+       sits inside, and the in-chart title/legend/axis titles are gone, so
+       nearly all of this is plot area. */
+    height: 340px;
   }
 
   .comparisonTable {

nextjs-app/components/ComparisonView.tsx

@@ -111,8 +111,10 @@ export function ComparisonView({
           setComparisonData(data.comparison);
         })
         .catch((err) => {
+          // Keep whatever we already have (SSR data or a previous fetch) rather
+          // than blanking the chart — a transient refetch failure shouldn't
+          // destroy a working comparison the user is looking at.
           console.error('Failed to fetch comparison:', err);
-          setComparisonData(null);
         });
     } else {
       setComparisonData(null);
@@ -429,6 +431,7 @@ export function ComparisonView({
               <div className={styles.chartContainer}>
                 <ComparisonChart
                   comparisonData={activeComparisonData}
+                  schools={activeSchools}
                   metric={selectedMetric}
                   metricLabel={metricLabel}
                 />

nextjs-app/components/PerformanceChart.tsx

@@ -10,12 +10,13 @@
 
 'use client';
 
-import { useEffect, useMemo, useState } from 'react';
+import { useMemo, useState } from 'react';
 import { Line } from 'react-chartjs-2';
 import { ChartOptions, ChartDataset } from 'chart.js';
 import '@/lib/chartSetup';
 import type { SchoolResult } from '@/lib/types';
 import { formatAcademicYear } from '@/lib/utils';
+import { useIsMobile } from '@/hooks/useIsMobile';
 import { track } from '@/lib/analytics';
 import styles from './PerformanceChart.module.css';
 
@@ -68,16 +69,7 @@ export function PerformanceChart({
   const sortedData = [...data].sort((a, b) => a.year - b.year);
   const years = sortedData.map(d => formatAcademicYear(d.year));
 
-  // ── Mobile detection ─────────────────────────────────────────────────
+  const isMobile = useIsMobile();
-  // Hydration-safe: SSR renders desktop; client flips to mobile after mount.
-  const [isMobile, setIsMobile] = useState(false);
-  useEffect(() => {
-    const mq = window.matchMedia('(max-width: 640px)');
-    const update = () => setIsMobile(mq.matches);
-    update();
-    mq.addEventListener('change', update);
-    return () => mq.removeEventListener('change', update);
-  }, []);
 
   // ── Build per-year national averages ─────────────────────────────────
   const natRefRwm: (number | null)[] = sortedData.map(d => {

nextjs-app/components/SchoolHeroMap.module.css

@@ -34,6 +34,15 @@
     background: #fff;
 }
 
+/* Fallback fullscreen (iOS Safari — no Element.requestFullscreen): the API
+   can't promote the element, so pin it over the page ourselves. Above the
+   comparison toast (3000) and everything else except modals (9999+). */
+.wrapper[data-fs-fallback] {
+    position: fixed;
+    inset: 0;
+    z-index: 5000;
+}
+
 .skeleton {
     width: 100%;
     height: 100%;

nextjs-app/components/SchoolHeroMap.tsx

@@ -29,25 +29,50 @@ interface SchoolHeroMapProps {
 export const SchoolHeroMap = forwardRef<SchoolHeroMapHandle, SchoolHeroMapProps>(
   function SchoolHeroMap({ lat, lng }, ref) {
     const wrapperRef = useRef<HTMLDivElement>(null);
-    const [isFullscreen, setIsFullscreen] = useState(false);
+    const [nativeFullscreen, setNativeFullscreen] = useState(false);
+    // iOS Safari has no Element.requestFullscreen — fall back to a
+    // fixed-position overlay driven by state instead of the Fullscreen API.
+    const [fallbackFullscreen, setFallbackFullscreen] = useState(false);
+    const isFullscreen = nativeFullscreen || fallbackFullscreen;
 
     const open = useCallback(() => {
-      wrapperRef.current?.requestFullscreen?.().catch(() => {});
+      const el = wrapperRef.current;
+      if (!el) return;
+      if (el.requestFullscreen) {
+        el.requestFullscreen().catch(() => setFallbackFullscreen(true));
+      } else {
+        setFallbackFullscreen(true);
+      }
     }, []);
     const close = useCallback(() => {
       if (document.fullscreenElement) document.exitFullscreen().catch(() => {});
+      setFallbackFullscreen(false);
     }, []);
 
     useImperativeHandle(ref, () => ({ open }), [open]);
 
     useEffect(() => {
-      const onChange = () => setIsFullscreen(!!document.fullscreenElement);
+      const onChange = () => setNativeFullscreen(!!document.fullscreenElement);
       document.addEventListener('fullscreenchange', onChange);
       return () => document.removeEventListener('fullscreenchange', onChange);
     }, []);
 
+    // The fallback overlay sits on top of the page rather than replacing it,
+    // so lock body scroll while it is up.
+    useEffect(() => {
+      if (!fallbackFullscreen) return;
+      const prev = document.body.style.overflow;
+      document.body.style.overflow = 'hidden';
+      return () => { document.body.style.overflow = prev; };
+    }, [fallbackFullscreen]);
+
     return (
-      <div ref={wrapperRef} className={styles.wrapper} data-fullscreen={isFullscreen || undefined}>
+      <div
+        ref={wrapperRef}
+        className={styles.wrapper}
+        data-fullscreen={isFullscreen || undefined}
+        data-fs-fallback={fallbackFullscreen || undefined}
+      >
         <LeafletHeroMap lat={lat} lng={lng} interactive={isFullscreen} />
 
         {isFullscreen ? (

nextjs-app/hooks/useIsMobile.ts

@@ -0,0 +1,23 @@
+/**
+ * Viewport hook shared by the chart components.
+ * Hydration-safe: SSR and the first client render report desktop; the
+ * media-query subscription flips the value after mount.
+ */
+
+'use client';
+
+import { useEffect, useState } from 'react';
+
+export function useIsMobile(maxWidth = 640): boolean {
+  const [isMobile, setIsMobile] = useState(false);
+
+  useEffect(() => {
+    const mq = window.matchMedia(`(max-width: ${maxWidth}px)`);
+    const update = () => setIsMobile(mq.matches);
+    update();
+    mq.addEventListener('change', update);
+    return () => mq.removeEventListener('change', update);
+  }, [maxWidth]);
+
+  return isMobile;
+}

nextjs-app/lib/analytics.ts

@@ -29,6 +29,7 @@ export type EventName =
   | 'compare_viewed'
   | 'compare_metric_changed'
   | 'compare_shared'
+  | 'compare_focus_school'
   // Operational
   | 'api_error'
   | 'results_load_more';

nextjs-app/lib/utils.ts

@@ -317,6 +317,57 @@ export function getTrendColor(trend: 'up' | 'down' | 'stable'): string {
   }
 }
 
+/**
+ * Broad shape of a KS2/KS4 metric, used to scale chart axes and format values.
+ */
+export type MetricKind = 'percentage' | 'progress' | 'score';
+
+export function metricKind(metric: string): MetricKind {
+  if (metric.includes('progress')) return 'progress';
+  if (metric.includes('pct') || metric.includes('rate')) return 'percentage';
+  return 'score';
+}
+
+/**
+ * Fit a chart y-axis to the data instead of a fixed frame, so clustered
+ * series remain distinguishable. Padding keeps a minimum span so noise is
+ * not magnified into drama.
+ *
+ * - percentage: pad and snap to 5s; cap at 100; floor at 0 only when the
+ *   data is non-negative (some trend metrics have `pct` in the key but hold
+ *   negative year-over-year deltas).
+ * - progress: symmetric around 0 so the zero line always shows.
+ * - score (Attainment 8, scaled scores): pad and snap to integers; floor at
+ *   0 only when the data is non-negative.
+ */
+export function computeYBounds(
+  values: Array<number | null | undefined>,
+  kind: MetricKind,
+): { min?: number; max?: number } {
+  const nums = values.filter((v): v is number => typeof v === 'number' && Number.isFinite(v));
+  if (nums.length === 0) return {};
+
+  const lo = Math.min(...nums);
+  const hi = Math.max(...nums);
+
+  if (kind === 'progress') {
+    const reach = Math.max(2, Math.ceil(Math.max(Math.abs(lo), Math.abs(hi)) + 0.5));
+    return { min: -reach, max: reach };
+  }
+
+  if (kind === 'percentage') {
+    const pad = Math.max(5, Math.round((hi - lo) * 0.2));
+    const min = Math.floor((lo - pad) / 5) * 5;
+    const max = Math.min(100, Math.ceil((hi + pad) / 5) * 5);
+    return { min: lo >= 0 ? Math.max(0, min) : min, max };
+  }
+
+  // score
+  const pad = Math.max(2, (hi - lo) * 0.2);
+  const min = Math.floor(lo - pad);
+  return { min: lo >= 0 ? Math.max(0, min) : min, max: Math.ceil(hi + pad) };
+}
+
 // ============================================================================
 // Local Storage Utilities
 // ============================================================================