From ee20b9809169f58db504f404d6bc3a7d7e2a6ebb Mon Sep 17 00:00:00 2001
From: Ewan Croft <contact@ewancroft.uk>
Date: Thu, 13 Aug 2026 15:38:42 +0100
Subject: [PATCH 1/2] feat(tourmaline): expose monthlyArtistPlays on
 ListenerProfile
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The aggregator already computes per-month artist play counts
internally (AggregatedData.monthlyArtistPlays), but nothing surfaced
it on the client-facing ListenerProfile. Needed as the data source
for an upcoming bar-chart-race visualization — serialized as sorted
tuples rather than a Map since it needs to round-trip through
component props/state cleanly.
---
 packages/tourmaline/src/lib/client/load-profile.ts | 3 +++
 packages/tourmaline/src/lib/types.ts               | 6 ++++++
 2 files changed, 9 insertions(+)

diff --git a/packages/tourmaline/src/lib/client/load-profile.ts b/packages/tourmaline/src/lib/client/load-profile.ts
index 81453b3..9747012 100644
--- a/packages/tourmaline/src/lib/client/load-profile.ts
+++ b/packages/tourmaline/src/lib/client/load-profile.ts
@@ -159,6 +159,9 @@ export function computeProfile(
     albumMilestones: data.albumMilestones,
     longestNotListenedGap: data.longestNotListenedGap,
     recommendations: buildRecommendations(data.topArtists, data.allArtists, artistInfos),
+    monthlyArtistPlays: [...data.monthlyArtistPlays.entries()]
+      .sort(([a], [b]) => a.localeCompare(b))
+      .map(([month, plays]) => [month, [...plays.entries()]]),
   };
 
   const sessions = deriveSessions(filtered);
