Manual timezone is the single source of local-time truth (task 7e173881) (#285)

Co-authored-by: dev_agent <dev_agent@cubecraftlabs.com>
Co-committed-by: dev_agent <dev_agent@cubecraftlabs.com>

admin/src/history/HistoryTab.test.tsx

@@ -5,6 +5,7 @@ import type { HistoryFilter, HistoryRow } from "../api/history";
 import { storeTokens } from "../auth/oidc";
 import { TransitionsProvider } from "../api/useTransitions";
 import { frame, testStream, type TestStream } from "../api/testStream";
+import { AppTimezoneProvider } from "../time/AppTimezone";
 
 const TODAY = "2026-09-23";
 
@@ -629,3 +630,117 @@ describe("HistoryTab live updates", () => {
     expect(screen.getAllByTestId("history-row")).toHaveLength(ROWS.all.length);
   });
 });
+
+describe("HistoryTab in the stored application timezone", () => {
+  // 13:00 UTC on Sep 23 is 01:00 on Sep 24 in Auckland (NZST, UTC+12).
+  const NOW = new Date("2026-09-23T13:00:00Z");
+  // Due 00:10 Auckland on Sep 24, done 00:30 Auckland (12:30 UTC on Sep 23).
+  const LATE_NZ = row({
+    instance_id: 7,
+    quest_title: "Feed cat",
+    due_date: "2026-09-24",
+    due_time: "00:10",
+    occurred_at: "2026-09-23T12:30:00Z",
+    was_on_time: false,
+  });
+  // 22:00 Auckland on Sep 23; 10:00 UTC.
+  const EVENING_NZ = row({ instance_id: 8, occurred_at: "2026-09-23T10:00:00Z" });
+
+  let fetchMock: ReturnType<typeof vi.fn>;
+
+  function historyRequests(): URL[] {
+    return fetchMock.mock.calls
+      .map(([url]) => new URL(String(url), "http://x"))
+      .filter((url) => url.pathname === "/api/v1/admin/history");
+  }
+
+  async function renderWithZone(timezone: string, effective_timezone = timezone) {
+    fetchMock = vi.fn((url: string) => {
+      const parsed = new URL(url, "http://x");
+      if (parsed.pathname.endsWith("/api/v1/admin/settings")) {
+        return Promise.resolve(jsonResponse({ timezone, effective_timezone }));
+      }
+      const filter = parsed.searchParams.get("filter");
+      const rows = filter === "all" ? [EVENING_NZ, LATE_NZ] : [];
+      return Promise.resolve(
+        jsonResponse({
+          filter,
+          start: parsed.searchParams.get("start"),
+          end: parsed.searchParams.get("end"),
+          count: rows.length,
+          rows,
+        }),
+      );
+    });
+    vi.stubGlobal("fetch", fetchMock);
+    render(
+      <AppTimezoneProvider>
+        <HistoryTab />
+      </AppTimezoneProvider>,
+    );
+    await screen.findByTestId("stat-on-time");
+  }
+
+  function times(section: HTMLElement): string[] {
+    return Array.from(section.querySelectorAll(".history-event-time")).map(
+      (el) => el.textContent ?? "",
+    );
+  }
+
+  beforeAll(() => {
+    vi.stubEnv("TZ", "UTC");
+  });
+
+  afterAll(() => {
+    vi.unstubAllEnvs();
+  });
+
+  beforeEach(() => {
+    sessionStorage.clear();
+    storeTokens({ access_token: "at-123", expires_in: 600 });
+    vi.useFakeTimers({ toFake: ["Date"], now: NOW });
+  });
+
+  afterEach(() => {
+    cleanup();
+    vi.useRealTimers();
+    vi.unstubAllGlobals();
+  });
+
+  it.each([
+    ["the stored zone", "Pacific/Auckland"],
+    ["the API host's published zone when none is stored", ""],
+  ])("today, day grouping, clock and lateness follow %s", async (_label, stored) => {
+    await renderWithZone(stored, "Pacific/Auckland");
+
+    for (const url of historyRequests()) {
+      expect(url.searchParams.get("end")).toBe("2026-09-24");
+      expect(url.searchParams.get("start")).toBe("2026-09-11");
+    }
+    const today = screen.getByTestId("day-2026-09-24");
+    expect(within(today).getByText("Today")).toBeTruthy();
+    expect(times(today)).toEqual(["12:30 AM"]);
+    expect(metas(today)).toEqual(["completed · panel (Declan) · late 20 min"]);
+
+    const yesterday = screen.getByTestId("day-2026-09-23");
+    expect(within(yesterday).getByText("Yesterday")).toBeTruthy();
+    expect(times(yesterday)).toEqual(["10:00 PM"]);
+  });
+
+  it("only an API that publishes no zone leaves the browser's local day and clock", async () => {
+    await renderWithZone("", "");
+
+    for (const url of historyRequests()) {
+      expect(url.searchParams.get("end")).toBe("2026-09-23");
+    }
+    expect(screen.queryByTestId("day-2026-09-24")).toBeNull();
+    const today = screen.getByTestId("day-2026-09-23");
+    expect(within(today).getByText("Today")).toBeTruthy();
+    expect(times(today)).toEqual(["12:30 PM", "10:00 AM"]);
+    // Due 00:10 UTC on Sep 24 is after the 12:30 UTC completion: no minutes.
+    expect(metas(today)).toEqual([
+      "completed · panel (Declan) · late",
+      "completed · panel (Declan) · on time",
+    ]);
+  });
+});

