From 3ac942962db28250ea4a940c3608bce3bad68b53 Mon Sep 17 00:00:00 2001
From: Sean Lynch <techniq35@gmail.com>
Date: Mon, 19 Oct 2026 15:53:08 -0400
Subject: [PATCH] Add interactive college sports ranking chart examples

---
 .../Image/college-football-upsets.svelte      | 242 ++++++++++++
 .../LineChart/bump-sports-rankings.svelte     | 308 +++++++++++++++
 .../bump-state-population-ranks.svelte        |   4 +
 docs/src/lib/sports.remote.ts                 | 372 ++++++++++++++++++
 4 files changed, 926 insertions(+)
 create mode 100644 docs/src/examples/components/Image/college-football-upsets.svelte
 create mode 100644 docs/src/examples/components/LineChart/bump-sports-rankings.svelte
 create mode 100644 docs/src/lib/sports.remote.ts

diff --git a/docs/src/examples/components/Image/college-football-upsets.svelte b/docs/src/examples/components/Image/college-football-upsets.svelte
new file mode 100644
index 0000000000..5fc6ae6c5f
--- /dev/null
+++ b/docs/src/examples/components/Image/college-football-upsets.svelte
@@ -0,0 +1,242 @@
+<script module lang="ts">
+	export const title = 'College football upsets';
+	export const description =
+		"Every game involving a ranked team, placed at the team's rank for each week. Upsets (losing to a lower ranked or unranked team) stand out.";
+</script>
+
+<script lang="ts">
+	import { Axis, Chart, Group, Image, Layer, Rect, Tooltip } from 'layerchart';
+	import { Kbd, SelectField, getSettings } from 'svelte-ux';
+	import { scalePoint } from 'd3-scale';
+	import { range } from 'd3-array';
+	import { cls } from '@layerstack/tailwind';
+	import { getRankedMatchups, type Matchup, type MatchupTeam } from '$lib/sports.remote';
+
+	const maxRank = 25;
+	const rowHeight = 26;
+	const logoSize = 16;
+	const cellWidth = logoSize * 2 + 10;
+	const cellHeight = logoSize + 6;
+
+	// `undefined` loads the latest season
+	let season = $state<number>();
+
+	// Hold Shift to hide the tooltip and see the highlighted game underneath
+	let hideTooltip = $state(false);
+
+	const data = $derived(await getRankedMatchups({ season }));
+	export { data };
+
+	const seasonOptions = $derived(
+		data.seasons.map((year) => ({ label: String(year), value: year }))
+	);
+
+	/** Winner was ranked lower than the loser (or unranked) */
+	function isUpset(game: Matchup) {
+		const winner = game.teams.find((t) => t.result === 'W');
+		const loser = game.teams.find((t) => t.result === 'L');
+		return !!loser?.rank && (winner?.rank ?? Infinity) > loser.rank;
+	}
+
+	type Cell = {
+		game: Matchup;
+		week: string;
+		rank: number;
+		team: MatchupTeam;
+		opponent: MatchupTeam;
+		upset: boolean;
+	};
+
+	/** One cell for each ranked team in a game */
+	const cells = $derived.by(() => {
+		const cells: Cell[] = [];
+		for (const game of data.games) {
+			const [a, b] = game.teams;
+			for (const [team, opponent] of [
+				[a, b],
+				[b, a]
+			]) {
+				if (team.rank) {
+					cells.push({
+						game,
+						week: game.week,
+						rank: team.rank,
+						team,
+						opponent,
+						upset: isUpset(game)
+					});
+				}
+			}
+		}
+		return cells;
+	});
+
+	const upsetCount = $derived(data.games.filter(isUpset).length);
+
+	const { currentTheme } = getSettings();
+	const logoKey = $derived($currentTheme.dark ? 'logoDark' : 'logo');
+
+	/** Upsets stand out, while expected results recede (`cell` for the chart, `swatch` for the legend) */
+	const styles = {
+		win: {
+			label: 'Win',
+			cell: 'fill-surface-content/5 stroke-surface-content/20',
+			swatch: 'border bg-surface-content/5 border-surface-content/20'
+		},
+		loss: {
+			label: 'Loss',
+			cell: 'fill-danger/10 stroke-danger/40',
+			swatch: 'border bg-danger/10 border-danger/40'
+		},
+		upsetLoss: {
+			label: 'Upset loss',
+			cell: 'fill-danger/40 stroke-danger',
+			swatch: 'border-2 bg-danger/40 border-danger'
+		},
+		upsetWin: {
+			label: 'Upset win',
+			cell: 'fill-success/40 stroke-success',
+			swatch: 'border-2 bg-success/40 border-success'
+		}
+	};
+
+	function cellStyle(cell: Cell) {
+		if (cell.upset) return cell.team.result === 'W' ? styles.upsetWin : styles.upsetLoss;
+		return cell.team.result === 'L' ? styles.loss : styles.win;
+	}
+</script>
+
+<svelte:window
+	onkeydown={(e) => {
+		if (e.key === 'Shift') hideTooltip = true;
+	}}
+	onkeyup={(e) => {
+		if (e.key === 'Shift') hideTooltip = false;
+	}}
+	onblur={() => (hideTooltip = false)}
+/>
+
+<div class="grid grid-cols-[auto_1fr] items-end gap-4 mb-2">
+	<SelectField
+		label="Season"
+		options={seasonOptions}
+		bind:value={
+			() => data.season,
+			(v) => {
+				if (v !== data.season) season = v;
+			}
+		}
+		clearable={false}
+		toggleIcon={null}
+		stepper
+	/>
+	<div class="flex flex-wrap items-center gap-x-4 gap-y-1 text-sm text-surface-content/70 pb-2">
+		{#each Object.values(styles) as style (style.label)}
+			<span class="flex items-center gap-1">
+				<span class={cls('inline-block w-4 h-3 rounded-full', style.swatch)}></span>
+				{style.label}
+			</span>
+		{/each}
+		<span>{upsetCount} upsets</span>
+	</div>
+</div>
+
+<Chart
+	data={cells}
+	x="week"
+	xScale={scalePoint().padding(0.5)}
+	xDomain={data.weeks}
+	y="rank"
+	yDomain={[maxRank + 0.5, 0.5]}
+	padding={{ top: 24, bottom: 24, left: 32, right: 0 }}
+	height={maxRank * rowHeight + 48}
+	tooltipContext={{ mode: 'quadtree' }}
+>
+	{#snippet children({ context })}
+		{@const highlightId = context.tooltip.data?.game.id}
+		<Layer>
+			<Axis placement="top" rule={false} />
+			<Axis placement="bottom" rule={false} />
+			<Axis placement="left" ticks={range(1, maxRank + 1)} format={(d) => `#${d}`} />
+
+			{#each cells as cell (cell.game.id + cell.team.id)}
+				{@const x = context.xScale(cell.week) ?? 0}
+				{@const y = context.yScale(cell.rank)}
+				{@const style = cellStyle(cell)}
+				<Group
+					opacity={highlightId == null || highlightId === cell.game.id ? 1 : 0.2}
+					class="transition-opacity duration-200"
+				>
+					<Rect
+						x={x - cellWidth / 2}
+						y={y - cellHeight / 2}
+						width={cellWidth}
+						height={cellHeight}
+						rx={cellHeight / 2}
+						strokeWidth={cell.upset ? 2 : 1}
+						class={style.cell}
+					/>
+					<Image
+						href={cell.team[logoKey]}
+						x={x - logoSize / 2 - 2}
+						{y}
+						width={logoSize}
+						height={logoSize}
+					/>
+					<Image
+						href={cell.opponent[logoKey]}
+						x={x + logoSize / 2 + 2}
+						{y}
+						width={logoSize}
+						height={logoSize}
+					/>
+				</Group>
+			{/each}
+		</Layer>
+
+		{#if !hideTooltip}
+			<Tooltip.Root {context}>
+				{#snippet children({ data: cell })}
+					{@const result = cell.team.result}
+					<Tooltip.Header>
+						<div class="flex items-center gap-2">
+							<img src={cell.team[logoKey]} alt="" class="size-5" />
+							{cell.team.name} (#{cell.rank})
+						</div>
+					</Tooltip.Header>
+					<Tooltip.List>
+						<div class="col-span-full flex items-center gap-1">
+							{#if result}
+								<span
+									class={cls(result === 'W' && 'text-success', result === 'L' && 'text-danger')}
+								>
+									{result}
+								</span>
+								{cell.team.score}-{cell.opponent.score}
+							{:else}
+								{cell.game.status}
+							{/if}
+							vs
+							<img src={cell.opponent[logoKey]} alt="" class="size-4" />
+							{cell.opponent.abbreviation}
+							{cell.opponent.rank ? `(#${cell.opponent.rank})` : ''}
+						</div>
+						{#if cell.upset}
+							<div
+								class={cls(
+									'col-span-full text-xs font-semibold uppercase',
+									result === 'W' ? 'text-success' : 'text-danger'
+								)}
+							>
+								Upset
+							</div>
+						{/if}
+					</Tooltip.List>
+					<div class="-mx-2 -mb-1 mt-1 px-2 py-1 border-t text-xs text-surface-content/60">
+						Hold <Kbd class="py-0 px-1 mx-1 border">Shift</Kbd> to hide tooltip
+					</div>
+				{/snippet}
+			</Tooltip.Root>
+		{/if}
+	{/snippet}
+</Chart>
diff --git a/docs/src/examples/components/LineChart/bump-sports-rankings.svelte b/docs/src/examples/components/LineChart/bump-sports-rankings.svelte
new file mode 100644
index 0000000000..0ff034dd4c
--- /dev/null
+++ b/docs/src/examples/components/LineChart/bump-sports-rankings.svelte
@@ -0,0 +1,308 @@
+<script module lang="ts">
+	export const title = 'Bump chart (sports rankings)';
+	export const description = 'Weekly AP Top 25 poll for a college football or basketball season';
+</script>
+
+<script lang="ts">
+	import {
+		Axis,
+		Chart,
+		Circle,
+		Group,
+		Image,
+		Layer,
+		LinearGradient,
+		Spline,
+		Tooltip
+	} from 'layerchart';
+	import { Kbd, SelectField, getSettings } from 'svelte-ux';
+	import { curveBumpX } from 'd3-shape';
+	import { scalePoint } from 'd3-scale';
+	import { index, range } from 'd3-array';
+	import { cls } from '@layerstack/tailwind';
+	import {
+		getSportsRankings,
+		getTeamGames,
+		type SportsRank,
+		type TeamGame
+	} from '$lib/sports.remote';
+
+	type Sport = Parameters<typeof getSportsRankings>[0]['sport'];
+
+	const rowHeight = 28;
+	const logoSize = 20;
+	const WEEK_MS = 7 * 24 * 60 * 60 * 1000;
+
+	const sportOptions: { label: string; value: Sport }[] = [
+		{ label: 'College Football', value: 'college-football' },
+		{ label: "Men's College Basketball", value: 'mens-college-basketball' },
+		{ label: "Women's College Basketball", value: 'womens-college-basketball' }
+	];
+
+	let sport = $state<Sport>('college-football');
+	// `undefined` loads the latest season
+	let season = $state<number>();
+
+	// Hold Shift to hide the tooltip and see the highlighted lines underneath
+	let hideTooltip = $state(false);
+
+	const data = $derived(await getSportsRankings({ sport, season }));
+	export { data };
+
+	// Basketball seasons span two years (ex. 2026 = 2025-26)
+	const seasonOptions = $derived(
+		data.seasons.map((year) => ({
+			label: sport.includes('basketball') ? `${year - 1}-${String(year).slice(2)}` : String(year),
+			value: year
+		}))
+	);
+
+	const teamsById = $derived(index(data.teams, (d) => d.id));
+	const weekLabels = $derived(data.weeks.map((w) => w.label));
+
+	/** Team abbreviations for the right axis, by position in the latest poll */
+	const finalAbbreviations = $derived(
+		new Map(
+			data.ranks
+				.filter((d) => d.week === weekLabels.at(-1))
+				.map((d) => [d.position, teamsById.get(d.teamId)?.abbreviation])
+		)
+	);
+
+	const rankByTeamWeek = $derived(
+		index(
+			data.ranks,
+			(d) => d.teamId,
+			(d) => d.week
+		)
+	);
+
+	/** Color each segment by the move into the next week's poll */
+	function lineColor(d: SportsRank) {
+		const nextWeek = weekLabels[weekLabels.indexOf(d.week) + 1];
+		const next = rankByTeamWeek.get(d.teamId)?.get(nextWeek);
+		if (next == null || next.position === d.position) {
+			return 'color-mix(in srgb, var(--color-surface-content) 30%, transparent)';
+		}
+		return next.position < d.position ? 'url(#gradient-improved)' : 'url(#gradient-declined)';
+	}
+
+	/** Split into runs of consecutive weeks so lines break where a team drops out */
+	function teamSegments(teamId: string) {
+		const segments: SportsRank[][] = [[]];
+		for (const week of weekLabels) {
+			const rank = rankByTeamWeek.get(teamId)?.get(week);
+			if (rank) segments.at(-1)!.push(rank);
+			else if (segments.at(-1)!.length) segments.push([]);
+		}
+		return segments.filter((segment) => segment.length);
+	}
+
+	/** Draw the highlighted team last so it is on top */
+	function teamsInDrawOrder(highlightId: string | undefined) {
+		return [...data.teams].sort(
+			(a, b) => Number(a.id === highlightId) - Number(b.id === highlightId)
+		);
+	}
+
+	/**
+	 * When a week's games are played: from the poll's release until the next poll (or a week for
+	 * the latest).  Older seasons don't have poll dates, so games can't be matched to a week.
+	 */
+	function pollWindow(week: string) {
+		const i = weekLabels.indexOf(week);
+		const start = data.weeks[i].date;
+		if (!start) return undefined;
+		const end = data.weeks[i + 1]?.date;
+		return {
+			start: new Date(start).getTime(),
+			end: end ? new Date(end).getTime() : new Date(start).getTime() + WEEK_MS
+		};
+	}
+
+	function gamesInWindow(games: TeamGame[], { start, end }: { start: number; end: number }) {
+		return games.filter((g) => {
+			const time = new Date(g.date).getTime();
+			return time >= start && time < end;
+		});
+	}
+
+	function opponentLabel(game: TeamGame) {
+		const { abbreviation } = game.opponent;
+		if (game.opponentRank) return `${abbreviation} (#${game.opponentRank})`;
+		if (game.opponentSeed) return `${abbreviation} (${game.opponentSeed} seed)`;
+		return abbreviation;
+	}
+
+	const { currentTheme } = getSettings();
+	const logoKey = $derived($currentTheme.dark ? 'logoDark' : 'logo');
+</script>
+
+<svelte:window
+	onkeydown={(e) => {
+		if (e.key === 'Shift') hideTooltip = true;
+	}}
+	onkeyup={(e) => {
+		if (e.key === 'Shift') hideTooltip = false;
+	}}
+	onblur={() => (hideTooltip = false)}
+/>
+
+<div class="grid grid-cols-[1fr_auto] gap-2 mb-2">
+	<SelectField
+		label="Sport"
+		options={sportOptions}
+		bind:value={
+			() => sport,
+			(v) => {
+				sport = v;
+				season = undefined;
+			}
+		}
+		clearable={false}
+		toggleIcon={null}
+		stepper
+	/>
+	<SelectField
+		label="Season"
+		options={seasonOptions}
+		bind:value={
+			() => data.season,
+			(v) => {
+				if (v !== data.season) season = v;
+			}
+		}
+		clearable={false}
+		toggleIcon={null}
+		stepper
+	/>
+</div>
+
+<div class="text-sm text-surface-content/50 mb-1">AP Top 25</div>
+
+<Chart
+	data={data.ranks}
+	x="week"
+	xScale={scalePoint().padding(0.5)}
+	xDomain={weekLabels}
+	y="position"
+	yDomain={[data.maxRank + 0.5, 0.5]}
+	padding={{ top: 24, bottom: 24, left: 36, right: 52 }}
+	height={data.maxRank * rowHeight + 48}
+	tooltipContext={{ mode: 'quadtree' }}
+>
+	{#snippet children({ context })}
+		{@const highlightId = context.tooltip.data?.teamId}
+		<Layer>
+			<LinearGradient
+				id="gradient-improved"
+				stops={['var(--color-success-700)', 'var(--color-success-300)']}
+			/>
+			<LinearGradient
+				id="gradient-declined"
+				stops={['var(--color-danger-300)', 'var(--color-danger-700)']}
+			/>
+
+			<Axis placement="top" rule={false} />
+			<Axis placement="bottom" rule={false} />
+			<Axis placement="left" ticks={range(1, data.maxRank + 1)} format={(d) => `#${d}`} />
+			<Axis
+				placement="right"
+				ticks={[...finalAbbreviations.keys()]}
+				format={(d) => finalAbbreviations.get(d) ?? ''}
+			/>
+
+			{#each teamsInDrawOrder(highlightId) as team (team.id)}
+				{@const segments = teamSegments(team.id)}
+				{@const ranks = segments.flat()}
+				<Group
+					opacity={highlightId == null || highlightId === team.id ? 1 : 0.15}
+					class="transition-opacity duration-200"
+				>
+					{#each segments as segment, i (i)}
+						<Spline
+							data={segment}
+							curve={curveBumpX}
+							stroke={lineColor}
+							strokeWidth={highlightId === team.id ? 4 : 2}
+							opacity={highlightId === team.id ? 1 : 0.5}
+						/>
+					{/each}
+					<Circle
+						data={ranks}
+						cx="week"
+						cy="position"
+						r={logoSize / 2 + 2}
+						class="fill-surface-100 stroke-surface-content/20"
+					/>
+					<Image
+						data={ranks}
+						href={team[logoKey]}
+						x="week"
+						y="position"
+						width={logoSize}
+						height={logoSize}
+					/>
+				</Group>
+			{/each}
+		</Layer>
+
+		{#if !hideTooltip}
+			<Tooltip.Root {context}>
+				{#snippet children({ data: d })}
+					{@const team = teamsById.get(d.teamId)}
+					{@const gameWindow = pollWindow(d.week)}
+					{@const games = gameWindow
+						? getTeamGames({ sport, season: data.season, teamId: d.teamId })
+						: undefined}
+					<Tooltip.Header>
+						<div class="flex items-center gap-2">
+							<img src={team?.[logoKey]} alt="" class="size-5" />
+							{team?.name}
+						</div>
+					</Tooltip.Header>
+					<Tooltip.List>
+						<Tooltip.Item label="Week" value={d.week === 'Pre' ? 'Preseason' : d.week} />
+						<Tooltip.Item label="Rank" value="{d.tied ? 'T-' : '#'}{d.rank}" />
+						{#if d.record}
+							<Tooltip.Item label="Record" value={d.record} />
+						{/if}
+
+						{#if gameWindow && games && !games.error}
+							<Tooltip.Separator />
+							{#if games.current == null}
+								<Tooltip.Item label="Games" value="Loading..." />
+							{:else}
+								{#each gamesInWindow(games.current, gameWindow) as game (game.id)}
+									<div class="col-span-full flex items-center gap-1">
+										{#if game.result}
+											<span
+												class={cls(
+													game.result === 'W' && 'text-success',
+													game.result === 'L' && 'text-danger'
+												)}
+											>
+												{game.result}
+											</span>
+											{game.score}-{game.opponentScore}
+										{:else}
+											{game.status}
+										{/if}
+										{game.home || game.neutralSite ? 'vs' : '@'}
+										<img src={game.opponent[logoKey]} alt="" class="size-4" />
+										{opponentLabel(game)}
+									</div>
+								{:else}
+									<Tooltip.Item label="Games" value="None" />
+								{/each}
+							{/if}
+						{/if}
+					</Tooltip.List>
+					<div class="-mx-2 -mb-1 mt-1 px-2 py-1 border-t text-xs text-surface-content/60">
+						Hold <Kbd class="py-0 px-1 mx-1 border">Shift</Kbd> to hide tooltip
+					</div>
+				{/snippet}
+			</Tooltip.Root>
+		{/if}
+	{/snippet}
+</Chart>
diff --git a/docs/src/examples/components/LineChart/bump-state-population-ranks.svelte b/docs/src/examples/components/LineChart/bump-state-population-ranks.svelte
index 1b939639d3..2ce2921369 100644
--- a/docs/src/examples/components/LineChart/bump-state-population-ranks.svelte
+++ b/docs/src/examples/components/LineChart/bump-state-population-ranks.svelte
@@ -1,3 +1,7 @@
+<script module lang="ts">
+	export const title = 'Bump chart (state population)';
+</script>
+
 <script lang="ts">
 	import { Chart, Axis, LinearGradient, Layer, Spline } from 'layerchart';
 	import { curveBumpX } from 'd3-shape';
diff --git a/docs/src/lib/sports.remote.ts b/docs/src/lib/sports.remote.ts
new file mode 100644
index 0000000000..7cece6efd2
--- /dev/null
+++ b/docs/src/lib/sports.remote.ts
@@ -0,0 +1,372 @@
+import { error } from '@sveltejs/kit';
+import { getRequestEvent, query } from '$app/server';
+import { z } from 'zod';
+
+// Sports data from ESPN's public (undocumented) APIs
+
+const SITE_API = 'https://site.api.espn.com/apis/site/v2/sports';
+const CORE_API = 'https://sports.core.api.espn.com/v2/sports';
+
+/** Number of past seasons offered in the season picker */
+const SEASON_COUNT = 15;
+
+/** Sports with an AP Top 25 poll */
+const leagues = {
+	'college-football': { sport: 'football', league: 'college-football' },
+	'mens-college-basketball': { sport: 'basketball', league: 'mens-college-basketball' },
+	'womens-college-basketball': { sport: 'basketball', league: 'womens-college-basketball' }
+} as const;
+
+type Sport = keyof typeof leagues;
+
+const sportSchema = z.enum(Object.keys(leagues) as [Sport, ...Sport[]]);
+
+const siteUrl = (sport: Sport) => `${SITE_API}/${leagues[sport].sport}/${leagues[sport].league}`;
+const coreUrl = (sport: Sport) =>
+	`${CORE_API}/${leagues[sport].sport}/leagues/${leagues[sport].league}`;
+
+export type SportsTeam = {
+	id: string;
+	name: string;
+	abbreviation: string;
+	logo: string;
+	/** Variant for dark backgrounds */
+	logoDark: string;
+};
+
+export type GameResult = 'W' | 'L' | 'T';
+
+// --- Weekly poll rankings ---
+
+export type SportsRank = {
+	week: string;
+	teamId: string;
+	/** Unique position within the week (1-based), used for plotting */
+	position: number;
+	/** Published rank, which can be shared by multiple teams */
+	rank: number;
+	tied: boolean;
+	record?: string;
+};
+
+export type SportsWeek = {
+	label: string;
+	/** When the poll was released (missing for older seasons) */
+	date?: string;
+};
+
+export type SportsRankings = {
+	season: number;
+	seasons: number[];
+	weeks: SportsWeek[];
+	maxRank: number;
+	teams: SportsTeam[];
+	ranks: SportsRank[];
+};
+
+/**
+ * Weekly AP Top 25 poll rankings for a season.
+ */
+export const getSportsRankings = query(
+	z.object({
+		sport: sportSchema,
+		season: z.number().int().optional()
+	}),
+	async ({ sport, season }): Promise<SportsRankings> => {
+		// Only waited on first when loading the latest season
+		const latestSeasonRequest = fetchJson(`${siteUrl(sport)}/rankings`).then(
+			(d): number => d.latestSeason.year
+		);
+		season ??= await latestSeasonRequest;
+
+		// AP poll (id: 1) for every week of the season
+		const [latestSeason, index, teamsResponse] = await Promise.all([
+			latestSeasonRequest,
+			fetchJson(`${coreUrl(sport)}/seasons/${season}/rankings/1`),
+			fetchJson(`${siteUrl(sport)}/teams?limit=1000`)
+		]);
+		const polls: any[] = await Promise.all(
+			(index.rankings as { $ref: string }[]).map((r) => fetchJson(r.$ref))
+		);
+
+		// Some polls were later overwritten with another poll's rankings and date (ex. the 2025-26
+		// basketball "Week 2" poll holds the final rankings), so skip any dated after a later poll
+		const validPolls = polls.filter(
+			(poll, i) => !polls.slice(i + 1).some((next) => next.date < poll.date)
+		);
+
+		const weeks: SportsWeek[] = [];
+		const ranks: SportsRank[] = [];
+		for (const poll of validPolls) {
+			const label = pollLabel(poll);
+			if (weeks.some((w) => w.label === label)) continue;
+			weeks.push({ label, date: poll.date });
+
+			for (const [i, r] of (poll.ranks as any[]).entries()) {
+				ranks.push({
+					week: label,
+					teamId: r.team.$ref.match(/teams\/(\d+)/)[1],
+					position: i + 1,
+					rank: r.current,
+					tied: poll.ranks.some((other: any) => other !== r && other.current === r.current),
+					record: r.record?.summary
+				});
+			}
+		}
+
+		const teamsById = new Map<string, SportsTeam>(
+			teamsResponse.sports[0].leagues[0].teams.map(({ team }: any) => [team.id, toTeam(team)])
+		);
+		const rankedTeamIds = [...new Set(ranks.map((r) => r.teamId))];
+
+		// Look up any teams missing from the current team list (renamed, moved divisions, etc)
+		const missingTeams = await Promise.all(
+			rankedTeamIds
+				.filter((id) => !teamsById.has(id))
+				.map((id) => fetchJson(`${coreUrl(sport)}/seasons/${season}/teams/${id}`))
+		);
+		for (const team of missingTeams) {
+			teamsById.set(team.id, toTeam(team));
+		}
+
+		return {
+			season,
+			seasons: seasonRange(latestSeason),
+			weeks,
+			maxRank: Math.max(25, ...ranks.map((r) => r.position)),
+			teams: rankedTeamIds.map((id) => teamsById.get(id)!),
+			ranks
+		};
+	}
+);
+
+// --- A team's games ---
+
+export type TeamGame = {
+	id: string;
+	date: string;
+	home: boolean;
+	neutralSite: boolean;
+	opponent: SportsTeam;
+	/** Opponent's rank at the time of the game */
+	opponentRank?: number;
+	/** Opponent's tournament seed (basketball postseason) */
+	opponentSeed?: number;
+	score?: number;
+	opponentScore?: number;
+	/** Set once the game is final */
+	result?: GameResult;
+	/** Status summary (ex. `Final`, `10/24 - 12:00 PM EDT`) */
+	status: string;
+};
+
+/**
+ * A team's games for a season (regular season and postseason), fetched on demand since a full
+ * season of scoreboards for every ranked team is far larger than needed.
+ */
+export const getTeamGames = query(
+	z.object({
+		sport: sportSchema,
+		season: z.number().int(),
+		teamId: z.string().regex(/^\d+$/)
+	}),
+	async ({ sport, season, teamId }): Promise<TeamGame[]> => {
+		const url = `${siteUrl(sport)}/teams/${teamId}/schedule?season=${season}`;
+		// Postseason is a separate request for football (basketball includes it in both)
+		const schedules = await Promise.all([fetchJson(url), fetchJson(`${url}&seasontype=3`)]);
+		const events = new Map<string, any>(
+			schedules.flatMap((schedule) => schedule.events).map((e: any) => [e.id, e])
+		);
+
+		return [...events.values()]
+			.sort((a, b) => a.date.localeCompare(b.date))
+			.map((event) => {
+				const competition = event.competitions[0];
+				const competitors: any[] = competition.competitors;
+				const team = competitors.find((c) => c.team.id === teamId);
+				const opponent = competitors.find((c) => c.team.id !== teamId);
+				const completed = competition.status.type.completed;
+				// Basketball tournament games list seeds instead of ranks
+				const isTournament = leagues[sport].sport === 'basketball' && event.seasonType?.type === 3;
+
+				return {
+					id: event.id,
+					date: event.date,
+					home: team.homeAway === 'home',
+					neutralSite: competition.neutralSite,
+					opponent: toTeam(opponent.team),
+					opponentRank: isTournament ? undefined : topRank(opponent),
+					opponentSeed: isTournament ? opponent.curatedRank?.current : undefined,
+					score: completed ? team.score?.value : undefined,
+					opponentScore: completed ? opponent.score?.value : undefined,
+					result: completed ? gameResult(team, opponent) : undefined,
+					status: competition.status.type.shortDetail
+				};
+			});
+	}
+);
+
+// --- Ranked matchups (college football) ---
+
+export type MatchupTeam = SportsTeam & {
+	/** Rank at kickoff (AP poll, or CFP rankings once released) */
+	rank?: number;
+	score?: number;
+	/** Set once the game is final */
+	result?: GameResult;
+};
+
+export type Matchup = {
+	id: string;
+	week: string;
+	date: string;
+	/** Status summary (ex. `Final`, `10/24 - 12:00 PM EDT`) */
+	status: string;
+	teams: [MatchupTeam, MatchupTeam];
+};
+
+export type SeasonMatchups = {
+	season: number;
+	seasons: number[];
+	weeks: string[];
+	games: Matchup[];
+};
+
+const POSTSEASON_ROUNDS = ['Bowls', 'R1', 'QF', 'SF', 'Title'];
+
+/**
+ * College football games involving a ranked team, for each week of a season (through the current
+ * week).  Postseason games are split into bowls and each playoff round.
+ */
+export const getRankedMatchups = query(
+	z.object({ season: z.number().int().optional() }),
+	async ({ season }): Promise<SeasonMatchups> => {
+		const url = `${siteUrl('college-football')}/scoreboard`;
+		// Only waited on first when loading the latest season
+		const latestSeasonRequest = fetchJson(`${url}?limit=1`).then((d): number => d.season.year);
+		season ??= await latestSeasonRequest;
+		const scoreboardUrl = (seasonType: number, week: string | number) =>
+			`${url}?dates=${season}&seasontype=${seasonType}&week=${week}`;
+
+		// Week 1 includes the season calendar, used to find the remaining (started) weeks
+		const [latestSeason, firstWeek] = await Promise.all([
+			latestSeasonRequest,
+			fetchJson(scoreboardUrl(2, 1))
+		]);
+		const calendar: any[] = firstWeek.leagues[0].calendar;
+		const started = (entry: any) => new Date(entry.startDate) <= new Date();
+		const regularWeeks: string[] = calendar
+			.find((c) => c.value === '2')
+			.entries.filter(started)
+			.map((entry: any) => entry.value);
+		const postseasonStarted = calendar.find((c) => c.value === '3')?.entries.some(started);
+
+		const requests = regularWeeks.slice(1).map((week) => fetchJson(scoreboardUrl(2, week)));
+		if (postseasonStarted) {
+			// All postseason games (bowls and playoff) are in the first postseason "week"
+			requests.push(fetchJson(scoreboardUrl(3, 1)));
+		}
+		const scoreboards = [firstWeek, ...(await Promise.all(requests))];
+
+		const games: Matchup[] = [];
+		for (const event of scoreboards.flatMap((scoreboard) => scoreboard.events as any[])) {
+			const competition = event.competitions[0];
+			const headline: string = competition.notes?.[0]?.headline ?? '';
+			if (headline.startsWith('FCS')) continue;
+
+			const [a, b] = competition.competitors as any[];
+			const completed = competition.status.type.completed;
+			const toMatchupTeam = (c: any, opponent: any): MatchupTeam => ({
+				...toTeam(c.team),
+				rank: topRank(c),
+				score: c.score != null ? Number(c.score) : undefined,
+				result: completed ? gameResult(c, opponent) : undefined
+			});
+			const teams: [MatchupTeam, MatchupTeam] = [toMatchupTeam(a, b), toMatchupTeam(b, a)];
+			if (!teams.some((t) => t.rank)) continue;
+
+			games.push({
+				id: event.id,
+				week: event.season.type === 3 ? postseasonRound(headline) : String(event.week.number),
+				date: event.date,
+				status: competition.status.type.shortDetail,
+				teams
+			});
+		}
+
+		const weeks = [...regularWeeks, ...POSTSEASON_ROUNDS].filter((week) =>
+			games.some((g) => g.week === week)
+		);
+
+		return { season, seasons: seasonRange(latestSeason), weeks, games };
+	}
+);
+
+// --- Helpers ---
+
+async function fetchJson(url: string, retries = 1): Promise<any> {
+	const { fetch } = getRequestEvent();
+	// `$ref` links returned by the core API use `http`
+	const response = await fetch(url.replace(/^http:/, 'https:')).catch(() => null);
+	// Retry dropped connections and server errors, which ESPN returns occasionally
+	if ((!response || response.status >= 500) && retries > 0) {
+		return fetchJson(url, retries - 1);
+	}
+	if (!response?.ok) {
+		error(502, `Unable to load ${url} (${response?.status ?? 'network error'})`);
+	}
+	return response.json();
+}
+
+function toTeam(team: any): SportsTeam {
+	// Team endpoints have a list of `logos`, while scoreboards have `logo` / `logoDark`
+	const logos: { href: string; rel: string[] }[] = team.logos ?? [];
+	const logo: string =
+		logos.find((l) => l.rel.includes('default'))?.href ?? logos[0]?.href ?? team.logo ?? '';
+	const logoDark: string = logos.find((l) => l.rel.includes('dark'))?.href ?? team.logoDark ?? logo;
+	return {
+		id: team.id,
+		name: team.displayName,
+		abbreviation: team.abbreviation,
+		logo: resizeLogo(logo),
+		logoDark: resizeLogo(logoDark)
+	};
+}
+
+/** Request a small, resized logo (originals are 500px) */
+function resizeLogo(href: string) {
+	return href.startsWith('https://a.espncdn.com/')
+		? `https://a.espncdn.com/combiner/i?img=${new URL(href).pathname}&w=64&h=64`
+		: href;
+}
+
+/** A competitor's Top 25 rank at the time of the game (unranked teams are `99`) */
+function topRank(competitor: any): number | undefined {
+	const rank = competitor.curatedRank?.current;
+	return rank && rank <= 25 ? rank : undefined;
+}
+
+function gameResult(competitor: any, opponent: any): GameResult {
+	return competitor.winner ? 'W' : opponent.winner ? 'L' : 'T';
+}
+
+function postseasonRound(headline: string) {
+	if (/national championship/i.test(headline)) return 'Title';
+	if (/semifinal/i.test(headline)) return 'SF';
+	if (/quarterfinal/i.test(headline)) return 'QF';
+	if (/first round/i.test(headline)) return 'R1';
+	return 'Bowls';
+}
+
+function pollLabel(poll: any) {
+	// Postseason polls are numbered (ex. `Week 3`) for basketball rather than `Final Rankings`
+	if (poll.$ref.includes('/types/3/')) return 'Final';
+	const displayValue: string = poll.occurrence.displayValue;
+	// `occurrence.number` is off by one for basketball, so use the label
+	return displayValue.startsWith('Pre') ? 'Pre' : displayValue.replace('Week ', '');
+}
+
+/** Oldest to latest, so a stepper's "next" moves forward in time */
+function seasonRange(latest: number) {
+	return Array.from({ length: SEASON_COUNT }, (_, i) => latest - SEASON_COUNT + 1 + i);
+}