From 0d56a04d770c2df492ecf59c941e8d90578b0b60 Mon Sep 17 00:00:00 2001
From: nsfisis <nsfisis@gmail.com>
Date: Sat, 3 Jan 2026 00:33:56 +0900
Subject: feat(study): shuffle cards when starting study session
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cards are now randomized using Fisher-Yates algorithm to improve
learning by preventing users from memorizing card order.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
---
 src/client/pages/StudyPage.test.tsx |  5 ++++
 src/client/pages/StudyPage.tsx      |  3 ++-
 src/client/utils/shuffle.test.ts    | 54 +++++++++++++++++++++++++++++++++++++
 src/client/utils/shuffle.ts         | 14 ++++++++++
 4 files changed, 75 insertions(+), 1 deletion(-)
 create mode 100644 src/client/utils/shuffle.test.ts
 create mode 100644 src/client/utils/shuffle.ts

(limited to 'src')

diff --git a/src/client/pages/StudyPage.test.tsx b/src/client/pages/StudyPage.test.tsx
index edf683a..c257b24 100644
--- a/src/client/pages/StudyPage.test.tsx
+++ b/src/client/pages/StudyPage.test.tsx
@@ -14,6 +14,11 @@ const mockStudyGet = vi.fn();
 const mockStudyPost = vi.fn();
 const mockHandleResponse = vi.fn();
 
+// Mock shuffle to return array in original order for predictable tests
+vi.mock("../utils/shuffle", () => ({
+	shuffle: <T,>(array: T[]): T[] => [...array],
+}));
+
 vi.mock("../api/client", () => ({
 	apiClient: {
 		login: vi.fn(),
diff --git a/src/client/pages/StudyPage.tsx b/src/client/pages/StudyPage.tsx
index 43fd195..b6c9a3b 100644
--- a/src/client/pages/StudyPage.tsx
+++ b/src/client/pages/StudyPage.tsx
@@ -8,6 +8,7 @@ import { FontAwesomeIcon } from "@fortawesome/react-fontawesome";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Link, useParams } from "wouter";
 import { ApiClientError, apiClient } from "../api";
+import { shuffle } from "../utils/shuffle";
 import { renderCard } from "../utils/templateRenderer";
 
 interface Card {
@@ -82,7 +83,7 @@ export function StudyPage() {
 			param: { deckId },
 		});
 		const data = await apiClient.handleResponse<{ cards: Card[] }>(res);
-		setCards(data.cards);
+		setCards(shuffle(data.cards));
 	}, [deckId]);
 
 	const fetchData = useCallback(async () => {
diff --git a/src/client/utils/shuffle.test.ts b/src/client/utils/shuffle.test.ts
new file mode 100644
index 0000000..687aec4
--- /dev/null
+++ b/src/client/utils/shuffle.test.ts
@@ -0,0 +1,54 @@
+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
new file mode 100644
index 0000000..a2b8fec
--- /dev/null
+++ b/src/client/utils/shuffle.ts
@@ -0,0 +1,14 @@
+/**
+ * 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;
+}
-- 
cgit v1.2.3-70-g09d2