From 012afea5ef2be77995de248c9227c004865e8425 Mon Sep 17 00:00:00 2001
From: Jenny <jennyliu07@gmail.com>
Date: Mon, 22 Jun 2026 22:40:38 +0800
Subject: [PATCH] fix(events): align event timing with Luma EDT start/end
 instants

- Use exact startsAt timestamp for upcoming visibility instead of UTC date string
- Add endsAt field to CortexEvent (CONNEX: 9 AM - 9 PM EDT)
- Show three countdown states: ticking clock, "Happening now", "Event ended"
- Add countdown and upcoming test coverage
---
 skills/context/architecture-context.md        |   2 +-
 skills/context/progress-tracker.md            |   5 +-
 .../header/header-upcoming-event-link.tsx     |   2 +-
 src/components/sections/events-section.tsx    |   8 +-
 .../sections/events/event-countdown.tsx       |  33 ++++--
 src/lib/content/events.ts                     |  10 +-
 src/lib/events/countdown.test.ts              | 111 ++++++++++++++++++
 src/lib/events/countdown.ts                   |  43 +++----
 src/lib/events/upcoming.test.ts               |  97 +++++++++++++++
 src/lib/events/upcoming.ts                    |  13 +-
 10 files changed, 280 insertions(+), 44 deletions(-)
 create mode 100644 src/lib/events/countdown.test.ts
 create mode 100644 src/lib/events/upcoming.test.ts

diff --git a/skills/context/architecture-context.md b/skills/context/architecture-context.md
index c2dc94c..9d33b88 100644
--- a/skills/context/architecture-context.md
+++ b/skills/context/architecture-context.md
@@ -111,7 +111,7 @@ Recommended pattern:
 - no CMS or external content source yet
 - revisit content source later based on team workflow and editing needs
 
-The root layout and homepage route export `revalidate = EVENTS_DATE_REVALIDATE_SECONDS` (3600) from `src/lib/events/upcoming.ts` so date-aware event UI—`HeaderUpcomingEvent` in the site header and `EventsSection` on the homepage—can re-run filtering after event dates pass without a manual rebuild. Event content is still hardcoded TypeScript, so hourly revalidation only refreshes which events are shown—not content from an external source. Events whose `date` is earlier than the current UTC `YYYY-MM-DD` are hidden from the Upcoming Events list; when no upcoming events remain, the Events section renders only its follow-up bridge copy.
+The root layout and homepage route export `revalidate = EVENTS_DATE_REVALIDATE_SECONDS` (3600) from `src/lib/events/upcoming.ts` so date-aware event UI—`HeaderUpcomingEvent` in the site header and `EventsSection` on the homepage—can re-run filtering after event dates pass without a manual rebuild. Event content is still hardcoded TypeScript, so hourly revalidation only refreshes which events are shown—not content from an external source. Each event keeps two machine-readable instants sourced from Luma as UTC: `startsAt` and `endsAt`. Upcoming-event visibility filters by the exact `startsAt` timestamp (events disappear once their start instant passes). The client-side `EventCountdown` ticks every second and shows three states: a countdown clock before start, "Happening now" between `startsAt` and `endsAt`, and "Event ended" after `endsAt`. `dateLabel` remains display copy.
 
 ## Observability
 
