@forcecalendar/core 2.1.69 → 2.2.0

package/core/calendar/Calendar.js

@@ -12,7 +12,7 @@ import { TimezoneManager } from '../timezone/TimezoneManager.js';
 export class Calendar {
   /**
    * Create a new Calendar instance
-   * @param {import('../../types.js').CalendarConfig} [config={}] - Configuration options
+   * @param {import('../types.js').CalendarConfig} [config={}] - Configuration options
    */
   constructor(config = {}) {
     // Initialize timezone manager first (use singleton to share cache)
@@ -69,7 +69,7 @@ export class Calendar {
 
   /**
    * Set the calendar view
-   * @param {import('../../types.js').ViewType} viewType - The view type ('month', 'week', 'day', 'list')
+   * @param {import('../types.js').ViewType} viewType - The view type ('month', 'week', 'day', 'list')
    * @param {Date} [date=null] - Optional date to navigate to
    */
   setView(viewType, date = null) {
@@ -87,7 +87,7 @@ export class Calendar {
 
   /**
    * Get the current view type
-   * @returns {import('../../types.js').ViewType} The current view type
+   * @returns {import('../types.js').ViewType} The current view type
    */
   getView() {
     return this.state.get('view');
@@ -160,7 +160,7 @@ export class Calendar {
 
   /**
    * Add an event
-   * @param {import('../events/Event.js').Event|import('../../types.js').EventData} eventData - Event data or Event instance
+   * @param {import('../events/Event.js').Event|import('../types.js').EventData} eventData - Event data or Event instance
    * @returns {import('../events/Event.js').Event} The added event
    */
   addEvent(eventData) {
@@ -389,7 +389,7 @@ export class Calendar {
 
   /**
    * Get the current view's data
-   * @returns {import('../../types.js').MonthViewData|import('../../types.js').WeekViewData|import('../../types.js').DayViewData|import('../../types.js').ListViewData|null} View-specific data
+   * @returns {import('../types.js').MonthViewData|import('../types.js').WeekViewData|import('../types.js').DayViewData|import('../types.js').ListViewData|null} View-specific data
    */
   getViewData() {
     const view = this.state.get('view');

package/core/conflicts/ConflictDetector.js

@@ -14,9 +14,9 @@ export class ConflictDetector {
 
   /**
    * Check for conflicts for a specific event
-   * @param {import('../events/Event.js').Event|import('../../types.js').EventData} event - Event to check
-   * @param {import('../../types.js').ConflictCheckOptions} [options={}] - Check options
-   * @returns {import('../../types.js').ConflictSummary} Conflict summary
+   * @param {import('../events/Event.js').Event|import('../types.js').EventData} event - Event to check
+   * @param {import('../types.js').ConflictCheckOptions} [options={}] - Check options
+   * @returns {import('../types.js').ConflictSummary} Conflict summary
    */
   checkConflicts(event, options = {}) {
     // Default options
@@ -87,8 +87,8 @@ export class ConflictDetector {
    * Check for conflicts between two specific events
    * @param {import('../events/Event.js').Event} event1 - First event
    * @param {import('../events/Event.js').Event} event2 - Second event
-   * @param {import('../../types.js').ConflictCheckOptions} [options={}] - Check options
-   * @returns {import('../../types.js').ConflictDetails[]} Array of conflicts
+   * @param {import('../types.js').ConflictCheckOptions} [options={}] - Check options
+   * @returns {import('../types.js').ConflictDetails[]} Array of conflicts
    */
   checkEventPairConflicts(event1, event2, options = {}) {
     const opts = {

package/core/events/Event.js

@@ -18,8 +18,8 @@ export class Event {
 
   /**
    * Normalize event data
-   * @param {import('../../types.js').EventData} data - Raw event data
-   * @returns {import('../../types.js').EventData} Normalized event data
+   * @param {import('../types.js').EventData} data - Raw event data
+   * @returns {import('../types.js').EventData} Normalized event data
    */
   static normalize(data) {
     const normalized = { ...data };
@@ -109,7 +109,7 @@ export class Event {
 
   /**
    * Validate event data
-   * @param {import('../../types.js').EventData} data - Normalized event data
+   * @param {import('../types.js').EventData} data - Normalized event data
    * @throws {Error} If validation fails
    */
   static validate(data) {
@@ -173,7 +173,7 @@ export class Event {
       try {
         new Intl.DateTimeFormat('en-US', { timeZone: data.timeZone });
       } catch (e) {
-        throw new Error(`Invalid timezone: ${data.timeZone}`);
+        throw new Error(`Invalid timezone: ${data.timeZone}`, { cause: e });
       }
     }
 
@@ -182,14 +182,14 @@ export class Event {
       try {
         new Intl.DateTimeFormat('en-US', { timeZone: data.endTimeZone });
       } catch (e) {
-        throw new Error(`Invalid end timezone: ${data.endTimeZone}`);
+        throw new Error(`Invalid end timezone: ${data.endTimeZone}`, { cause: e });
       }
     }
   }
 
   /**
    * Create a new Event instance
-   * @param {import('../../types.js').EventData} eventData - Event data object
+   * @param {import('../types.js').EventData} eventData - Event data object
    * @throws {Error} If required fields are missing or invalid
    */
   constructor({
@@ -426,7 +426,7 @@ export class Event {
 
   /**
    * Backward-compatible alias for recurrenceRule
-   * @returns {import('../../types.js').RecurrenceRule|string|null}
+   * @returns {import('../types.js').RecurrenceRule|string|null}
    */
   get recurrence() {
     return this.recurrenceRule;
@@ -513,7 +513,7 @@ export class Event {
 
   /**
    * Clone the event with optional updates
-   * @param {Partial<import('../../types.js').EventData>} [updates={}] - Properties to update in the clone
+   * @param {Partial<import('../types.js').EventData>} [updates={}] - Properties to update in the clone
    * @returns {Event} New Event instance with updated properties
    */
   clone(updates = {}) {
@@ -548,7 +548,7 @@ export class Event {
 
   /**
    * Convert event to plain object
-   * @returns {import('../../types.js').EventData} Plain object representation of the event
+   * @returns {import('../types.js').EventData} Plain object representation of the event
    */
   toObject() {
     return {
@@ -580,7 +580,7 @@ export class Event {
 
   /**
    * Create Event from plain object
-   * @param {import('../../types.js').EventData} obj - Plain object with event properties
+   * @param {import('../types.js').EventData} obj - Plain object with event properties
    * @returns {Event} New Event instance
    */
   static fromObject(obj) {
@@ -613,7 +613,7 @@ export class Event {
 
   /**
    * Add an attendee to the event
-   * @param {import('../../types.js').Attendee} attendee - Attendee to add
+   * @param {import('../types.js').Attendee} attendee - Attendee to add
    * @returns {boolean} True if attendee was added, false if already exists
    */
   addAttendee(attendee) {
@@ -662,7 +662,7 @@ export class Event {
   /**
    * Update an attendee's response status
    * @param {string} email - Attendee's email
-   * @param {import('../../types.js').AttendeeResponseStatus} responseStatus - New response status
+   * @param {import('../types.js').AttendeeResponseStatus} responseStatus - New response status
    * @returns {boolean} True if attendee was updated
    */
   updateAttendeeResponse(email, responseStatus) {
@@ -678,7 +678,7 @@ export class Event {
   /**
    * Get an attendee by email
    * @param {string} email - Attendee's email
-   * @returns {import('../../types.js').Attendee|null} The attendee or null
+   * @returns {import('../types.js').Attendee|null} The attendee or null
    */
   getAttendee(email) {
     return this.attendees.find(a => a.email === email) || null;
@@ -695,8 +695,8 @@ export class Event {
 
   /**
    * Get attendees by response status
-   * @param {import('../../types.js').AttendeeResponseStatus} status - Response status to filter by
-   * @returns {import('../../types.js').Attendee[]} Filtered attendees
+   * @param {import('../types.js').AttendeeResponseStatus} status - Response status to filter by
+   * @returns {import('../types.js').Attendee[]} Filtered attendees
    */
   getAttendeesByStatus(status) {
     return this.attendees.filter(a => a.responseStatus === status);
@@ -718,7 +718,7 @@ export class Event {
 
   /**
    * Add a reminder to the event
-   * @param {import('../../types.js').Reminder} reminder - Reminder to add
+   * @param {import('../types.js').Reminder} reminder - Reminder to add
    * @returns {boolean} True if reminder was added
    */
   addReminder(reminder) {
@@ -764,7 +764,7 @@ export class Event {
 
   /**
    * Get active reminders
-   * @returns {import('../../types.js').Reminder[]} Active reminders
+   * @returns {import('../types.js').Reminder[]} Active reminders
    */
   getActiveReminders() {
     return this.reminders.filter(r => r.enabled !== false);

package/core/events/EventStore.js

@@ -56,13 +56,13 @@ export class EventStore {
     // Change tracking
     /** @type {number} */
     this.version = 0;
-    /** @type {Set<import('../../types.js').EventListener>} */
+    /** @type {Set<import('../types.js').EventListener>} */
     this.listeners = new Set();
   }
 
   /**
    * Add an event to the store
-   * @param {Event|import('../../types.js').EventData} event - The event to add
+   * @param {Event|import('../types.js').EventData} event - The event to add
    * @returns {Event} The added event
    * @throws {Error} If event with same ID already exists
    */
@@ -107,7 +107,7 @@ export class EventStore {
   /**
    * Update an existing event
    * @param {string} eventId - The event ID
-   * @param {Partial<import('../../types.js').EventData>} updates - Properties to update
+   * @param {Partial<import('../types.js').EventData>} updates - Properties to update
    * @returns {Event} The updated event
    * @throws {Error} If event not found
    */
@@ -212,7 +212,7 @@ export class EventStore {
 
   /**
    * Query events with filters
-   * @param {import('../../types.js').QueryFilters} [filters={}] - Query filters
+   * @param {import('../types.js').QueryFilters} [filters={}] - Query filters
    * @returns {Event[]} Filtered events
    */
   queryEvents(filters = {}) {
@@ -566,7 +566,7 @@ export class EventStore {
    * @returns {Event[]}
    */
   getEventsInRange(start, end, expandRecurringOrOptions = true, timezone = null) {
-    let expandRecurring = true;
+    let expandRecurring;
 
     if (typeof expandRecurringOrOptions === 'object' && expandRecurringOrOptions !== null) {
       // Options object form: getEventsInRange(start, end, { expandRecurring, timezone })
@@ -1117,7 +1117,7 @@ export class EventStore {
 
   /**
    * Add multiple events in batch
-   * @param {Array<Event|import('../../types.js').EventData>} events - Events to add
+   * @param {Array<Event|import('../types.js').EventData>} events - Events to add
    * @returns {Event[]} Added events
    */
   addEvents(events) {
@@ -1277,9 +1277,9 @@ export class EventStore {
 
   /**
    * Check for conflicts for an event
-   * @param {Event|import('../../types.js').EventData} event - Event to check
-   * @param {import('../../types.js').ConflictCheckOptions} [options={}] - Check options
-   * @returns {import('../../types.js').ConflictSummary} Conflict summary
+   * @param {Event|import('../types.js').EventData} event - Event to check
+   * @param {import('../types.js').ConflictCheckOptions} [options={}] - Check options
+   * @returns {import('../types.js').ConflictSummary} Conflict summary
    */
   checkConflicts(event, options = {}) {
     return this.conflictDetector.checkConflicts(event, options);
@@ -1289,8 +1289,8 @@ export class EventStore {
    * Check conflicts between two events
    * @param {string} eventId1 - First event ID
    * @param {string} eventId2 - Second event ID
-   * @param {import('../../types.js').ConflictCheckOptions} [options={}] - Check options
-   * @returns {import('../../types.js').ConflictDetails[]} Conflicts between events
+   * @param {import('../types.js').ConflictCheckOptions} [options={}] - Check options
+   * @returns {import('../types.js').ConflictDetails[]} Conflicts between events
    */
   checkEventPairConflicts(eventId1, eventId2, options = {}) {
     const event1 = this.getEvent(eventId1);
@@ -1307,8 +1307,8 @@ export class EventStore {
    * Get all conflicts in a date range
    * @param {Date} start - Start date
    * @param {Date} end - End date
-   * @param {import('../../types.js').ConflictCheckOptions} [options={}] - Check options
-   * @returns {import('../../types.js').ConflictSummary} All conflicts in range
+   * @param {import('../types.js').ConflictCheckOptions} [options={}] - Check options
+   * @returns {import('../types.js').ConflictSummary} All conflicts in range
    */
   getAllConflicts(start, end, options = {}) {
     const events = this.getEventsInRange(start, end, false);
@@ -1363,9 +1363,9 @@ export class EventStore {
 
   /**
    * Add event with conflict checking
-   * @param {Event|import('../../types.js').EventData} event - Event to add
+   * @param {Event|import('../types.js').EventData} event - Event to add
    * @param {boolean} [allowConflicts=true] - Whether to allow adding with conflicts
-   * @returns {{event: Event, conflicts: import('../../types.js').ConflictSummary}} Result
+   * @returns {{event: Event, conflicts: import('../types.js').ConflictSummary}} Result
    */
   addEventWithConflictCheck(event, allowConflicts = true) {
     // Check conflicts before adding
@@ -1387,7 +1387,7 @@ export class EventStore {
   /**
    * Find events with conflicts
    * @param {Object} [options={}] - Options
-   * @returns {Array<{event: Event, conflicts: import('../../types.js').ConflictDetails[]}>} Events with conflicts
+   * @returns {Array<{event: Event, conflicts: import('../types.js').ConflictDetails[]}>} Events with conflicts
    */
   findEventsWithConflicts(options = {}) {
     const eventsWithConflicts = [];

package/core/events/RecurrenceEngine.js

@@ -2,6 +2,8 @@ import { DateUtils } from '../calendar/DateUtils.js';
 import { TimezoneManager } from '../timezone/TimezoneManager.js';
 import { RRuleParser } from './RRuleParser.js';
 
+const DAYS_IN_MONTH = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+
 /**
  * RecurrenceEngine - Handles expansion of recurring events
  * Full support for RFC 5545 (iCalendar) RRULE specification
@@ -10,6 +12,11 @@ export class RecurrenceEngine {
   // Hard limit to prevent resource exhaustion regardless of caller input
   static MAX_OCCURRENCES_HARD_LIMIT = 10000;
 
+  // expandEvent is typically called many times with the same RRULE string
+  // (every view render), so parsed rules are cached by their source string
+  static _ruleCache = new Map();
+  static _RULE_CACHE_MAX = 500;
+
   /**
    * Expand a recurring event into individual occurrences
    * @param {import('./Event.js').Event} event - The recurring event
@@ -17,7 +24,7 @@ export class RecurrenceEngine {
    * @param {Date} rangeEnd - End of the expansion range
    * @param {number} [maxOccurrences=365] - Maximum number of occurrences to generate
    * @param {string} [timezone] - Timezone for expansion (important for DST)
-   * @returns {import('../../types.js').EventOccurrence[]} Array of occurrence objects with start/end dates
+   * @returns {import('../types.js').EventOccurrence[]} Array of occurrence objects with start/end dates
    */
   static expandEvent(event, rangeStart, rangeEnd, maxOccurrences = 365, timezone = null) {
     // Enforce hard limit regardless of caller-provided value
@@ -26,14 +33,14 @@ export class RecurrenceEngine {
       return [{ start: event.start, end: event.end, timezone: event.timeZone }];
     }
 
-    const rule = this.parseRule(event.recurrenceRule);
+    const rule = this._getParsedRule(event.recurrenceRule);
     const occurrences = [];
     const duration = event.end - event.start;
     const eventTimezone = timezone || event.timeZone || 'UTC';
     const tzManager = TimezoneManager.getInstance();
 
     // Work in event's timezone for accurate recurrence calculation
-    let currentDate = new Date(event.start);
+    const currentDate = new Date(event.start);
     let count = 0;
 
     // If UNTIL is specified, use it as the range end
@@ -48,11 +55,18 @@ export class RecurrenceEngine {
     let stuckCount = 0;
     const maxStuckIterations = 3;
 
-    while (currentDate <= rangeEnd && count < maxOccurrences) {
+    // Compare on numeric timestamps in the loop — Date-object comparisons
+    // re-coerce through valueOf on every check
+    const rangeStartMs = rangeStart.getTime();
+    const rangeEndMs = rangeEnd.getTime();
+    const hasExceptions = !!(rule.exceptions && rule.exceptions.length > 0);
+    let currentMs = currentDate.getTime();
+
+    while (currentMs <= rangeEndMs && count < maxOccurrences) {
       // Check if this occurrence is within the range
-      if (currentDate >= rangeStart) {
-        const occurrenceStart = new Date(currentDate);
-        const occurrenceEnd = new Date(currentDate.getTime() + duration);
+      if (currentMs >= rangeStartMs) {
+        const occurrenceStart = new Date(currentMs);
+        const occurrenceEnd = new Date(currentMs + duration);
 
         // Handle DST transitions
         const currentOffset = tzManager.getTimezoneOffset(occurrenceStart, eventTimezone);
@@ -65,7 +79,7 @@ export class RecurrenceEngine {
         lastOffset = currentOffset;
 
         // Apply exceptions if any
-        if (!this.isException(occurrenceStart, rule, event.id)) {
+        if (!hasExceptions || !this.isException(occurrenceStart, rule, event.id)) {
           occurrences.push({
             start: occurrenceStart,
             end: occurrenceEnd,
@@ -77,12 +91,13 @@ export class RecurrenceEngine {
       }
 
       // Calculate next occurrence
-      const previousTimestamp = currentDate.getTime();
-      currentDate = this.getNextOccurrence(currentDate, rule, eventTimezone);
+      this._advanceInPlace(currentDate, rule);
+      const previousTimestamp = currentMs;
+      currentMs = currentDate.getTime();
       count++;
 
       // Safeguard: detect if date is not advancing (infinite loop risk)
-      if (currentDate.getTime() === previousTimestamp) {
+      if (currentMs === previousTimestamp) {
         stuckCount++;
         if (stuckCount >= maxStuckIterations) {
           console.warn('RecurrenceEngine: Date not advancing, breaking to prevent infinite loop');
@@ -150,14 +165,36 @@ export class RecurrenceEngine {
 
   /**
    * Parse an RRULE string into a rule object
-   * @param {string|import('../../types.js').RecurrenceRule} ruleString - RRULE string (e.g., "FREQ=DAILY;INTERVAL=1;COUNT=10") or rule object
-   * @returns {import('../../types.js').RecurrenceRule} Parsed rule object
+   * @param {string|import('../types.js').RecurrenceRule} ruleString - RRULE string (e.g., "FREQ=DAILY;INTERVAL=1;COUNT=10") or rule object
+   * @returns {import('../types.js').RecurrenceRule} Parsed rule object
    */
   static parseRule(ruleString) {
     // Use the new comprehensive parser
     return RRuleParser.parse(ruleString);
   }
 
+  /**
+   * Parse a rule with caching for string rules (internal use by expandEvent).
+   * Cached rule objects are shared across calls and must not be mutated.
+   * @param {string|Object} recurrenceRule - RRULE string or rule object
+   * @returns {import('../types.js').RecurrenceRule} Parsed rule object
+   * @private
+   */
+  static _getParsedRule(recurrenceRule) {
+    if (typeof recurrenceRule !== 'string') {
+      return this.parseRule(recurrenceRule);
+    }
+    let rule = this._ruleCache.get(recurrenceRule);
+    if (!rule) {
+      rule = this.parseRule(recurrenceRule);
+      if (this._ruleCache.size >= this._RULE_CACHE_MAX) {
+        this._ruleCache.clear();
+      }
+      this._ruleCache.set(recurrenceRule, rule);
+    }
+    return rule;
+  }
+
   /**
    * Calculate the next occurrence based on the rule
    * @param {Date} currentDate - Current occurrence date
@@ -167,7 +204,18 @@ export class RecurrenceEngine {
    */
   static getNextOccurrence(currentDate, rule, _timezone = 'UTC') {
     const next = new Date(currentDate);
+    this._advanceInPlace(next, rule);
+    return next;
+  }
 
+  /**
+   * Advance a date to the next occurrence, mutating it in place.
+   * Used by expandEvent to avoid one Date allocation per step.
+   * @param {Date} next - Date to advance (mutated)
+   * @param {Object} rule - Recurrence rule object
+   * @private
+   */
+  static _advanceInPlace(next, rule) {
     switch (rule.freq) {
       case 'SECONDLY':
         next.setSeconds(next.getSeconds() + rule.interval);
@@ -187,21 +235,17 @@ export class RecurrenceEngine {
 
       case 'WEEKLY':
         if (rule.byDay && rule.byDay.length > 0) {
-          // Find next day that matches byDay
-          // Limit iterations to prevent infinite loop with malformed byDay
-          const maxIterations = 8; // 7 days + 1 for safety
-          let iterations = 0;
-          const originalDate = next.getDate();
-          next.setDate(next.getDate() + 1);
-          while (!this.matchesByDay(next, rule.byDay) && iterations < maxIterations) {
-            next.setDate(next.getDate() + 1);
-            iterations++;
-          }
-          // If no match found, fall back to simple weekly interval from original date
-          if (iterations >= maxIterations) {
+          // Jump straight to the next matching weekday using a delta table
+          // precompiled once per rule instead of stepping day by day
+          const daySet = rule._byDaySet || (rule._byDaySet = this._buildByDaySet(rule.byDay));
+          if (daySet.size > 0) {
+            const deltas =
+              rule._byDayDeltas || (rule._byDayDeltas = this._buildByDayDeltas(daySet));
+            next.setDate(next.getDate() + deltas[next.getDay()]);
+          } else {
+            // No valid day codes: fall back to simple weekly interval
             console.warn('RecurrenceEngine: Invalid byDay rule, falling back to weekly interval');
-            // Reset to original and add weekly interval
-            next.setDate(originalDate + 7 * rule.interval);
+            next.setDate(next.getDate() + 7 * rule.interval);
           }
         } else {
           // Simple weekly recurrence
@@ -215,7 +259,7 @@ export class RecurrenceEngine {
           const currentMonth = next.getMonth();
           next.setMonth(currentMonth + rule.interval);
           // Clamp to last day of month if day doesn't exist
-          const daysInMonth = new Date(next.getFullYear(), next.getMonth() + 1, 0).getDate();
+          const daysInMonth = this._daysInMonth(next.getFullYear(), next.getMonth());
           next.setDate(Math.min(rule.byMonthDay[0], daysInMonth));
         } else if (rule.byDay && rule.byDay.length > 0) {
           // Specific weekday of month (e.g., "2nd Tuesday")
@@ -246,8 +290,58 @@ export class RecurrenceEngine {
         // Unsupported frequency
         next.setTime(next.getTime() + 24 * 60 * 60 * 1000); // Daily fallback
     }
+  }
 
-    return next;
+  /**
+   * Days to add from each weekday (index 0-6) to reach the next weekday
+   * present in the given set
+   * @param {Set<number>} daySet - Non-empty set of weekday numbers
+   * @returns {number[]} Delta table indexed by Date#getDay()
+   * @private
+   */
+  static _buildByDayDeltas(daySet) {
+    const deltas = new Array(7);
+    for (let dow = 0; dow < 7; dow++) {
+      for (let d = 1; d <= 7; d++) {
+        if (daySet.has((dow + d) % 7)) {
+          deltas[dow] = d;
+          break;
+        }
+      }
+    }
+    return deltas;
+  }
+
+  /**
+   * Number of days in a month without allocating a Date
+   * @param {number} year - Full year
+   * @param {number} month - Month index (0-11)
+   * @returns {number}
+   * @private
+   */
+  static _daysInMonth(year, month) {
+    if (month === 1) {
+      return year % 4 === 0 && (year % 100 !== 0 || year % 400 === 0) ? 29 : 28;
+    }
+    return DAYS_IN_MONTH[month];
+  }
+
+  /**
+   * Build a Set of numeric weekdays (0-6) from BYDAY codes
+   * @param {Array<string>} byDay - Array of day codes (e.g., ['MO', '2TU'])
+   * @returns {Set<number>} Weekday numbers; invalid codes are skipped
+   * @private
+   */
+  static _buildByDaySet(byDay) {
+    const dayMap = { SU: 0, MO: 1, TU: 2, WE: 3, TH: 4, FR: 5, SA: 6 };
+    const set = new Set();
+    for (const day of byDay) {
+      const match = /^(-?\d+)?([A-Z]{2})$/.exec(day);
+      if (match && dayMap[match[2]] !== undefined) {
+        set.add(dayMap[match[2]]);
+      }
+    }
+    return set;
   }
 
   /**

package/core/ics/ICSHandler.js

@@ -106,7 +106,7 @@ export class ICSHandler {
 
       return results;
     } catch (error) {
-      throw new Error(`ICS import failed: ${error.message}`);
+      throw new Error(`ICS import failed: ${error.message}`, { cause: error });
     }
   }
 
@@ -221,9 +221,11 @@ export class ICSHandler {
       }
     } catch (error) {
       if (error.name === 'AbortError') {
-        throw new Error(`Failed to import from URL: request timed out after ${requestTimeout}ms`);
+        throw new Error(`Failed to import from URL: request timed out after ${requestTimeout}ms`, {
+          cause: error
+        });
       }
-      throw new Error(`Failed to import from URL: ${error.message}`);
+      throw new Error(`Failed to import from URL: ${error.message}`, { cause: error });
     }
   }
 

package/core/index.js

@@ -24,11 +24,15 @@ export { RecurrenceEngine } from './events/RecurrenceEngine.js';
 export { RecurrenceEngineV2 } from './events/RecurrenceEngineV2.js';
 export { RRuleParser } from './events/RRuleParser.js';
 
+// Timezone and Conflicts
+export { TimezoneManager } from './timezone/TimezoneManager.js';
+export { ConflictDetector } from './conflicts/ConflictDetector.js';
+
 // Enhanced Integration
 export { EnhancedCalendar } from './integration/EnhancedCalendar.js';
 
 // Version — keep in sync with package.json
-export const VERSION = '2.1.69';
+export const VERSION = '2.2.0';
 
 // Default export
 export { Calendar as default } from './calendar/Calendar.js';

package/core/state/StateManager.js

@@ -5,7 +5,7 @@
 export class StateManager {
   /**
    * Create a new StateManager instance
-   * @param {Partial<import('../../types.js').CalendarState>} [initialState={}] - Initial state values
+   * @param {Partial<import('../types.js').CalendarState>} [initialState={}] - Initial state values
    */
   constructor(initialState = {}) {
     this.state = {
@@ -75,7 +75,7 @@ export class StateManager {
 
   /**
    * Get the current state
-   * @returns {import('../../types.js').CalendarState} Current state (frozen)
+   * @returns {import('../types.js').CalendarState} Current state (frozen)
    */
   getState() {
     return Object.freeze({ ...this.state });
@@ -83,7 +83,7 @@ export class StateManager {
 
   /**
    * Get a specific state value
-   * @param {keyof import('../../types.js').CalendarState} key - The state key
+   * @param {keyof import('../types.js').CalendarState} key - The state key
    * @returns {any} The state value
    */
   get(key) {