# Phase 2: Calendar Display - Research

**Researched:** 2026-06-04
**Domain:** React PWA calendar rendering · CalDAV recurrence expansion · Timezone/DST correctness · CSS token theming
**Confidence:** HIGH (locked stack verified against live codebase and official docs)

---

<user_constraints>
## User Constraints (from CONTEXT.md)

### Locked Decisions

- **D-01:** Design-token layer — color, spacing, density, typography as CSS custom properties + TypeScript token object. No hard-coded colors/spacing in components.
- **D-02:** Ship only the "clean" theme in Phase 2. Token architecture must make a future kiosk theme a token-set swap, not a refactor.
- **D-03:** Clean theme is tuned for legibility at tablet distance (information density first-class).
- **D-04:** All four views: day, week, month, agenda.
- **D-05:** Device-adaptive default: phone → Agenda; tablet/desktop → Month. Persist last-used view per device.
- **D-06:** Per-member color fill from `users.color` (6-color palette). Shared-family calendar uses `#F25C7A`.
- **D-07:** Color legend always visible. Per-member show/hide filter deferred.
- **D-08:** Informational + tap-to-expand. Month = colored bars with title. EventDetailPopover is read-only in Phase 2 but must be reusable as Phase 3 edit surface.
- **D-09:** Recurring events expanded server-side. Client renders concrete occurrences.
- **D-10:** Single local timezone for v1. All-day events render with no date shift (D-13 schema already splits allDay/timed).
- **Calendar rendering library:** Schedule-X (`@schedule-x/react` + `@schedule-x/calendar`) — selected by UI-SPEC. CSS token override strategy documented there.
- **Week start day:** Sunday (WEEK_START_DAY = 0). `calendarConfig.ts` constant.
- **TanStack Query = server state; Zustand = UI state.** Server events never enter Zustand.
- **Broker boundary:** Routes never call tsdav. `/api/events` reads MariaDB cache only.

### Claude's Discretion

- Skeleton/loading states: build polished versions.
- Dev-auth bypass: documented env-flagged middleware injecting a fixed dev user. Must be off by default and impossible in production builds.

### Deferred Ideas (OUT OF SCOPE)

- Tablet/wall-display kiosk mode + Skylight display theme + runtime theme-switcher UI (v2).
- Per-member show/hide filter (add when membership > 2).
- Secondary timezone display toggle (v1.x).
- Single-occurrence / "this and following" recurring edits (v1.x).
</user_constraints>

---

<phase_requirements>
## Phase Requirements

| ID | Description | Research Support |
|----|-------------|------------------|
| CAL-02 | User sees a unified, color-coded calendar that aggregates every accessible calendar into one view | §Backend: /api/events evolution; §Frontend: Schedule-X calendars config with per-calendar lightColors |
| CAL-03 | User can switch between week, month, day, and agenda/list views | §Schedule-X Views; all four views confirmed in @schedule-x/calendar v4.6.0 |
| CAL-07 | User can create a recurring event and see all its occurrences expanded correctly (display portion only — creation is Phase 3) | §Recurrence expansion pipeline; §DST correctness; §All-day event handling |
</phase_requirements>

---

## Summary

Phase 2 is a read-only calendar display layer built on top of the Phase 1 broker and schema. The backend work is evolving `/api/events` from a raw table dump to a display-ready shape: a windowed query that joins `calendarEvents → calendars → users.color`, expands recurring events via `ICAL.RecurExpansion`, and serializes concrete occurrences as JSON. The frontend work is building a React calendar shell around Schedule-X, wiring TanStack Query to the windowed endpoint, and implementing the CSS token layer.

The hardest technical areas are (1) the recurrence expansion pipeline — specifically extracting and registering VTIMEZONE components before calling `ICAL.RecurExpansion` so DST boundaries produce correct wall-clock times — and (2) the Schedule-X v4 event format, which requires `Temporal.ZonedDateTime` and `Temporal.PlainDate` objects rather than ISO strings. The server returns JSON; the frontend must hydrate those strings into Temporal objects before passing them to Schedule-X. Both conversions have well-known pitfall patterns documented below.

All-day event correctness is already partially solved by the D-13 schema split (Phase 1): `allDay=true` events have a `dtstartDate` DATE column with no time component. The API must pass `Temporal.PlainDate` for these, not a `Temporal.ZonedDateTime` derived from midnight UTC, or Schedule-X will shift the date.

**Primary recommendation:** Expand recurrences on the server using `ICAL.RecurExpansion` with registered VTIMEZONE, serialize occurrences as plain ISO date strings in JSON, and hydrate to Temporal objects in the React client layer before feeding Schedule-X.

---

## Architectural Responsibility Map

| Capability | Primary Tier | Secondary Tier | Rationale |
|------------|-------------|----------------|-----------|
| Event storage and polling | API / Backend | — | Phase 1 broker owns all Fastmail I/O; routes read MariaDB cache |
| Recurrence expansion | API / Backend | — | Server expands to concrete occurrences for the requested window; client renders, never expands (D-09) |
| All-day / timed discrimination | API / Backend | — | D-13 schema split already done in Phase 1; route must preserve and expose the distinction |
| Color and ownership join | API / Backend | — | `calendars.userId → users.color` join lives closest to the data; frontend just reads the color hex |
| Temporal object construction | Frontend (PWA) | — | Server sends plain strings; client converts to `Temporal.ZonedDateTime` / `Temporal.PlainDate` before Schedule-X |
| Calendar rendering (views) | Frontend (PWA) | — | Schedule-X renders day/week/month/agenda in the browser |
| Token layer / theming | Frontend (PWA) | — | CSS custom properties + TS token object; Schedule-X `--sx-color-*` vars overridden |
| View state, selected date, open popover | Frontend (PWA) — Zustand | — | UI-only state; never server data |
| Event list caching and re-fetch | Frontend (PWA) — TanStack Query | — | Cache key = `['events', start, end]`; invalidated on range change |
| Dev-auth bypass | API / Backend | — | Env-flagged middleware injecting fixed user; never active in production |

---

## Standard Stack

### Core (all versions verified against npm registry 2026-06-04)