diff --git a/skills/context/progress-tracker.md b/skills/context/progress-tracker.md
index e706699..bdd036d 100644
--- a/skills/context/progress-tracker.md
+++ b/skills/context/progress-tracker.md
@@ -101,5 +101,6 @@ All seven homepage sections are built, wired, and animated (scroll-driven entran
 - **Rate-limit IP hardening** — Parses `x-vercel-forwarded-for`, `Forwarded`, IPv4-with-port, bracketed IPv6; **skips loopback** in production-like runtimes. Unknown IP returns `null` identifier; **fail closed** in production (no shared `local` bucket).
 - **Footer hash nav** — `hash-navigation.ts` keeps `#footer` while footer is visible and while focus is in the newsletter/contact region (prevents demotion to `#events` during footer interaction).
 - **Resend re-subscribe** — Reactivates unsubscribed contacts only; reactivated members get success message, not already-submitted.
-- **Tests** — `submit.test.ts`, `turnstile.test.ts`, `rate-limit.test.ts`, `resend.test.ts`.
-- **Verified** — `bun run test`, `bun run typecheck`, `bun run build`. Localhost `#footer` Turnstile submit confirmed against Resend.
+- **Event timing source** — Each event carries two Luma UTC instants: `startsAt` and `endsAt`. Upcoming-event visibility (`getUpcomingEvents`) filters by exact `startsAt` timestamp — events are removed once their start instant passes. The client-side `EventCountdown` uses `getEventTimingState` (discriminated union: `countdown` | `live` | `ended`) to show a ticking clock before start, "Happening now" between start and end, and "Event ended" after `endsAt`. CONNEX: `startsAt` `2026-06-27T13:00:00Z` (9 AM EDT), `endsAt` `2026-06-28T01:00:00Z` (9 PM EDT).
+- **Tests** — `submit.test.ts`, `turnstile.test.ts`, `rate-limit.test.ts`, `resend.test.ts`, `countdown.test.ts`, `upcoming.test.ts`.
+- **Verified** — `bun run test`, `bun run typecheck`, `bun run lint` (existing Monad `_section` warning only), `bun run build`. Localhost `#footer` Turnstile submit confirmed against Resend.
diff --git a/src/components/layout/header/header-upcoming-event-link.tsx b/src/components/layout/header/header-upcoming-event-link.tsx
index 7b2232c..22c5d3b 100644
--- a/src/components/layout/header/header-upcoming-event-link.tsx
+++ b/src/components/layout/header/header-upcoming-event-link.tsx
@@ -24,7 +24,7 @@ export function HeaderUpcomingEventLink({
     <span className="header-upcoming-event-content">
       <span className="header-upcoming-event-pill">{event.label}</span>
       <span className="header-upcoming-event-copy">
-        <time className="header-upcoming-event-date" dateTime={event.date}>
+        <time className="header-upcoming-event-date" dateTime={event.startsAt}>
           {event.dateLabel}
         </time>
         <span className="header-upcoming-event-title">{event.title}</span>
diff --git a/src/components/sections/events-section.tsx b/src/components/sections/events-section.tsx
index f8a7f4e..1a9a34d 100644
--- a/src/components/sections/events-section.tsx
+++ b/src/components/sections/events-section.tsx
@@ -36,7 +36,7 @@ function EventMetaDetails({
 }) {
   return (
     <div className={`event-meta-details${className ? ` ${className}` : ""}`}>
-      <time dateTime={event.date}>{event.dateLabel}</time>
+      <time dateTime={event.startsAt}>{event.dateLabel}</time>
       <span className="event-location">
         <MapPin className="event-location-icon" aria-hidden="true" />
         <span>{event.location.city}</span>
@@ -49,7 +49,11 @@ function EventMeta({ event }: { event: CortexEvent }) {
   return (
     <div className="event-meta">
       <EventMetaDetails className="event-meta-details-inline" event={event} />
-      <EventCountdown className="event-countdown-slot" date={event.date} />
+      <EventCountdown
+        className="event-countdown-slot"
+        startsAt={event.startsAt}
+        endsAt={event.endsAt}
+      />
     </div>
   );
 }
diff --git a/src/components/sections/events/event-countdown.tsx b/src/components/sections/events/event-countdown.tsx
index 2d5a0a4..52566a2 100644
--- a/src/components/sections/events/event-countdown.tsx
+++ b/src/components/sections/events/event-countdown.tsx
@@ -2,15 +2,20 @@
 
 import { useState } from "react";
 import { useOnMount } from "@/hooks/use-on-mount";
-import { getEventCountdownState } from "@/lib/events/countdown";
+import { getEventTimingState } from "@/lib/events/countdown";
 import { cn } from "@/lib/utils";
 
 type EventCountdownProps = {
   className?: string;
-  date: string;
+  startsAt: string;
+  endsAt: string;
 };
 
-export function EventCountdown({ className, date }: EventCountdownProps) {
+export function EventCountdown({
+  className,
+  startsAt,
+  endsAt,
+}: EventCountdownProps) {
   const [now, setNow] = useState<number | null>(null);
 
   useOnMount(() => {
@@ -36,27 +41,39 @@ export function EventCountdown({ className, date }: EventCountdownProps) {
     );
   }
 
-  const countdown = getEventCountdownState(date, now);
+  const timing = getEventTimingState(startsAt, endsAt, now);
 
-  if (!countdown) {
+  if (!timing) {
     return null;
   }
 
+  if (timing.status !== "countdown") {
+    return (
+      <p
+        className={cn("event-countdown", className)}
+        aria-live="polite"
+        aria-atomic="true"
+      >
+        <span className="event-countdown-label">{timing.label}</span>
+      </p>
+    );
+  }
+
   return (
     <p
       className={cn("event-countdown", className)}
       aria-live="polite"
       aria-atomic="true"
     >
-      <span className="event-countdown-label">{countdown.label}</span>
+      <span className="event-countdown-label">{timing.label}</span>
       <span className="event-countdown-separator" aria-hidden="true">
         ·
       </span>
       <time
         className="event-countdown-clock"
-        dateTime={`P${countdown.days}DT${countdown.hours}H${countdown.minutes}M${countdown.seconds}S`}
+        dateTime={`P${timing.days}DT${timing.hours}H${timing.minutes}M${timing.seconds}S`}
       >
-        {countdown.clock}
+        {timing.clock}
       </time>
     </p>
   );
diff --git a/src/lib/content/events.ts b/src/lib/content/events.ts
index e2754d7..4d0c28e 100644
--- a/src/lib/content/events.ts
+++ b/src/lib/content/events.ts
@@ -9,8 +9,11 @@ export type CortexEvent = {
   id: string;
   label: string;
   title: string;
-  /** ISO calendar date (YYYY-MM-DD), interpreted as UTC midnight. */
-  date: string;
+  /** ISO UTC event start instant, sourced from Luma. */
+  startsAt: `${string}T${string}Z`;
+  /** ISO UTC event end instant, sourced from Luma. */
+  endsAt: `${string}T${string}Z`;
+  /** Display label for the event date. */
   dateLabel: string;
   location: EventLocation;
   description: string;
@@ -34,7 +37,8 @@ export const eventsSection = {
       id: "cortex-connex-tech-fest",
       label: "GLOBAL",
       title: "Cortex CONNEX Tech Fest",
-      date: "2026-06-27",
+      startsAt: "2026-06-27T13:00:00Z", // 9:00 AM EDT
+      endsAt: "2026-06-28T01:00:00Z", // 9:00 PM EDT
       dateLabel: "Jun 27, 2026",
       location: {
         city: "Online",
diff --git a/src/lib/events/countdown.test.ts b/src/lib/events/countdown.test.ts
new file mode 100644
index 0000000..59d79c2
--- /dev/null
+++ b/src/lib/events/countdown.test.ts
@@ -0,0 +1,111 @@
+import { describe, expect, test } from "bun:test";
+import { getEventTimingState } from "@/lib/events/countdown";
+
+const STARTS_AT = "2026-06-27T13:00:00Z";
+const ENDS_AT = "2026-06-28T01:00:00Z";
+
+describe("getEventTimingState", () => {
+  test("counts down to the exact start instant", () => {
+    const state = getEventTimingState(
+      STARTS_AT,
+      ENDS_AT,
+      Date.parse("2026-06-27T00:00:00Z"),
+    );
+
+    expect(state).toEqual({
+      status: "countdown",
+      days: 0,
+      hours: 13,
+      minutes: 0,
+      seconds: 0,
+      label: "Today",
+      clock: "13:00:00",
+    });
+  });
+
+  test("shows countdown one minute before start", () => {
+    const state = getEventTimingState(
+      STARTS_AT,
+      ENDS_AT,
+      Date.parse("2026-06-27T12:59:00Z"),
+    );
+
+    expect(state).toEqual({
+      status: "countdown",
+      days: 0,
+      hours: 0,
+      minutes: 1,
+      seconds: 0,
+      label: "Today",
+      clock: "00:01:00",
+    });
+  });
+
+  test("returns live status at the exact start instant", () => {
+    const state = getEventTimingState(
+      STARTS_AT,
+      ENDS_AT,
+      Date.parse("2026-06-27T13:00:00Z"),
+    );
+
+    expect(state).toEqual({ status: "live", label: "Happening now" });
+  });
+
+  test("returns live status during the event", () => {
+    const state = getEventTimingState(
+      STARTS_AT,
+      ENDS_AT,
+      Date.parse("2026-06-27T18:00:00Z"),
+    );
+
+    expect(state).toEqual({ status: "live", label: "Happening now" });
+  });
+
+  test("returns ended status at the exact end instant", () => {
+    const state = getEventTimingState(
+      STARTS_AT,
+      ENDS_AT,
+      Date.parse("2026-06-28T01:00:00Z"),
+    );
+
+    expect(state).toEqual({ status: "ended", label: "Event ended" });
+  });
+
+  test("returns ended status after the event", () => {
+    const state = getEventTimingState(
+      STARTS_AT,
+      ENDS_AT,
+      Date.parse("2026-06-28T05:00:00Z"),
+    );
+
+    expect(state).toEqual({ status: "ended", label: "Event ended" });
+  });
+
+  test("shows days label for multi-day countdown", () => {
+    const state = getEventTimingState(
+      STARTS_AT,
+      ENDS_AT,
+      Date.parse("2026-06-24T13:00:00Z"),
+    );
+
+    expect(state?.status).toBe("countdown");
+    if (state?.status === "countdown") {
+      expect(state.days).toBe(3);
+      expect(state.label).toBe("3 days left");
+    }
+  });
+
+  test("shows singular day label", () => {
+    const state = getEventTimingState(
+      STARTS_AT,
+      ENDS_AT,
+      Date.parse("2026-06-26T13:00:00Z"),
+    );
+
+    expect(state?.status).toBe("countdown");
+    if (state?.status === "countdown") {
+      expect(state.days).toBe(1);
+      expect(state.label).toBe("1 day left");
+    }
+  });
+});
diff --git a/src/lib/events/countdown.ts b/src/lib/events/countdown.ts
index 5f71371..c96b3c1 100644
--- a/src/lib/events/countdown.ts
+++ b/src/lib/events/countdown.ts
@@ -7,6 +7,14 @@ type EventCountdownState = {
   clock: string;
 };
 
+type EventLiveState = {
+  label: "Happening now" | "Event ended";
+};
+
+export type EventTimingState =
+  | (EventCountdownState & { status: "countdown" })
+  | (EventLiveState & { status: "live" | "ended" });
+
 const DAY_MS = 86_400_000;
 const HOUR_MS = 3_600_000;
 const MINUTE_MS = 60_000;
@@ -16,30 +24,24 @@ function padTime(value: number): string {
   return String(value).padStart(2, "0");
 }
 
-/** Calendar date key (YYYY-MM-DD) in UTC for the given instant. */
-export function getUtcDateKey(date: Date): string {
-  const year = date.getUTCFullYear();
-  const month = String(date.getUTCMonth() + 1).padStart(2, "0");
-  const day = String(date.getUTCDate()).padStart(2, "0");
-
-  return `${year}-${month}-${day}`;
-}
-
-/** Midnight UTC on the event's calendar day. Event `date` fields are UTC calendar dates. */
-function getEventTargetTime(date: string): number {
-  return new Date(`${date}T00:00:00Z`).getTime();
-}
-
-export function getEventCountdownState(
-  date: string,
+export function getEventTimingState(
+  startsAt: string,
+  endsAt: string,
   now: number,
-): EventCountdownState | null {
-  const diff = getEventTargetTime(date) - now;
+): EventTimingState | null {
+  const startMs = new Date(startsAt).getTime();
+  const endMs = new Date(endsAt).getTime();
 
-  if (diff <= 0) {
-    return null;
+  if (now >= endMs) {
+    return { status: "ended", label: "Event ended" };
   }
 
+  if (now >= startMs) {
+    return { status: "live", label: "Happening now" };
+  }
+
+  const diff = startMs - now;
+
   const days = Math.floor(diff / DAY_MS);
   const hours = Math.floor((diff % DAY_MS) / HOUR_MS);
   const minutes = Math.floor((diff % HOUR_MS) / MINUTE_MS);
@@ -55,6 +57,7 @@ export function getEventCountdownState(
   }
 
   return {
+    status: "countdown",
     days,
     hours,
     minutes,
diff --git a/src/lib/events/upcoming.test.ts b/src/lib/events/upcoming.test.ts
new file mode 100644
index 0000000..62afa6e
--- /dev/null
+++ b/src/lib/events/upcoming.test.ts
@@ -0,0 +1,97 @@
+import { describe, expect, test } from "bun:test";
+import type { CortexEvent } from "@/lib/content/events";
+import {
+  getNextUpcomingEvent,
+  getUpcomingEvents,
+} from "@/lib/events/upcoming";
+
+function createEvent(id: string, startsAt: `${string}T${string}Z`): CortexEvent {
+  return {
+    id,
+    label: "GLOBAL",
+    title: id,
+    startsAt,
+    endsAt: "2026-06-28T01:00:00Z",
+    dateLabel: "Jun 27, 2026",
+    location: {
+      city: "Online",
+      region: "GLOBAL",
+    },
+    description: "Test event",
+  };
+}
+
+describe("getUpcomingEvents", () => {
+  test("excludes events whose start instant has passed", () => {
+    const now = Date.parse("2026-06-27T13:00:01Z");
+    const upcoming = getUpcomingEvents(
+      [
+        createEvent("past", "2026-06-26T23:00:00Z"),
+        createEvent("just-started", "2026-06-27T13:00:00Z"),
+        createEvent("future", "2026-06-28T13:00:00Z"),
+      ],
+      now,
+    );
+
+    expect(upcoming.map((event) => event.id)).toEqual(["future"]);
+  });
+
+  test("excludes events at the exact start instant", () => {
+    const now = Date.parse("2026-06-27T13:00:00Z");
+    const upcoming = getUpcomingEvents(
+      [createEvent("starting-now", "2026-06-27T13:00:00Z")],
+      now,
+    );
+
+    expect(upcoming).toEqual([]);
+  });
+
+  test("includes events that have not started yet", () => {
+    const now = Date.parse("2026-06-27T12:59:59Z");
+    const upcoming = getUpcomingEvents(
+      [createEvent("almost", "2026-06-27T13:00:00Z")],
+      now,
+    );
+
+    expect(upcoming.map((event) => event.id)).toEqual(["almost"]);
+  });
+
+  test("sorts upcoming events by their exact start instant", () => {
+    const now = Date.parse("2026-06-27T00:00:00Z");
+    const upcoming = getUpcomingEvents(
+      [
+        createEvent("later", "2026-06-27T18:00:00Z"),
+        createEvent("earlier", "2026-06-27T13:00:00Z"),
+      ],
+      now,
+    );
+
+    expect(upcoming.map((event) => event.id)).toEqual(["earlier", "later"]);
+  });
+});
+
+describe("getNextUpcomingEvent", () => {
+  test("returns only the earliest upcoming event for the header promo", () => {
+    const now = Date.parse("2026-06-27T00:00:00Z");
+    const next = getNextUpcomingEvent(
+      [
+        createEvent("later", "2026-06-27T18:00:00Z"),
+        createEvent("earlier", "2026-06-27T13:00:00Z"),
+        createEvent("latest", "2026-06-28T13:00:00Z"),
+      ],
+      now,
+    );
+
+    expect(next?.id).toBe("earlier");
+  });
+
+  test("returns undefined when every event has started", () => {
+    const now = Date.parse("2026-06-27T13:00:00Z");
+    const next = getNextUpcomingEvent(
+      [createEvent("starting-now", "2026-06-27T13:00:00Z")],
+      now,
+    );
+
+    expect(next).toBeUndefined();
+  });
+});
diff --git a/src/lib/events/upcoming.ts b/src/lib/events/upcoming.ts
index 4060cdf..92fb3f7 100644
--- a/src/lib/events/upcoming.ts
+++ b/src/lib/events/upcoming.ts
@@ -1,21 +1,20 @@
 import type { CortexEvent } from "@/lib/content/events";
-import { getUtcDateKey } from "@/lib/events/countdown";
 
-/** Hourly ISR for date-aware event visibility (header promo, Events section). */
+/** Hourly ISR for event visibility (header promo, Events section). */
 export const EVENTS_DATE_REVALIDATE_SECONDS = 3600;
 
 export function getUpcomingEvents(
   events: readonly CortexEvent[],
-  today = getUtcDateKey(new Date()),
+  now = Date.now(),
 ): CortexEvent[] {
   return events
-    .filter((event) => event.date >= today)
-    .sort((a, b) => a.date.localeCompare(b.date));
+    .filter((event) => new Date(event.startsAt).getTime() > now)
+    .sort((a, b) => a.startsAt.localeCompare(b.startsAt));
 }
 
 export function getNextUpcomingEvent(
   events: readonly CortexEvent[],
-  today = getUtcDateKey(new Date()),
+  now = Date.now(),
 ): CortexEvent | undefined {
-  return getUpcomingEvents(events, today)[0];
+  return getUpcomingEvents(events, now)[0];
 }