2 files changed, 79 insertions, 0 deletions
diff --git a/src/shared/date.test.ts b/src/shared/date.test.ts
new file mode 100644
index 0000000..1c61a15
--- /dev/null
+++ b/src/shared/date.test.ts
@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+import { getEndOfStudyDayBoundary } from "./date";
+
+describe("getEndOfStudyDayBoundary", () => {
+	it("should return next day 3:00 AM when current time is after 3:00 AM", () => {
+		// Feb 2, 2026 10:00 AM
+		const now = new Date(2026, 1, 2, 10, 0, 0, 0);
+		const boundary = getEndOfStudyDayBoundary(now);
+
+		expect(boundary.getFullYear()).toBe(2026);
+		expect(boundary.getMonth()).toBe(1);
+		expect(boundary.getDate()).toBe(3);
+		expect(boundary.getHours()).toBe(3);
+		expect(boundary.getMinutes()).toBe(0);
+		expect(boundary.getSeconds()).toBe(0);
+	});
+
+	it("should return today 3:00 AM when current time is before 3:00 AM", () => {
+		// Feb 2, 2026 1:30 AM
+		const now = new Date(2026, 1, 2, 1, 30, 0, 0);
+		const boundary = getEndOfStudyDayBoundary(now);
+
+		expect(boundary.getFullYear()).toBe(2026);
+		expect(boundary.getMonth()).toBe(1);
+		expect(boundary.getDate()).toBe(2);
+		expect(boundary.getHours()).toBe(3);
+		expect(boundary.getMinutes()).toBe(0);
+		expect(boundary.getSeconds()).toBe(0);
+	});
+
+	it("should return next day 3:00 AM when current time is exactly 3:00 AM", () => {
+		// Feb 2, 2026 3:00 AM
+		const now = new Date(2026, 1, 2, 3, 0, 0, 0);
+		const boundary = getEndOfStudyDayBoundary(now);
+
+		expect(boundary.getDate()).toBe(3);
+		expect(boundary.getHours()).toBe(3);
+	});
+
+	it("should return next day 3:00 AM when current time is 11:59 PM", () => {
+		// Feb 2, 2026 11:59 PM
+		const now = new Date(2026, 1, 2, 23, 59, 0, 0);
+		const boundary = getEndOfStudyDayBoundary(now);
+
+		expect(boundary.getDate()).toBe(3);
+		expect(boundary.getHours()).toBe(3);
+	});
+
+	it("should handle month boundaries correctly", () => {
+		// Jan 31, 2026 15:00
+		const now = new Date(2026, 0, 31, 15, 0, 0, 0);
+		const boundary = getEndOfStudyDayBoundary(now);
+
+		expect(boundary.getMonth()).toBe(1); // February
+		expect(boundary.getDate()).toBe(1);
+		expect(boundary.getHours()).toBe(3);
+	});
+});
diff --git a/src/shared/date.ts b/src/shared/date.ts
new file mode 100644
index 0000000..583d2a6
--- /dev/null
+++ b/src/shared/date.ts
@@ -0,0 +1,21 @@
+/**
+ * Returns the end-of-day boundary for due card comparison.
+ *
+ * The "study day" is defined as 3:00 AM to the next day's 3:00 AM.
+ * All cards with `due < boundary` are considered due for the current study day.
+ *
+ * - If current time >= 3:00 AM, boundary = tomorrow 3:00 AM local time
+ * - If current time < 3:00 AM, boundary = today 3:00 AM local time
+ */
+export function getEndOfStudyDayBoundary(now: Date = new Date()): Date {
+	const boundary = new Date(now);
+	boundary.setMinutes(0, 0, 0);
+
+	if (boundary.getHours() >= 3) {
+		// Move to next day
+		boundary.setDate(boundary.getDate() + 1);
+	}
+
+	boundary.setHours(3);
+	return boundary;
+}