| Library | Version | Purpose | Why Standard |
|---------|---------|---------|--------------|
| `@schedule-x/calendar` | 4.6.0 | Calendar engine (views, Temporal-based event model) | Selected in UI-SPEC; active maintenance; last published 2026-05-12 |
| `@schedule-x/react` | 4.1.0 | React adapter (`useCalendarApp`, `ScheduleXCalendar`) | Official React adapter; peer-requires `@schedule-x/calendar ^3.1.0 \|\| ^4.0.0`; 4.6.0 satisfies this |
| `@schedule-x/theme-default` | 4.6.0 | Default CSS layout; overridden by project tokens | Required for Schedule-X internal layout engine; all colors are token-overridden |
| `@schedule-x/event-modal` | 4.6.0 | `createEventModalPlugin()` for custom `eventModal` component | Required to replace default modal with `EventDetailPopover` |
| `@schedule-x/events-service` | 4.6.0 | `createEventsServicePlugin()` for dynamic event updates | Required to update events after TanStack Query fetches new window |
| `temporal-polyfill` | 0.3.2 | `Temporal` global polyfill for browsers without native support | `@schedule-x/calendar` peer-requires `temporal-polyfill@0.3.0`; 0.3.2 satisfies |
| `lucide-react` | 1.17.0 | Icon library (CalendarDays, X, MapPin, ChevronLeft/Right) | Specified in UI-SPEC; tree-shakeable; active maintenance |
| `ical.js` | 2.2.1 | VEVENT parse + `ICAL.RecurExpansion` for recurrence | Already in both `apps/api` and `apps/pwa`; Phase 1 pattern established |
| `rrule` | 2.8.1 | RRULE string parsing (used only if `ICAL.RecurExpansion` is insufficient) | Already in project stack per CLAUDE.md; last pub 2023-11-10 — treat as stable |

### No New Backend Dependencies Needed

Phase 1 already installed all required API packages: `ical.js`, `hono`, `drizzle-orm`, `mysql2`, `zod`. The recurrence expansion work (`ICAL.RecurExpansion`) uses ical.js already present. No new API npm packages are required.

### Installation (PWA only)

```bash
cd apps/pwa
pnpm add @schedule-x/calendar@4.6.0 @schedule-x/react@4.1.0 @schedule-x/theme-default@4.6.0 @schedule-x/event-modal@4.6.0 @schedule-x/events-service@4.6.0 temporal-polyfill@0.3.2 lucide-react@1.17.0
```

**Note on version mismatch:** `@schedule-x/react` tops out at 4.1.0 (last published 2026-01-21) while `@schedule-x/calendar` is at 4.6.0 (2026-05-12). The React adapter peer-depends on `^3.1.0 || ^4.0.0` for `@schedule-x/calendar` — 4.6.0 satisfies `^4.0.0`. They are **compatible**. [VERIFIED: npm registry]

**Note on `firstDayOfWeek`:** Schedule-X v4 uses Temporal numbering where `7 = Sunday`, NOT `0 = Sunday`. [VERIFIED: schedule-x.dev/docs/calendar/configuration]. The UI-SPEC sets `WEEK_START_DAY = 0` as a constant — the constant must be converted: pass `7` to Schedule-X when the constant is `0`. Document this translation in `calendarConfig.ts`.

---

## Package Legitimacy Audit

slopcheck was not available at research time. All packages below were verified via official documentation or established source repos. No packages flagged as suspicious by manual review.

| Package | Registry | Age | Source Repo | Postinstall | Disposition |
|---------|----------|-----|-------------|-------------|-------------|
| `@schedule-x/calendar` | npm | 2+ yrs | github.com/schedule-x/schedule-x | none | Approved |
| `@schedule-x/react` | npm | 2+ yrs | github.com/schedule-x/react | none | Approved |
| `@schedule-x/theme-default` | npm | 2+ yrs | github.com/schedule-x/schedule-x | none | Approved |
| `@schedule-x/event-modal` | npm | 2+ yrs | github.com/schedule-x/schedule-x | none | Approved |
| `@schedule-x/events-service` | npm | 2+ yrs | github.com/schedule-x/schedule-x | none | Approved |
| `temporal-polyfill` | npm | 2+ yrs | github.com/fullcalendar/temporal-polyfill | none | Approved |
| `lucide-react` | npm | 4+ yrs | github.com/lucide-icons/lucide | none | Approved |

**Packages removed due to slopcheck [SLOP] verdict:** none
**Packages flagged as suspicious [SUS]:** none

*slopcheck was unavailable at research time. All packages are tagged [VERIFIED: npm registry] based on official source repos confirmed via npm view. Planner should add `checkpoint:human-verify` before install if extra caution is warranted — this two-person household app is self-hosted with no third-party attack surface for these well-established packages.*

---

## Architecture Patterns

### System Architecture Diagram

```
Fastmail CalDAV
      │
      ▼
  [Broker Poller] ──5min ctag──▶ [MariaDB: calendarEvents]
                                         │
                                         ▼
                              [GET /api/events?start=&end=]
                                    ┌────┴────┐
                                    │ Window  │
                                    │ filter  │
                                    │ (SQL)   │
                                    └────┬────┘
                                         │  rawVevent rows + calendar.userId + users.color
                                         ▼
                               [expandOccurrences()]
                               ┌─────────────────────┐
                               │ ICAL.parse(rawVevent) │
                               │ ICAL.RecurExpansion   │
                               │ VTIMEZONE register    │
                               │ EXDATE filter         │
                               │ allDay / timed split  │
                               └──────────┬────────────┘
                                          │  JSON: CalendarOccurrence[]
                                          ▼
                              [TanStack Query: ['events', start, end]]
                                          │
                                          ▼
                              [hydrateEvents()] ← converts ISO→Temporal
                                          │
                                          ▼
                              [Schedule-X eventsService.set()]
                                          │
                              ┌───────────┴────────────┐
                              │   ScheduleXCalendar     │
                              │  Day | Week | Month |   │
                              │  Agenda                 │
                              └────────────────────────-┘
                                          │
                                          ▼
                              [EventDetailPopover] (custom eventModal)
```

### Recommended Project Structure

```
apps/
├── api/src/
│   ├── routes/
│   │   └── events.ts            ← evolve: windowed query + expansion
│   └── broker/
│       └── expand.ts            ← new: expandOccurrences() helper
└── pwa/src/
    ├── styles/
    │   ├── tokens.css            ← CSS custom properties (clean theme)
    │   ├── tokens.ts             ← TypeScript token object
    │   └── index.css             ← imports tokens.css + global resets
    ├── lib/
    │   ├── calendarConfig.ts     ← WEEK_START_DAY + Schedule-X config factory
    │   └── colorUtils.ts         ← derive container/onContainer from main hex
    ├── components/
    │   ├── CalendarShell.tsx     ← layout: AppNav + ViewToolbar + ColorLegend + SX
    │   ├── AppNav.tsx
    │   ├── ViewToolbar.tsx
    │   ├── ColorLegend.tsx
    │   ├── EventDetailPopover.tsx ← read-only; Phase 3 adds edit actions in footer
    │   └── SkeletonCalendar.tsx
    ├── store/
    │   └── calendarStore.ts      ← Zustand: selectedView, selectedDate, openEventId, calendarRange
    └── api/
        └── client.ts             ← extend with fetchEvents(start, end)
```

### Pattern 1: `/api/events` Windowed Query with Expansion

