feat(study): use seeded PRNG for deterministic card shuffle order

Shuffle order is now fixed within a study day by seeding mulberry32
with the study day boundary timestamp (3:00 AM rollover).

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

3 files changed, 48 insertions, 15 deletions

diff --git a/src/client/utils/shuffle.test.ts b/src/client/utils/random.test.ts
index 687aec4..8d5f57e 100644
--- a/src/client/utils/shuffle.test.ts
+++ b/src/client/utils/random.test.ts
@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { shuffle } from "./shuffle";
+import { createSeededRandom, shuffle } from "./random";
 
 describe("shuffle", () => {
 	it("returns an array of the same length", () => {
@@ -36,6 +36,21 @@ describe("shuffle", () => {
 		expect(result.map((x) => x.id).sort()).toEqual([1, 2, 3]);
 	});
 
+	it("produces deterministic result with seeded random", () => {
+		const input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+		const seed = 12345;
+		const result1 = shuffle(input, createSeededRandom(seed));
+		const result2 = shuffle(input, createSeededRandom(seed));
+		expect(result1).toEqual(result2);
+	});
+
+	it("produces different results with different seeds", () => {
+		const input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+		const result1 = shuffle(input, createSeededRandom(1));
+		const result2 = shuffle(input, createSeededRandom(2));
+		expect(result1).not.toEqual(result2);
+	});
+
 	it("actually shuffles (statistical test)", () => {
 		const input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
 		let sameOrderCount = 0;
diff --git a/src/client/utils/random.ts b/src/client/utils/random.ts
new file mode 100644
index 0000000..53de45e
--- /dev/null
+++ b/src/client/utils/random.ts
@@ -0,0 +1,32 @@
+/**
+ * Mulberry32 seeded PRNG.
+ * Returns a function that produces deterministic values in [0, 1).
+ */
+export function createSeededRandom(seed: number): () => number {
+	let s = seed | 0;
+	return () => {
+		s = (s + 0x6d2b79f5) | 0;
+		let t = Math.imul(s ^ (s >>> 15), 1 | s);
+		t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+		return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+	};
+}
+
+/**
+ * Fisher-Yates shuffle algorithm.
+ * Returns a new shuffled array (does not mutate the original).
+ * Accepts an optional `random` function for deterministic shuffling.
+ */
+export function shuffle<T>(
+	array: T[],
+	random: () => number = Math.random,
+): T[] {
+	const result = [...array];
+	for (let i = result.length - 1; i > 0; i--) {
+		const j = Math.floor(random() * (i + 1));
+		const temp = result[i] as T;
+		result[i] = result[j] as T;
+		result[j] = temp;
+	}
+	return result;
+}
diff --git a/src/client/utils/shuffle.ts b/src/client/utils/shuffle.ts
deleted file mode 100644
index a2b8fec..0000000
--- a/src/client/utils/shuffle.ts
+++ /dev/null
@@ -1,14 +0,0 @@
-/**
- * Fisher-Yates shuffle algorithm.
- * Returns a new shuffled array (does not mutate the original).
- */
-export function shuffle<T>(array: T[]): T[] {
-	const result = [...array];
-	for (let i = result.length - 1; i > 0; i--) {
-		const j = Math.floor(Math.random() * (i + 1));
-		const temp = result[i] as T;
-		result[i] = result[j] as T;
-		result[j] = temp;
-	}
-	return result;
-}