From 5e7c3ad7ed8c287b538de97d4de3a4df87e9a100 Mon Sep 17 00:00:00 2001 From: nsfisis Date: Sun, 8 Feb 2026 21:18:55 +0900 Subject: 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 --- src/client/atoms/study.ts | 6 ++-- src/client/utils/random.test.ts | 69 ++++++++++++++++++++++++++++++++++++++++ src/client/utils/random.ts | 32 +++++++++++++++++++ src/client/utils/shuffle.test.ts | 54 ------------------------------- src/client/utils/shuffle.ts | 14 -------- 5 files changed, 105 insertions(+), 70 deletions(-) create mode 100644 src/client/utils/random.test.ts create mode 100644 src/client/utils/random.ts delete mode 100644 src/client/utils/shuffle.test.ts delete mode 100644 src/client/utils/shuffle.ts (limited to 'src/client') diff --git a/src/client/atoms/study.ts b/src/client/atoms/study.ts index 324f92e..fca17b7 100644 --- a/src/client/atoms/study.ts +++ b/src/client/atoms/study.ts @@ -1,7 +1,8 @@ import { atomFamily } from "jotai-family"; import { atomWithSuspenseQuery } from "jotai-tanstack-query"; +import { getStartOfStudyDayBoundary } from "../../shared/date"; import { apiClient } from "../api/client"; -import { shuffle } from "../utils/shuffle"; +import { createSeededRandom, shuffle } from "../utils/random"; export interface StudyCard { id: string; @@ -54,9 +55,10 @@ export const studyDataAtomFamily = atomFamily((deckId: string) => cards: StudyCard[]; }>(cardsRes); + const seed = getStartOfStudyDayBoundary().getTime(); return { deck: deckData.deck, - cards: shuffle(cardsData.cards), + cards: shuffle(cardsData.cards, createSeededRandom(seed)), }; }, })), diff --git a/src/client/utils/random.test.ts b/src/client/utils/random.test.ts new file mode 100644 index 0000000..8d5f57e --- /dev/null +++ b/src/client/utils/random.test.ts @@ -0,0 +1,69 @@ +import { describe, expect, it } from "vitest"; +import { createSeededRandom, shuffle } from "./random"; + +describe("shuffle", () => { + it("returns an array of the same length", () => { + const input = [1, 2, 3, 4, 5]; + const result = shuffle(input); + expect(result).toHaveLength(input.length); + }); + + it("contains all original elements", () => { + const input = [1, 2, 3, 4, 5]; + const result = shuffle(input); + expect(result.sort()).toEqual(input.sort()); + }); + + it("does not mutate the original array", () => { + const input = [1, 2, 3, 4, 5]; + const original = [...input]; + shuffle(input); + expect(input).toEqual(original); + }); + + it("returns empty array for empty input", () => { + expect(shuffle([])).toEqual([]); + }); + + it("returns single element array unchanged", () => { + expect(shuffle([1])).toEqual([1]); + }); + + it("works with objects", () => { + const input = [{ id: 1 }, { id: 2 }, { id: 3 }]; + const result = shuffle(input); + expect(result).toHaveLength(3); + 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; + const iterations = 100; + + for (let i = 0; i < iterations; i++) { + const result = shuffle(input); + if (JSON.stringify(result) === JSON.stringify(input)) { + sameOrderCount++; + } + } + + // Should very rarely keep original order (probability ~1/3628800) + expect(sameOrderCount).toBeLessThan(iterations * 0.1); + }); +}); 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( + 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.test.ts b/src/client/utils/shuffle.test.ts deleted file mode 100644 index 687aec4..0000000 --- a/src/client/utils/shuffle.test.ts +++ /dev/null @@ -1,54 +0,0 @@ -import { describe, expect, it } from "vitest"; -import { shuffle } from "./shuffle"; - -describe("shuffle", () => { - it("returns an array of the same length", () => { - const input = [1, 2, 3, 4, 5]; - const result = shuffle(input); - expect(result).toHaveLength(input.length); - }); - - it("contains all original elements", () => { - const input = [1, 2, 3, 4, 5]; - const result = shuffle(input); - expect(result.sort()).toEqual(input.sort()); - }); - - it("does not mutate the original array", () => { - const input = [1, 2, 3, 4, 5]; - const original = [...input]; - shuffle(input); - expect(input).toEqual(original); - }); - - it("returns empty array for empty input", () => { - expect(shuffle([])).toEqual([]); - }); - - it("returns single element array unchanged", () => { - expect(shuffle([1])).toEqual([1]); - }); - - it("works with objects", () => { - const input = [{ id: 1 }, { id: 2 }, { id: 3 }]; - const result = shuffle(input); - expect(result).toHaveLength(3); - expect(result.map((x) => x.id).sort()).toEqual([1, 2, 3]); - }); - - it("actually shuffles (statistical test)", () => { - const input = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]; - let sameOrderCount = 0; - const iterations = 100; - - for (let i = 0; i < iterations; i++) { - const result = shuffle(input); - if (JSON.stringify(result) === JSON.stringify(input)) { - sameOrderCount++; - } - } - - // Should very rarely keep original order (probability ~1/3628800) - expect(sameOrderCount).toBeLessThan(iterations * 0.1); - }); -}); 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(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; -} -- cgit v1.3-1-g0d28