**What:** `GET /api/events?start=2026-06-01&end=2026-07-01` returns a flat array of concrete occurrences (no recurring master events, no raw VCALENDAR blobs). Each occurrence has all fields the UI needs: title, start (ISO string), end (ISO string), allDay, color, calendarId, calendarName, uid, occurrenceId (uid + dtstart for identity), location, description.

**Server implementation shape:**

```typescript
// apps/api/src/broker/expand.ts
// Source: https://github.com/kewisch/ical.js/wiki/Common-Use-Cases
import ICAL from 'ical.js'

export interface CalendarOccurrence {
  id: string          // `${uid}::${dtstart_iso}` — stable identity for Schedule-X
  uid: string
  calendarId: number
  calendarName: string
  ownerUserId: number
  color: string       // hex from users.color or shared-family constant
  isShared: boolean   // true when calendar is the shared-family calendar
  title: string
  start: string       // ISO 8601 with timezone offset: '2026-06-15T10:00:00+02:00[America/Toronto]'
                      // for all-day: 'DATE:2026-06-15' — use a distinct format so client knows
  end: string
  allDay: boolean
  location: string | null
  description: string | null
}

export function expandOccurrences(
  rawVevent: string,
  windowStart: Date,
  windowEnd: Date,
  calendarId: number,
  calendarName: string,
  ownerUserId: number,
  color: string,
  isShared: boolean,
): CalendarOccurrence[] {
  const parsed = ICAL.parse(rawVevent)
  const comp = new ICAL.Component(parsed)

  // CRITICAL: Register VTIMEZONE components before RecurExpansion
  // Without this, RecurExpansion uses UTC and DST transitions produce wrong wall-clock times
  for (const vtimezone of comp.getAllSubcomponents('vtimezone')) {
    const tzid = vtimezone.getFirstPropertyValue('tzid') as string
    if (tzid && !ICAL.TimezoneService.has(tzid)) {
      ICAL.TimezoneService.register(tzid, new ICAL.Timezone({ component: vtimezone, tzid }))
    }
  }

  const vevent = comp.getFirstSubcomponent('vevent')
  if (!vevent) return []

  const event = new ICAL.Event(vevent)
  const dtstart = vevent.getFirstPropertyValue('dtstart') as ICAL.Time
  const uid = event.uid

  // Non-recurring event: single occurrence check
  if (!event.isRecurring()) {
    // ... check if within window, return single occurrence
  }

  // Recurring event: use RecurExpansion
  const expand = new ICAL.RecurExpansion({ component: vevent, dtstart })
  const rangeStart = ICAL.Time.fromJSDate(windowStart, /* useUtc */ false)
  const rangeEnd = ICAL.Time.fromJSDate(windowEnd, /* useUtc */ false)

  const occurrences: CalendarOccurrence[] = []
  let next: ICAL.Time | null

  while ((next = expand.next()) && next.compare(rangeEnd) < 0) {
    if (next.compare(rangeStart) < 0) continue
    // Build occurrence, compute end from duration
    // ...
  }
  return occurrences
}
```

**Key insight:** `ICAL.RecurExpansion` handles EXDATE exclusions internally — you do not need to extract and compare EXDATEs manually when using the high-level API. [CITED: github.com/kewisch/ical.js/wiki/Common-Use-Cases]

### Pattern 2: Schedule-X Event Format (Temporal, not ISO strings)

**What:** Schedule-X v4 requires `Temporal.ZonedDateTime` for timed events and `Temporal.PlainDate` for all-day events. The backend returns ISO strings; the client hydrates them.

**Critical finding:** Schedule-X v3 changed from the old `"2024-01-15 09:00"` ISO string format to Temporal objects. v4 continues this. You cannot pass plain strings. [VERIFIED: schedule-x.dev/blog/schedule-x-v3-temporal-api]

```typescript
// apps/pwa/src/lib/hydrateEvents.ts
// Source: https://schedule-x.dev/docs/calendar/events
import 'temporal-polyfill/global'  // registers Temporal on globalThis
import type { CalendarOccurrence } from '@familysync/shared'  // server type

export interface ScheduleXEvent {
  id: string
  title: string
  start: Temporal.ZonedDateTime | Temporal.PlainDate
  end: Temporal.ZonedDateTime | Temporal.PlainDate
  calendarId: string  // must be string matching the key in calendars config
  location?: string
  description?: string
  // custom business fields pass through
  _familySync?: { uid: string; color: string; isShared: boolean }
}

export function hydrateEvents(occurrences: CalendarOccurrence[]): ScheduleXEvent[] {
  return occurrences.map((occ) => {
    if (occ.allDay) {
      // All-day: use PlainDate — do NOT construct ZonedDateTime from midnight UTC
      return {
        id: occ.id,
        title: occ.title,
        start: Temporal.PlainDate.from(occ.start),  // occ.start is 'YYYY-MM-DD'
        end: Temporal.PlainDate.from(occ.end),
        calendarId: String(occ.calendarId),
        _familySync: { uid: occ.uid, color: occ.color, isShared: occ.isShared },
      }
    }
    // Timed: use ZonedDateTime from the offset-aware ISO string the server returns
    return {
      id: occ.id,
      title: occ.title,
      start: Temporal.ZonedDateTime.from(occ.start),
      end: Temporal.ZonedDateTime.from(occ.end),
      calendarId: String(occ.calendarId),
      location: occ.location ?? undefined,
      description: occ.description ?? undefined,
      _familySync: { uid: occ.uid, color: occ.color, isShared: occ.isShared },
    }
  })
}
```

### Pattern 3: Schedule-X Calendar Configuration

```typescript
// apps/pwa/src/lib/calendarConfig.ts
// Source: https://schedule-x.dev/docs/calendar/calendars
// Source: https://schedule-x.dev/docs/calendar/configuration
import {
  createViewDay,
  createViewWeek,
  createViewMonthGrid,
  createViewMonthAgenda,
} from '@schedule-x/calendar'
import { createEventsServicePlugin } from '@schedule-x/events-service'
import { createEventModalPlugin } from '@schedule-x/event-modal'

export const WEEK_START_DAY = 0  // 0 = Sunday in project convention; Schedule-X uses 7 = Sunday

// Schedule-X v4 firstDayOfWeek: Temporal numbering — 1=Mon, 7=Sun
// Must translate from project convention (0=Sun) to Schedule-X (7=Sun)
function toSXWeekStart(dayConvention: number): number {
  return dayConvention === 0 ? 7 : dayConvention
}

export interface MemberCalendarConfig {
  id: string        // String(users.id)
  name: string      // users.displayName
  color: string     // users.color hex
}

export function buildCalendarConfig(members: MemberCalendarConfig[]) {
  const calendars: Record<string, { colorName: string; lightColors: { main: string; container: string; onContainer: string } }> = {}

  // Shared-family calendar: reserved rose color
  calendars['shared'] = {
    colorName: 'shared',
    lightColors: deriveScheduleXColors('#F25C7A'),
  }

  // Per-member calendars keyed by String(userId)
  for (const m of members) {
    calendars[m.id] = {
      colorName: `member-${m.id}`,
      lightColors: deriveScheduleXColors(m.color),
    }
  }

  return { calendars }
}

// UI-SPEC color derivation: container = main at 15% opacity over white, onContainer = main darkened 40%
function deriveScheduleXColors(main: string) {
  return {
    main,
    container: hexWithOpacity(main, 0.15),   // CSS rgba computed over #FFFFFF
    onContainer: darkenHex(main, 0.4),
  }
}
```

