feat(timeline): add overview mini-map

CLAUDE.md

@@ -139,7 +139,7 @@ In this codebase, it is acceptable and preferred to define helper functions (suc
 
 ## Git Workflow
 
-- **Auto-commit Rule**: For every user message that requests code changes, automatically commit the changes after implementation with an appropriate commit message, if there are no other staged files
+- **Auto-commit Rule**: For every user message that requests code changes, automatically commit the changes after implementation with an appropriate commit message
 
 - never run "supabase db push"
 - don't run supabase db reset

src/hooks/useTimelineScrollSync.ts

@@ -18,9 +18,8 @@ interface UseTimelineScrollSyncOptions {
 
 /**
  * One-way sync between the timeline viewport and the `scrollTo` URL param:
- * URL -> scroll only on mount; user scroll -> URL only (debounced, 5-min
- * rounded, history replace). Never loops. See `jumpToTimelineMoment` for
- * imperative jumps.
+ * URL -> scroll only on mount and via `jumpTo`; user scroll -> URL only
+ * (debounced, 5-min rounded, history replace). Never loops.
  */
 export function useTimelineScrollSync({
   scrollContainerRef,
@@ -33,6 +32,7 @@ export function useTimelineScrollSync({
   const { scrollTo, day } = useSearch({
     from: route,
     select: (search) => ({ scrollTo: search.scrollTo, day: search.day }),
+    structuralSharing: true,
   });
   const navigate = useNavigate({ from: route });
 
@@ -109,4 +109,31 @@ export function useTimelineScrollSync({
       }, SCROLL_DEBOUNCE_MS);
     }
   }, [scrollContainerRef, festivalStart, navigate]);
+
+  function jumpTo(moment: Date) {
+    const container = scrollContainerRef.current;
+    if (!container) return;
+
+    const rounded = roundToNearestMinutes(moment, SCROLL_ROUND_MINUTES);
+    const targetScrollLeft = Math.max(
+      0,
+      timeToOffset(rounded, festivalStart) - container.clientWidth / 2,
+    );
+    // A clamped target (e.g. first-day jump) centers on a different moment
+    // than requested; write the one the viewport actually settles on.
+    const settledMoment = roundToNearestMinutes(
+      offsetToTime(targetScrollLeft + container.clientWidth / 2, festivalStart),
+      SCROLL_ROUND_MINUTES,
+    );
+
+    container.scrollTo({ left: targetScrollLeft, behavior: "smooth" });
+
+    navigate({
+      to: ".",
+      search: (prev) => ({ ...prev, scrollTo: settledMoment.toISOString() }),
+      replace: true,
+    });
+  }
+
+  return { jumpTo };
 }

src/hooks/useTimelineUrlState.ts

@@ -7,13 +7,17 @@ export type TimeFilter = TimelineSearch["time"];
 export function useTimelineUrlState(tab: "timeline" | "list" = "timeline") {
   const route =
     `/festivals/$festivalSlug/editions/$editionSlug/schedule/${tab}` as const;
+  // Select only the filter params this hook exposes, with structural sharing,
+  // so a `scrollTo` write (from scroll syncing) doesn't change this object's
+  // identity and trigger consumers to recompute the filtered schedule.
   const state = useSearch({
     from: route,
     select: (search) => ({
       day: search.day,
       time: search.time,
       stages: search.stages,
     }),
+    structuralSharing: true,
   });
   const navigate = useNavigate({ from: route });
 

src/lib/timeUtils.test.ts

@@ -10,8 +10,7 @@ import {
   convertLocalTimeToUTC,
   getFestivalDayKey,
   getFestivalDayLabel,
-  getFestivalDayParts,
-  areFestivalDaysAdjacent,
+  getFestivalDayShortLabel,
   getFestivalHour,
 } from "./timeUtils";
 
@@ -438,43 +437,22 @@ describe("getFestivalDayLabel", () => {
   });
 });
 
-describe("getFestivalDayParts", () => {
+describe("getFestivalDayShortLabel", () => {
   it("returns null for null input", () => {
-    expect(getFestivalDayParts(null)).toBeNull();
+    expect(getFestivalDayShortLabel(null)).toBeNull();
   });
 
   it("returns null for invalid input", () => {
-    expect(getFestivalDayParts("invalid")).toBeNull();
+    expect(getFestivalDayShortLabel("invalid")).toBeNull();
   });
 
-  it("splits a day-key into weekday and day-of-month", () => {
-    expect(getFestivalDayParts("2024-12-16")).toEqual({
-      weekday: "Mon",
-      dayOfMonth: "16",
-    });
+  it("formats a day-key into a short weekday + date label", () => {
+    expect(getFestivalDayShortLabel("2024-12-16")).toBe("Mon 16");
   });
 
   it("disambiguates repeated weekdays across a multi-weekend festival", () => {
-    expect(getFestivalDayParts("2024-12-13")?.dayOfMonth).toBe("13");
-    expect(getFestivalDayParts("2024-12-20")?.dayOfMonth).toBe("20");
-  });
-});
-
-describe("areFestivalDaysAdjacent", () => {
-  it("is true for consecutive calendar days", () => {
-    expect(areFestivalDaysAdjacent("2024-12-16", "2024-12-17")).toBe(true);
-  });
-
-  it("is true across a month boundary", () => {
-    expect(areFestivalDaysAdjacent("2024-11-30", "2024-12-01")).toBe(true);
-  });
-
-  it("is false across a gap between festival weekends", () => {
-    expect(areFestivalDaysAdjacent("2024-12-19", "2024-12-23")).toBe(false);
-  });
-
-  it("is false for invalid input", () => {
-    expect(areFestivalDaysAdjacent("invalid", "2024-12-17")).toBe(false);
+    expect(getFestivalDayShortLabel("2024-12-13")).toBe("Fri 13");
+    expect(getFestivalDayShortLabel("2024-12-20")).toBe("Fri 20");
   });
 });
 
@@ -494,7 +472,10 @@ describe("getFestivalHour", () => {
 
   it("is independent of the machine's local zone", () => {
     const lisbon = getFestivalHour("2024-07-15T23:30:00Z", "Europe/Lisbon");
-    const newYork = getFestivalHour("2024-07-15T23:30:00Z", "America/New_York");
+    const newYork = getFestivalHour(
+      "2024-07-15T23:30:00Z",
+      "America/New_York",
+    );
     expect(lisbon).toBe(0);
     expect(newYork).toBe(19);
   });

src/lib/timeUtils.ts

@@ -1,10 +1,4 @@
-import {
-  format,
-  isValid,
-  parseISO,
-  isSameDay,
-  differenceInCalendarDays,
-} from "date-fns";
+import { format, isValid, parseISO, isSameDay } from "date-fns";
 import { formatInTimeZone, fromZonedTime, toZonedTime } from "date-fns-tz";
 
 export function formatTimeRange(
@@ -200,26 +194,13 @@ export function getFestivalDayLabel(dayKey: string | null): string | null {
   return format(date, "EEEE, MMM d");
 }
 
-// The two halves of a day-jump label, rendered as a stacked pair.
-export function getFestivalDayParts(
-  dayKey: string | null,
-): { weekday: string; dayOfMonth: string } | null {
+// Short weekday + date label, e.g. "Thu 13"; the date disambiguates repeated
+// weekday names at multi-weekend festivals.
+export function getFestivalDayShortLabel(dayKey: string | null): string | null {
   if (!dayKey) return null;
   const date = parseISO(dayKey);
   if (!isValid(date)) return null;
-  return { weekday: format(date, "EEE"), dayOfMonth: format(date, "d") };
-}
-
-// True when two day keys are calendar-adjacent. A false result marks a break in
-// the festival's run, which the day rail renders as a divider.
-export function areFestivalDaysAdjacent(
-  earlierDayKey: string,
-  laterDayKey: string,
-): boolean {
-  const earlier = parseISO(earlierDayKey);
-  const later = parseISO(laterDayKey);
-  if (!isValid(earlier) || !isValid(later)) return false;
-  return differenceInCalendarDays(later, earlier) === 1;
+  return format(date, "EEE d");
 }
 
 // The wall-clock hour (0-23) a UTC timestamp falls on in the festival's