admin/src/history/HistoryTab.tsx

@@ -9,9 +9,10 @@ import { ApiForbiddenError } from "../api/client";
 import type { TransitionEvent } from "../api/events";
 import { useTransitions } from "../api/useTransitions";
 import { exportHistoryCsv, fetchHistory, type HistoryFilter, type HistoryRow } from "../api/history";
-import { localTodayIso } from "../schedule/cycle";
 import { dayLabel, groupByDay, rowMeta, rowTime, shiftIso } from "./format";
 import { DownloadGlyph, LockGlyph } from "./glyphs";
+import { useAppTimezone } from "../time/AppTimezone";
+import { todayIn } from "../time/zone";
 import "./HistoryTab.css";
 
 /** ADMIN-SPEC §1: every scroll column ends with 92px so content clears the tab bar. */
@@ -129,7 +130,7 @@ function StatRow({ stats }: { stats: HistoryStats }) {
   );
 }
 
-function EventRow({ row }: { row: HistoryRow }) {
+function EventRow({ row, timeZone }: { row: HistoryRow; timeZone: string }) {
   return (
     <li className="history-event" data-testid="history-row">
       <span
@@ -142,10 +143,10 @@ function EventRow({ row }: { row: HistoryRow }) {
           {row.quest_title} · {row.child_name}
         </div>
         <div className="history-event-meta" data-testid="history-meta">
-          {rowMeta(row)}
+          {rowMeta(row, timeZone)}
         </div>
       </div>
-      <span className="history-event-time">{rowTime(row)}</span>
+      <span className="history-event-time">{rowTime(row, timeZone)}</span>
     </li>
   );
 }
@@ -161,7 +162,10 @@ function FooterNote() {
   );
 }
 
-export default function HistoryTab({ today = localTodayIso() }: { today?: string }) {
+/** `today` ("YYYY-MM-DD") defaults to today in the application timezone. */
+export default function HistoryTab({ today: todayProp }: { today?: string }) {
+  const timeZone = useAppTimezone();
+  const today = todayProp ?? todayIn(timeZone);
   const [filter, setFilter] = useState<HistoryFilter>("all");
   const [state, setState] = useState<LoadState>({ kind: "loading" });
   const [attempt, setAttempt] = useState(0);
@@ -244,7 +248,7 @@ export default function HistoryTab({ today = localTodayIso() }: { today?: string
       </div>
     );
   } else {
-    const groups = groupByDay(shown.data.rows);
+    const groups = groupByDay(shown.data.rows, timeZone);
     body =
       groups.length > 0 ? (
         groups.map((group) => (
@@ -252,7 +256,7 @@ export default function HistoryTab({ today = localTodayIso() }: { today?: string
             <h3 className="history-section-label">{dayLabel(group.day, today)}</h3>
             <ul className="history-card history-list">
               {group.rows.map((row, index) => (
-                <EventRow key={`${row.instance_id}-${row.event_type}-${row.occurred_at ?? ""}-${index}`} row={row} />
+                <EventRow key={`${row.instance_id}-${row.event_type}-${row.occurred_at ?? ""}-${index}`} row={row} timeZone={timeZone} />
               ))}
             </ul>
           </section>

admin/src/history/format.ts

@@ -4,12 +4,13 @@
  * Calendar dates ("YYYY-MM-DD") are handled by their components (never
  * `new Date("YYYY-MM-DD")`, which is UTC midnight and reads as the previous
  * day in negative-offset zones); event stamps are UTC and shown in the
- * viewer's local time.
+ * application timezone (`timeZone`: the stored IANA zone, "" = browser).
  */
 import type { HistoryRow } from "../api/history";
-import { dayNumber, isoFromDayNumber, localTodayIso } from "../schedule/cycle";
+import { dayNumber, isoFromDayNumber } from "../schedule/cycle";
 import { shortDate } from "../schedule/format";
 import { formatClockTime, formatDueTime } from "../today/format";
+import { isoDateIn, wallClockInstant } from "../time/zone";
 
 const MS_PER_MINUTE = 60_000;
 
@@ -19,25 +20,21 @@ export function shiftIso(iso: string, days: number): string {
 }
 
 /** The local calendar day an event belongs to (due_date for missed rows). */
-export function rowDay(row: HistoryRow): string {
-  return row.occurred_at ? localTodayIso(new Date(row.occurred_at)) : row.due_date;
+export function rowDay(row: HistoryRow, timeZone: string): string {
+  return row.occurred_at ? isoDateIn(new Date(row.occurred_at), timeZone) : row.due_date;
 }
 
-/** The row's due moment as local wall-clock time, or null without a due time. */
-function dueMoment(row: HistoryRow): Date | null {
+/** The row's due moment (epoch ms) as local wall-clock time, or null without a due time. */
+function dueMoment(row: HistoryRow, timeZone: string): number | null {
   const match = /^(\d{2}):(\d{2})/.exec(row.due_time ?? "");
   if (!match) return null;
-  const [year, month, day] = row.due_date.split("-").map(Number);
-  return new Date(year, month - 1, day, Number(match[1]), Number(match[2]));
+  return wallClockInstant(row.due_date, Number(match[1]), Number(match[2]), timeZone);
 }
 
 /** Newest first; a missed row sorts at its due moment (or the end of its day). */
-function sortKey(row: HistoryRow): number {
+function sortKey(row: HistoryRow, timeZone: string): number {
   if (row.occurred_at) return Date.parse(row.occurred_at);
-  const due = dueMoment(row);
-  if (due) return due.getTime();
-  const [year, month, day] = row.due_date.split("-").map(Number);
-  return new Date(year, month - 1, day, 23, 59).getTime();
+  return dueMoment(row, timeZone) ?? wallClockInstant(row.due_date, 23, 59, timeZone);
 }
 
 export interface DayGroup {
@@ -46,10 +43,10 @@ export interface DayGroup {
 }
 
 /** Rows grouped by day, newest day first and newest row first within a day. */
-export function groupByDay(rows: HistoryRow[]): DayGroup[] {
+export function groupByDay(rows: HistoryRow[], timeZone: string): DayGroup[] {
   const groups = new Map<string, HistoryRow[]>();
   for (const row of rows) {
-    const day = rowDay(row);
+    const day = rowDay(row, timeZone);
     groups.set(day, [...(groups.get(day) ?? []), row]);
   }
   return [...groups.entries()]
@@ -57,7 +54,7 @@ export function groupByDay(rows: HistoryRow[]): DayGroup[] {
     .map(([day, dayRows]) => ({
       day,
       // Stable sort: rows at the same moment keep the API's append order.
-      rows: [...dayRows].sort((a, b) => sortKey(b) - sortKey(a)),
+      rows: [...dayRows].sort((a, b) => sortKey(b, timeZone) - sortKey(a, timeZone)),
     }));
 }
 
@@ -72,23 +69,23 @@ export function dayLabel(day: string, today: string): string {
 }
 
 /** "on time", "late 22 min", or "late" when the lateness is not derivable. */
-function onTimeFlag(row: HistoryRow): string | null {
+function onTimeFlag(row: HistoryRow, timeZone: string): string | null {
   if (row.event_type !== "completed" || row.was_on_time === null) return null;
   if (row.was_on_time) return "on time";
-  const due = dueMoment(row);
-  if (!due || !row.occurred_at) return "late";
-  const minutes = Math.round((Date.parse(row.occurred_at) - due.getTime()) / MS_PER_MINUTE);
+  const due = dueMoment(row, timeZone);
+  if (due === null || !row.occurred_at) return "late";
+  const minutes = Math.round((Date.parse(row.occurred_at) - due) / MS_PER_MINUTE);
   return minutes > 0 ? `late ${minutes} min` : "late";
 }
 
 /** `<event type> · <actor>` plus the on-time flag for completions. */
-export function rowMeta(row: HistoryRow): string {
-  const flag = onTimeFlag(row);
+export function rowMeta(row: HistoryRow, timeZone: string): string {
+  const flag = onTimeFlag(row, timeZone);
   return [row.event_type, row.actor, flag].filter(Boolean).join(" · ");
 }
 
 /** The event's local clock time; a missed row shows its due time, if any. */
-export function rowTime(row: HistoryRow): string {
-  if (row.occurred_at) return formatClockTime(row.occurred_at);
+export function rowTime(row: HistoryRow, timeZone: string): string {
+  if (row.occurred_at) return formatClockTime(row.occurred_at, timeZone);
   return row.due_time ? formatDueTime(row.due_time) : "";
 }