**`firstDayOfWeek` translation note:** The UI-SPEC declares `WEEK_START_DAY = 0` (Sunday in JS/date-fns convention). Schedule-X v4 uses Temporal convention where Sunday = 7. Pass `7` to Schedule-X when `WEEK_START_DAY === 0`. [VERIFIED: schedule-x.dev/docs/calendar/configuration]

### Pattern 4: TanStack Query + onRangeUpdate Wiring

```typescript
// apps/pwa/src/components/CalendarShell.tsx (sketch)
import { useCalendarApp, ScheduleXCalendar } from '@schedule-x/react'
import { createViewDay, createViewWeek, createViewMonthGrid, createViewMonthAgenda } from '@schedule-x/calendar'
import { useQuery } from '@tanstack/react-query'

function CalendarShell() {
  const rangeStore = useCalendarStore()  // Zustand
  const { start, end } = rangeStore.calendarRange

  // TanStack Query — key includes the visible window
  const eventsQuery = useQuery({
    queryKey: ['events', start, end],
    queryFn: () => fetchEvents(start, end),
    retry: 2,
    staleTime: 5 * 60 * 1000,  // 5 min — poller refreshes broker every 5 min
  })

  const eventsService = useState(() => createEventsServicePlugin())[0]
  const eventModal = useState(() => createEventModalPlugin())[0]

  const calendar = useCalendarApp({
    views: [createViewDay(), createViewWeek(), createViewMonthGrid(), createViewMonthAgenda()],
    defaultView: isMobile ? 'month-agenda' : 'month-grid',  // D-05
    firstDayOfWeek: 7,  // Sunday — Temporal convention
    calendars: buildCalendarConfig(members).calendars,
    plugins: [eventsService, eventModal],
    onRangeUpdate(range) {
      // Schedule-X fires this when the user navigates to a new window
      // range.start and range.end are ISO date strings in v4
      rangeStore.setCalendarRange({ start: range.start, end: range.end })
      // Setting Zustand range triggers queryKey change → TanStack Query re-fetches
    },
  })

  // Sync TanStack Query result into Schedule-X eventsService
  useEffect(() => {
    if (eventsQuery.data) {
      const sxEvents = hydrateEvents(eventsQuery.data.occurrences)
      eventsService.set(sxEvents)
    }
  }, [eventsQuery.data])

  return (
    <ScheduleXCalendar
      calendarApp={calendar}
      customComponents={{ eventModal: EventDetailPopover }}
    />
  )
}
```

### Pattern 5: Dev-Auth Bypass Middleware

```typescript
// apps/api/src/auth/devBypass.ts
// Active ONLY when DEV_AUTH_BYPASS=true AND NODE_ENV !== 'production'
// Injects a fixed dev user into the request context so oidcAuthMiddleware is skipped
import type { MiddlewareHandler } from 'hono'

const DEV_USER = {
  id: 1,
  oidcIss: 'dev',
  oidcSub: 'dev-user',
  displayName: 'Dev User',
  color: '#4A90D9',
}

export function devAuthBypass(): MiddlewareHandler {
  if (process.env.NODE_ENV === 'production') {
    // Hard guard — never active in production regardless of env flag
    return async (_c, next) => next()
  }
  if (process.env.DEV_AUTH_BYPASS !== 'true') {
    return async (_c, next) => next()
  }
  // Inject fixed dev user into Hono context (replaces getAuth(c) result)
  return async (c, next) => {
    c.set('user', DEV_USER)
    await next()
  }
}
```

Mount in `index.ts` BEFORE `oidcAuthMiddleware` on `/api/*` when bypass is active. The bypass must short-circuit the OIDC redirect — `oidcAuthMiddleware` must be conditionally swapped out, not just prepended. Cleanest pattern: `app.use('/api/*', devAuthBypass() ?? oidcAuthMiddleware())`.

### Anti-Patterns to Avoid

- **Putting timed events on CalendarShell with a plain ISO string:** Schedule-X v4 rejects ISO strings. Hydrate to Temporal before calling `eventsService.set()`.
- **Constructing `Temporal.ZonedDateTime` for all-day events:** All-day events must use `Temporal.PlainDate`. Using `ZonedDateTime` midnight UTC will shift the date in non-UTC local timezones.
- **Expanding RRULE in the client:** D-09 locks server-side expansion. Never import rrule or call `ICAL.RecurExpansion` in the React frontend.
- **Fetching all events without a window:** With 503+ cached events and recurring series expanding infinitely, an unwindowed `/api/events` call will time out or exhaust memory. The `?start=&end=` window is mandatory.
- **Skipping VTIMEZONE registration:** If `ICAL.TimezoneService.register()` is not called before `ICAL.RecurExpansion`, ical.js falls back to UTC for timezone-aware events. Events in summer DST will appear one hour off.
- **Using rrule directly when ical.js RecurExpansion is available:** `ICAL.RecurExpansion` handles EXDATE, RDATE, and VTIMEZONE in one integrated call. rrule only handles the RRULE string — you must separately handle EXDATEs and VTIMEZONE registration. Use rrule only as a fallback for parsing RRULE strings that `ICAL.RecurExpansion` cannot handle.
- **Hard-coding `0` as `firstDayOfWeek` in Schedule-X config:** Schedule-X v4 uses Temporal numbering (7 = Sunday, not 0). Passing `0` will default to Monday.

---

## Don't Hand-Roll

| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Recurring event expansion with EXDATE | Custom RRULE iterator | `ICAL.RecurExpansion` | RecurExpansion handles RDATE, EXDATE, RECURRENCE-ID in one integrated iterator |
| All four calendar views | Custom React grid | `@schedule-x/calendar` views | Day/week/month/agenda correctly handling overlap, all-day banners, and touch is 3-6 weeks of work |
| Custom event modal | Custom DOM overlay | `createEventModalPlugin` + `customComponents.eventModal` | Schedule-X positions the modal relative to the event; re-use in Phase 3 is built-in |
| VTIMEZONE DST tables | Custom offset lookup | `ICAL.TimezoneService.register()` from parsed VTIMEZONE | The VTIMEZONE component in the ICS already contains the correct DST rules for the calendar's timezone |
| Calendar color derivation | Manual CSS computation | `colorUtils.ts` utility function (small, one-file) | The 15%/darken derivation is simple enough to implement inline; no third-party needed |
| iCalendar string parsing | Custom VCALENDAR parser | `ICAL.parse()` + `ICAL.Component` | VCALENDAR has pathological edge cases (folded lines, UTF-8 encoded params, VTIMEZONE nesting) |

