Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
fix(calendar): preserve event colors during cache handoffs (#7756)
gbirman9dc5cab86fb4
diff --git a/apps/web/src/features/block-calendar/CalendarBlockAdapter.tsx b/apps/web/src/features/block-calendar/CalendarBlockAdapter.tsxindex d5503bf77b..47fd5be5a0 100644--- a/apps/web/src/features/block-calendar/CalendarBlockAdapter.tsx+++ b/apps/web/src/features/block-calendar/CalendarBlockAdapter.tsx@@ -85,11 +85,7 @@ function CalendarBlockAdapter(props: CalendarBlockProps) {// occurrences land anyway.const focusTarget = createMemo(() => {const request = targetRequest();- if (- !request ||- !occurrencesQuery.isSuccess ||- occurrencesQuery.isPlaceholderData- ) {+ if (!request || !occurrencesQuery.isSuccess) {return undefined;}return resolveCalendarTarget(occurrencesQuery.data?.items ?? [], request);diff --git a/apps/web/src/features/calendar-view/calendar-call-sidebar.tsx b/apps/web/src/features/calendar-view/calendar-call-sidebar.tsxindex 1433038ad2..3fbf47d316 100644--- a/apps/web/src/features/calendar-view/calendar-call-sidebar.tsx+++ b/apps/web/src/features/calendar-view/calendar-call-sidebar.tsx@@ -26,6 +26,7 @@ export function CalendarCallSidebar() {const upcoming = useUpcomingCalendarEventsSource({userId,sourceById: calendar.sourceById,+ sourcesReady: calendar.sourcesReady,isSourceVisible: isRenderedSourceVisible,now,});diff --git a/apps/web/src/features/calendar-view/calendar-view.tsx b/apps/web/src/features/calendar-view/calendar-view.tsxindex 75132aa3d7..0b77929d45 100644--- a/apps/web/src/features/calendar-view/calendar-view.tsx+++ b/apps/web/src/features/calendar-view/calendar-view.tsx@@ -176,11 +176,7 @@ export function CalendarView(props: CalendarViewProps) {);const focusTarget = createMemo(() => {const request = targetRequest();- if (- !request ||- !occurrencesQuery.isSuccess ||- occurrencesQuery.isPlaceholderData- ) {+ if (!request || !occurrencesQuery.isSuccess) {return undefined;}return resolveCalendarTarget(occurrencesQuery.data?.items ?? [], request);diff --git a/apps/web/src/features/calendar-view/components/Page.tsx b/apps/web/src/features/calendar-view/components/Page.tsxindex de623d6e89..ca2df1be16 100644--- a/apps/web/src/features/calendar-view/components/Page.tsx+++ b/apps/web/src/features/calendar-view/components/Page.tsx@@ -223,6 +223,7 @@ export function Page(props: {const data = useCalendarOccurrenceData({range,sourceById: calendarView.sourceById,+ sourcesReady: calendarView.sourcesReady,isSourceVisible: isRenderedSourceVisible,queryOptions: () => ({pollWhileSyncing: isActive(),@@ -435,8 +436,7 @@ function CalendarPageHost(props: {wasActive === false &&props.data.occurrencesQuery.isSuccess &&props.data.occurrencesQuery.isStale &&- !props.data.occurrencesQuery.isFetching &&- !props.data.occurrencesQuery.isPlaceholderData+ !props.data.occurrencesQuery.isFetching) {void props.data.occurrencesQuery.refetch();}@@ -454,12 +454,11 @@ function CalendarPageHost(props: {([active, selectedEventId, eventsById]) => {if (!active || !selectedEventId) return;- // Placeholder data is the previous range, so an absent event proves- // nothing yet.+ // An absent event proves nothing until its occurrences and source+ // metadata are ready to render.calendarView.refreshSelectedEventFromPage(eventsById,- props.data.occurrencesQuery.isSuccess &&- !props.data.occurrencesQuery.isPlaceholderData+ props.data.occurrencesQuery.isSuccess && !props.data.isLoading());})diff --git a/apps/web/src/features/calendar/availability/use-availability-ranges.ts b/apps/web/src/features/calendar/availability/use-availability-ranges.tsindex c5f21b8378..12a3ade883 100644--- a/apps/web/src/features/calendar/availability/use-availability-ranges.ts+++ b/apps/web/src/features/calendar/availability/use-availability-ranges.ts@@ -41,8 +41,7 @@ export function useAvailabilityRanges(settings: () => AvailabilitySettings) {});const days = createMemo(() => {- const data =- query.isSuccess && !query.isPlaceholderData ? query.data : undefined;+ const data = query.isSuccess ? query.data : undefined;if (!data || data.syncStatus === CalendarSyncStatus.syncing) return;const busyIntervals = busyIntervalsFromOccurrences(data.items);diff --git a/apps/web/src/features/calendar/components/CalendarViewContext.tsx b/apps/web/src/features/calendar/components/CalendarViewContext.tsxindex cee9dd5c97..3640a84f69 100644--- a/apps/web/src/features/calendar/components/CalendarViewContext.tsx+++ b/apps/web/src/features/calendar/components/CalendarViewContext.tsx@@ -70,7 +70,7 @@ export const [CalendarViewContextProvider, useCalendarView] ='CalendarViewContext',(props: CalendarViewContextProps) => {const [preferences, setPreferences] = useCalendarPreferences();- const { sources, sourceById } = useCalendarSources();+ const { sources, sourceById, sourcesReady } = useCalendarSources();// Sources default to visible, so calendars discovered after a// preference was saved (or events whose calendar is still loading)// never silently disappear.@@ -175,6 +175,7 @@ export const [CalendarViewContextProvider, useCalendarView] =displaySettings,sources,sourceById,+ sourcesReady,hiddenSourceIds,isSourceVisible,setSourceVisibility,diff --git a/apps/web/src/features/calendar/hooks/use-calendar-occurrence-data.test.tsx b/apps/web/src/features/calendar/hooks/use-calendar-occurrence-data.test.tsxnew file mode 100644index 0000000000..d3360c68fc--- /dev/null+++ b/apps/web/src/features/calendar/hooks/use-calendar-occurrence-data.test.tsx@@ -0,0 +1,299 @@+import type {+ CalendarOccurrencesData,+ CalendarOccurrencesQueryInput,+} from '@queries/calendar/occurrences';+import type { VisibleCalendar } from '@service-calendar/generated/schemas/visibleCalendar';+import { cleanup, render, screen, waitFor } from '@solidjs/testing-library';+import {+ QueryClient,+ QueryClientProvider,+ useQuery,+ useQueryClient,+} from '@tanstack/solid-query';+import { type Accessor, createSignal, For, Suspense } from 'solid-js';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { DEFAULT_CALENDAR_SOURCE } from '../types';+import {+ type CalendarOccurrenceData,+ useCalendarOccurrenceData,+} from './use-calendar-occurrence-data';+import { useCalendarSources } from './use-calendar-sources';++const requests = vi.hoisted(() => ({+ calendars: vi.fn<() => Promise<VisibleCalendar[]>>(),+ occurrences: vi.fn<() => Promise<CalendarOccurrencesData>>(),+ transport: (): string => 'rest',+}));++vi.mock('@core/context/user', () => ({+ useUserId: () => () => 'user',+}));+vi.mock('@queries/calendar/calendars', () => ({+ useVisibleCalendarsQuery: () =>+ useQuery(() => ({+ queryKey: ['calendars'],+ queryFn: requests.calendars,+ })),+}));+vi.mock('@queries/calendar/occurrences', () => ({+ useCalendarOccurrencesQuery: (+ input: Accessor<CalendarOccurrencesQueryInput>+ ) => {+ const client = useQueryClient();+ return useQuery(() => {+ const { userId, range } = input();+ const transport = requests.transport();+ return {+ queryKey: ['occurrences', userId, range, transport],+ queryFn: requests.occurrences,+ // The query layer seeds the new reader from the same user and range.+ initialData: () =>+ client.getQueryData<CalendarOccurrencesData>([+ 'occurrences',+ userId,+ range,+ transport === 'rest' ? 'graphql' : 'rest',+ ]),+ initialDataUpdatedAt: 0,+ staleTime: (query) => (query.state.dataUpdatedAt === 0 ? 0 : Infinity),+ };+ });+ },+}));+vi.mock('../utils/preferences', () => ({+ useCalendarPreferences: () => [{ sourceColors: {}, accountColors: {} }],+}));++function deferred<T>() {+ let resolve!: (value: T) => void;+ let reject!: (error: Error) => void;+ const promise = new Promise<T>((resolvePromise, rejectPromise) => {+ resolve = resolvePromise;+ reject = rejectPromise;+ });+ return { promise, resolve, reject };+}++const calendar: VisibleCalendar = {+ id: 'primary',+ name: 'My calendar',+ color: '#dc2127',+ defaultReminders: [],+ emailAddress: '[email protected]',+ emailLinkId: 'inbox',+ isPrimary: true,+ isSubscription: false,+ isWritable: true,+};++function occurrenceData(): CalendarOccurrencesData {+ const start = new Date().toISOString();+ const end = new Date(Date.now() + 3_600_000).toISOString();+ const time = { kind: 'timed' as const, startsAt: start, endsAt: end };+ return {+ syncStatus: 'ready',+ items: [+ {+ event: {+ id: 'event',+ ownerId: 'user',+ icalUid: 'uid',+ calendarId: calendar.id,+ title: 'Planning',+ time,+ attendees: [],+ recurrenceLines: [],+ sequence: 0,+ isReadOnly: false,+ status: 'confirmed',+ transparency: 'opaque',+ visibility: 'default',+ createdAt: start,+ updatedAt: start,+ },+ occurrence: {+ eventId: 'event',+ occurrenceKey: start,+ time,+ isCancelled: false,+ },+ },+ ],+ };+}++let queryClient: QueryClient;++function renderCalendarData() {+ let data!: CalendarOccurrenceData;+ const start = new Date();+ const end = new Date(start.getTime() + 86_400_000);+ const range = {+ start: start.toISOString(),+ end: end.toISOString(),+ startDate: start.toISOString().slice(0, 10),+ endDate: end.toISOString().slice(0, 10),+ };+ function Calendar() {+ const { sourceById, sourcesReady } = useCalendarSources();+ data = useCalendarOccurrenceData({+ range: () => range,+ sourceById,+ sourcesReady,+ });+ return (+ <div data-testid="calendar" aria-busy={data.isLoading()}>+ <For each={data.visibleEvents()}>+ {(event) => (+ <span data-color={event.calendar.color}>{event.title}</span>+ )}+ </For>+ </div>+ );+ }+ render(() => (+ <QueryClientProvider client={queryClient}>+ <Suspense fallback={<div>Suspended</div>}>+ <Calendar />+ </Suspense>+ </QueryClientProvider>+ ));+ return data;+}++beforeEach(() => {+ vi.clearAllMocks();+ requests.transport = () => 'rest';+ queryClient = new QueryClient({+ defaultOptions: { queries: { retry: false, staleTime: Infinity } },+ });+});++afterEach(() => {+ cleanup();+ queryClient.clear();+});++describe('calendar occurrence presentation readiness', () => {+ it('keeps colored events visible during a same-range transport handoff', async () => {+ const [transport, setTransport] = createSignal('rest');+ requests.transport = transport;+ requests.calendars.mockResolvedValue([calendar]);+ const occurrences = occurrenceData();+ requests.occurrences.mockResolvedValue(occurrences);+ const data = renderCalendarData();+ await waitFor(() => expect(screen.getByText('Planning')).toBeTruthy());++ const replacement = deferred<CalendarOccurrencesData>();+ requests.occurrences.mockReturnValue(replacement.promise);+ setTransport('graphql');+ await waitFor(() => expect(data.occurrencesQuery.isFetching).toBe(true));+ expect(screen.getByText('Planning').getAttribute('data-color')).toBe(+ calendar.color+ );+ expect(data.isLoading()).toBe(false);+ expect(screen.getByTestId('calendar').getAttribute('aria-busy')).toBe(+ 'false'+ );++ replacement.resolve(occurrences);+ await waitFor(() => expect(data.occurrencesQuery.isFetching).toBe(false));+ expect(screen.getByText('Planning').getAttribute('data-color')).toBe(+ calendar.color+ );+ expect(data.isLoading()).toBe(false);+ });++ it('keeps the grid loading until fast occurrences have their calendar colors', async () => {+ const calendars = deferred<VisibleCalendar[]>();+ requests.calendars.mockReturnValue(calendars.promise);+ requests.occurrences.mockResolvedValue(occurrenceData());+ const data = renderCalendarData();++ await waitFor(() => expect(data.occurrencesQuery.isSuccess).toBe(true));+ expect(screen.queryByText('Planning')).toBeNull();+ expect(screen.queryByText('Suspended')).toBeNull();+ expect(screen.getByTestId('calendar').getAttribute('aria-busy')).toBe(+ 'true'+ );++ calendars.resolve([calendar]);+ await waitFor(() => {+ expect(screen.getByText('Planning').getAttribute('data-color')).toBe(+ calendar.color+ );+ expect(data.isLoading()).toBe(false);+ });+ });++ it('still waits for occurrences when calendar metadata arrives first', async () => {+ const occurrences = deferred<CalendarOccurrencesData>();+ requests.calendars.mockResolvedValue([calendar]);+ requests.occurrences.mockReturnValue(occurrences.promise);+ const data = renderCalendarData();++ await waitFor(() =>+ expect(queryClient.getQueryState(['calendars'])?.status).toBe('success')+ );+ expect(data.isLoading()).toBe(true);+ expect(screen.queryByText('Planning')).toBeNull();++ occurrences.resolve(occurrenceData());+ await waitFor(() => {+ expect(screen.getByText('Planning').getAttribute('data-color')).toBe(+ calendar.color+ );+ expect(data.isLoading()).toBe(false);+ });+ });++ it.each(['empty', 'error'] as const)(+ 'uses the default source after a terminal metadata result: %s',+ async (result) => {+ const calendars = deferred<VisibleCalendar[]>();+ requests.calendars.mockReturnValue(calendars.promise);+ requests.occurrences.mockResolvedValue(occurrenceData());+ const data = renderCalendarData();++ await waitFor(() => expect(data.occurrencesQuery.isSuccess).toBe(true));+ expect(screen.queryByText('Planning')).toBeNull();+ if (result === 'error') calendars.reject(new Error('Unavailable'));+ else calendars.resolve([]);++ await waitFor(() => {+ expect(screen.getByText('Planning').getAttribute('data-color')).toBe(+ DEFAULT_CALENDAR_SOURCE.color+ );+ expect(data.isLoading()).toBe(false);+ });+ }+ );++ it('keeps colored events visible while calendar metadata refreshes', async () => {+ requests.calendars.mockResolvedValue([calendar]);+ requests.occurrences.mockResolvedValue(occurrenceData());+ const data = renderCalendarData();+ await waitFor(() => expect(screen.getByText('Planning')).toBeTruthy());++ const refreshedCalendars = deferred<VisibleCalendar[]>();+ requests.calendars.mockReturnValue(refreshedCalendars.promise);+ const refresh = queryClient.invalidateQueries({ queryKey: ['calendars'] });+ await waitFor(() =>+ expect(queryClient.getQueryState(['calendars'])?.fetchStatus).toBe(+ 'fetching'+ )+ );+ expect(data.isLoading()).toBe(false);+ expect(screen.getByText('Planning').getAttribute('data-color')).toBe(+ calendar.color+ );++ refreshedCalendars.resolve([{ ...calendar, color: '#16a765' }]);+ await refresh;+ await waitFor(() =>+ expect(screen.getByText('Planning').getAttribute('data-color')).toBe(+ '#16a765'+ )+ );+ });+});diff --git a/apps/web/src/features/calendar/hooks/use-calendar-occurrence-data.ts b/apps/web/src/features/calendar/hooks/use-calendar-occurrence-data.tsindex c2840f5616..c97db72da9 100644--- a/apps/web/src/features/calendar/hooks/use-calendar-occurrence-data.ts+++ b/apps/web/src/features/calendar/hooks/use-calendar-occurrence-data.ts@@ -27,6 +27,8 @@ export interface CalendarOccurrenceData {export interface CalendarOccurrenceDataOptions {range: Accessor<CalendarOccurrenceQueryRange | undefined>;sourceById?: Accessor<ReadonlyMap<string, CalendarSource>>;+ /** Wait for calendar metadata before painting source colors. */+ sourcesReady?: Accessor<boolean>;isSourceVisible?: (sourceId: string) => boolean;queryOptions?: Accessor<CalendarOccurrencesQueryOptions>;}@@ -54,7 +56,7 @@ export function useCalendarOccurrenceData(if (!isRangeSupported() ||!occurrencesQuery.isSuccess ||- occurrencesQuery.isPlaceholderData+ options.sourcesReady?.() === false)return [];const sourceById = options.sourceById?.();@@ -76,10 +78,9 @@ export function useCalendarOccurrenceData(const isLoading = () =>options.range() === undefined ||(isRangeSupported() &&- (occurrencesQuery.isPending || occurrencesQuery.isPlaceholderData));+ (occurrencesQuery.isPending || options.sourcesReady?.() === false));const isSyncing = () =>occurrencesQuery.isSuccess &&- !occurrencesQuery.isPlaceholderData &&occurrencesQuery.data?.syncStatus === CalendarSyncStatus.syncing;return {diff --git a/apps/web/src/features/calendar/hooks/use-calendar-sources.ts b/apps/web/src/features/calendar/hooks/use-calendar-sources.tsindex f57fe33da7..090a2e3f9c 100644--- a/apps/web/src/features/calendar/hooks/use-calendar-sources.ts+++ b/apps/web/src/features/calendar/hooks/use-calendar-sources.ts@@ -36,6 +36,9 @@ export function useCalendarSources() {const sourceById = createMemo(() => new Map(sources().map((source) => [source.id, source])));+ // A failed lookup still permits the default source; a pending one must not+ // briefly paint every event with the default color.+ const sourcesReady = () => !calendarsQuery.isPending;- return { calendarsQuery, sourceById, sources };+ return { calendarsQuery, sourceById, sources, sourcesReady };}diff --git a/apps/web/src/features/meetings/queries/upcoming-calendar-events.test.ts b/apps/web/src/features/meetings/queries/upcoming-calendar-events.test.tsindex f32ce15265..72c72d7363 100644--- a/apps/web/src/features/meetings/queries/upcoming-calendar-events.test.ts+++ b/apps/web/src/features/meetings/queries/upcoming-calendar-events.test.ts@@ -73,18 +73,20 @@ function respond(items: CalendarOccurrenceItem[]) {list.mockResolvedValue(ok({ items, hasMore: false, syncStatus: 'ready' }));}-function setup() {+function setup(metadataReady = true) {const [now, setNow] = createSignal(today);const [userId, setUserId] = createSignal<string | undefined>('macro|[email protected]');const [hidden, setHidden] = createSignal<ReadonlySet<string>>(new Set());+ const [sourcesReady, setSourcesReady] = createSignal(metadataReady);let result!: ReturnType<typeof useUpcomingCalendarEventsSource>;const Harness = () => {result = useUpcomingCalendarEventsSource({userId,now,sourceById: () => sources,+ sourcesReady,isSourceVisible: (id) => !hidden().has(id),});return null;@@ -99,7 +101,7 @@ function setup() {return dispose;});disposers.push(dispose);- return { result, setNow, setUserId, setHidden };+ return { result, setNow, setUserId, setHidden, setSourcesReady };}beforeEach(() => {@@ -114,6 +116,25 @@ afterEach(() => {});describe('upcoming calendar events source', () => {+ it('waits to display agenda colors without delaying occurrence fetches', async () => {+ respond([1, 2, 3, 4, 5].map((day) => occurrence(day)));+ const { result, setSourcesReady } = setup(false);+ await vi.waitFor(() =>+ expect(client.getQueryCache().getAll()[0]?.state.status).toBe('success')+ );+ expect(result.events()).toEqual([]);+ expect(result.loading()).toBe(true);+ expect(list).toHaveBeenCalledTimes(1);++ setSourcesReady(true);+ expect(result.events()).toHaveLength(5);+ expect(result.events().every((event) => event.color === source.color)).toBe(+ true+ );+ expect(result.loading()).toBe(false);+ expect(list).toHaveBeenCalledTimes(1);+ });+it('skips working locations and keeps looking for upcoming events', async () => {const locations = [0, 1, 2, 3, 4].map((day) =>occurrence(day, { title: 'Office', eventType: 'working_location' })diff --git a/apps/web/src/features/meetings/queries/upcoming-calendar-events.ts b/apps/web/src/features/meetings/queries/upcoming-calendar-events.tsindex 8ff05a23e2..599e329d31 100644--- a/apps/web/src/features/meetings/queries/upcoming-calendar-events.ts+++ b/apps/web/src/features/meetings/queries/upcoming-calendar-events.ts@@ -23,6 +23,7 @@ const TARGET_EVENT_COUNT = 5;type SourceOptions = {userId: Accessor<string | undefined>;sourceById: Accessor<ReadonlyMap<string, CalendarSource>>;+ sourcesReady?: Accessor<boolean>;isSourceVisible: (sourceId: string) => boolean;now: Accessor<Date>;};@@ -46,9 +47,7 @@ export function useUpcomingCalendarEventsSource(options: SourceOptions) {const previous = windows.slice();const enabled = () =>Boolean(options.userId()) &&- previous.every(- ({ query }) => query.isSuccess && !query.isPlaceholderData- ) &&+ previous.every(({ query }) => query.isSuccess) &&selectUpcomingCalendarEvents(previous.flatMap((window) => window.events()),options.now()@@ -65,7 +64,7 @@ export function useUpcomingCalendarEventsSource(options: SourceOptions) {() => ({ enabled: enabled() }));const calendarEvents = createMemo(() => {- if (!query.isSuccess || query.isPlaceholderData) return [];+ if (!query.isSuccess) return [];const sources = options.sourceById();return query.data.items.flatMap((item): CalendarEvent[] => {const event = mapCalendarOccurrence(item, {@@ -107,20 +106,20 @@ export function useUpcomingCalendarEventsSource(options: SourceOptions) {const activeWindows = () => windows.filter((window) => window.enabled());return {- events: createMemo(() =>- selectUpcomingCalendarEvents(+ events: createMemo(() => {+ if (options.sourcesReady?.() === false) return [];+ return selectUpcomingCalendarEvents(activeWindows().flatMap((window) => window.events()),options.now()- )- ),+ );+ }),findEvent: (id: string) =>activeWindows().flatMap((window) => window.calendarEvents()).find((event) => event.id === id),loading: () =>- activeWindows().some(- ({ query }) => query.isPending || query.isPlaceholderData- ),+ options.sourcesReady?.() === false ||+ activeWindows().some(({ query }) => query.isPending),error: () =>activeWindows().some(({ query }) => query.isError)? 'Could not load upcoming events.'diff --git a/apps/web/src/lib/core/component/AI/component/tool/calendar/EventPreview.tsx b/apps/web/src/lib/core/component/AI/component/tool/calendar/EventPreview.tsxindex 06faef062c..fc0c125856 100644--- a/apps/web/src/lib/core/component/AI/component/tool/calendar/EventPreview.tsx+++ b/apps/web/src/lib/core/component/AI/component/tool/calendar/EventPreview.tsx@@ -220,15 +220,14 @@ export function CalendarToolEventPreview(props: CalendarToolEventPreviewProps) {? createCalendarOccurrenceQueryRange(window.start, window.end): undefined;});- const { sourceById } = useCalendarSources();- const occurrenceData = useCalendarOccurrenceData({ range, sourceById });- const availableExistingEvents = createMemo(() =>- occurrenceData.occurrencesQuery.isPlaceholderData- ? []- : occurrenceData.visibleEvents()- );+ const { sourceById, sourcesReady } = useCalendarSources();+ const occurrenceData = useCalendarOccurrenceData({+ range,+ sourceById,+ sourcesReady,+ });const existingEvents = createMemo(() =>- availableExistingEvents().slice(0, MAX_EXISTING_PREVIEW_EVENTS)+ occurrenceData.visibleEvents().slice(0, MAX_EXISTING_PREVIEW_EVENTS));const previewEvents = createMemo(() => {const event = previewEvent();diff --git a/apps/web/src/lib/queries/calendar/calendars.ts b/apps/web/src/lib/queries/calendar/calendars.tsindex d302d15d90..a88cc45030 100644--- a/apps/web/src/lib/queries/calendar/calendars.ts+++ b/apps/web/src/lib/queries/calendar/calendars.ts@@ -57,6 +57,7 @@ export function useVisibleCalendarsQuery(staleTime: Infinity,networkMode: 'offlineFirst' as const,enabled: options?.().enabled !== false,+ placeholderData: (previous: VisibleCalendar[] | undefined) => previous,};}return {@@ -64,6 +65,7 @@ export function useVisibleCalendarsQuery(queryFn: listCalendars,staleTime: CALENDAR_LIST_STALE_TIME,enabled: options?.().enabled !== false,+ placeholderData: (previous: VisibleCalendar[] | undefined) => previous,};});}diff --git a/apps/web/src/lib/queries/calendar/occurrences.ts b/apps/web/src/lib/queries/calendar/occurrences.tsindex d4c9c01c77..5d68ac2b5f 100644--- a/apps/web/src/lib/queries/calendar/occurrences.ts+++ b/apps/web/src/lib/queries/calendar/occurrences.ts@@ -109,6 +109,7 @@ export async function fetchCalendarOccurrences(};}+/** Reuses only the current user's date range when the transport changes. */export function useCalendarOccurrencesQuery(input: Accessor<CalendarOccurrencesQueryInput>,options?: Accessor<CalendarOccurrencesQueryOptions>@@ -142,11 +143,30 @@ export function useCalendarOccurrencesQuery(const enabled =Boolean(userId) && range !== undefined && options?.().enabled !== false;const host = cacheHost();+ const keys = calendarKeys.occurrences(userId ?? '', range);+ // Seed the new transport's cache, rather than an observer-only placeholder,+ // so optimistic edits and rollbacks can update the visible events too.+ const queryKey = host ? keys._ctx.graphql.queryKey : keys.queryKey;+ if (activeQueryClient.getQueryData(queryKey) === undefined) {+ const previous = activeQueryClient.getQueryData<CalendarOccurrencesData>(+ host ? keys.queryKey : keys._ctx.graphql.queryKey+ );+ if (previous) {+ activeQueryClient.setQueryData(queryKey, previous, { updatedAt: 0 });+ }+ }+ // Even the otherwise infinitely fresh GraphQL query must run once after+ // being seeded. A successful read restores its normal freshness policy.+ const staleTime = (query: { state: { dataUpdatedAt: number } }) =>+ query.state.dataUpdatedAt === 0+ ? 0+ : host+ ? Infinity+ : CALENDAR_STALE_TIME;if (host) {return {- queryKey: calendarKeys.occurrences(userId ?? '', range)._ctx.graphql- .queryKey,+ queryKey: keys._ctx.graphql.queryKey,queryFn: async ({ signal }: { signal: AbortSignal }) => {if (!range) {throw new Error('Calendar occurrence range is unavailable');@@ -157,10 +177,9 @@ export function useCalendarOccurrencesQuery(return fetchCalendarOccurrences(range, signal);},enabled,- staleTime: Infinity,+ staleTime,// Covered viewports never touch the network, so offline reads run.networkMode: 'offlineFirst' as const,- placeholderData: (p: CalendarOccurrencesData | undefined) => p,refetchOnWindowFocus: false,// Read from REST while the cache was starting: poll like the REST// path until the provider sync finishes.@@ -176,7 +195,7 @@ export function useCalendarOccurrencesQuery(}return {- queryKey: calendarKeys.occurrences(userId ?? '', range).queryKey,+ queryKey: keys.queryKey,queryFn: ({ signal }) => {if (!range) {throw new Error('Calendar occurrence range is unavailable');@@ -186,8 +205,7 @@ export function useCalendarOccurrencesQuery(},enabled:Boolean(userId) && range !== undefined && options?.().enabled !== false,- staleTime: CALENDAR_STALE_TIME,- placeholderData: (p) => p,+ staleTime,refetchOnWindowFocus: options?.().refetchOnWindowFocus ?? true,refetchInterval: (query) =>options?.().pollWhileSyncing !== false &&diff --git a/apps/web/src/lib/queries/calendar/tests/handoff.test.tsx b/apps/web/src/lib/queries/calendar/tests/handoff.test.tsxnew file mode 100644index 0000000000..12091c11e0--- /dev/null+++ b/apps/web/src/lib/queries/calendar/tests/handoff.test.tsx@@ -0,0 +1,357 @@+import type { CacheHost, CalendarRangeCacheResult } from '@graphql-cache/index';+import { parseCacheRevision } from '@graphql-cache/protocol';+import type { ListCalendarsResponse } from '@service-calendar/generated/schemas/listCalendarsResponse';+import type { CalendarOccurrenceResponse } from '@service-storage/generated/schemas/calendarOccurrenceResponse';+import type { CalendarFieldsFragment } from '@service-storage/graphql/generated/graphql';+import { QueryClient, QueryClientProvider } from '@tanstack/solid-query';+import { type Ok, ok } from 'neverthrow';+import { type Accessor, batch, createSignal } from 'solid-js';+import { render } from 'solid-js/web';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';+import { useVisibleCalendarsQuery } from '../calendars';+import { mapCalendarOccurrence, mapVisibleCalendar } from '../graphql/map';+import { markCalendarCacheAnswered } from '../graphql/readiness';+import { graphqlOccurrence } from '../graphql/tests/fixtures';+import { calendarKeys } from '../keys';+import {+ type CalendarOccurrencesQueryInput,+ useCalendarOccurrencesQuery,+} from '../occurrences';++const mocks = vi.hoisted(() => ({+ listOccurrences: vi.fn(),+ listCalendars: vi.fn(),+ graphqlQuery: vi.fn(),+}));++let cacheHost: Accessor<CacheHost | undefined>;+let client: QueryClient;+let dispose: (() => void) | undefined;++vi.mock('../graphql/flag', () => ({+ useGraphqlCalendarHost: () => () => cacheHost(),+ markCalendarCacheUnsupported: vi.fn(),+}));+vi.mock('@service-storage/client', () => ({+ storageServiceClient: { listCalendarOccurrences: mocks.listOccurrences },+}));+vi.mock('@service-email/client', () => ({+ emailClient: { listCalendars: mocks.listCalendars },+}));+vi.mock('@service-storage/graphql-soup', () => ({+ getGraphqlSoupClient: () => ({ query: mocks.graphqlQuery }),+}));+vi.mock('../../client', () => ({+ get queryClient() {+ return client;+ },+}));++const range = {+ start: '2026-10-05T00:00:00.000Z',+ end: '2026-10-12T00:00:00.000Z',+ startDate: '2026-10-05',+ endDate: '2026-10-12',+};+const nextRange = {+ start: '2026-10-12T00:00:00.000Z',+ end: '2026-10-19T00:00:00.000Z',+ startDate: '2026-10-12',+ endDate: '2026-10-19',+};+const initialData = {+ items: [mapCalendarOccurrence(graphqlOccurrence())],+ syncStatus: 'ready' as const,+};+const updatedOccurrence = graphqlOccurrence({ overrideTitle: 'Updated' });+const updatedData = {+ items: [mapCalendarOccurrence(updatedOccurrence)],+ syncStatus: 'ready' as const,+};+const calendar: CalendarFieldsFragment = {+ __typename: 'GraphqlCalendar',+ id: 'calendar-1',+ linkId: 'link-1',+ emailAddress: '[email protected]',+ name: 'Work',+ color: '#ff0000',+ isPrimary: true,+ isWritable: true,+ isSubscription: false,+ syncError: null,+ defaultReminders: [],+};++function deferred<T>() {+ let resolve!: (value: T) => void;+ const promise = new Promise<T>((res) => {+ resolve = res;+ });+ return { promise, resolve };+}++function makeHost() {+ const read = deferred<CalendarRangeCacheResult>();+ const calendarRange = vi.fn(() => read.promise);+ const host = {+ calendarRange,+ onCacheChanged: () => () => {},+ readRecordsByKeys: async () => ({+ revision: '1',+ records: [+ {+ recordKey: `GraphqlCalendarOccurrence:${updatedOccurrence.id}`,+ record: updatedOccurrence,+ },+ ],+ }),+ } as unknown as CacheHost;+ markCalendarCacheAnswered(host);+ return {+ host,+ calendarRange,+ finish: () =>+ read.resolve({+ kind: 'range',+ revision: parseCacheRevision('1'),+ occurrenceKeys: [`GraphqlCalendarOccurrence:${updatedOccurrence.id}`],+ gaps: [],+ freshness: 'fresh',+ uncertainEventKeys: [],+ optimistic: false,+ watermark: null,+ }),+ };+}++function renderHook<T>(factory: () => T): T {+ let hook!: T;+ const Harness = () => {+ hook = factory();+ return null;+ };+ dispose = render(+ () => (+ <QueryClientProvider client={client}>+ <Harness />+ </QueryClientProvider>+ ),+ document.body+ );+ return hook;+}++beforeEach(() => {+ vi.clearAllMocks();+ client = new QueryClient({+ defaultOptions: { queries: { retry: false } },+ });+});++afterEach(() => {+ dispose?.();+ dispose = undefined;+ client.clear();+});++describe('calendar query transport handoff', () => {+ it.each(['REST', 'GraphQL'] as const)(+ 'retains the same viewport while switching from %s and fetches its replacement',+ async (from) => {+ const cached = makeHost();+ const [host, setHost] = createSignal<CacheHost | undefined>(+ from === 'GraphQL' ? cached.host : undefined+ );+ cacheHost = host;+ const keys = calendarKeys.occurrences('user-1', range);+ client.setQueryData(+ from === 'GraphQL' ? keys._ctx.graphql.queryKey : keys.queryKey,+ initialData+ );+ const rest = deferred<Ok<CalendarOccurrenceResponse, never>>();+ mocks.listOccurrences.mockReturnValue(rest.promise);+ const query = renderHook(() =>+ useCalendarOccurrencesQuery(() => ({ userId: 'user-1', range }))+ );+ await vi.waitFor(() => expect(query.data).toEqual(initialData));++ setHost(from === 'REST' ? cached.host : undefined);++ await vi.waitFor(() => {+ expect(+ from === 'REST' ? cached.calendarRange : mocks.listOccurrences+ ).toHaveBeenCalledOnce();+ expect(query.isSuccess).toBe(true);+ expect(query.data).toEqual(initialData);+ });+ if (from === 'REST') cached.finish();+ else+ rest.resolve(ok({ ...updatedData, hasMore: false, nextCursor: null }));+ await vi.waitFor(() => expect(query.data).toEqual(updatedData));+ }+ );++ it.each(['date', 'user'] as const)(+ 'withholds the previous viewport when the %s changes during a transport switch',+ async (change) => {+ const cached = makeHost();+ const [host, setHost] = createSignal<CacheHost>();+ cacheHost = host;+ const [input, setInput] = createSignal<CalendarOccurrencesQueryInput>({+ userId: 'user-1',+ range,+ });+ client.setQueryData(+ calendarKeys.occurrences('user-1', range).queryKey,+ initialData+ );+ const query = renderHook(() => useCalendarOccurrencesQuery(input));+ await vi.waitFor(() => expect(query.data).toEqual(initialData));++ batch(() => {+ setHost(cached.host);+ setInput({+ userId: change === 'user' ? 'user-2' : 'user-1',+ range: change === 'date' ? nextRange : range,+ });+ });++ await vi.waitFor(() => {+ expect(cached.calendarRange).toHaveBeenCalledOnce();+ expect(query.isPending).toBe(true);+ expect(query.data).toBeUndefined();+ });+ }+ );++ it.each(['REST', 'GraphQL'] as const)(+ 'applies optimistic edits while the replacement for %s is still loading',+ async (from) => {+ const cached = makeHost();+ const [host, setHost] = createSignal<CacheHost | undefined>(+ from === 'GraphQL' ? cached.host : undefined+ );+ cacheHost = host;+ const keys = calendarKeys.occurrences('user-1', range);+ client.setQueryData(+ from === 'GraphQL' ? keys._ctx.graphql.queryKey : keys.queryKey,+ initialData+ );+ const rest = deferred<Ok<CalendarOccurrenceResponse, never>>();+ mocks.listOccurrences.mockReturnValue(rest.promise);+ const query = renderHook(() =>+ useCalendarOccurrencesQuery(() => ({ userId: 'user-1', range }))+ );+ await vi.waitFor(() => expect(query.data).toEqual(initialData));++ setHost(from === 'REST' ? cached.host : undefined);+ await vi.waitFor(() => {+ expect(+ from === 'REST' ? cached.calendarRange : mocks.listOccurrences+ ).toHaveBeenCalledOnce();+ expect(query.data).toEqual(initialData);+ });++ // Calendar mutations cancel reads before patching all occurrence caches.+ // A retained observer-only placeholder would keep showing its old value.+ const filter = { queryKey: calendarKeys.occurrences._def };+ await client.cancelQueries(filter);+ const previous = client.getQueriesData<typeof initialData>(filter);+ client.setQueriesData<typeof initialData>(filter, (data) =>+ data ? updatedData : data+ );++ await vi.waitFor(() => expect(query.data).toEqual(updatedData));++ for (const [queryKey, data] of previous) {+ client.setQueryData(queryKey, data);+ }+ await vi.waitFor(() => expect(query.data).toEqual(initialData));++ // Settlement invalidation must refetch despite the normal Infinity+ // freshness policy restored by the optimistic write and rollback.+ const refresh = client.invalidateQueries(filter);+ await vi.waitFor(() =>+ expect(+ from === 'REST' ? cached.calendarRange : mocks.listOccurrences+ ).toHaveBeenCalledTimes(2)+ );+ if (from === 'REST') cached.finish();+ else+ rest.resolve(ok({ ...updatedData, hasMore: false, nextCursor: null }));+ await refresh;+ await vi.waitFor(() => expect(query.data).toEqual(updatedData));+ }+ );++ it.each(['REST', 'GraphQL'] as const)(+ 'retains an exact viewport cached by %s when its new reader mounts',+ async (from) => {+ const cached = makeHost();+ cacheHost = () => (from === 'REST' ? cached.host : undefined);+ const keys = calendarKeys.occurrences('user-1', range);+ client.setQueryData(+ from === 'GraphQL' ? keys._ctx.graphql.queryKey : keys.queryKey,+ initialData+ );+ const rest = deferred<Ok<CalendarOccurrenceResponse, never>>();+ mocks.listOccurrences.mockReturnValue(rest.promise);++ const query = renderHook(() =>+ useCalendarOccurrencesQuery(() => ({ userId: 'user-1', range }))+ );++ await vi.waitFor(() => {+ expect(+ from === 'REST' ? cached.calendarRange : mocks.listOccurrences+ ).toHaveBeenCalledOnce();+ expect(query.isSuccess).toBe(true);+ expect(query.data).toEqual(initialData);+ });+ }+ );++ it.each(['REST', 'GraphQL'] as const)(+ 'keeps calendar names and colors while switching from %s',+ async (from) => {+ const cached = makeHost();+ const [host, setHost] = createSignal<CacheHost | undefined>(+ from === 'GraphQL' ? cached.host : undefined+ );+ cacheHost = host;+ const keys = calendarKeys.visibleCalendars;+ const calendars = [mapVisibleCalendar(calendar)];+ client.setQueryData(+ from === 'GraphQL' ? keys._ctx.graphql.queryKey : keys.queryKey,+ calendars+ );+ const replacement = { ...calendar, name: 'Renamed', color: '#00ff00' };+ const graphql = deferred<{+ data: { user: { calendars: CalendarFieldsFragment[] } };+ }>();+ mocks.graphqlQuery.mockReturnValue({ toPromise: () => graphql.promise });+ const rest = deferred<Ok<ListCalendarsResponse, never>>();+ mocks.listCalendars.mockReturnValue(rest.promise);+ const query = renderHook(useVisibleCalendarsQuery);+ await vi.waitFor(() => expect(query.data).toEqual(calendars));++ setHost(from === 'REST' ? cached.host : undefined);++ await vi.waitFor(() => {+ expect(+ from === 'REST' ? mocks.graphqlQuery : mocks.listCalendars+ ).toHaveBeenCalledOnce();+ expect(query.isSuccess).toBe(true);+ expect(query.data).toEqual(calendars);+ });+ if (from === 'REST') {+ graphql.resolve({ data: { user: { calendars: [replacement] } } });+ } else {+ rest.resolve(ok({ calendars: [mapVisibleCalendar(replacement)] }));+ }+ await vi.waitFor(() =>+ expect(query.data).toEqual([mapVisibleCalendar(replacement)])+ );+ }+ );+});diff --git a/docs/AGENT_GUIDE/surfaces.md b/docs/AGENT_GUIDE/surfaces.mdindex 2d6212b5c7..e22375e622 100644--- a/docs/AGENT_GUIDE/surfaces.md+++ b/docs/AGENT_GUIDE/surfaces.md@@ -1208,7 +1208,13 @@ Quick loads skip the skeletons. Real events lay out underneath during the briefminimum display, then fade in as the skeletons fade out. Changing period during aload carries feedback into the new cells without restarting the appearance delay.Background refreshes retain current events without skeletons or a transient loading-pill. Provider backfill shows a persistent `Syncing your calendar…` banner above the+pill. On a cold reload, the first event paint waits for calendar metadata so events+appear in their configured colors. A REST/GraphQL handoff for the same user and+date range keeps the visible events and calendar list while the new reader loads;+changing the user or date range must not retain the old events. Verify both handoff+directions with delayed responses and delay calendar metadata past occurrences.+If metadata fails, events remain usable with the default calendar presentation.+Provider backfill shows a persistent `Syncing your calendar…` banner above thegrid, explaining that events will appear automatically and Macro remains usable.The banner stays visible as partial results arrive and disappears when sync finishes.Errors retain the separate retry state. Verify delayed occurrence