silverbullet-icalendar/conductor/tracks/timezone_rrule_20260218/spec.md

Specification: Proper Timezone Handling & Recurring Events

Overview

Upgrade the SilverBullet iCalendar plug to provide accurate, DST-aware timezone resolution and full support for recurring events (RRULE expansion). This replaces manual hour shifting with an automated, reliable system using IANA timezone standards and the Intl API.

Functional Requirements

• IANA Timezone Mapping: Implement a comprehensive mapping of 139 Windows timezone names to IANA identifiers using Unicode CLDR data.
• DST-Aware Offsets: Calculate UTC offsets at runtime for specific event dates using the built-in Intl.DateTimeFormat API, ensuring accuracy during Daylight Saving Time transitions.
• Robust Date Extraction: Correct the wall-clock extraction logic to prevent "double-shifting" of event times.
• Recurring Event Expansion:
  • Integrate the rrule library to expand recurring events into individual occurrences.
  • Support EXDATE for excluding specific instances of a recurring series.
  • Implement a configurable syncWindowDays (default: 365) to limit the expansion range.
• Advanced Filtering:
  • Filter out "CANCELLED" events based on the iCalendar status field.
  • (Optional) Add includeTransparent and includeDeclined per-source flags.
• Error Handling & Fallbacks:
  • If a timezone is unrecognized, fallback to UTC and append a warning to the event's description.
• Configuration Cleanup:
  • Remove the redundant tzShift / hourShift parameters.
  • Add syncWindowDays global config.

Non-Functional Requirements

• Self-Contained: Maintain the plug as a Deno-compatible project using esm.sh or deno.json imports.
• Performance: Ensure efficient expansion of recurrences, even for busy calendars.

Acceptance Criteria

1. Events from various providers (Google, O365, Nextcloud) appear at the correct local time in SilverBullet, regardless of DST.
2. All occurrences of a weekly recurring event within the sync window are indexed.
3. Excluded dates (EXDATE) are correctly omitted from the index.
4. Cancelled events are not indexed.
5. The manual tzShift configuration is no longer required for correct time display.

Out of Scope

• Full CalDAV synchronization (this remains a read-only .ics fetcher).
• UI for managing individual recurring instances (handled via SilverBullet queries).