**Key insight:** Calendar view rendering that handles overlap, drag handle exclusion zones, DST, all-day banners, and touch gestures for iOS correctly is multi-month work. Schedule-X exists precisely for this.

---

## Common Pitfalls

### Pitfall 1: `firstDayOfWeek` Temporal Numbering Mismatch

**What goes wrong:** Passing `0` to Schedule-X `firstDayOfWeek` instead of `7` causes week views to start on Monday (the default), silently ignoring Sunday.

**Why it happens:** JS/date-fns use `0 = Sunday`; Temporal (and therefore Schedule-X v4) uses `1 = Monday ... 7 = Sunday`.

**How to avoid:** The constant `WEEK_START_DAY = 0` in `calendarConfig.ts` is in the JS convention. Translate it: `const sxFirstDay = WEEK_START_DAY === 0 ? 7 : WEEK_START_DAY`.

**Warning signs:** Week view starts on Monday even after setting Sunday; calendar headers show Mon as the first column.

### Pitfall 2: All-Day Events Shifting by One Day

**What goes wrong:** An all-day event for "June 15" appears on "June 14" (or "June 16") in the calendar.

**Why it happens:** If the all-day event's ISO string (`2026-06-15`) is passed to `Temporal.ZonedDateTime.from('2026-06-15T00:00:00Z')`, the UTC midnight maps to June 14 in timezones west of UTC. Schedule-X expects `Temporal.PlainDate` for all-day events.

**How to avoid:** In `hydrateEvents()`, check `occ.allDay`. If `true`, use `Temporal.PlainDate.from(occ.start)` where `occ.start` is already `'YYYY-MM-DD'`. Never construct a ZonedDateTime for an all-day event. The D-13 schema split (Phase 1) already separates `dtstartDate` (DATE column, all-day) from `dtstartUtc` (TIMESTAMP, timed) — the API must expose this as a clean flag.

**Warning signs:** Birthday/holiday events appear one day early; affects users in UTC-N timezones (Americas).

### Pitfall 3: Missing VTIMEZONE Registration Causes DST-Shifted Occurrences

**What goes wrong:** A weekly meeting at 10:00 America/New_York produces occurrences at 10:00 UTC during EST (correct) and 10:00 UTC during EDT (one hour off — shows as 11:00 local time).

**Why it happens:** `ICAL.RecurExpansion` defers to `ICAL.TimezoneService` for timezone-aware ICAL.Time conversion. If the TZID is not registered, ical.js silently falls back to UTC, treating all occurrences as UTC regardless of DST.

**How to avoid:** Before calling `new ICAL.RecurExpansion(...)`, iterate `comp.getAllSubcomponents('vtimezone')` and call `ICAL.TimezoneService.register(tzid, new ICAL.Timezone({ component, tzid }))` for each one. Guard with `!ICAL.TimezoneService.has(tzid)` to avoid double-registration.

**Warning signs:** Recurring events across DST transitions display at the wrong wall-clock time by exactly ±1 hour.

### Pitfall 4: Schedule-X ISO String Events Silently Fail

**What goes wrong:** Events appear to not render, or Schedule-X throws a runtime error.

**Why it happens:** Schedule-X v4 dropped ISO string event format in v3. The old format was `{ start: "2024-01-15 09:00", end: "2024-01-15 10:00" }`. Passing these strings now produces a type error or silent failure.

**How to avoid:** All events passed to `eventsService.set()` must have `Temporal.ZonedDateTime` or `Temporal.PlainDate` for start/end. The `hydrateEvents()` function must run before `eventsService.set()`. Ensure `temporal-polyfill/global` is imported in `main.tsx` before any Schedule-X component mounts.

**Warning signs:** Calendar renders with no events even when the query returns data; console shows `Temporal is not defined`.

### Pitfall 5: Unwindowed `/api/events` Endpoint

**What goes wrong:** First page load fetches all 503+ events (as of the Phase 1 spike) plus all recurring occurrences expanded to "all time", causing the request to time out or return a 10 MB payload.

**Why it happens:** Phase 1 `/api/events` returns `db.select().from(calendarEvents)` — no window filter. This was fine as a proof-of-concept; it is unsuitable for the display layer.

**How to avoid:** The new `/api/events?start=YYYY-MM-DD&end=YYYY-MM-DD` endpoint filters `dtstartUtc BETWEEN start AND end` (for timed events) and `dtstartDate BETWEEN start AND end` (for all-day), then expands recurring masters within the window. The SQL filter is a pre-filter; `ICAL.RecurExpansion` does the precise window check. Non-recurring events can be filtered entirely in SQL.

**Warning signs:** Initial page load takes >3s; response payload >1 MB; memory usage spikes during expansion.

### Pitfall 6: `@schedule-x/react` Version Behind `@schedule-x/calendar`

**What goes wrong:** Potential API mismatch if `@schedule-x/react@4.1.0` does not expose new Schedule-X features added in `@schedule-x/calendar@4.4–4.6`.

**Why it happens:** The React adapter (`github.com/schedule-x/react`) has a separate release cadence from the core (`github.com/schedule-x/schedule-x`). React adapter was last published 2026-01-21; core was 2026-05-12.

**How to avoid:** The adapter peer-dep `^4.0.0` for `@schedule-x/calendar` is satisfied by 4.6.0 — the API contract is maintained. Limit usage to the API surface confirmed in docs: `useCalendarApp`, `ScheduleXCalendar`, `customComponents`. Test the integration in Wave 0 before building dependent components.

**Warning signs:** TypeScript errors on `useCalendarApp` options that are documented but not typed in `@schedule-x/react@4.1.0`.

### Pitfall 7: Dev-Auth Bypass Active in Production

**What goes wrong:** A `DEV_AUTH_BYPASS=true` env var accidentally set in production gives unauthenticated access to all `/api/*` routes.

**Why it happens:** Env vars leak into production containers via `.env` file copy mistakes or CI/CD misconfiguration.

**How to avoid:** The bypass middleware must have a hard `process.env.NODE_ENV === 'production'` guard as its FIRST check, before reading `DEV_AUTH_BYPASS`. The Docker Compose production configuration must NOT set `DEV_AUTH_BYPASS`. Document this in the env var table in `.env.example` with a warning comment.

**Warning signs:** `/api/me` returns a response without an Authelia session cookie in production.

---

## Code Examples

### VTIMEZONE Registration + ICAL.RecurExpansion (complete pattern)

