@luckydye/calendar 1.3.1 → 1.4.0

package/src/CalendarInternal.ts

@@ -1,75 +1,76 @@
+import { rrulestr } from "rrule";
 import type { CalendarStorage } from "./CalendarStorage.js";
-import { rrulestr } from 'rrule';
 
 export interface Attendee {
-  email: string;
-  name?: string;
-  role?: 'REQ-PARTICIPANT' | 'OPT-PARTICIPANT' | 'NON-PARTICIPANT' | 'CHAIR';
-  status?: 'NEEDS-ACTION' | 'ACCEPTED' | 'DECLINED' | 'TENTATIVE' | 'DELEGATED';
+	email: string;
+	name?: string;
+	role?: "REQ-PARTICIPANT" | "OPT-PARTICIPANT" | "NON-PARTICIPANT" | "CHAIR";
+	status?: "NEEDS-ACTION" | "ACCEPTED" | "DECLINED" | "TENTATIVE" | "DELEGATED";
 }
 
 export interface Organizer {
-  email: string;
-  name?: string;
+	email: string;
+	name?: string;
 }
 
 export interface NotificationConfig {
-  id: string;
-  triggerOffset: number;
-  enabled: boolean;
+	id: string;
+	triggerOffset: number;
+	enabled: boolean;
 }
 
 export const NOTIFICATION_PRESETS = [
-  { label: "At time of event", value: 0 },
-  { label: "5 minutes before", value: 5 },
-  { label: "15 minutes before", value: 15 },
-  { label: "30 minutes before", value: 30 },
-  { label: "1 hour before", value: 60 },
-  { label: "2 hours before", value: 120 },
-  { label: "1 day before", value: 1440 },
+	{ label: "At time of event", value: 0 },
+	{ label: "5 minutes before", value: 5 },
+	{ label: "15 minutes before", value: 15 },
+	{ label: "30 minutes before", value: 30 },
+	{ label: "1 hour before", value: 60 },
+	{ label: "2 hours before", value: 120 },
+	{ label: "1 day before", value: 1440 },
 ];
 
 export interface CalendarEvent {
-  id: string;
-  title: string;
-  start: Date;
-  end: Date;
-  color?: string;
-  calendar?: string;
-  calendarId?: string;
-  sourceId?: string;
-  description?: string;
-  location?: string;
-  url?: string;
-  rrule?: string;
-  readOnly?: boolean;
-  lastSynced?: Date;
-  organizer?: Organizer;
-  attendees?: Attendee[];
-  status?: 'TENTATIVE' | 'CONFIRMED' | 'CANCELLED';
-  reminders?: NotificationConfig[];
-  isAllDay?: boolean;
-  visualStyle?: 'heatmap';
+	id: string;
+	title: string;
+	start: Date;
+	end: Date;
+	color?: string;
+	calendar?: string;
+	calendarId?: string;
+	sourceId?: string;
+	description?: string;
+	location?: string;
+	url?: string;
+	rrule?: string;
+	readOnly?: boolean;
+	lastSynced?: Date;
+	organizer?: Organizer;
+	attendees?: Attendee[];
+	status?: "TENTATIVE" | "CONFIRMED" | "CANCELLED";
+	reminders?: NotificationConfig[];
+	isAllDay?: boolean;
+	visualStyle?: "heatmap";
+	resourceUrl?: string;
 }
 
 export interface WeekInfo {
-  weekNumber: number;
-  year: number;
-  days: Date[];
-  yOffset: number;
-  height: number;
+	weekNumber: number;
+	year: number;
+	days: Date[];
+	yOffset: number;
+	height: number;
 }
 
 // Compute event segments per week
 export interface EventSegment {
-  event: CalendarEvent;
-  weekIndex: number;
-  week: WeekInfo;
-  startDayIndex: number; // 0-6 within week
-  endDayIndex: number; // 0-6 within week
-  isStart: boolean; // Is this the first segment of the event?
-  isEnd: boolean; // Is this the last segment of the event?
-  totalWeeks: number; // Total weeks this event spans
+	event: CalendarEvent;
+	weekIndex: number;
+	week: WeekInfo;
+	startDayIndex: number; // 0-6 within week
+	endDayIndex: number; // 0-6 within week
+	isStart: boolean; // Is this the first segment of the event?
+	isEnd: boolean; // Is this the last segment of the event?
+	totalWeeks: number; // Total weeks this event spans
 }
 
 // Configuration for the sliding window buffer
