@open-webapp/calendar 0.1.0 → 0.2.0

package/README.md

@@ -2,6 +2,8 @@
 
 Multi-account Google Calendar read-only sync (controller) plus React UI (`CalendarPane`, `CalendarSelector`). Storage and encryption are host-supplied adapters.
 
+> **0.2.0 is BREAKING.** See [Breaking changes in 0.2.0](#breaking-changes-in-020).
+
 ## Install
 
 ```bash
@@ -30,13 +32,18 @@ const controller = createCalendarController({
   storage,   // StorageAdapter
   crypto,    // CryptoAdapter
 });
-await controller.refresh();
+await controller.hydrate();  // publishes cached events immediately (no network)
+void controller.refresh();   // then syncs from Google
 
 <CalendarPane
   sources={sources}
   controller={controller}
   selectedRsvpStatuses={statuses}          // Set<RsvpStatus>
   onRsvpStatusesChange={setStatuses}
+  connected={connected}                    // optional, see CalendarPane props
+  needsReauth={needsReauth}
+  onConnect={connect}
+  onReconnect={reconnect}
 />
 ```
 
@@ -44,21 +51,58 @@ await controller.refresh();
 
 `createCalendarController({ sources, getToken, storage, crypto, now? })`
 
+- `hydrate(): Promise<void>` loads the stored rows and publishes cached events before any network call. Never throws. Offline, the cache stays visible.
 - `refresh(): Promise<void>` syncs every source in parallel; never throws.
-- `getEvents(): CalendarEvent[]` stable snapshot (updated on `refresh`/`setSelectedIds`), sources concatenated in `sources` order.
+- `retryDeferred(): Promise<void>` re-runs a refresh after a deferred pass (see [Deferred refresh](#deferred-refresh)).
+- `getEvents(): CalendarEvent[]` stable snapshot (updated on `hydrate`/`refresh`/`setSelectedIds`/`clearSelectedIds`), sources concatenated in `sources` order. Only events that pass the read-time filter are returned (see [Window](#window)).
+- `getState(): { loading, error, deferred, lastSyncAt }`:
+  - `loading`: a refresh pass is in flight.
+  - `error`: true only when every selected calendar (across sources) errored and nothing is cached.
+  - `deferred`: the last pass was deferred.
+  - `lastSyncAt`: ms epoch of the most recent refresh pass across sources, or `null`.
 - `getSourceStatus()` / `sourceStatus`: `Record<sourceId, 'ok' | 'needs-scope' | 'error'>`.
 - `getCalendars(sourceId)`, `getSelectedIds(sourceId)`.
-- `setSelectedIds(sourceId, ids)`: primary calendar is always kept; drops events/tokens of deselected calendars, persists, notifies.
-- `clearSelectedIds(sourceId)`: same as `setSelectedIds(sourceId, [])` (leaves primary only).
+- `setSelectedIds(sourceId, ids)`: see [Selection](#selection). Fetches calendars newly added to the selection; drops nothing it has cached for deselected calendars.
+- `clearSelectedIds(sourceId)`: resets the selection to the primary calendar.
 - `subscribe(listener): () => void`.
 
+### Selection
+
+- Default selection is the primary calendar.
+- On refresh, the stored selection is filtered to calendars that still exist. If none remain, the selection falls back to the primary calendar (else the first calendar).
+- Primary is not forced: a stored selection that omits primary is kept.
+- `setSelectedIds(id, [])` is ignored; at least one calendar always remains selected. Use `clearSelectedIds` to reset to primary.
+- `setSelectedIds` persists the selection and fetches any calendars newly added to it.
+- Deselecting a calendar keeps its cached events and sync tokens (retained, hidden by the read-time filter). Re-selecting it shows the cache immediately and syncs it.
+
 ### sourceStatus
 
-- `ok`: last refresh succeeded (also the initial value).
+- `ok`: last refresh succeeded, or only some calendars failed (also the initial value).
 - `needs-scope`: Google returned 403 `insufficientPermissions`; the host should prompt re-consent.
 - `error`: any other failure (401, 5xx, non-403 HTTP, unexpected exception).
 - Network failures leave the previous status unchanged and keep cached events.
 
+### Deferred refresh
+
+- A host `getToken` (or fetch path) may throw `RefreshDeferredError`, or any error with `deferred: true`. `isRefreshDeferredError(e)` recognises both.
+- A deferred pass is quiet: it does not change `sourceStatus`, does not set `getState().error`, and is not retried immediately. `getState().deferred` becomes `true`; the host calls `retryDeferred()` when it is ready.
+
+## Sync behavior
+
+Per calendar:
+
+- Full (windowed) sync when there is no sync token, no `lastFullSyncAt` for that calendar, or the last full sync is more than 24h old. Full sync uses `singleEvents=true`, window now -30d .. now +30d (RFC3339, no milliseconds), all pages (`maxResults=250`), and stores `nextSyncToken` and `lastFullSyncAt`.
+- Otherwise incremental with `syncToken` (no time bounds); cancelled items remove events.
+- HTTP 410 (`gone`): token dropped, full windowed resync.
+- A failing calendar is retried once immediately (deferred errors are not retried).
+- Calendars are isolated: one failing calendar keeps its cached events and token; other calendars and sources are unaffected.
+- Per-source status: if some targeted calendars succeed and none reports a scope error, the source is `ok` (failed calendars keep their cached events). A scope error gives `needs-scope`. If every targeted calendar fails, the status follows the `sourceStatus` rules above (`error` for non-network failures, unchanged on network-only failures).
+
+### Window
+
+- Stored events whose end is strictly before now -30d are pruned on refresh.
+- Read-time filter (`getEvents()`): events on deselected calendars are hidden; events are kept when they end after now -30d and start before now +30d (edges excluded, overlaps kept).
+
 ## Adapters
 
 ```ts
@@ -69,12 +113,18 @@ interface StorageAdapter {
   clear(sourceId): Promise<void>;
 }
 interface StorageRow { events: CalendarEvent[] | string | unknown[]; syncState: SyncState | string | null | unknown; selectedIds: string[] }
-interface SyncState { tokens: Record<calendarId, string> }
+interface SyncState {
+  tokens: Record<calendarId, string>;
+  lastFullSyncAt?: Record<calendarId, number>; // ms epoch; absent on 0.1.0 rows
+  lastSyncAt?: number;                         // ms epoch; absent on 0.1.0 rows
+}
 interface CryptoAdapter { encrypt(s: string): Promise<string>; decrypt(s: string): Promise<string> }
 ```
 
 The controller writes `events` and `syncState` as `crypto.encrypt(JSON.stringify(...))` strings and `selectedIds` as a plain array. On read, string values are decrypted and parsed; non-string (legacy plain) values are used as-is. Corrupt rows or decrypt failures read back as empty.
 
+Rows written by 0.1.0 (no `lastFullSyncAt`/`lastSyncAt`, no retained-calendar data) still read. A missing `lastFullSyncAt` triggers one full windowed sync on the next refresh.
+
 ### Contract harness
 
 ```ts
@@ -84,12 +134,9 @@ runStorageAdapterContract(() => ({ storage, crypto, seedRaw?, wrongKeyCrypto?, e
 
 Call at top level of a vitest file; it registers a `describe('StorageAdapter contract')` suite (round trip, source isolation, delete/clear, missing source, legacy plain row, legacy encrypted fixture, corrupt row, wrong key).
 
-## Sync behavior
+### Event key
 
-- First sync per calendar: full fetch, `singleEvents=true`, window now -30d .. now +30d (RFC3339, no milliseconds), all pages (`maxResults=250`); stores `nextSyncToken`.
-- Later syncs: incremental with `syncToken` (no time bounds); cancelled items remove events.
-- HTTP 410: token dropped, full windowed resync.
-- Several sources are fetched independently; one failing source does not affect others.
+`getCalendarEventKey(event)` returns `${sourceId}:${calendarId}:${eventId}` (e.g. `src1:calA:ev1`). This multi-source form is the one intentional divergence from notesdiary (`calA:ev1`), kept by decision for multi-source.
 
 ## UI
 
@@ -102,14 +149,26 @@ Call at top level of a vitest file; it registers a `describe('StorageAdapter con
 | `selectedRsvpStatuses` | `Set<RsvpStatus>` | filter; `DEFAULT_RSVP_STATUSES` = accepted, tentative, needsAction |
 | `onRsvpStatusesChange` | `(next) => void` | |
 | `renderEventAction?` | `(event) => ReactNode` | per-event slot |
-| `emptyState?` | `ReactNode` | shown when no sources are connected |
-| `sourceNotice?` | `(source) => ReactNode` | per-source slot (e.g. re-consent button when `needs-scope`) |
+| `connected?` | `boolean` | defaults to `sources.length > 0` (back-compat). `false` shows the not-connected block |
+| `needsReauth?` | `boolean` | defaults to every source being `needs-scope`. Shows the reauth block |
+| `onConnect?` | `() => void` | wired to the built-in "Connect Google Calendar" button |
+| `onReconnect?` | `() => void` | wired to the built-in "Reconnect to restore sync" button |
+| `emptyState?` | `ReactNode` | replaces the built-in not-connected block |
+| `sourceNotice?` | `(source) => ReactNode` | per-source slot, rendered for `needs-scope` sources (e.g. re-consent button); without it the built-in reauth block is shown |
 | `onClose?` | `() => void` | |
 | `popupName?` | `string` | `window.open` name for the event popup (default `notesdiary-cal-event`) |
 
+Built-in copy (overridable only through the slots above):
+
+- Not connected: "Not connected to Google Calendar." with "Connect Google Calendar".
+- Reauth: "Calendar connection needs reauthorization." with "Reconnect to restore sync".
+- Error with nothing cached: "Couldn't load calendar events. Try again shortly."
+- Loading: "Loading calendar…".
+- Empty: "No matching events in the next 30 days".
+
 ### CalendarSelector props
 
-`calendars: CalendarInfo[]`, `selectedIds: string[]`, `onChange(ids)`, `heading?: string` (account heading in multi-source use). It has no slot props or `popupName`. At least one calendar stays selected; "Clear" resets to the primary calendar.
+`calendars: CalendarInfo[]`, `selectedIds: string[]`, `onChange(ids)`, `heading?: string` (account heading in multi-source use). It has no slot props or `popupName`. At least one calendar stays selected (deselecting the last one is ignored). "Clear" resets to the primary calendar. Built-in copy: "Search calendars", "Select all", "Clear", "Done", "No calendars found", "No calendars available".
 
 ### Host CSS
 
@@ -118,3 +177,12 @@ Call at top level of a vitest file; it registers a `describe('StorageAdapter con
 - `--calendar-footer-height` (default `64px`, set on `.calendar-pane`; override to match host footer)
 - `--chip-row-height` (fallback `44px`; host may set it to match its chip row for sticky headers)
 - `--rsvp-bar` (set internally per RSVP status; do not override)
+
+## Breaking changes in 0.2.0
+
+BREAKING (0.1.0 to 0.2.0):
+
+- **Selection semantics.** Primary is no longer forced into the selection. Stored selections are honored (filtered to existing calendars). `setSelectedIds` no longer always adds primary, and an empty list is ignored. `clearSelectedIds` resets to primary.
+- **Cache and storage rows.** `setSelectedIds` no longer drops events and sync tokens of deselected calendars; they are retained. `syncState` gains optional `lastFullSyncAt` and `lastSyncAt`. Window pruning and the read-time window filter are new. 0.1.0 rows still read (missing fields take their defaults).
+- **Pane behavior.** `CalendarPane` gains `connected`, `needsReauth`, `onConnect`, `onReconnect`. Omitting `connected` keeps the old behavior (`sources.length > 0`). Deferred refreshes are quiet. `getState()` and `hydrate()` are new; hosts that want cache-first display should call `hydrate()` before `refresh()`.
+- Unchanged: event key form (`src1:calA:ev1`), `sourceStatus` values, `StorageAdapter`/`CryptoAdapter` signatures.

package/dist/core/controller.d.ts

@@ -8,8 +8,19 @@ export interface CalendarControllerOptions {
     crypto: CryptoAdapter;
     now?: () => Date;
 }
+export interface CalendarControllerState {
+    loading: boolean;
+    /** True only when every selected calendar failed and nothing is cached. */
+    error: boolean;
+    deferred: boolean;
+    lastSyncAt: number | null;
+}
 export interface CalendarController {
+    hydrate(): Promise<void>;
     refresh(): Promise<void>;
+    /** Re-runs a refresh after a deferred pass. */
+    retryDeferred(): Promise<void>;
+    getState(): CalendarControllerState;
     getEvents(): CalendarEvent[];
     getSourceStatus(): Record<string, SourceStatus>;
     readonly sourceStatus: Record<string, SourceStatus>;

package/dist/core/controller.js

@@ -1,4 +1,4 @@
-import { CalendarFetchError, fetchCalendarList } from './fetch.js';
+import { CalendarFetchError, fetchCalendarList, isRefreshDeferredError } from './fetch.js';
 import { reconcileSelection } from './reconcile.js';
 import { syncCalendar } from './sync.js';
 export function createCalendarController(opts) {
@@ -7,19 +7,35 @@ export function createCalendarController(opts) {
     const state = new Map();
     const listeners = new Set();
     let snapshot = [];
+    let loadingCount = 0;
+    let deferred = false;
     let statusSnapshot = {};
     for (const s of sources) {
         state.set(s.id, {
             loaded: false,
             events: [],
             syncState: { tokens: {} },
-            selectedIds: [],
+            selectedIds: ['primary'],
             calendars: [],
             status: 'ok',
+            errored: new Set(),
+            gen: 0,
         });
     }
     function publish() {
-        snapshot = sources.flatMap((s) => state.get(s.id).events);
+        snapshot = sources.flatMap((s) => {
+            const st = state.get(s.id);
+            const ws = now().getTime() - 30 * 86400000;
+            const we = now().getTime() + 30 * 86400000;
+            const ms = (v, d) => {
+                const t = v ? new Date(v).getTime() : NaN;
+                return Number.isNaN(t) ? d : t;
+            };
+            // read-time window: exact edges excluded, overlaps kept (notesdiary loadCached)
+            return st.events.filter((e) => (!e.calendarId || st.selectedIds.includes(e.calendarId)) &&
+                ms(e.end.dateTime ?? e.end.date, Infinity) > ws &&
+                ms(e.start.dateTime ?? e.start.date, -Infinity) < we);
+        });
         statusSnapshot = Object.fromEntries(sources.map((s) => [s.id, state.get(s.id).status]));
         listeners.forEach((l) => l());
     }
@@ -46,7 +62,8 @@ export function createCalendarController(opts) {
             st.events = await decode(row.events, []);
             const ss = await decode(row.syncState, null);
             st.syncState = ss && ss.tokens ? ss : { tokens: {} };
-            st.selectedIds = Array.isArray(row.selectedIds) ? row.selectedIds : [];
+            if (Array.isArray(row.selectedIds))
+                st.selectedIds = row.selectedIds;
         }
         catch {
             /* unreadable cache: start empty */
@@ -65,37 +82,87 @@ export function createCalendarController(opts) {
             /* persistence is best-effort */
         }
     }
-    async function refreshSource(sourceId) {
+    async function syncWithRetry(run) {
+        try {
+            return await run();
+        }
+        catch (e) {
+            if (isRefreshDeferredError(e))
+                throw e;
+            return run();
+        }
+    }
+    /** Returns true when the pass was deferred. `only` limits syncing to those calendars. */
+    async function refreshSource(sourceId, only) {
         const st = state.get(sourceId);
         await load(sourceId);
+        const gen = st.gen;
+        let wasDeferred = false;
         try {
             const token = await getToken(sourceId);
             const calendars = await fetchCalendarList(token);
             st.calendars = calendars;
             const selected = reconcileSelection(st.selectedIds, calendars);
-            const next = [];
-            const tokens = {};
-            for (const calendarId of selected) {
-                const res = await syncCalendar({
-                    token,
-                    sourceId,
-                    calendarId,
-                    existing: st.events.filter((e) => e.calendarId === calendarId),
-                    syncToken: st.syncState.tokens[calendarId],
-                    now: now(),
-                });
-                next.push(...res.events);
-                if (res.syncToken)
-                    tokens[calendarId] = res.syncToken;
+            const targets = only ? selected.filter((c) => only.includes(c)) : selected;
+            const fresh = [];
+            const synced = [];
+            const tokens = { ...st.syncState.tokens };
+            const lastFull = { ...st.syncState.lastFullSyncAt };
+            const failures = [];
+            for (const calendarId of targets) {
+                try {
+                    const res = await syncWithRetry(() => syncCalendar({
+                        token,
+                        sourceId,
+                        calendarId,
+                        existing: st.events.filter((e) => e.calendarId === calendarId),
+                        syncToken: st.syncState.tokens[calendarId],
+                        lastFullSyncAt: st.syncState.lastFullSyncAt?.[calendarId],
+                        now: now(),
+                    }));
+                    fresh.push(...res.events);
+                    synced.push(calendarId);
+                    st.errored.delete(calendarId);
+                    if (res.syncToken)
+                        tokens[calendarId] = res.syncToken;
+                    else
+                        delete tokens[calendarId];
+                    if (res.full)
+                        lastFull[calendarId] = now().getTime();
+                }
+                catch (e) {
+                    if (isRefreshDeferredError(e))
+                        throw e;
+                    failures.push(e);
+                    st.errored.add(calendarId);
+                }
             }
-            st.events = next;
-            st.syncState = { tokens };
-            st.selectedIds = selected;
-            st.status = 'ok';
-            await persist(sourceId);
+            const winStart = new Date(now().getTime() - 30 * 86400000).getTime();
+            const endMs = (e) => {
+                const v = e.end.dateTime ?? e.end.date;
+                const t = v ? new Date(v).getTime() : NaN;
+                return Number.isNaN(t) ? Infinity : t;
+            };
+            st.events = [...st.events.filter((e) => !(e.calendarId && synced.includes(e.calendarId))), ...fresh].filter((e) => endMs(e) >= winStart);
+            st.syncState = { ...st.syncState, tokens, lastFullSyncAt: lastFull };
+            if (st.gen === gen)
+                st.selectedIds = selected;
+            if (failures.length === 0)
+                st.status = 'ok';
+            else if (failures.some((e) => e instanceof CalendarFetchError && e.kind === 'scope'))
+                st.status = 'needs-scope';
+            else if (failures.length < targets.length)
+                st.status = 'ok';
+            else if (failures.some((e) => !(e instanceof CalendarFetchError) || e.kind !== 'network'))
+                st.status = 'error';
         }
         catch (e) {
-            if (e instanceof CalendarFetchError) {
+            if (st.selectedIds.length === 0)
+                st.selectedIds = ['primary'];
+            if (isRefreshDeferredError(e)) {
+                wasDeferred = true;
+            }
+            else if (e instanceof CalendarFetchError) {
                 if (e.kind === 'scope')
                     st.status = 'needs-scope';
                 else if (e.kind !== 'network')
@@ -105,34 +172,66 @@ export function createCalendarController(opts) {
                 st.status = 'error';
             }
         }
+        st.syncState = { ...st.syncState, lastSyncAt: now().getTime() };
+        await persist(sourceId);
+        return wasDeferred;
+    }
+    async function runPass(only) {
+        loadingCount++;
+        try {
+            const ids = sources.map((s) => s.id).filter((id) => !only || only[id]);
+            const results = await Promise.all(ids.map((id) => refreshSource(id, only?.[id])));
+            deferred = results.some(Boolean);
+        }
+        catch {
+            /* never throws */
+        }
+        finally {
+            loadingCount--;
+        }
+        publish();
     }
     async function setSelected(sourceId, ids) {
         const st = state.get(sourceId);
         if (!st)
             return;
         await load(sourceId);
-        const primary = st.calendars.find((c) => c.primary)?.id ?? (st.selectedIds.includes('primary') ? 'primary' : undefined);
-        const next = [...new Set(primary && !ids.includes(primary) ? [primary, ...ids] : ids)];
+        const next = [...new Set(ids)];
+        if (next.length === 0)
+            return;
+        const added = next.filter((id) => !st.selectedIds.includes(id));
         st.selectedIds = next;
-        st.events = st.events.filter((e) => e.calendarId && next.includes(e.calendarId));
-        const tokens = {};
-        for (const id of next)
-            if (st.syncState.tokens[id])
-                tokens[id] = st.syncState.tokens[id];
-        st.syncState = { tokens };
+        st.gen++;
         await persist(sourceId);
         publish();
+        if (added.length > 0)
+            await runPass({ [sourceId]: added });
     }
     const controller = {
-        async refresh() {
+        async hydrate() {
             try {
-                await Promise.all(sources.map((s) => refreshSource(s.id)));
+                await Promise.all(sources.map((s) => load(s.id)));
             }
             catch {
                 /* never throws */
             }
             publish();
         },
+        refresh: () => runPass(),
+        retryDeferred: () => runPass(),
+        getState() {
+            const sel = sources.flatMap((s) => {
+                const st = state.get(s.id);
+                return st.selectedIds.map((c) => st.errored.has(c));
+            });
+            const lasts = sources.map((s) => state.get(s.id).syncState.lastSyncAt).filter((v) => typeof v === 'number');
+            return {
+                loading: loadingCount > 0,
+                error: sel.length > 0 && sel.every(Boolean) && snapshot.length === 0,
+                deferred,
+                lastSyncAt: lasts.length ? Math.max(...lasts) : null,
+            };
+        },
         getEvents: () => snapshot,
         getSourceStatus: () => statusSnapshot,
         get sourceStatus() {
@@ -141,7 +240,7 @@ export function createCalendarController(opts) {
         getCalendars: (id) => state.get(id)?.calendars ?? [],
         getSelectedIds: (id) => state.get(id)?.selectedIds ?? [],
         setSelectedIds: (id, ids) => setSelected(id, ids),
-        clearSelectedIds: (id) => setSelected(id, []),
+        clearSelectedIds: (id) => setSelected(id, [state.get(id)?.calendars.find((c) => c.primary)?.id ?? 'primary']),
         subscribe(l) {
             listeners.add(l);
             return () => listeners.delete(l);

package/dist/core/fetch.d.ts

@@ -4,6 +4,12 @@ export declare class CalendarFetchError extends Error {
     status: number;
     constructor(kind: 'network' | 'auth' | 'scope' | 'gone' | 'http', status?: number);
 }
+/** Thrown by a host's getToken when a token refresh was deferred (e.g. app inactive). Aborts a pass quietly. */
+export declare class RefreshDeferredError extends Error {
+    readonly deferred = true;
+    constructor(message?: string);
+}
+export declare function isRefreshDeferredError(e: unknown): boolean;
 export declare function fetchCalendarList(token: string): Promise<CalendarInfo[]>;
 export interface EventsPage {
     items: any[];

package/dist/core/fetch.js

@@ -8,6 +8,20 @@ export class CalendarFetchError extends Error {
         this.status = status;
     }
 }
+/** Thrown by a host's getToken when a token refresh was deferred (e.g. app inactive). Aborts a pass quietly. */
+export class RefreshDeferredError extends Error {
+    deferred = true;
+    constructor(message = 'token refresh deferred') {
+        super(message);
+        this.name = 'RefreshDeferredError';
+    }
+}
+export function isRefreshDeferredError(e) {
+    if (e instanceof RefreshDeferredError)
+        return true;
+    const x = e;
+    return !!x && (x.deferred === true || x.name === 'RefreshDeferredError');
+}
 async function request(url, token) {
     let res;
     try {

package/dist/core/reconcile.d.ts

@@ -1,5 +1,5 @@
 import type { CalendarEvent, CalendarInfo } from './types.js';
-/** Stored selection filtered to existing calendars; the primary calendar is always included. */
+/** Stored selection filtered to existing calendars; falls back to primary (else first). Primary is not forced. */
 export declare function reconcileSelection(stored: string[] | null, calendars: CalendarInfo[]): string[];
 /** Applies an incremental page of raw items to one calendar's events (cancelled items remove). */
 export declare function applyChanges(existing: CalendarEvent[], items: any[], ctx: {

package/dist/core/reconcile.js

@@ -1,12 +1,8 @@
 import { reconcileSelectedCalendarIds } from './events.js';
 import { parseEvent } from './events.js';
-/** Stored selection filtered to existing calendars; the primary calendar is always included. */
+/** Stored selection filtered to existing calendars; falls back to primary (else first). Primary is not forced. */
 export function reconcileSelection(stored, calendars) {
-    const ids = reconcileSelectedCalendarIds(stored, calendars);
-    const primary = calendars.find((c) => c.primary);
-    if (primary && !ids.includes(primary.id))
-        ids.unshift(primary.id);
-    return ids;
+    return reconcileSelectedCalendarIds(stored, calendars);
 }
 /** Applies an incremental page of raw items to one calendar's events (cancelled items remove). */
 export function applyChanges(existing, items, ctx) {

package/dist/core/storage.d.ts

@@ -2,6 +2,10 @@ import type { CalendarEvent } from './types.js';
 export interface SyncState {
     /** Per-calendar incremental sync tokens. */
     tokens: Record<string, string>;
+    /** Per-calendar ms epoch of last full sync (optional; absent on 0.1.0 rows). */
+    lastFullSyncAt?: Record<string, number>;
+    /** ms epoch of last successful sync pass (optional; absent on 0.1.0 rows). */
+    lastSyncAt?: number;
 }
 /** Persisted per-source row. `events` is an encrypted JSON string when written by the controller. */
 export interface StorageRow {

package/dist/core/sync.d.ts

@@ -2,7 +2,10 @@ import type { CalendarEvent } from './types.js';
 export interface CalendarSyncResult {
     events: CalendarEvent[];
     syncToken?: string;
+    /** True when a full (windowed) sync was performed. */
+    full: boolean;
 }
+export declare const FULL_SYNC_MAX_AGE_MS: number;
 /** Syncs one calendar: incremental when a token exists, full (windowed) otherwise or on 410. */
 export declare function syncCalendar(args: {
     token: string;
@@ -10,5 +13,6 @@ export declare function syncCalendar(args: {
     calendarId: string;
     existing: CalendarEvent[];
     syncToken?: string;
+    lastFullSyncAt?: number;
     now: Date;
 }): Promise<CalendarSyncResult>;

package/dist/core/sync.js

@@ -1,22 +1,25 @@
 import { CalendarFetchError, fetchEvents } from './fetch.js';
 import { getRollingWindow, parseEvents } from './events.js';
 import { applyChanges } from './reconcile.js';
+export const FULL_SYNC_MAX_AGE_MS = 24 * 3600_000;
 /** Syncs one calendar: incremental when a token exists, full (windowed) otherwise or on 410. */
 export async function syncCalendar(args) {
-    const { token, sourceId, calendarId, existing, syncToken, now } = args;
+    const { token, sourceId, calendarId, existing, syncToken, lastFullSyncAt, now } = args;
     const ctx = { sourceId, calendarId };
     const full = async () => {
         const w = getRollingWindow(now);
         const page = await fetchEvents(token, calendarId, { timeMin: w.start, timeMax: w.end });
-        return { events: parseEvents(page.items, ctx), syncToken: page.nextSyncToken };
+        return { events: parseEvents(page.items, ctx), syncToken: page.nextSyncToken, full: true };
     };
-    if (!syncToken)
+    const stale = lastFullSyncAt === undefined || now.getTime() - lastFullSyncAt > FULL_SYNC_MAX_AGE_MS;
+    if (!syncToken || stale)
         return full();
     try {
         const page = await fetchEvents(token, calendarId, { syncToken });
         return {
             events: applyChanges(existing, page.items, ctx),
             syncToken: page.nextSyncToken ?? syncToken,
+            full: false,
         };
     }
     catch (e) {

package/dist/react/CalendarPane.d.ts

@@ -11,6 +11,12 @@ export interface CalendarPaneProps {
     emptyState?: ReactNode;
     sourceNotice?: (source: Source) => ReactNode;
     onClose?: () => void;
+    /** Whether Google Calendar is connected. Defaults to `sources.length > 0`. */
+    connected?: boolean;
+    /** Whether the connection needs reauthorization. Defaults to all sources being 'needs-scope'. */
+    needsReauth?: boolean;
+    onConnect?: () => void;
+    onReconnect?: () => void;
     /** Window name used for the event popup. */
     popupName?: string;
 }

package/dist/react/CalendarPane.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { filterByRsvp, groupByDay, getOrganizerLabel, formatDayHeader, isEventCurrent, findNextUpcomingEvent, getCalendarEventKey, DEFAULT_RSVP_STATUSES, } from '../core/events.js';
 import { CalendarSelector } from './CalendarSelector.js';
@@ -98,13 +98,18 @@ export function CalendarPane(props) {
         setVersion((v) => v + 1);
         return unsubscribe;
     }, [controller]);
+    useEffect(() => {
+        if (typeof controller.hydrate === 'function')
+            void Promise.resolve(controller.hydrate()).catch(() => { });
+    }, [controller]);
     // eslint-disable-next-line react-hooks/exhaustive-deps
     const events = useMemo(() => controller.getEvents(), [controller, version]);
     const statuses = controller.getSourceStatus();
-    const connected = sources.length > 0;
+    const connected = props.connected ?? sources.length > 0;
+    const ctrlState = controller.getState();
     const multi = sources.length >= 2;
     const needsScopeSources = sources.filter((s) => statuses[s.id] === 'needs-scope');
-    const needsReauth = connected && needsScopeSources.length === sources.length;
+    const needsReauth = connected && (props.needsReauth ?? (sources.length > 0 && needsScopeSources.length === sources.length));
     const sourceColor = (id) => SOURCE_COLORS[Math.max(0, sources.findIndex((s) => s.id === id)) % SOURCE_COLORS.length];
     const sourceEmail = (id) => sources.find((s) => s.id === id)?.email ?? '';
     const todayIso = toIsoDate(new Date());
@@ -260,19 +265,19 @@ export function CalendarPane(props) {
         return () => observer.disconnect();
     }, [connected, needsReauth]);
     if (!connected) {
-        return (_jsx("div", { className: "calendar-pane", children: _jsx("div", { className: "calendar-pane-prompt", children: props.emptyState }) }));
+        return (_jsx("div", { className: "calendar-pane", children: _jsx("div", { className: "calendar-pane-prompt", children: props.emptyState ?? (_jsxs(_Fragment, { children: [_jsx("p", { children: "Not connected to Google Calendar." }), _jsx("button", { className: "calendar-connect-button", onClick: props.onConnect, children: "Connect Google Calendar" })] })) }) }));
     }
     if (needsReauth) {
-        return (_jsx("div", { className: "calendar-pane", children: _jsx("div", { className: "calendar-pane-prompt", children: needsScopeSources.map((s) => (_jsx("div", { children: props.sourceNotice?.(s) }, s.id))) }) }));
+        return (_jsx("div", { className: "calendar-pane", children: _jsx("div", { className: "calendar-pane-prompt", children: props.sourceNotice && needsScopeSources.length > 0 ? (needsScopeSources.map((s) => _jsx("div", { children: props.sourceNotice?.(s) }, s.id))) : (_jsxs(_Fragment, { children: [_jsx("p", { children: "Calendar connection needs reauthorization." }), _jsx("button", { className: "calendar-connect-button", onClick: props.onReconnect, children: "Reconnect to restore sync" })] })) }) }));
     }
     const sourcesWithEvents = new Set(filteredEvents.map((e) => e.sourceId));
     const hasErrorWithoutEvents = sources.some((s) => statuses[s.id] === 'error' && !sourcesWithEvents.has(s.id));
     const calendarSources = sources.filter((s) => controller.getCalendars(s.id).length > 0);
-    const error = hasErrorWithoutEvents;
-    const loading = false;
+    const error = hasErrorWithoutEvents || (ctrlState.error && filteredEvents.length === 0);
+    const loading = ctrlState.loading && filteredEvents.length === 0;
     const emptyStateText = 'No matching events in the next 30 days';
     const showCalendarSelector = calendarSources.length > 0;
-    return (_jsxs("div", { className: "calendar-pane", ref: paneRef, children: [_jsxs("div", { className: "calendar-pane-scroll", children: [_jsxs("div", { className: "calendar-rsvp-chips", ref: chipsRef, children: [_jsx("button", { type: "button", className: "calendar-rsvp-chip calendar-scroll-today-btn", "aria-label": "Scroll to today", title: "Scroll to today", onClick: () => recenter('smooth'), children: _jsxs("svg", { width: "15", height: "15", viewBox: "0 0 15 15", fill: "none", children: [_jsx("rect", { x: "2", y: "3", width: "11", height: "10", rx: "1.5", stroke: "currentColor", strokeWidth: "1.2" }), _jsx("path", { d: "M2 6H13", stroke: "currentColor", strokeWidth: "1.2" }), _jsx("path", { d: "M5 2V4M10 2V4", stroke: "currentColor", strokeWidth: "1.2", strokeLinecap: "round" }), _jsx("circle", { cx: "7.5", cy: "9.5", r: "1.3", fill: "currentColor" })] }) }), RSVP_CHIPS.map((chip) => (_jsx("button", { type: "button", className: `calendar-rsvp-chip${selectedRsvpStatuses.has(chip.status) ? ' selected' : ''}`, "aria-pressed": selectedRsvpStatuses.has(chip.status), "aria-label": chip.label, title: chip.label, onClick: () => handleToggle(chip.status), children: chip.icon }, chip.status)))] }), needsScopeSources.map((s) => (_jsx("div", { children: props.sourceNotice?.(s) }, s.id))), !loading && error && (_jsx("div", { className: "empty-state calendar-empty-state", role: "alert", children: _jsx("p", { children: "Couldn't load calendar events. Try again shortly." }) })), !(error && filteredEvents.length === 0) && (_jsxs("div", { className: "calendar-day-groups", children: [dayGroups.map((group) => (_jsxs("div", { className: "calendar-day-group", children: [_jsx("div", { className: "calendar-day-header", ref: (el) => {
+    return (_jsxs("div", { className: "calendar-pane", ref: paneRef, children: [_jsxs("div", { className: "calendar-pane-scroll", children: [_jsxs("div", { className: "calendar-rsvp-chips", ref: chipsRef, children: [_jsx("button", { type: "button", className: "calendar-rsvp-chip calendar-scroll-today-btn", "aria-label": "Scroll to today", title: "Scroll to today", onClick: () => recenter('smooth'), children: _jsxs("svg", { width: "15", height: "15", viewBox: "0 0 15 15", fill: "none", children: [_jsx("rect", { x: "2", y: "3", width: "11", height: "10", rx: "1.5", stroke: "currentColor", strokeWidth: "1.2" }), _jsx("path", { d: "M2 6H13", stroke: "currentColor", strokeWidth: "1.2" }), _jsx("path", { d: "M5 2V4M10 2V4", stroke: "currentColor", strokeWidth: "1.2", strokeLinecap: "round" }), _jsx("circle", { cx: "7.5", cy: "9.5", r: "1.3", fill: "currentColor" })] }) }), RSVP_CHIPS.map((chip) => (_jsx("button", { type: "button", className: `calendar-rsvp-chip${selectedRsvpStatuses.has(chip.status) ? ' selected' : ''}`, "aria-pressed": selectedRsvpStatuses.has(chip.status), "aria-label": chip.label, title: chip.label, onClick: () => handleToggle(chip.status), children: chip.icon }, chip.status)))] }), needsScopeSources.map((s) => (_jsx("div", { children: props.sourceNotice?.(s) }, s.id))), error && (_jsx("div", { className: "empty-state calendar-empty-state", role: "alert", children: _jsx("p", { children: "Couldn't load calendar events. Try again shortly." }) })), !(error && filteredEvents.length === 0) && (_jsxs("div", { className: "calendar-day-groups", children: [dayGroups.map((group) => (_jsxs("div", { className: "calendar-day-group", children: [_jsx("div", { className: "calendar-day-header", ref: (el) => {
                                             if (el) {
                                                 dayHeaderRefs.current.set(group.dateKey, el);
                                             }
@@ -317,7 +322,7 @@ export function CalendarPane(props) {
                                                                     openEventPopup(event.htmlLink, popupRef, popupName);
                                                                 }
                                                             }, children: _jsx("span", { className: "calendar-event-title", children: event.summary }) })) : (_jsx("span", { className: "calendar-event-title", children: event.summary })), props.renderEventAction?.(event)] }), showCalendarLabel && (_jsxs("span", { className: "calendar-event-calendar", children: [_jsx("span", { className: "calendar-event-calendar-dot", style: { backgroundColor: calendar.backgroundColor } }), calendar.summary] })), showOrganizerLabel && (_jsxs("span", { className: "calendar-event-organizer", children: [multi && (_jsx("span", { className: "calendar-event-source-dot", style: { backgroundColor: sourceColor(event.sourceId) } })), organizerText] }))] }, eventKey));
-                                    })] }, group.dateKey))), filteredEvents.length === 0 && !error && needsScopeSources.length === 0 && _jsx("p", { className: "calendar-empty-state-text", children: emptyStateText })] }))] }), showCalendarSelector && (_jsx("footer", { className: "calendar-pane-footer", children: calendarSources.map((s) => (_jsx(CalendarSelector, { calendars: controller.getCalendars(s.id), selectedIds: controller.getSelectedIds(s.id), onChange: (ids) => {
+                                    })] }, group.dateKey))), loading && _jsx("p", { className: "calendar-empty-state-text", children: "Loading calendar\u2026" }), filteredEvents.length === 0 && !loading && !error && needsScopeSources.length === 0 && _jsx("p", { className: "calendar-empty-state-text", children: emptyStateText })] }))] }), showCalendarSelector && (_jsx("footer", { className: "calendar-pane-footer", children: calendarSources.map((s) => (_jsx(CalendarSelector, { calendars: controller.getCalendars(s.id), selectedIds: controller.getSelectedIds(s.id), onChange: (ids) => {
                         void controller.setSelectedIds(s.id, ids);
                     }, heading: multi ? s.email : undefined }, s.id))) }))] }));
 }

package/dist/testing/storageContract.js

@@ -72,7 +72,7 @@ export function runStorageAdapterContract(factory) {
         });
         it('missing source reads back as empty', async () => {
             const h = await factory();
-            expect(await readBack(h)).toEqual({ events: [], selected: [] });
+            expect(await readBack(h)).toEqual({ events: [], selected: ['primary'] });
         });
         it('reads a legacy plain (unencrypted) row', async () => {
             const h = await factory();
@@ -90,10 +90,17 @@ export function runStorageAdapterContract(factory) {
             expect(out.events).toEqual([LEGACY_EVENT]);
             expect(out.selected).toEqual(['cal']);
         });
+        it('reads a 0.1.0 row that has no lastFullSyncAt/lastSyncAt fields', async () => {
+            const h = await factory();
+            await seed(h, 'src', { events: [LEGACY_EVENT], syncState: { tokens: { cal: 't' } }, selectedIds: ['cal'] });
+            const out = await readBack(h);
+            expect(out.events).toEqual([LEGACY_EVENT]);
+            expect(out.selected).toEqual(['cal']);
+        });
         it('a corrupt row reads back empty without throwing', async () => {
             const h = await factory();
             await seed(h, 'src', h.corruptRow ?? { events: '%%not-json%%', syncState: '{{', selectedIds: 'bad' });
-            await expect(readBack(h)).resolves.toEqual({ events: [], selected: [] });
+            await expect(readBack(h)).resolves.toEqual({ events: [], selected: ['primary'] });
         });
         it('a wrong key reads back empty without throwing', async () => {
             const h = await factory();
@@ -104,7 +111,7 @@ export function runStorageAdapterContract(factory) {
                 syncState: await h.crypto.encrypt(JSON.stringify({ tokens: {} })),
                 selectedIds: [],
             });
-            await expect(readBack(h, h.wrongKeyCrypto)).resolves.toEqual({ events: [], selected: [] });
+            await expect(readBack(h, h.wrongKeyCrypto)).resolves.toEqual({ events: [], selected: ['primary'] });
         });
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-webapp/calendar",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "type": "module",
   "repository": {
     "type": "git",