```typescript
// Source: https://github.com/kewisch/ical.js/wiki/Common-Use-Cases
// Source: https://kewisch.github.io/ical.js/api/
import ICAL from 'ical.js'

function expandVeventOccurrences(
  rawVcalendar: string,
  windowStart: Date,
  windowEnd: Date,
): Array<{ dtstart: Date; dtend: Date; allDay: boolean }> {
  const parsed = ICAL.parse(rawVcalendar)
  const comp = new ICAL.Component(parsed)

  // Step 1: Register all VTIMEZONE components in this VCALENDAR.
  // Must happen BEFORE constructing ICAL.RecurExpansion.
  for (const vtz of comp.getAllSubcomponents('vtimezone')) {
    const tzid = vtz.getFirstPropertyValue('tzid') as string
    if (tzid && !ICAL.TimezoneService.has(tzid)) {
      ICAL.TimezoneService.register(
        tzid,
        new ICAL.Timezone({ component: vtz, tzid }),
      )
    }
  }

  const vevent = comp.getFirstSubcomponent('vevent')
  if (!vevent) return []

  const event = new ICAL.Event(vevent)
  const dtstart = vevent.getFirstPropertyValue('dtstart') as ICAL.Time
  const allDay = dtstart.isDate

  const results: Array<{ dtstart: Date; dtend: Date; allDay: boolean }> = []
  const rangeStart = ICAL.Time.fromJSDate(windowStart, false)
  const rangeEnd = ICAL.Time.fromJSDate(windowEnd, false)

  if (!event.isRecurring()) {
    if (dtstart.compare(rangeStart) >= 0 && dtstart.compare(rangeEnd) < 0) {
      const dtend = vevent.getFirstPropertyValue('dtend') as ICAL.Time | null
      results.push({
        dtstart: dtstart.toJSDate(),
        dtend: (dtend ?? dtstart).toJSDate(),
        allDay,
      })
    }
    return results
  }

  // RecurExpansion handles RRULE + RDATE + EXDATE internally
  const expand = new ICAL.RecurExpansion({ component: vevent, dtstart })
  let next: ICAL.Time | null
  while ((next = expand.next()) && next.compare(rangeEnd) < 0) {
    if (next.compare(rangeStart) < 0) continue
    // Compute end using the original event's duration
    const duration = event.duration
    const occEnd = next.clone()
    occEnd.addDuration(duration)
    results.push({ dtstart: next.toJSDate(), dtend: occEnd.toJSDate(), allDay })
  }
  return results
}
```

### All-Day Event: Server Format to Schedule-X PlainDate

```typescript
// Source: https://schedule-x.dev/docs/calendar/events
// The server sends allDay events with start: 'YYYY-MM-DD' (from dtstartDate column)
// The client must use Temporal.PlainDate — NOT ZonedDateTime

// WRONG (shifts date in negative-offset timezones):
{ start: Temporal.ZonedDateTime.from('2026-06-15T00:00:00Z') }

// CORRECT:
{ start: Temporal.PlainDate.from('2026-06-15') }
```

### Schedule-X CSS Token Override Pattern

```css
/* apps/pwa/src/styles/tokens.css */
/* Source: https://schedule-x.dev — import theme-default, then override all --sx-color-* vars */

/* Import Schedule-X default layout CSS in main.tsx:
   import '@schedule-x/theme-default/dist/index.css'
   Import tokens.css after — these overrides take precedence */

:root {
  /* Map Schedule-X color vars to project tokens */
  --sx-color-primary: var(--color-member-0);  /* current user's color */
  --sx-color-on-primary: #ffffff;
  --sx-color-surface: var(--color-surface);
  --sx-color-on-surface: var(--color-text-primary);
  --sx-color-on-surface-variant: var(--color-text-secondary);
  --sx-color-outline: var(--color-border);
  --sx-color-neutral: var(--color-surface-dim);
  --sx-color-neutral-variant: var(--color-border-subtle);

  /* Typography */
  --sx-font-family: var(--font-family-base);
}
```

---

## Backend: `/api/events` Evolution

### Current state (Phase 1)

```typescript
// apps/api/src/routes/events.ts — current implementation
eventsRouter.get('/', async (c) => {
  const events = await db.select().from(calendarEvents)  // no window, no join, no expansion
  return c.json({ events })
})
```

### Target state (Phase 2)

```typescript
// apps/api/src/routes/events.ts — evolved
eventsRouter.get('/', async (c) => {
  const { start, end } = c.req.query()
  // Zod-validate start/end as ISO dates
  // SQL: calendarEvents JOIN calendars JOIN users
  //   WHERE (dtstartUtc BETWEEN start AND end) OR (dtstartDate BETWEEN start AND end)
  //      OR event.hasRrule (to catch recurring masters whose window occurrence may differ)
  // For each row: call expandOccurrences(rawVevent, windowStart, windowEnd, ...)
  // Return: { occurrences: CalendarOccurrence[] }
})
```

**SQL pre-filter strategy:** The SQL `WHERE` must also include events with an RRULE property that _started before_ the window, because a weekly meeting created 3 years ago can still have occurrences in the current window. Include a `hasRrule` boolean column (can be added via migration) or parse `rawVevent` in the expansion step and skip in-memory if no occurrences fall in window. The simpler approach: include all events where `dtstartUtc < windowEnd` (no lower bound) OR `dtstartDate < windowEnd`, then let `expandOccurrences` handle the window check. Add a schema migration to add a `hasRrule` boolean indexed column to `calendarEvents` to avoid scanning all historical events on every request.

**Shared calendar identification:** The `calendars` table has `userId` but no explicit `isShared` flag. The shared-family calendar is identified by being the one that has its `displayName = 'Calendar'` (from CAL-08-DECISION.md) or, more robustly, by convention (the broker user is the broker account, not a household member). The Phase 2 plan should resolve this: either add a `isShared` boolean to `calendars`, or identify shared calendars by comparing `calendars.userId` to a designated broker user ID.

---

## State of the Art

| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| Schedule-X ISO string events `"YYYY-MM-DD HH:MM"` | `Temporal.ZonedDateTime` / `Temporal.PlainDate` | Schedule-X v3 (2024) | Server must return parseable strings; client must hydrate |
| `react-big-calendar` (moment/date-fns) | Schedule-X (Temporal-based) | 2024 ecosystem shift | react-big-calendar's CSS is hard to override; Schedule-X CSS tokens are first-class |
| `FullCalendar` open-source | Schedule-X (fully MIT) | 2024 for self-hosted | FullCalendar premium features are commercial; Schedule-X is fully open |
| rrule-only recurrence expansion | `ICAL.RecurExpansion` (higher-level) | ical.js 1.x+ | RecurExpansion integrates RRULE + RDATE + EXDATE; no separate EXDATE handling needed |

**Deprecated/outdated:**
- `react-big-calendar`: Not deprecated per se, but the CSS override story is significantly worse for a token-based design system. The UI-SPEC already rejected it.
- Schedule-X v2 ISO string format: Removed in v3. Any tutorial older than mid-2024 using string dates is wrong.

