2 files changed, 61 insertions, 0 deletions
diff --git a/src/lib/shared/temporal.test.ts b/src/lib/shared/temporal.test.ts
new file mode 100644
index 0000000..ef3477a
--- /dev/null
+++ b/src/lib/shared/temporal.test.ts
@@ -0,0 +1,35 @@
+import { describe, expect, it } from 'vitest';
+import { instantFromDay } from './temporal';
+
+// A weekday well inside the year so noon UTC never collides with a clamp.
+const NOW = Temporal.Instant.from('2026-09-20T08:00:00.000Z');
+
+describe('instantFromDay', () => {
+	it('stamps a past day at noon UTC', () => {
+		expect(instantFromDay('2026-09-13', NOW)).toBe('2026-09-13T12:00:00.000Z');
+	});
+
+	it('clamps today to the current instant', () => {
+		expect(instantFromDay('2026-09-20', NOW)).toBe('2026-09-20T08:00:00.000Z');
+	});
+
+	it('keeps a past day that is only hours old as-is', () => {
+		// 21:00 the day before: noon of that day is still in the past.
+		expect(instantFromDay('2026-09-19', NOW)).toBe('2026-09-19T12:00:00.000Z');
+	});
+
+	it('accepts a day a few hours ahead and clamps it to now', () => {
+		const late = Temporal.Instant.from('2026-09-20T22:00:00.000Z');
+		expect(instantFromDay('2026-09-21', late)).toBe('2026-09-20T22:00:00.000Z');
+	});
+
+	it('rejects a day more than a day ahead', () => {
+		expect(instantFromDay('2026-09-22', NOW)).toBeNull();
+	});
+
+	it('rejects malformed and impossible dates', () => {
+		expect(instantFromDay('', NOW)).toBeNull();
+		expect(instantFromDay('hier', NOW)).toBeNull();
+		expect(instantFromDay('2026-02-30', NOW)).toBeNull();
+	});
+});
diff --git a/src/lib/shared/temporal.ts b/src/lib/shared/temporal.ts
index 103f209..6fd085d 100644
--- a/src/lib/shared/temporal.ts
+++ b/src/lib/shared/temporal.ts
@@ -24,3 +24,29 @@ export function formatDayMonthYear(iso: string): string {
 		year: 'numeric',
 	});
 }
+
+const ONE_DAY_MS = 86_400_000;
+
+/**
+ * Stamp to store for a `YYYY-MM-DD` form day: noon UTC — a midnight stamp can
+ * read back as the wrong day in a timezone ahead of UTC. Clamped to `now` when
+ * the day is still ahead of the clock, and null for a malformed day or one
+ * more than a day in the future (timezones ahead of UTC make "today" fuzzy).
+ */
+export function instantFromDay(
+	day: string,
+	now: Temporal.Instant,
+): string | null {
+	let midnight: Temporal.Instant;
+	try {
+		midnight = Temporal.PlainDate.from(day.trim())
+			.toZonedDateTime('UTC')
+			.toInstant();
+	} catch {
+		return null;
+	}
+	const noon = midnight.add({ hours: 12 });
+	if (noon.epochMilliseconds - now.epochMilliseconds > ONE_DAY_MS) return null;
+	const stamp = Temporal.Instant.compare(noon, now) > 0 ? now : noon;
+	return stamp.toString({ smallestUnit: 'millisecond' });
+}