fix(calendar): RECURRENCE-ID handling — overrides replace their instance

Google exports every edited instance of a recurring event as a separate
VEVENT with the SAME UID plus RECURRENCE-ID naming the original
occurrence start. The parser treated those as independent events,
duplicating each edited occurrence (and breaking uid uniqueness — the
false-alarm diff from the move/resize QA).

parseIcs is now two-pass: protos collected, then overrides grouped per
UID and substituted for the matching expanded instance — moved/renamed
instances replace the original slot, STATUS:CANCELLED overrides delete
it, and overrides whose master never expanded (outside horizon,
unsupported rule, partial export) emit standalone rather than
vanishing. Instance uid keys stay unique (#i for plain instances,
#r<recurrence-id> for overrides). RANGE=THISANDFUTURE remains out of
scope (treated as a single-instance override).

Note: previously imported calendars carry the old duplicates in
localStorage — re-importing the .ics cleans them.

Co-Authored-By: Claude Fable 5 <[email protected]>

Author: snomiao

src/calendar/ics.test.ts

@@ -133,6 +133,60 @@ describe("parseIcs / serializeIcs", () => {
     expect(a.startMs).toBe(Date.UTC(2026, 6, 21, 13));
   });
 
+  test("RECURRENCE-ID overrides replace their instance (Google-style)", () => {
+    const text = [
+      "BEGIN:VCALENDAR",
+      "BEGIN:VEVENT",
+      "UID:std@x",
+      "DTSTART:20260706T090000Z",
+      "DTEND:20260706T093000Z",
+      "RRULE:FREQ=DAILY;COUNT=4",
+      "SUMMARY:Standup",
+      "END:VEVENT",
+      "BEGIN:VEVENT", // moved + renamed 2nd instance
+      "UID:std@x",
+      "RECURRENCE-ID:20260707T090000Z",
+      "DTSTART:20260707T140000Z",
+      "DTEND:20260707T143000Z",
+      "SUMMARY:Standup (moved)",
+      "END:VEVENT",
+      "BEGIN:VEVENT", // cancelled 3rd instance
+      "UID:std@x",
+      "RECURRENCE-ID:20260708T090000Z",
+      "DTSTART:20260708T090000Z",
+      "STATUS:CANCELLED",
+      "SUMMARY:Standup",
+      "END:VEVENT",
+      "END:VCALENDAR",
+    ].join("\r\n");
+    const cal = parseIcs(text, { fromMs: 0, toMs: Date.UTC(2027, 0, 1) });
+    const starts = cal.events.map((e) => new Date(e.startMs).toISOString().slice(0, 13)).sort();
+    // 4 instances − 1 cancelled = 3; the moved one sits at 14:00, no 09:00 dupe
+    expect(cal.events.length).toBe(3);
+    expect(starts).toEqual(["2026-07-06T09", "2026-07-07T14", "2026-07-09T09"]);
+    const moved = cal.events.find((e) => e.summary === "Standup (moved)")!;
+    expect(moved.endMs - moved.startMs).toBe(1800_000);
+    // uid keys stay unique
+    expect(new Set(cal.events.map((e) => e.uid)).size).toBe(3);
+  });
+
+  test("orphan overrides (master missing) emit standalone", () => {
+    const text = [
+      "BEGIN:VCALENDAR",
+      "BEGIN:VEVENT",
+      "UID:orphan@x",
+      "RECURRENCE-ID:20260701T100000Z",
+      "DTSTART:20260701T110000Z",
+      "DTEND:20260701T113000Z",
+      "SUMMARY:Rescheduled thing",
+      "END:VEVENT",
+      "END:VCALENDAR",
+    ].join("\r\n");
+    const cal = parseIcs(text, { fromMs: 0, toMs: Date.UTC(2027, 0, 1) });
+    expect(cal.events.length).toBe(1);
+    expect(cal.events[0]!.startMs).toBe(Date.UTC(2026, 6, 1, 11));
+  });
+
   test("long summaries fold at 74 chars and unfold back", () => {
     const long = "x".repeat(200);
     const text = serializeIcs([

src/calendar/ics.ts

@@ -224,6 +224,15 @@ export function expandRrule(
 
 // ── document parse / serialize ────────────────────────────────────────────
 
+type ProtoEvent = Partial<IcsEvent> & {
+  rrule?: string;
+  durMs?: number;
+  exdates?: Set<number>;
+  /** RECURRENCE-ID: this VEVENT overrides ONE instance of the same-UID series */
+  recurrenceId?: number;
+  cancelled?: boolean;
+};
+
 export function parseIcs(
   text: string,
   opts: { fromMs?: number; toMs?: number } = {},
@@ -232,51 +241,28 @@ export function parseIcs(
   const toMs = opts.toMs ?? Date.now() + 2 * 365 * DAY_MS;
   const lines = unfoldLines(text);
   const cal: IcsCalendar = { events: [] };
-  let ev: Partial<IcsEvent> & { rrule?: string; durMs?: number; exdates?: Set<number> } | null = null;
-  let uidSeq = 0;
+
+  // pass 1 — collect every VEVENT as a proto record
+  const protos: ProtoEvent[] = [];
+  let ev: ProtoEvent | null = null;
   for (const line of lines) {
     const p = parseLine(line);
     if (!p) continue;
     if (p.name === "X-WR-CALNAME") cal.name = unescapeText(p.value).trim();
     else if (p.name === "BEGIN" && p.value.toUpperCase() === "VEVENT") ev = {};
     else if (p.name === "END" && p.value.toUpperCase() === "VEVENT") {
-      if (ev && ev.startMs !== undefined) {
-        const allDay = ev.allDay ?? false;
-        const endMs =
-          ev.endMs ??
-          (ev.durMs != null ? ev.startMs + ev.durMs : ev.startMs + (allDay ? DAY_MS : HOUR_MS));
-        const base: IcsEvent = {
-          uid: ev.uid ?? `ics-${++uidSeq}`,
-          summary: ev.summary ?? "(untitled)",
-          location: ev.location,
-          description: ev.description,
-          startMs: ev.startMs,
-          endMs,
-          allDay,
-        };
-        if (ev.rrule) {
-          const starts = expandRrule(ev.rrule, base.startMs, fromMs, toMs);
-          if (starts === null) {
-            cal.events.push({ ...base, recurring: true });
-          } else {
-            const dur = base.endMs - base.startMs;
-            let i = 0;
-            for (const s of starts) {
-              if (ev.exdates?.has(s)) continue;
-              cal.events.push({ ...base, uid: `${base.uid}#${i++}`, startMs: s, endMs: s + dur });
-            }
-          }
-        } else if (!ev.exdates?.has(base.startMs)) {
-          cal.events.push(base);
-        }
-      }
+      if (ev && ev.startMs !== undefined) protos.push(ev);
       ev = null;
     } else if (ev) {
       if (p.name === "UID") ev.uid = p.value.trim();
       else if (p.name === "SUMMARY") ev.summary = unescapeText(p.value).trim();
       else if (p.name === "LOCATION") ev.location = unescapeText(p.value).trim();
       else if (p.name === "DESCRIPTION") ev.description = unescapeText(p.value).trim();
-      else if (p.name === "DTSTART") {
+      else if (p.name === "STATUS") ev.cancelled = p.value.trim().toUpperCase() === "CANCELLED";
+      else if (p.name === "RECURRENCE-ID") {
+        const d = parseIcsDate(p.value.trim(), p.params);
+        if (d) ev.recurrenceId = d.ms;
+      } else if (p.name === "DTSTART") {
         const d = parseIcsDate(p.value.trim(), p.params);
         if (d) {
           ev.startMs = d.ms;
@@ -296,6 +282,75 @@ export function parseIcs(
       }
     }
   }
+
+  // pass 2 — emit. Overrides (same UID + RECURRENCE-ID) REPLACE the matching
+  // expanded instance of their series (Google exports every edited instance
+  // of a recurring event this way); STATUS:CANCELLED overrides delete it;
+  // overrides whose master never expanded (outside horizon, unsupported
+  // rule, partial export) emit standalone rather than vanishing.
+  let uidSeq = 0;
+  const finish = (p: ProtoEvent, uid: string): IcsEvent => {
+    const allDay = p.allDay ?? false;
+    const endMs =
+      p.endMs ??
+      (p.durMs != null ? p.startMs! + p.durMs : p.startMs! + (allDay ? DAY_MS : HOUR_MS));
+    return {
+      uid,
+      summary: p.summary ?? "(untitled)",
+      location: p.location,
+      description: p.description,
+      startMs: p.startMs!,
+      endMs,
+      allDay,
+    };
+  };
+  const ovByUid = new Map<string, Map<number, ProtoEvent>>();
+  for (const p of protos) {
+    if (p.recurrenceId === undefined || !p.uid) continue;
+    let m = ovByUid.get(p.uid);
+    if (!m) ovByUid.set(p.uid, (m = new Map()));
+    m.set(p.recurrenceId, p);
+  }
+  const consumed = new Set<ProtoEvent>();
+  for (const p of protos) {
+    if (p.recurrenceId !== undefined) continue; // overrides emit via masters
+    const uid = p.uid ?? `ics-${++uidSeq}`;
+    const overrides = p.uid ? ovByUid.get(p.uid) : undefined;
+    if (p.rrule) {
+      const starts = expandRrule(p.rrule, p.startMs!, fromMs, toMs);
+      if (starts === null) {
+        if (!p.cancelled) cal.events.push({ ...finish(p, uid), recurring: true });
+        continue;
+      }
+      const dur = (p.endMs ?? p.startMs! + (p.durMs ?? (p.allDay ? DAY_MS : HOUR_MS))) - p.startMs!;
+      let i = 0;
+      for (const s of starts) {
+        if (p.exdates?.has(s)) continue;
+        const ov = overrides?.get(s);
+        if (ov) {
+          consumed.add(ov);
+          if (!ov.cancelled) cal.events.push(finish(ov, `${uid}#r${s}`));
+          continue;
+        }
+        cal.events.push({ ...finish(p, `${uid}#${i++}`), startMs: s, endMs: s + dur });
+      }
+      continue;
+    }
+    if (p.cancelled || p.exdates?.has(p.startMs!)) continue;
+    // even a non-recurring master can be overridden (degenerate but legal)
+    const ov = overrides?.get(p.startMs!);
+    if (ov) {
+      consumed.add(ov);
+      if (!ov.cancelled) cal.events.push(finish(ov, `${uid}#r${p.startMs}`));
+      continue;
+    }
+    cal.events.push(finish(p, uid));
+  }
+  for (const p of protos) {
+    if (p.recurrenceId === undefined || consumed.has(p) || p.cancelled) continue;
+    const uid = p.uid ?? `ics-${++uidSeq}`;
+    cal.events.push(finish(p, `${uid}#r${p.recurrenceId}`)); // orphan override
+  }
   return cal;
 }