---

## Validation Architecture

### Test Framework

| Property | Value |
|----------|-------|
| Framework | Vitest (already configured in `apps/api/vitest.config.ts`) |
| Config file | `apps/api/vitest.config.ts` (exists); `apps/pwa` has no test setup — needs Wave 0 |
| Quick run command | `pnpm --filter @familysync/api test` |
| Full suite command | `pnpm -r test` (workspace-wide) |

### Phase Requirements → Test Map

| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|--------|----------|-----------|-------------------|-------------|
| CAL-02 (color) | Events returned with correct `color` field from `users.color` | unit | `pnpm --filter @familysync/api test -- tests/routes/events.test.ts` | ❌ Wave 0 |
| CAL-02 (aggregation) | Events from multiple calendars (multiple users) returned in single response | unit | same file | ❌ Wave 0 |
| CAL-03 (views) | Schedule-X renders without error with all four views configured | smoke | `pnpm --filter @familysync/pwa test -- calendar.spec.tsx` | ❌ Wave 0 |
| CAL-07 (recurrence) | `expandOccurrences()` returns correct occurrences for weekly RRULE in a 30-day window | unit | `pnpm --filter @familysync/api test -- tests/broker/expand.test.ts` | ❌ Wave 0 |
| CAL-07 (DST) | `expandOccurrences()` with America/New_York RRULE across March DST boundary returns correct wall-clock times | unit | same file | ❌ Wave 0 |
| CAL-07 (all-day) | `expandOccurrences()` for all-day event returns `allDay: true` and `start: 'YYYY-MM-DD'` with no time component | unit | same file | ❌ Wave 0 |
| CAL-07 (EXDATE) | `expandOccurrences()` excludes EXDATE occurrences from expansion | unit | same file | ❌ Wave 0 |
| CAL-07 (Temporal) | `hydrateEvents()` converts all-day occurrences to `Temporal.PlainDate` and timed to `Temporal.ZonedDateTime` | unit | `pnpm --filter @familysync/pwa test -- lib/hydrateEvents.test.ts` | ❌ Wave 0 |

### Fixture ICS Files (test corpus)

The most valuable test artifacts are fixture `.ics` files. Create in `apps/api/tests/fixtures/`:

| Filename | Contents | Tests |
|----------|----------|-------|
| `weekly-dst.ics` | Weekly meeting at 10:00 America/New_York spanning March DST transition (2026-03-01 to 2026-04-30) | CAL-07 DST |
| `allday-birthday.ics` | Annual birthday event (DATE type, no DTEND) | CAL-07 all-day |
| `exdate-series.ics` | Weekly series with one EXDATE (a skipped occurrence) | CAL-07 EXDATE |
| `multi-cal.ics` | Two separate VCALENDAR blobs to represent two members' events | CAL-02 aggregation |

These fixture files can be generated from real Fastmail ICS exports or hand-crafted with known-correct VTIMEZONE blocks.

### Sampling Rate

- **Per task commit:** `pnpm --filter @familysync/api test` (API unit tests, <5s)
- **Per wave merge:** `pnpm -r test` + `pnpm -r typecheck`
- **Phase gate:** Full suite green + `tsc --noEmit` clean in both workspaces before `/gsd-verify-work`

### Wave 0 Gaps

- [ ] `apps/api/tests/broker/expand.test.ts` — covers CAL-07 recurrence + DST + EXDATE + all-day
- [ ] `apps/api/tests/routes/events.test.ts` — covers CAL-02 windowed query + color join
- [ ] `apps/pwa/vitest.config.ts` — Vitest not configured in PWA; needs `vitest` + `@testing-library/react` + `jsdom`
- [ ] `apps/pwa/src/lib/hydrateEvents.test.ts` — covers Temporal hydration + all-day guard
- [ ] `apps/pwa/src/lib/calendarConfig.test.ts` — covers `firstDayOfWeek` translation (0→7)
- [ ] `apps/pwa/package.json` — add `"test": "vitest run"` script + `vitest`, `@testing-library/react`, `jsdom` devDependencies

---

## Security Domain

`security_enforcement: true`, `security_asvs_level: 1` per config.json.

### Applicable ASVS Categories

| ASVS Category | Applies | Standard Control |
|---------------|---------|-----------------|
| V2 Authentication | yes — dev bypass must not leak | `NODE_ENV === 'production'` hard guard in `devAuthBypass()` |
| V3 Session Management | carried from Phase 1 | `@hono/oidc-auth` JWT cookie (httpOnly + Secure + SameSite) |
| V4 Access Control | yes — `/api/events` must be authenticated | `oidcAuthMiddleware` on `/api/*` (Phase 1 pattern) |
| V5 Input Validation | yes — `?start=` and `?end=` query params | `zod` + `@hono/zod-validator`: validate ISO date format before SQL |
| V6 Cryptography | no new crypto in Phase 2 | — |

### Known Threat Patterns for This Phase

| Pattern | STRIDE | Standard Mitigation |
|---------|--------|---------------------|
| Dev-auth bypass left active in production | Elevation of privilege | Hard `NODE_ENV !== 'production'` guard; `.env.example` warning |
| SQL injection via `?start=` / `?end=` date params | Tampering | Zod ISO date validation; Drizzle parameterized queries |
| XSS via event title/description in EventDetailPopover | Tampering | React's default JSX escaping; never use `dangerouslySetInnerHTML` for event fields |
| Overfetch (no window) timing/DoS | Denial of service | Zod-enforce required `start` + `end` params; cap window to 90 days max |

---

## Environment Availability

| Dependency | Required By | Available | Version | Fallback |
|------------|------------|-----------|---------|----------|
| Node.js 22 | API + PWA build | ✓ | (WSL2 dev env — assumed from Phase 1) | — |
| pnpm | Workspace install | ✓ | (Phase 1 used it) | — |
| MariaDB (Docker) | `/api/events` windowed query | ✓ | Phase 1 confirmed: 503 events cached | — |
| Temporal (browser) | Schedule-X v4 | Partial | Needs `temporal-polyfill` in PWA | `temporal-polyfill@0.3.2` — no fallback needed |
| Live Authelia/Pangolin | Full auth flow | ✗ (D-14 deferred) | — | Dev-auth bypass middleware (must build in Phase 2) |

**Missing with no fallback:** None. Dev-auth bypass covers the Authelia deferral.

---

## Assumptions Log

