@forcecalendar/core 2.1.70 → 2.3.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

@@ -24,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
@@ -34,20 +34,72 @@ export class RecurrenceEngine {
     }
 
     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
-    const currentDate = new Date(event.start);
-    let count = 0;
-
     // If UNTIL is specified, use it as the range end
     if (rule.until && rule.until < rangeEnd) {
       rangeEnd = rule.until;
     }
 
+    // DAILY and WEEKLY series iterate on numeric timestamps (no Date
+    // arithmetic per step); other frequencies use the general loop
+    let occurrences = null;
+    if (rule.freq === 'DAILY' || rule.freq === 'WEEKLY') {
+      occurrences = this._expandFast(
+        event,
+        rule,
+        rangeStart.getTime(),
+        rangeEnd.getTime(),
+        maxOccurrences,
+        eventTimezone,
+        tzManager,
+        duration
+      );
+    }
+    if (!occurrences) {
+      occurrences = this._expandGeneral(
+        event,
+        rule,
+        rangeStart.getTime(),
+        rangeEnd.getTime(),
+        maxOccurrences,
+        eventTimezone,
+        tzManager,
+        duration
+      );
+    }
+
+    // Apply BYSETPOS filtering if present and not already handled by MONTHLY+byDay
+    if (rule.bySetPos && rule.bySetPos.length > 0 && rule.freq !== 'MONTHLY') {
+      return this._applyBySetPos(occurrences, rule);
+    }
+
+    return occurrences;
+  }
+
+  /**
+   * General expansion loop: advances a Date cursor per step. Handles every
+   * frequency and degenerate rules (non-advancing dates, invalid intervals).
+   * @private
+   */
+  static _expandGeneral(
+    event,
+    rule,
+    rangeStartMs,
+    rangeEndMs,
+    maxOccurrences,
+    eventTimezone,
+    tzManager,
+    duration
+  ) {
+    const occurrences = [];
+
+    // Work in event's timezone for accurate recurrence calculation
+    const currentDate = new Date(event.start);
+    let count = 0;
+
     // Track DST transitions for proper timezone handling
     let lastOffset = tzManager.getTimezoneOffset(currentDate, eventTimezone);
 
@@ -57,8 +109,6 @@ export class RecurrenceEngine {
 
     // 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();
 
@@ -113,14 +163,179 @@ export class RecurrenceEngine {
       }
     }
 
-    // Apply BYSETPOS filtering if present and not already handled by MONTHLY+byDay
-    if (rule.bySetPos && rule.bySetPos.length > 0 && rule.freq !== 'MONTHLY') {
-      return this._applyBySetPos(occurrences, rule);
+    return occurrences;
+  }
+
+  /**
+   * Numeric expansion loop for DAILY and WEEKLY rules.
+   *
+   * Between DST transitions a wall-clock-preserving day step is a constant
+   * number of milliseconds, so the loop is pure numeric addition. Transition
+   * instants — in the system timezone (which defines Date arithmetic) and in
+   * the event's timezone (which drives occurrence adjustment) — are
+   * discovered by binary search and cached, so only the one step that
+   * crosses a transition falls back to Date arithmetic, and only the first
+   * occurrence after a transition queries a timezone offset.
+   *
+   * Produces output identical to _expandGeneral for the rules it accepts;
+   * returns null to delegate anything it cannot handle exactly.
+   * @private
+   */
+  static _expandFast(
+    event,
+    rule,
+    rangeStartMs,
+    rangeEndMs,
+    maxOccurrences,
+    eventTimezone,
+    tzManager,
+    duration
+  ) {
+    const DAY = 86400000;
+    let dayDeltas = null;
+    let stepDays = 0;
+    let weekday = 0;
+
+    const startDate = new Date(event.start);
+    if (rule.freq === 'WEEKLY' && rule.byDay && rule.byDay.length > 0) {
+      const daySet = rule._byDaySet || (rule._byDaySet = this._buildByDaySet(rule.byDay));
+      if (daySet.size === 0) {
+        return null; // invalid byDay — general loop handles the fallback warning
+      }
+      dayDeltas = rule._byDayDeltas || (rule._byDayDeltas = this._buildByDayDeltas(daySet));
+      weekday = startDate.getDay();
+    } else {
+      stepDays = (rule.freq === 'DAILY' ? 1 : 7) * rule.interval;
+      if (!Number.isInteger(stepDays) || stepDays <= 0) {
+        return null; // degenerate interval — general loop's stuck detection applies
+      }
+    }
+
+    const occurrences = [];
+    let currentMs = startDate.getTime();
+    if (Number.isNaN(currentMs)) {
+      return null;
+    }
+    let count = 0;
+    const hasExceptions = !!(rule.exceptions && rule.exceptions.length > 0);
+
+    let lastOffset = tzManager.getTimezoneOffset(startDate, eventTimezone);
+    let nextEventTzTransition = tzManager.getNextTransition(eventTimezone, currentMs, rangeEndMs);
+    let nextSystemTransition = this._nextSystemTransition(currentMs, rangeEndMs);
+
+    while (currentMs <= rangeEndMs && count < maxOccurrences) {
+      if (currentMs >= rangeStartMs) {
+        const occurrenceStart = new Date(currentMs);
+        const occurrenceEnd = new Date(currentMs + duration);
+
+        // Only the first occurrence past a transition needs an offset check
+        if (currentMs >= nextEventTzTransition) {
+          const currentOffset = tzManager.getTimezoneOffset(occurrenceStart, eventTimezone);
+          if (currentOffset !== lastOffset) {
+            const offsetDiff = lastOffset - currentOffset;
+            occurrenceStart.setMinutes(occurrenceStart.getMinutes() + offsetDiff);
+            occurrenceEnd.setMinutes(occurrenceEnd.getMinutes() + offsetDiff);
+            lastOffset = currentOffset;
+          }
+          nextEventTzTransition = tzManager.getNextTransition(eventTimezone, currentMs, rangeEndMs);
+        }
+
+        if (!hasExceptions || !this.isException(occurrenceStart, rule, event.id)) {
+          occurrences.push({
+            start: occurrenceStart,
+            end: occurrenceEnd,
+            recurringEventId: event.id,
+            timezone: eventTimezone,
+            originalStart: event.start
+          });
+        }
+      }
+
+      // Advance: pure addition unless the step crosses a system-timezone
+      // transition, where Date arithmetic reproduces wall-clock semantics
+      const days = dayDeltas ? dayDeltas[weekday] : stepDays;
+      if (dayDeltas) {
+        weekday = (weekday + days) % 7;
+      }
+      const naiveMs = currentMs + days * DAY;
+      if (naiveMs >= nextSystemTransition) {
+        const cursor = new Date(currentMs);
+        cursor.setDate(cursor.getDate() + days);
+        currentMs = cursor.getTime();
+        nextSystemTransition = this._nextSystemTransition(currentMs, rangeEndMs);
+      } else {
+        currentMs = naiveMs;
+      }
+      count++;
+
+      if (rule.count && count >= rule.count) {
+        break;
+      }
     }
 
     return occurrences;
   }
 
+  /**
+   * Find the next system-timezone offset transition after fromMs.
+   * Cached module-wide: the system timezone is fixed for the process.
+   * @param {number} fromMs - Search from this timestamp (exclusive)
+   * @param {number} toMs - Extend cache coverage at least this far
+   * @returns {number} Transition timestamp, or Infinity if none within coverage
+   * @private
+   */
+  static _nextSystemTransition(fromMs, toMs) {
+    if (fromMs >= toMs) {
+      return Infinity;
+    }
+    let cache = this._systemTransitions;
+    if (!cache || fromMs < cache.from || toMs > cache.to) {
+      const from = Math.min(fromMs, cache ? cache.from : fromMs);
+      const to = Math.max(toMs, cache ? cache.to : toMs);
+      cache = { from, to, transitions: this._scanSystemTransitions(from, to) };
+      this._systemTransitions = cache;
+    }
+    for (const t of cache.transitions) {
+      if (t > fromMs) {
+        return t;
+      }
+    }
+    return Infinity;
+  }
+
+  /**
+   * Scan for system-timezone offset transitions via Date#getTimezoneOffset.
+   * Probes weekly (shorter than any real-world gap between transitions)
+   * and binary-searches each change to the exact millisecond.
+   * @private
+   */
+  static _scanSystemTransitions(fromMs, toMs) {
+    const WEEK = 7 * 86400000;
+    const transitions = [];
+    let lo = fromMs;
+    let loOffset = new Date(lo).getTimezoneOffset();
+    while (lo < toMs) {
+      const hi = Math.min(lo + WEEK, toMs);
+      const hiOffset = new Date(hi).getTimezoneOffset();
+      if (hiOffset !== loOffset) {
+        let a = lo;
+        let b = hi;
+        while (b - a > 1) {
+          const mid = Math.floor((a + b) / 2);
+          if (new Date(mid).getTimezoneOffset() === loOffset) {
+            a = mid;
+          } else {
+            b = mid;
+          }
+        }
+        transitions.push(b);
+        loOffset = hiOffset;
+      }
+      lo = hi;
+    }
+    return transitions;
+  }
+
   /**
    * Apply BYSETPOS to filter occurrences within each frequency period
    * @param {Array} occurrences - Generated occurrences
@@ -165,8 +380,8 @@ 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
@@ -177,7 +392,7 @@ export class RecurrenceEngine {
    * 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
+   * @returns {import('../types.js').RecurrenceRule} Parsed rule object
    * @private
    */
   static _getParsedRule(recurrenceRule) {

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.70';
+export const VERSION = '2.3.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) {