@@ -79,567 +80,598 @@ const EXTEND_WEEKS = 26; // Weeks to add per extension (~6 months); must be >> B
 const MAX_WEEKS = 96; // Maximum weeks to keep in memory (trim beyond this)
 
 export class CalendarInternal {
-  locale: string;
-  
-  // Generate weeks for a smaller initial range (sliding window will extend as needed)
-  startDate = new Date();
-  endDate = CalendarInternal.addDays(new Date(), 26 * 7); // ~6 months forward
-  
-  /**
-   * First day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday).
-   * Defaults to locale-appropriate value.
-   */
-  weekStart: number = 0;
-
-  filter?: string = "";
-
-  getFilter() {
-    return this.filter;
-  }
-
-  calendarEvents: Map<string, CalendarEvent> = new Map();
-
-  selectedEvents: Set<CalendarEvent> = new Set();
-
-  enabledCalendars: Set<string> = new Set();
-
-  lockedCalendars: Set<string> = new Set();
-
-  storage?: CalendarStorage;
-  initPromise: Promise<void>;
-
-  stream: ReadableStream<CalendarEvent[]>;
-
-  controller?: ReadableStreamDefaultController<CalendarEvent[]>;
-
-  constructor(config?: {
-    locale?: string;
-    weekStart?: number;
-    storage?: CalendarStorage;
-  }) {
-    this.locale = config?.locale || navigator.language;
-    this.weekStart = config?.weekStart || CalendarInternal.getWeekStartFromLocale(this.locale);
-
-    this.startDate = this.getStartOfWeek(CalendarInternal.addDays(new Date(), -26 * 7)); // ~6 months back
-
-    const eventSource: UnderlyingDefaultSource<CalendarEvent[]> = {
-      start: (controller) => {
-        this.controller = controller;
-      },
-    };
-
-    this.stream = new ReadableStream(eventSource);
-
-    this.storage = config?.storage;
-    this.initPromise = this.loadFromStorage();
-  }
-  
-  /**
-   * Syncs multiple events to event storage on device.
-   * Performs differential sync: adds new events, updates existing ones,
-   * and removes events that belong to this source but are not in the fetched list.
-   *
-   * @param sourceName - The name of the calendar source (used to identify source ownership)
-   * @param syncTimestamp - The timestamp of this sync operation (used to identify stale events)
-   * @param events - The events fetched from the source
-   */
-  sync = (sourceName: string, syncTimestamp: Date, events: CalendarEvent[]): CalendarEvent[] => {
-    const updatedEvents: CalendarEvent[] = [];
-
-    // Add or update fetched events with the sync timestamp
-    for (const event of events) {
-      const updated = {
-        ...event,
-        lastSynced: syncTimestamp,
-      };
-      this.calendarEvents.set(event.id, updated);
-      updatedEvents.push(updated);
-    }
-
-    for (const [id, event] of this.calendarEvents.entries()) {
-      if (event.calendar === sourceName) {
-        if(!event.lastSynced || event.lastSynced < syncTimestamp) {
-          this.calendarEvents.delete(id);
-        }
-      }
-    }
-
-    this.sendEvents();
-
-    const syncedSources = new Map<string, Date>([[sourceName, syncTimestamp]]);
-    this.storage?.sync(updatedEvents, syncedSources).catch(error => {
-      console.error("Failed to persist events:", error);
-    });
-
-    return updatedEvents;
-  }
-
-  /**
-   * Loads events from persistent storage on initialization
-   */
-  async loadFromStorage(): Promise<CalendarEvent[]> {
-    const events = await this.storage?.loadEvents() || [];
-    for (const event of events) {
-      this.calendarEvents.set(event.id, event);
-    }
-    this.sendEvents();
-    return events;
-  }
-
-
-  applyEventOptimistically(event: CalendarEvent): void {
-    this.calendarEvents.set(event.id, event);
-    this.storage?.putEvent(event).catch(() => { /* sync will fix it */ });
-    this.sendEvents();
-  }
-
-  removeEventOptimistically(eventId: string): void {
-    this.calendarEvents.delete(eventId);
-    this.storage?.deleteEvent(eventId).catch(() => { /* sync will fix it */ });
-    this.sendEvents();
-  }
-
-  setFilter(filter: string) {
-    this.filter = filter;
-    this.sendEvents();
-  }
-
-  setEnabledCalendars(calendarIds: string[]) {
-    this.enabledCalendars = new Set(calendarIds);
-    this.sendEvents();
-  }
-
-  setLockedCalendars(calendarIds: string[]) {
-    this.lockedCalendars = new Set(calendarIds);
-    this.sendEvents();
-  }
-
-  expandRecurringEvent(event: CalendarEvent): CalendarEvent[] {
-    if (!event.rrule) {
-      return [event];
-    }
-
-    try {
-      const dtstart = event.start;
-      const year = dtstart.getUTCFullYear();
-      const month = String(dtstart.getUTCMonth() + 1).padStart(2, '0');
-      const day = String(dtstart.getUTCDate()).padStart(2, '0');
-      const hours = String(dtstart.getUTCHours()).padStart(2, '0');
-      const minutes = String(dtstart.getUTCMinutes()).padStart(2, '0');
-      const seconds = String(dtstart.getUTCSeconds()).padStart(2, '0');
-
-      const dtstartFormatted = `${year}${month}${day}T${hours}${minutes}${seconds}Z`;
-      const rruleString = `DTSTART:${dtstartFormatted}\nRRULE:${event.rrule}`;
-
-      const rule = rrulestr(rruleString);
-
-      const twoYearsAgo = new Date();
-      twoYearsAgo.setFullYear(twoYearsAgo.getFullYear() - 2);
-      const twoYearsFromNow = new Date();
-      twoYearsFromNow.setFullYear(twoYearsFromNow.getFullYear() + 2);
-
-      const occurrences = rule.between(twoYearsAgo, twoYearsFromNow, true);
-
-      return occurrences.map((occurrenceStart) => {
-        const duration = event.end.getTime() - event.start.getTime();
-        const occurrenceEnd = new Date(occurrenceStart.getTime() + duration);
-
-        return {
-          ...event,
-          id: `${event.id}-${occurrenceStart.getTime()}`,
-          start: occurrenceStart,
-          end: occurrenceEnd,
-        };
-      });
-    } catch (error) {
-      console.error(`Failed to parse RRULE for event ${event.title} (${event.id}):`, error);
-      console.error(`  RRULE string: ${event.rrule}`);
-      return [event];
-    }
-  }
-
-  getFilteredEvents(filter?: string) {
-    const baseEvents = Array.from(this.calendarEvents.values());
-    return this.filterEvents(baseEvents, filter);
-  }
-
-  filterEvents(events: CalendarEvent[], filter?: string): CalendarEvent[] {
-    // Filter by enabled calendars
-    // Note: enabledCalendars contains calendar IDs, not sourceIds
-    const enabledEvents = this.enabledCalendars.size > 0
-      ? events.filter(e => {
-          // For backwards compatibility: check both sourceId and calendarId
-          // CalDAV events: match via calendarId
-          // Other sources: match via sourceId
-          return (e.calendarId && this.enabledCalendars.has(e.calendarId)) ||
-                 (e.sourceId && this.enabledCalendars.has(e.sourceId));
-        })
-      : events;
-
-    // Mark events from locked calendars as read-only
-    const lockedEvents = this.lockedCalendars.size > 0
-      ? enabledEvents.map(e => {
-          const isLocked = (e.calendarId && this.lockedCalendars.has(e.calendarId)) ||
-                          (e.sourceId && this.lockedCalendars.has(e.sourceId));
-          if (isLocked) {
-            return { ...e, readOnly: true };
-          }
-          return e;
-        })
-      : enabledEvents;
-
-    const expandedEvents: CalendarEvent[] = [];
-    for (const event of lockedEvents) {
-      const instances = this.expandRecurringEvent(event);
-      expandedEvents.push(...instances);
-    }
-
-    if (!filter) {
-      return expandedEvents;
-    }
-    return expandedEvents.filter(e => e.title.toLowerCase()
-        .includes(filter.toLowerCase())
-    );
-  }
-  
-  sendEvents() {
-    const filteredEvents = this.getFilteredEvents(this.filter);
-    const inRangeEvents = filteredEvents.filter(event => {
-      // TODO: only send events within the date-range
-      return true;
-    });
-    this.controller?.enqueue(inRangeEvents);
-  }
-  
-  /**
-   * Selects an event with the specified mode.
-   * 
-   * @example
-   * // Replace current selection with this event
-   * internal.selectEvent(event, 'replace');
-   * 
-   * @example
-   * // Add event to current selection (cmd/ctrl key behavior)
-   * internal.selectEvent(event, 'add');
-   * 
-   * @example
-   * // Toggle event selection
-   * internal.selectEvent(event, 'toggle');
-   */
-  selectEvent(event: CalendarEvent, mode: 'replace' | 'add' | 'toggle' = 'replace') {
-    if (mode === 'replace') {
-      this.selectedEvents.clear();
-      this.selectedEvents.add(event);
-    } else if (mode === 'add') {
-      this.selectedEvents.add(event);
-    } else if (mode === 'toggle') {
-      if (this.selectedEvents.has(event)) {
-        this.selectedEvents.delete(event);
-      } else {
-        this.selectedEvents.add(event);
-      }
-    }
-  }
-  
-  /**
-   * Clears all selected events.
-   */
-  clearSelection() {
-    this.selectedEvents.clear();
-  }
-  
-  /**
-   * Checks if an event is currently selected.
-   */
-  isEventSelected(event: CalendarEvent): boolean {
-    return this.selectedEvents.has(event);
-  }
-  
-  /**
-   * Returns an array of all currently selected events.
-   *
-   * @example
-   * const selected = internal.getSelectedEvents();
-   * console.log(`${selected.length} events selected`);
-   */
-  getSelectedEvents(): CalendarEvent[] {
-    return Array.from(this.selectedEvents);
-  }
-
-  /**
-   * Returns all events that overlap with the given time range.
-   * Does not modify selection state.
-   *
-   * @example
-   * // Get all events in January 2024
-   * const start = new Date('2024-01-01');
-   * const end = new Date('2024-01-31T23:59:59');
-   * const events = internal.queryEvents(start, end);
-   *
-   * @example
-   * // Get events for the next week
-   * const now = new Date();
-   * const nextWeek = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000);
-   * const upcoming = internal.queryEvents(now, nextWeek);
-   */
-  queryEvents(start: Date, end: Date): CalendarEvent[] {
-    const startTime = start.getTime();
-    const endTime = end.getTime();
-    const result: CalendarEvent[] = [];
-
-    for (const event of this.calendarEvents.values()) {
-      const eventStartTime = event.start.getTime();
-      const eventEndTime = event.end.getTime();
-
-      // Check if event overlaps with time range
-      const overlaps = !(
-        eventEndTime < startTime ||
-        eventStartTime > endTime
-      );
-
-      if (overlaps) {
-        result.push(event);
-      }
-    }
-
-    return result;
-  }
-
-  /**
-   * Selects all events that overlap with the given time range.
-   * 
-   * @example
-   * // Select all events in January 2024
-   * const start = new Date('2024-01-01');
-   * const end = new Date('2024-01-31T23:59:59');
-   * internal.selectEventsByTimeRange(start, end, 'replace');
-   * 
-   * @example
-   * // Add events in a time range to current selection
-   * internal.selectEventsByTimeRange(start, end, 'add');
-   */
-  selectEventsByTimeRange(start: Date, end: Date, mode: 'replace' | 'add' = 'replace') {
-    if (mode === 'replace') {
-      this.selectedEvents.clear();
-    }
-
-    const startTime = start.getTime();
-    const endTime = end.getTime();
-
-    for (const event of this.calendarEvents.values()) {
-      const eventStartTime = event.start.getTime();
-      const eventEndTime = event.end.getTime();
-
-      // Check if event overlaps with time range
-      const overlaps = !(
-        eventEndTime < startTime ||
-        eventStartTime > endTime
-      );
-
-      if (overlaps) {
-        this.selectedEvents.add(event);
-      }
-    }
-  }
-  
-  /**
-   * Returns a minimal list of all events.
-   */
-  getAllEvents() {
-    throw new Error("not implemented");
-  }
-  
-  /**
-   * Returns a stream of events in range
-   */
-  events() {
-    return this.stream;
-  }
-
-  generateWeeks() {
-    const startDate = this.startDate; 
-    const endDate = this.endDate;
-    
-    const weeks: WeekInfo[]= [];
-    let current = new Date(startDate);
-
-    while (current < endDate) {
-      const days: Date[] = [];
-      for (let i = 0; i < 7; i++) {
-        days.push(new Date(current));
-        current = CalendarInternal.addDays(current, 1);
-      }
-
-      const firstDay = days[0];
-      const thursday = days[3];
-      if (firstDay && thursday) {
-        weeks.push({
-          weekNumber: CalendarInternal.getWeekNumber(firstDay),
-          year: thursday.getFullYear(), // Use Thursday for year
-          days,
-          yOffset: 0,
-          height: 0,
-        });
-      }
-    }
-
-    return weeks;
-  }
-
-  // Extends the date range and returns new weeks added
-  extendRange(direction: "past" | "future"): WeekInfo[] {
-    const weeksToAdd = EXTEND_WEEKS;
-    const newWeeks: WeekInfo[] = [];
-
-    if (direction === "past") {
-      const newStartDate = CalendarInternal.addDays(this.startDate, -weeksToAdd * 7);
-      let current = new Date(newStartDate);
-      
-      while (current < this.startDate) {
-        const days: Date[] = [];
-        for (let i = 0; i < 7; i++) {
-          days.push(new Date(current));
-          current = CalendarInternal.addDays(current, 1);
-        }
-        
-        const firstDay = days[0];
-        const thursday = days[3];
-        if (firstDay && thursday) {
-          newWeeks.push({
-            weekNumber: CalendarInternal.getWeekNumber(firstDay),
-            year: thursday.getFullYear(),
-            days,
-            yOffset: 0,
-            height: 0,
-          });
-        }
-      }
-      
-      this.startDate = newStartDate;
-    } else {
-      const newEndDate = CalendarInternal.addDays(this.endDate, weeksToAdd * 7);
-      let current = new Date(this.endDate);
-      
-      while (current < newEndDate) {
-        const days: Date[] = [];
-        for (let i = 0; i < 7; i++) {
-          days.push(new Date(current));
-          current = CalendarInternal.addDays(current, 1);
-        }
-        
-        const firstDay = days[0];
-        const thursday = days[3];
-        if (firstDay && thursday) {
-          newWeeks.push({
-            weekNumber: CalendarInternal.getWeekNumber(firstDay),
-            year: thursday.getFullYear(),
-            days,
-            yOffset: 0,
-            height: 0,
-          });
-        }
-      }
-      
-      this.endDate = newEndDate;
-    }
-
-    return newWeeks;
-  }
-
-  getBufferWeeks(): number {
-    return BUFFER_WEEKS;
-  }
-
-  getMaxWeeks(): number {
-    return MAX_WEEKS;
-  }
-
-  trimRange(direction: "past" | "future", weeksToTrim: number): void {
-    if (direction === "past") {
-      this.startDate = CalendarInternal.addDays(this.startDate, -weeksToTrim * 7);
-    } else {
-      this.endDate = CalendarInternal.addDays(this.endDate, -weeksToTrim * 7);
-    }
-  }
-
-  // Resets the range to be centered around the target date
-  resetRangeAroundDate(targetDate: Date): WeekInfo[] {
-    // Set range to ~6 months before and after target
-    const target = new Date(targetDate);
-    target.setHours(0, 0, 0, 0);
-
-    this.startDate = this.getStartOfWeek(CalendarInternal.addDays(target, -26 * 7));
-    this.endDate = CalendarInternal.addDays(target, 26 * 7);
-
-    // Generate all weeks for the new range
-    return this.generateWeeks();
-  }
-
-  getWeekdayNames(): string[] {
-    const formatter = new Intl.DateTimeFormat(this.locale, { weekday: "short" });
-    const names: string[] = [];
-    for (let i = 0; i < 7; i++) {
-      const dayIndex = (this.weekStart + i) % 7;
-      // Jan 7, 2024 is a Sunday (0)
-      const date = new Date(2024, 0, 7 + dayIndex);
-      names.push(formatter.format(date));
-    }
-    return names;
-  }
-
-  getStartOfWeek(date: Date): Date {
-    const d = new Date(date);
-    const day = d.getDay();
-    const diff = (day - this.weekStart + 7) % 7;
-    d.setDate(d.getDate() - diff);
-    d.setHours(0, 0, 0, 0);
-    return d;
-  }
-
-  static getWeekNumber(date: Date): number {
-    const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
-    const dayNum = d.getUTCDay() || 7;
-    d.setUTCDate(d.getUTCDate() + 4 - dayNum);
-    const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
-    return Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
-  }
-
-  static isSameDay(a: Date, b: Date): boolean {
-    return (
-      a.getFullYear() === b.getFullYear() &&
-      a.getMonth() === b.getMonth() &&
-      a.getDate() === b.getDate()
-    );
-  }
-
-  static addDays(date: Date, days: number): Date {
-    const d = new Date(date);
-    d.setDate(d.getDate() + days);
-    return d;
-  }
-
-  // Returns timestamp for start of day using pure math (no Date object creation)
-  static startOfDayTime(date: Date | undefined): number {
-    if (!date) return 0;
-    const time = date.getTime();
-    const timezoneOffset = date.getTimezoneOffset() * 60000;
-    return time - ((time - timezoneOffset) % 86400000);
-  }
-
-  // Returns timestamp for end of day using pure math (no Date object creation)
-  static endOfDayTime(date: Date | undefined): number {
-    if (!date) return 0;
-    return CalendarInternal.startOfDayTime(date) + 86400000 - 1;
-  }
-  
-  static getWeekStartFromLocale(locale: string) {
-    // Use Intl to determine locale's week start
-    // Most locales start on Monday (1), US/Canada start on Sunday (0)
-    const sundayLocales = ["en-US", "en-CA", "ja-JP", "ko-KR", "zh-TW"];
-    const lang = locale.split("-")[0];
-    if (sundayLocales.includes(locale) || lang === "he" || lang === "ar") {
-      return 0;
-    }
-    return 1;
-  }
+	locale: string;
+
+	// Generate weeks for a smaller initial range (sliding window will extend as needed)
+	startDate = new Date();
+	endDate = CalendarInternal.addDays(new Date(), 26 * 7); // ~6 months forward
+
+	/**
+	 * First day of the week (0 = Sunday, 1 = Monday, ..., 6 = Saturday).
+	 * Defaults to locale-appropriate value.
+	 */
+	weekStart = 0;
+
+	filter?: string = "";
+
+	getFilter() {
+		return this.filter;
+	}
+
+	calendarEvents: Map<string, CalendarEvent> = new Map();
+
+	selectedEvents: Set<CalendarEvent> = new Set();
+
+	enabledCalendars: Set<string> = new Set();
+
+	lockedCalendars: Set<string> = new Set();
+
+	storage?: CalendarStorage;
+	initPromise: Promise<void>;
+
+	stream: ReadableStream<CalendarEvent[]>;
+
+	controller?: ReadableStreamDefaultController<CalendarEvent[]>;
+
+	constructor(config?: {
+		locale?: string;
+		weekStart?: number;
+		storage?: CalendarStorage;
+	}) {
+		this.locale = config?.locale || navigator.language;
+		this.weekStart =
+			config?.weekStart || CalendarInternal.getWeekStartFromLocale(this.locale);
+
+		this.startDate = this.getStartOfWeek(
+			CalendarInternal.addDays(new Date(), -26 * 7),
+		); // ~6 months back
+
+		const eventSource: UnderlyingDefaultSource<CalendarEvent[]> = {
+			start: (controller) => {
+				this.controller = controller;
+			},
+		};
+
+		this.stream = new ReadableStream(eventSource);
+
+		this.storage = config?.storage;
+		this.initPromise = this.loadFromStorage();
+	}
+
+	/**
+	 * Syncs multiple events to event storage on device.
+	 * Performs differential sync: adds new events, updates existing ones,
+	 * and removes events that belong to this source but are not in the fetched list.
+	 *
+	 * @param sourceName - The name of the calendar source (used to identify source ownership)
+	 * @param syncTimestamp - The timestamp of this sync operation (used to identify stale events)
+	 * @param events - The events fetched from the source
+	 */
+	sync = (
+		sourceName: string,
+		syncTimestamp: Date,
+		events: CalendarEvent[],
+	): CalendarEvent[] => {
+		const updatedEvents: CalendarEvent[] = [];
+
+		// Add or update fetched events with the sync timestamp
+		for (const event of events) {
+			const updated = {
+				...event,
+				lastSynced: syncTimestamp,
+			};
+			this.calendarEvents.set(event.id, updated);
+			updatedEvents.push(updated);
+		}
+
+		for (const [id, event] of this.calendarEvents.entries()) {
+			if (event.calendar === sourceName) {
+				if (!event.lastSynced || event.lastSynced < syncTimestamp) {
+					this.calendarEvents.delete(id);
+				}
+			}
+		}
+
+		this.sendEvents();
+
+		const syncedSources = new Map<string, Date>([[sourceName, syncTimestamp]]);
+		this.storage?.sync(updatedEvents, syncedSources).catch((error) => {
+			console.error("Failed to persist events:", error);
+		});
+
+		return updatedEvents;
+	};
+
+	/**
+	 * Loads events from persistent storage on initialization
+	 */
+	async loadFromStorage(): Promise<CalendarEvent[]> {
+		const events = (await this.storage?.loadEvents()) || [];
+		for (const event of events) {
+			this.calendarEvents.set(event.id, event);
+		}
+		this.sendEvents();
+		return events;
+	}
+
+	applyEventOptimistically(event: CalendarEvent): void {
+		this.calendarEvents.set(event.id, event);
+		this.storage?.putEvent(event).catch(() => {
+			/* sync will fix it */
+		});
+		this.sendEvents();
+	}
+
+	removeEventOptimistically(eventId: string): void {
+		this.calendarEvents.delete(eventId);
+		this.storage?.deleteEvent(eventId).catch(() => {
+			/* sync will fix it */
+		});
+		this.sendEvents();
+	}
+
+	setFilter(filter: string) {
+		this.filter = filter;
+		this.sendEvents();
+	}
+
+	setEnabledCalendars(calendarIds: string[]) {
+		this.enabledCalendars = new Set(calendarIds);
+		this.sendEvents();
+	}
+
+	setLockedCalendars(calendarIds: string[]) {
+		this.lockedCalendars = new Set(calendarIds);
+		this.sendEvents();
+	}
+
+	expandRecurringEvent(event: CalendarEvent): CalendarEvent[] {
+		if (!event.rrule) {
+			return [event];
+		}
+
+		try {
+			const dtstart = event.start;
+			const year = dtstart.getUTCFullYear();
+			const month = String(dtstart.getUTCMonth() + 1).padStart(2, "0");
+			const day = String(dtstart.getUTCDate()).padStart(2, "0");
+			const hours = String(dtstart.getUTCHours()).padStart(2, "0");
+			const minutes = String(dtstart.getUTCMinutes()).padStart(2, "0");
+			const seconds = String(dtstart.getUTCSeconds()).padStart(2, "0");
+
+			const dtstartFormatted = `${year}${month}${day}T${hours}${minutes}${seconds}Z`;
+			const rruleString = `DTSTART:${dtstartFormatted}\nRRULE:${event.rrule}`;
+
+			const rule = rrulestr(rruleString);
+
+			const twoYearsAgo = new Date();
+			twoYearsAgo.setFullYear(twoYearsAgo.getFullYear() - 2);
+			const twoYearsFromNow = new Date();
+			twoYearsFromNow.setFullYear(twoYearsFromNow.getFullYear() + 2);
+
+			const occurrences = rule.between(twoYearsAgo, twoYearsFromNow, true);
+
+			return occurrences.map((occurrenceStart) => {
+				const duration = event.end.getTime() - event.start.getTime();
+				const occurrenceEnd = new Date(occurrenceStart.getTime() + duration);
+
+				return {
+					...event,
+					id: `${event.id}-${occurrenceStart.getTime()}`,
+					start: occurrenceStart,
+					end: occurrenceEnd,
+				};
+			});
+		} catch (error) {
+			console.error(
+				`Failed to parse RRULE for event ${event.title} (${event.id}):`,
+				error,
+			);
+			console.error(`  RRULE string: ${event.rrule}`);
+			return [event];
+		}
+	}
+
+	getFilteredEvents(filter?: string) {
+		const baseEvents = Array.from(this.calendarEvents.values());
+		return this.filterEvents(baseEvents, filter);
+	}
+
+	filterEvents(events: CalendarEvent[], filter?: string): CalendarEvent[] {
+		// Filter by enabled calendars
+		// Note: enabledCalendars contains calendar IDs, not sourceIds
+		const enabledEvents =
+			this.enabledCalendars.size > 0
+				? events.filter((e) => {
+						// For backwards compatibility: check both sourceId and calendarId
+						// CalDAV events: match via calendarId
+						// Other sources: match via sourceId
+						return (
+							(e.calendarId && this.enabledCalendars.has(e.calendarId)) ||
+							(e.sourceId && this.enabledCalendars.has(e.sourceId))
+						);
+				  })
+				: events;
+
+		// Mark events from locked calendars as read-only
+		const lockedEvents =
+			this.lockedCalendars.size > 0
+				? enabledEvents.map((e) => {
+						const isLocked =
+							(e.calendarId && this.lockedCalendars.has(e.calendarId)) ||
+							(e.sourceId && this.lockedCalendars.has(e.sourceId));
+						if (isLocked) {
+							return { ...e, readOnly: true };
+						}
+						return e;
+				  })
+				: enabledEvents;
+
+		const expandedEvents: CalendarEvent[] = [];
+		for (const event of lockedEvents) {
+			const instances = this.expandRecurringEvent(event);
+			expandedEvents.push(...instances);
+		}
+
+		if (!filter) {
+			return expandedEvents;
+		}
+		return expandedEvents.filter((e) =>
+			e.title.toLowerCase().includes(filter.toLowerCase()),
+		);
+	}
+
+	sendEvents() {
+		const filteredEvents = this.getFilteredEvents(this.filter);
+		const inRangeEvents = filteredEvents.filter((event) => {
+			// TODO: only send events within the date-range
+			return true;
+		});
+		this.controller?.enqueue(inRangeEvents);
+	}
+
+	/**
+	 * Selects an event with the specified mode.
+	 *
+	 * @example
+	 * // Replace current selection with this event
+	 * internal.selectEvent(event, 'replace');
+	 *
+	 * @example
+	 * // Add event to current selection (cmd/ctrl key behavior)
+	 * internal.selectEvent(event, 'add');
+	 *
+	 * @example
+	 * // Toggle event selection
+	 * internal.selectEvent(event, 'toggle');
+	 */
+	selectEvent(
+		event: CalendarEvent,
+		mode: "replace" | "add" | "toggle" = "replace",
+	) {
+		if (mode === "replace") {
+			this.selectedEvents.clear();
+			this.selectedEvents.add(event);
+		} else if (mode === "add") {
+			this.selectedEvents.add(event);
+		} else if (mode === "toggle") {
+			if (this.selectedEvents.has(event)) {
+				this.selectedEvents.delete(event);
+			} else {
+				this.selectedEvents.add(event);
+			}
+		}
+	}
+
+	/**
+	 * Clears all selected events.
+	 */
+	clearSelection() {
+		this.selectedEvents.clear();
+	}
+
+	/**
+	 * Checks if an event is currently selected.
+	 */
+	isEventSelected(event: CalendarEvent): boolean {
+		return this.selectedEvents.has(event);
+	}
+
+	/**
+	 * Returns an array of all currently selected events.
+	 *
+	 * @example
+	 * const selected = internal.getSelectedEvents();
+	 * console.log(`${selected.length} events selected`);
+	 */
+	getSelectedEvents(): CalendarEvent[] {
+		return Array.from(this.selectedEvents);
+	}
+
+	/**
+	 * Returns all events that overlap with the given time range.
+	 * Does not modify selection state.
+	 *
+	 * @example
+	 * // Get all events in January 2024
+	 * const start = new Date('2024-01-01');
+	 * const end = new Date('2024-01-31T23:59:59');
+	 * const events = internal.queryEvents(start, end);
+	 *
+	 * @example
+	 * // Get events for the next week
+	 * const now = new Date();
+	 * const nextWeek = new Date(now.getTime() + 7 * 24 * 60 * 60 * 1000);
+	 * const upcoming = internal.queryEvents(now, nextWeek);
+	 */
+	queryEvents(start: Date, end: Date): CalendarEvent[] {
+		const startTime = start.getTime();
+		const endTime = end.getTime();
+		const result: CalendarEvent[] = [];
+
+		for (const event of this.calendarEvents.values()) {
+			const eventStartTime = event.start.getTime();
+			const eventEndTime = event.end.getTime();
+
+			// Check if event overlaps with time range
+			const overlaps = !(eventEndTime < startTime || eventStartTime > endTime);
+
+			if (overlaps) {
+				result.push(event);
+			}
+		}
+
+		return result;
+	}
+
+	/**
+	 * Selects all events that overlap with the given time range.
+	 *
+	 * @example
+	 * // Select all events in January 2024
+	 * const start = new Date('2024-01-01');
+	 * const end = new Date('2024-01-31T23:59:59');
+	 * internal.selectEventsByTimeRange(start, end, 'replace');
+	 *
+	 * @example
+	 * // Add events in a time range to current selection
+	 * internal.selectEventsByTimeRange(start, end, 'add');
+	 */
+	selectEventsByTimeRange(
+		start: Date,
+		end: Date,
+		mode: "replace" | "add" = "replace",
+	) {
+		if (mode === "replace") {
+			this.selectedEvents.clear();
+		}
+
+		const startTime = start.getTime();
+		const endTime = end.getTime();
+
+		for (const event of this.calendarEvents.values()) {
+			const eventStartTime = event.start.getTime();
+			const eventEndTime = event.end.getTime();
+
+			// Check if event overlaps with time range
+			const overlaps = !(eventEndTime < startTime || eventStartTime > endTime);
+
+			if (overlaps) {
+				this.selectedEvents.add(event);
+			}
+		}
+	}
+
+	/**
+	 * Returns a minimal list of all events.
+	 */
+	getAllEvents() {
+		throw new Error("not implemented");
+	}
+
+	/**
+	 * Returns a stream of events in range
+	 */
+	events() {
+		return this.stream;
+	}
+
+	generateWeeks() {
+		const startDate = this.startDate;
+		const endDate = this.endDate;
+
+		const weeks: WeekInfo[] = [];
+		let current = new Date(startDate);
+
+		while (current < endDate) {
+			const days: Date[] = [];
+			for (let i = 0; i < 7; i++) {
+				days.push(new Date(current));
+				current = CalendarInternal.addDays(current, 1);
+			}
+
+			const firstDay = days[0];
+			const thursday = days[3];
+			if (firstDay && thursday) {
+				weeks.push({
+					weekNumber: CalendarInternal.getWeekNumber(firstDay),
+					year: thursday.getFullYear(), // Use Thursday for year
+					days,
+					yOffset: 0,
+					height: 0,
+				});
+			}
+		}
+
+		return weeks;
+	}
+
+	// Extends the date range and returns new weeks added
+	extendRange(direction: "past" | "future"): WeekInfo[] {
+		const weeksToAdd = EXTEND_WEEKS;
+		const newWeeks: WeekInfo[] = [];
+
+		if (direction === "past") {
+			const newStartDate = CalendarInternal.addDays(
+				this.startDate,
+				-weeksToAdd * 7,
+			);
+			let current = new Date(newStartDate);
+
+			while (current < this.startDate) {
+				const days: Date[] = [];
+				for (let i = 0; i < 7; i++) {
+					days.push(new Date(current));
+					current = CalendarInternal.addDays(current, 1);
+				}
+
+				const firstDay = days[0];
+				const thursday = days[3];
+				if (firstDay && thursday) {
+					newWeeks.push({
+						weekNumber: CalendarInternal.getWeekNumber(firstDay),
+						year: thursday.getFullYear(),
+						days,
+						yOffset: 0,
+						height: 0,
+					});
+				}
+			}
+
+			this.startDate = newStartDate;
+		} else {
+			const newEndDate = CalendarInternal.addDays(this.endDate, weeksToAdd * 7);
+			let current = new Date(this.endDate);
+
+			while (current < newEndDate) {
+				const days: Date[] = [];
+				for (let i = 0; i < 7; i++) {
+					days.push(new Date(current));
+					current = CalendarInternal.addDays(current, 1);
+				}
+
+				const firstDay = days[0];
+				const thursday = days[3];
+				if (firstDay && thursday) {
+					newWeeks.push({
+						weekNumber: CalendarInternal.getWeekNumber(firstDay),
+						year: thursday.getFullYear(),
+						days,
+						yOffset: 0,
+						height: 0,
+					});
+				}
+			}
+
+			this.endDate = newEndDate;
+		}
+
+		return newWeeks;
+	}
+
+	getBufferWeeks(): number {
+		return BUFFER_WEEKS;
+	}
+
+	getMaxWeeks(): number {
+		return MAX_WEEKS;
+	}
+
+	trimRange(direction: "past" | "future", weeksToTrim: number): void {
+		if (direction === "past") {
+			this.startDate = CalendarInternal.addDays(
+				this.startDate,
+				-weeksToTrim * 7,
+			);
+		} else {
+			this.endDate = CalendarInternal.addDays(this.endDate, -weeksToTrim * 7);
+		}
+	}
+
+	// Resets the range to be centered around the target date
+	resetRangeAroundDate(targetDate: Date): WeekInfo[] {
+		// Set range to ~6 months before and after target
+		const target = new Date(targetDate);
+		target.setHours(0, 0, 0, 0);
+
+		this.startDate = this.getStartOfWeek(
+			CalendarInternal.addDays(target, -26 * 7),
+		);
+		this.endDate = CalendarInternal.addDays(target, 26 * 7);
+
+		// Generate all weeks for the new range
+		return this.generateWeeks();
+	}
+
+	getWeekdayNames(): string[] {
+		const formatter = new Intl.DateTimeFormat(this.locale, {
+			weekday: "short",
+		});
+		const names: string[] = [];
+		for (let i = 0; i < 7; i++) {
+			const dayIndex = (this.weekStart + i) % 7;
+			// Jan 7, 2024 is a Sunday (0)
+			const date = new Date(2024, 0, 7 + dayIndex);
+			names.push(formatter.format(date));
+		}
+		return names;
+	}
+
+	getStartOfWeek(date: Date): Date {
+		const d = new Date(date);
+		const day = d.getDay();
+		const diff = (day - this.weekStart + 7) % 7;
+		d.setDate(d.getDate() - diff);
+		d.setHours(0, 0, 0, 0);
+		return d;
+	}
+
+	static getWeekNumber(date: Date): number {
+		const d = new Date(
+			Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()),
+		);
+		const dayNum = d.getUTCDay() || 7;
+		d.setUTCDate(d.getUTCDate() + 4 - dayNum);
+		const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+		return Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+	}
+
+	static isSameDay(a: Date, b: Date): boolean {
+		return (
+			a.getFullYear() === b.getFullYear() &&
+			a.getMonth() === b.getMonth() &&
+			a.getDate() === b.getDate()
+		);
+	}
+
+	static addDays(date: Date, days: number): Date {
+		const d = new Date(date);
+		d.setDate(d.getDate() + days);
+		return d;
+	}
+
+	// Returns timestamp for start of day using pure math (no Date object creation)
+	static startOfDayTime(date: Date | undefined): number {
+		if (!date) return 0;
+		const time = date.getTime();
+		const timezoneOffset = date.getTimezoneOffset() * 60000;
+		return time - ((time - timezoneOffset) % 86400000);
+	}
+
+	// Returns timestamp for end of day using pure math (no Date object creation)
+	static endOfDayTime(date: Date | undefined): number {
+		if (!date) return 0;
+		return CalendarInternal.startOfDayTime(date) + 86400000 - 1;
+	}
+
+	static getWeekStartFromLocale(locale: string) {
+		// Use Intl to determine locale's week start
+		// Most locales start on Monday (1), US/Canada start on Sunday (0)
+		const sundayLocales = ["en-US", "en-CA", "ja-JP", "ko-KR", "zh-TW"];
+		const lang = locale.split("-")[0];
+		if (sundayLocales.includes(locale) || lang === "he" || lang === "ar") {
+			return 0;
+		}
+		return 1;
+	}
 }