| # | Claim | Section | Risk if Wrong |
|---|-------|---------|---------------|
| A1 | `ICAL.RecurExpansion` handles EXDATE internally when using the high-level API | Architecture Patterns | Planner would need to add manual EXDATE filtering in `expandOccurrences` |
| A2 | `@schedule-x/react@4.1.0` is API-compatible with `@schedule-x/calendar@4.6.0` for the features used (views, calendars, onRangeUpdate, customComponents) | Standard Stack | Version mismatch may cause TypeScript errors on newer options; test in Wave 0 |
| A3 | The shared-family calendar can be identified programmatically (by displayName or a new `isShared` column) without a schema migration | Backend: /api/events evolution | If not deterministic, Phase 2 plan must include a migration adding `calendars.isShared` |
| A4 | `onRangeUpdate` fires immediately on mount with the initial window | Architecture Patterns | If it does not fire on mount, initial fetch requires a separate first-render trigger |

**A1 verification:** The ical.js wiki states RecurExpansion "takes into account recurrence exceptions (RDATE and EXDATE)" [CITED: github.com/kewisch/ical.js/wiki/Common-Use-Cases]. Treat as HIGH confidence.
**A2 verification:** Peer dep `^4.0.0` satisfied by 4.6.0 [VERIFIED: npm registry]. API surface used (views, calendars, onRangeUpdate) is stable since v4.0.0. Treat as MEDIUM confidence — validate in Wave 0.
**A3 risk:** The Phase 1 spike showed Lucas's broker account has two calendars: "Calendar" and "USA Holidays". The shared-family calendar is the household-shared one. Since the per-member app-password model means each member's own calendars are fetched under their own credential, "shared" in the context of Phase 2 likely means a calendar explicitly shared at the Fastmail account level, not just a personal calendar. The plan should include a `checkpoint:human-verify` to confirm how to mark shared calendars, or default to: the calendar synced under the broker account is shared-family; calendars synced under member credentials are personal.
**A4 note:** Schedule-X fires `onRangeUpdate` when the view changes (navigation). Initial mount may not fire it. The TanStack Query initial key should be set from Zustand's default `calendarRange` (today ± buffer), not depend on `onRangeUpdate` for the first fetch.

---

## Open Questions

1. **Identifying the shared-family calendar**
   - What we know: Phase 1 caches calendars under `calendars.userId`. Lucas's broker account has "Calendar" and "USA Holidays". The wife's personal calendar will be added.
   - What's unclear: Which calendar(s) are "shared-family" vs "personal"? Is it deterministic from displayName? From which user account synced it? The UI-SPEC assigns the rose `#F25C7A` to the shared-family calendar.
   - Recommendation: Add a `calendars.isShared` boolean column (default false). The operator marks the shared-family calendar during initial setup. Alternatively, treat "Calendar" (exact displayName match) from the broker account as shared — but this is fragile.

2. **`onRangeUpdate` initial mount behavior**
   - What we know: Schedule-X fires `onRangeUpdate` on navigation. Docs do not specify if it fires on mount.
   - What's unclear: Does the calendar fire `onRangeUpdate` immediately with the initial visible window, or only on user navigation?
   - Recommendation: Do not rely on `onRangeUpdate` for the initial fetch. Set Zustand `calendarRange` to a sensible default (e.g., current month ± 1 week) on store initialization; use that as the initial TanStack Query key.

3. **Recurring masters with `dtstartUtc` before the window**
   - What we know: A weekly meeting created 3 years ago has `dtstartUtc` from 3 years ago. The SQL pre-filter `WHERE dtstartUtc BETWEEN start AND end` will miss it entirely.
   - What's unclear: The right balance between SQL efficiency and correctness.
   - Recommendation: Add `hasRrule boolean` indexed column to `calendarEvents` (schema migration in Wave 0). Pre-filter: `WHERE (NOT hasRrule AND dtstartUtc BETWEEN start AND end) OR (hasRrule AND dtstartUtc < windowEnd)`. The expansion step then filters the precise window.

---

## Sources

### Primary (HIGH confidence)
- [schedule-x.dev/docs/frameworks/react](https://schedule-x.dev/docs/frameworks/react) — React adapter usage, views, eventsService plugin
- [schedule-x.dev/docs/calendar/calendars](https://schedule-x.dev/docs/calendar/calendars) — lightColors config, calendarId on events
- [schedule-x.dev/docs/calendar/events](https://schedule-x.dev/docs/calendar/events) — Temporal.ZonedDateTime / Temporal.PlainDate requirement
- [schedule-x.dev/docs/calendar/configuration](https://schedule-x.dev/docs/calendar/configuration) — firstDayOfWeek (Temporal: 7=Sunday), onRangeUpdate
- [schedule-x.dev/blog/schedule-x-v3-temporal-api](https://schedule-x.dev/blog/schedule-x-v3-temporal-api) — breaking change from ISO strings to Temporal in v3
- [github.com/kewisch/ical.js/wiki/Common-Use-Cases](https://github.com/kewisch/ical.js/wiki/Common-Use-Cases) — ICAL.RecurExpansion pattern, VTIMEZONE registration
- [github.com/kewisch/ical.js/wiki/Parsing-iCalendar](https://github.com/kewisch/ical.js/wiki/Parsing-iCalendar) — ICAL.parse + ICAL.Component + ICAL.Event pipeline
- Phase 1 codebase: `apps/api/src/broker/sync.ts`, `apps/api/src/db/schema.ts`, CAL-08-DECISION.md — confirmed Phase 1 foundation
- `npm view` on all Phase 2 packages — versions and publish dates confirmed [VERIFIED: npm registry]

### Secondary (MEDIUM confidence)
- [schedule-x.dev/docs/calendar/major-version-migrations](https://schedule-x.dev/docs/calendar/major-version-migrations) — v2→v3 breaking changes (Temporal adoption confirmed)
- [schedule-x.dev/docs/calendar/plugins/event-modal](https://schedule-x.dev/docs/calendar/plugins/event-modal) — createEventModalPlugin + customComponents.eventModal
- WebSearch on rrule DST behavior — confirmed known issue with `tzid` parameter and UTC fallback; `ICAL.RecurExpansion` is the recommended alternative

### Tertiary (LOW confidence)
- WebSearch results on VTIMEZONE registration best practices — cross-verified with official ical.js wiki

---

## Metadata

**Confidence breakdown:**
- Standard stack: HIGH — all packages verified on npm registry; Schedule-X selected in UI-SPEC
- Architecture (recurrence expansion): HIGH — ICAL.RecurExpansion documented in official ical.js wiki; Phase 1 sync.ts pattern extended
- Architecture (Schedule-X Temporal format): HIGH — verified against official Schedule-X docs
- firstDayOfWeek translation: HIGH — verified in Schedule-X configuration docs
- All-day event PlainDate requirement: HIGH — verified in Schedule-X events docs
- VTIMEZONE registration for DST: MEDIUM — pattern documented in ical.js wiki; ICAL.js DST behavior not independently regression-tested
- Shared calendar identification: LOW — depends on runtime data shape not fully inspected

**Research date:** 2026-06-04
**Valid until:** 2026-09-04 (90 days — Schedule-X v4 is in active development; re-verify if minor versions change significantly before execution)