diff --git a/packages/tourmaline/src/lib/types.ts b/packages/tourmaline/src/lib/types.ts
index dd4cf32..90d7c46 100644
--- a/packages/tourmaline/src/lib/types.ts
+++ b/packages/tourmaline/src/lib/types.ts
@@ -137,6 +137,12 @@ export interface ListenerProfile {
   albumMilestones: Milestone[];
   longestNotListenedGap: Gap | null;
   recommendations: Recommendation[];
+  /**
+   * Chronologically ordered per-month artist play counts, serialized as
+   * tuples (Maps don't survive structured cloning the way we need for
+   * $state). Used by the bar-chart-race visualization.
+   */
+  monthlyArtistPlays: Array<[month: string, plays: Array<[artist: string, count: number]>]>;
 }
 
 export interface UnusualMonth {
-- 
2.51.2


From 1d6da7da98af94ea67b77875382e26f193672e89 Mon Sep 17 00:00:00 2001
From: Ewan Croft <contact@ewancroft.uk>
Date: Thu, 13 Aug 2026 15:38:49 +0100
Subject: [PATCH 2/2] feat(tourmaline): add animated bar-chart race for top
 artists
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Precomputes one frame per month up front (running cumulative counts,
snapshotted to the top 15 artists), then drives a horizontal Chart.js
bar chart through the frames on a setInterval, relying on Chart.js's
built-in animation to tween between frames — the standard bar-chart-
race technique, no extra library.

Playback (play/pause, scrubber, 0.5x/1x/2x speed) is driven by a
single $effect keyed on `playing`/`speed`: the effect's cleanup
clears the interval on every re-run, so pausing, changing speed, or
unmounting can never leak a timer (same discipline as
StoryRecap.svelte's resetAutoAdvance). Playback stops (without
looping) at the last frame and the play button re-enables once the
user scrubs back.

Wired into the catalogue tab above the existing Top Artists list.
---
 .../src/routes/profile/[did]/+page.svelte     |   6 +
 .../src/routes/profile/[did]/RaceChart.svelte | 227 ++++++++++++++++++
 2 files changed, 233 insertions(+)
 create mode 100644 packages/tourmaline/src/routes/profile/[did]/RaceChart.svelte

diff --git a/packages/tourmaline/src/routes/profile/[did]/+page.svelte b/packages/tourmaline/src/routes/profile/[did]/+page.svelte
index c3e6515..bdb5660 100644
--- a/packages/tourmaline/src/routes/profile/[did]/+page.svelte
+++ b/packages/tourmaline/src/routes/profile/[did]/+page.svelte
@@ -40,6 +40,7 @@
 	import CatalogueTab from './CatalogueTab.svelte';
 	import PunchcardHeatmap from './PunchcardHeatmap.svelte';
 	import EddingtonChart from './EddingtonChart.svelte';
+	import RaceChart from './RaceChart.svelte';
 	import Recommendations from './Recommendations.svelte';
 	import TrackPreview from '$lib/components/TrackPreview.svelte';
 	import ListeningContext from './ListeningContext.svelte';
@@ -488,6 +489,11 @@
 
 		<!-- ── Catalogue tab ─────────────────────────────── -->
 		{:else if activeTab === 'catalogue'}
+			<!-- Top artists race -->
+			<div class="mb-6 sm:mb-8">
+				<RaceChart monthlyArtistPlays={profile.monthlyArtistPlays} />
+			</div>
+
 			<!-- Top artists -->
 			<div class="mb-6 overflow-hidden rounded border border-[var(--border)] bg-[var(--surface)] p-3 sm:mb-8 sm:p-4">
 				<div class="mb-3 flex items-center justify-between sm:mb-4">
diff --git a/packages/tourmaline/src/routes/profile/[did]/RaceChart.svelte b/packages/tourmaline/src/routes/profile/[did]/RaceChart.svelte
new file mode 100644
index 0000000..cfb53ce
--- /dev/null
+++ b/packages/tourmaline/src/routes/profile/[did]/RaceChart.svelte
@@ -0,0 +1,227 @@
+<script lang="ts">
+	import { Chart } from '$lib/chart';
+	import { Play, Pause, TrendingUp } from '@lucide/svelte';
+
+	let {
+		monthlyArtistPlays = []
+	}: {
+		monthlyArtistPlays: Array<[month: string, plays: Array<[artist: string, count: number]>]>;
+	} = $props();
+
+	const TOP_N = 15;
+	const BASE_INTERVAL_MS = 800;
+	const SPEEDS = [0.5, 1, 2] as const;
+
+	interface RaceFrame {
+		month: string;
+		entries: Array<{ name: string; cumulativeCount: number }>;
+	}
+
+	/**
+	 * Precompute one frame per month: a running cumulative-count map across
+	 * all artists, snapshotted to the top 15 as of that month. Computed once
+	 * up front (not per animation frame) — adapted from lastfm-stats-web's
+	 * bar-chart-race approach.
+	 */
+	const frames: RaceFrame[] = $derived.by(() => {
+		const cumulative = new Map<string, number>();
+		const sortedMonths = [...monthlyArtistPlays].sort(([a], [b]) => a.localeCompare(b));
+		const result: RaceFrame[] = [];
+
+		for (const [month, plays] of sortedMonths) {
+			for (const [artist, count] of plays) {
+				cumulative.set(artist, (cumulative.get(artist) ?? 0) + count);
+			}
+			const entries = [...cumulative.entries()]
+				.sort((a, b) => b[1] - a[1])
+				.slice(0, TOP_N)
+				.map(([name, cumulativeCount]) => ({ name, cumulativeCount }));
+			result.push({ month, entries });
+		}
+
+		return result;
+	});
+
+	let frameIndex = $state(0);
+	let playing = $state(false);
+	let speed = $state<(typeof SPEEDS)[number]>(1);
+
+	const currentFrame = $derived(frames[frameIndex] ?? null);
+	const atEnd = $derived(frames.length === 0 || frameIndex >= frames.length - 1);
+
+	function formatMonth(month: string): string {
+		const [y, m] = month.split('-').map(Number);
+		if (!y || !m) return month;
+		return new Date(y, m - 1, 1).toLocaleDateString(undefined, {
+			month: 'long',
+			year: 'numeric'
+		});
+	}
+
+	function togglePlay() {
+		if (playing) {
+			playing = false;
+			return;
+		}
+		if (atEnd) return; // reached the end — user must scrub back to restart
+		playing = true;
+	}
+
+	function onScrub(e: Event) {
+		playing = false;
+		frameIndex = Number((e.target as HTMLInputElement).value);
+	}
+
+	function setSpeed(s: (typeof SPEEDS)[number]) {
+		speed = s;
+	}
+
+	// Drives frame advancement. Re-runs (and tears down/recreates the
+	// interval) whenever `playing` or `speed` changes; the effect's cleanup
+	// function clears the interval, so pausing, changing speed, or
+	// unmounting the component can never leak an interval.
+	$effect(() => {
+		if (!playing) return;
+
+		const intervalMs = BASE_INTERVAL_MS / speed;
+		const timer = setInterval(() => {
+			if (frameIndex >= frames.length - 1) {
+				playing = false;
+				return;
+			}
+			frameIndex += 1;
+		}, intervalMs);
+
+		return () => clearInterval(timer);
+	});
+
+	let canvas: HTMLCanvasElement | undefined = $state();
+	let chart: Chart | null = null;
+
+	$effect(() => {
+		if (!canvas || !currentFrame) return;
+
+		const labels = currentFrame.entries.map((e) => e.name);
+		const data = currentFrame.entries.map((e) => e.cumulativeCount);
+		const intervalMs = BASE_INTERVAL_MS / speed;
+
+		if (chart) {
+			chart.data.labels = labels;
+			chart.data.datasets[0].data = data;
+			(chart.options.animation as { duration: number }).duration = Math.round(intervalMs * 0.9);
+			chart.update();
+			return;
+		}
+
+		chart = new Chart(canvas, {
+			type: 'bar',
+			data: {
+				labels,
+				datasets: [
+					{
+						data,
+						backgroundColor: '#4ade80',
+						borderColor: '#22c55e',
+						borderWidth: 1
+					}
+				]
+			},
+			options: {
+				indexAxis: 'y',
+				responsive: true,
+				maintainAspectRatio: false,
+				animation: {
+					duration: Math.round(intervalMs * 0.9),
+					easing: 'linear'
+				},
+				plugins: {
+					legend: { display: false },
+					tooltip: {
+						callbacks: {
+							label(ctx) {
+								return `${(ctx.parsed.x ?? 0).toLocaleString()} plays`;
+							}
+						}
+					}
+				},
+				scales: {
+					x: {
+						beginAtZero: true,
+						ticks: { color: '#9ca3af', font: { size: 10 } },
+						grid: { color: 'rgba(255,255,255,0.05)' }
+					},
+					y: {
+						ticks: { color: '#e5e7eb', font: { size: 11 } },
+						grid: { display: false }
+					}
+				}
+			}
+		});
+	});
+</script>
+
+{#if frames.length > 0}
+	<div class="rounded border border-[var(--border)] bg-[var(--surface)] p-3 sm:p-4">
+		<div class="mb-3 flex items-center justify-between sm:mb-4">
+			<h2 class="flex items-center gap-1.5 text-base font-semibold sm:text-lg">
+				<TrendingUp size={16} class="text-[var(--accent)]" />
+				Top Artists Race
+			</h2>
+			<span class="text-lg font-bold tabular-nums text-[var(--accent)] sm:text-xl">
+				{formatMonth(currentFrame?.month ?? '')}
+			</span>
+		</div>
+
+		<div class="h-[420px] sm:h-[520px]">
+			<canvas bind:this={canvas}></canvas>
+		</div>
+
+		<div class="mt-4 flex flex-col gap-3">
+			<div class="flex items-center gap-3">
+				<button
+					onclick={togglePlay}
+					disabled={atEnd && !playing}
+					class="flex shrink-0 items-center gap-1.5 rounded border border-[var(--border)] px-2.5 py-1.5 text-xs text-[var(--text-muted)] transition-colors hover:border-[var(--accent)] hover:text-[var(--accent)] disabled:cursor-not-allowed disabled:opacity-40 disabled:hover:border-[var(--border)] disabled:hover:text-[var(--text-muted)]"
+					aria-label={playing ? 'Pause' : 'Play'}
+				>
+					{#if playing}
+						<Pause size={13} />
+						Pause
+					{:else}
+						<Play size={13} />
+						Play
+					{/if}
+				</button>
+
+				<input
+					type="range"
+					min="0"
+					max={frames.length - 1}
+					step="1"
+					value={frameIndex}
+					oninput={onScrub}
+					class="flex-1 accent-[var(--accent)]"
+					aria-label="Frame scrubber"
+				/>
+
+				<span class="w-14 shrink-0 text-right font-mono text-xs text-[var(--text-muted)]">
+					{frameIndex + 1}/{frames.length}
+				</span>
+			</div>
+
+			<div class="flex items-center gap-1.5">
+				<span class="text-xs text-[var(--text-dim)]">Speed</span>
+				{#each SPEEDS as s (s)}
+					<button
+						onclick={() => setSpeed(s)}
+						class="rounded border px-2 py-0.5 text-xs transition-colors {speed === s
+							? 'border-[var(--accent)] text-[var(--accent)]'
+							: 'border-[var(--border)] text-[var(--text-muted)] hover:border-[var(--accent)]/40 hover:text-[var(--text)]'}"
+					>
+						{s}x
+					</button>
+				{/each}
+			</div>
+		</div>
+	</div>
+{/if}
-- 
2.51.2