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
perf(soup): stop hidden tabs evaluating lists on every cache change (#9791)
Eric Hayes5e4df40cc7d8
diff --git a/apps/web/AGENTS.md b/apps/web/AGENTS.mdindex 546a1349ea..9e303ed031 100644--- a/apps/web/AGENTS.md+++ b/apps/web/AGENTS.md@@ -542,6 +542,13 @@ resolved session ID; keep the existing `AgentSessionProvider` subscription to- Coalesce broad browser cache-change hints across the coordinator's in-flightbacklog, not the engine's per-message queue; keep reset fences, mutationsettlements, and query-specific invalidations immediate.+- Open tabs share one cache engine, so a source that reads on cache changes must+ not read while hidden: use `createVisibleRefresh` to throttle too, or+ `createHiddenDeferral` when its own reads already coalesce. Initial and+ explicit reads still run.+- Report cache operation failures through `createCacheErrorThrottle`: one owner+ loss rejects every queued operation, and each report reaches the console and+ session replay. The next report for that kind carries `cache.suppressed_count`.- Retry still-current query reads once when engine replacement invalidates theirsnapshot; do not strand urql's in-flight key or revive torn-down or superseded reads.Keep network forwarding deduplicated and cache-only reads off the network.diff --git a/apps/web/src/lib/core/component/LexicalMarkdown/context/LexicalWrapperContext.tsx b/apps/web/src/lib/core/component/LexicalMarkdown/context/LexicalWrapperContext.tsxindex 8402e33473..b2ae85a84e 100644--- a/apps/web/src/lib/core/component/LexicalMarkdown/context/LexicalWrapperContext.tsx+++ b/apps/web/src/lib/core/component/LexicalMarkdown/context/LexicalWrapperContext.tsx@@ -9,6 +9,7 @@ import {RegisteredNodesByType,SupportedNodeTypes,} from '@macro-inc/lexical-core';+import { Telemetry } from '@macro-inc/observability';import type { NodeKey } from 'lexical';import {createEditor,@@ -101,7 +102,11 @@ export function createLexicalWrapper({theme: theme ?? baseTheme,namespace: namespace + '_' + _id,nodes: [...nodes, ...replacements],- onError: console.error,+ onError: (error) =>+ Telemetry.error(error, {+ 'error.source': 'lexical',+ 'lexical.editor_type': type,+ }),});const plugins = createPluginManager(editor, type);diff --git a/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.ts b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.tsindex 29d51b386e..e3c60e3b9b 100644--- a/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.ts+++ b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.test.ts@@ -265,3 +265,25 @@ it('does not create root performance spans for repeated cache evaluations', asynspan.mockRestore();}});++it('does not read on cache changes while hidden, then catches up once', async () => {+ const visibility = vi.spyOn(document, 'visibilityState', 'get');+ try {+ const state = setup();+ state.requests[0].resolve(snapshot());+ await flush();++ visibility.mockReturnValue('hidden');+ state.change('2');+ state.change('3');+ state.generations.forEach((cb) => cb({ storage: 'preserved' }));+ expect(state.requests).toHaveLength(1);++ visibility.mockReturnValue('visible');+ document.dispatchEvent(new Event('visibilitychange'));+ expect(state.requests).toHaveLength(2);+ expect(state.requests[1].args.liveQuery?.since).toBeUndefined();+ } finally {+ visibility.mockRestore();+ }+});diff --git a/apps/web/src/lib/queries/soup/graphql/create-predicate-query.ts b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.tsindex f09dac173e..4510eddfaa 100644--- a/apps/web/src/lib/queries/soup/graphql/create-predicate-query.ts+++ b/apps/web/src/lib/queries/soup/graphql/create-predicate-query.ts@@ -18,6 +18,7 @@ import {type EntityFilterCacheArgs,parseCacheRevision,} from '../../../graphql-cache/protocol';+import { createHiddenDeferral } from '../../visible-refresh';import { soupCacheTelemetry } from './cache-activity-telemetry';/** A declared source and generated fragment; no mutation-specific query updates. */@@ -242,10 +243,13 @@ export function createPredicateQuery<T extends object>(options: {if (!running) runPromise = run();};requestRefresh = refresh;+ // Every open tab shares one cache engine. A hidden tab keeps a dirty bit+ // instead of reading on each revision; initial and explicit reads still run.+ const deferral = createHiddenDeferral(refresh);const unsubscribeChanges = host.onCacheChanged((revision) => {latest = revision;- refresh();+ deferral.request();},{ includeHydration: true });@@ -258,11 +262,12 @@ export function createPredicateQuery<T extends object>(options: {setData(undefined);setStatus('loading');});- refresh();+ deferral.request();});refresh();onCleanup(() => {active = false;+ deferral.dispose();unsubscribeChanges();unsubscribeGeneration();// Serialize release after any pending read, so disposal cannot recreatediff --git a/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts b/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.tsindex f3b156f89e..c2c004b716 100644--- a/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts+++ b/apps/web/src/lib/queries/soup/graphql/create-soup-live-query.ts@@ -50,6 +50,7 @@ import {} from '../../../service-clients/service-storage/graphql-soup';import { createUrqlInfiniteQuery } from '../../../urql-solid/create-urql-infinite-query';import type { UrqlInfiniteData } from '../../../urql-solid/types';+import { createHiddenDeferral } from '../../visible-refresh';import { registerGraphqlSoupRevalidations } from './active-queries';import { soupCacheTelemetry } from './cache-activity-telemetry';import { createPredicateQuery } from './create-predicate-query';@@ -320,6 +321,13 @@ export function createSoupLiveQuery(// Keep network data usable while the local cache is unavailable.}};+ let latestRevision: CacheRevision | undefined;+ // Every open tab shares one cache engine. A hidden tab keeps a dirty bit+ // instead of evaluating this list on each revision or engine replacement.+ const deferral = createHiddenDeferral(() => {+ if (latestRevision !== undefined) setCurrentCacheRevision(latestRevision);+ else fireAndForget(observeCurrentRevision(), 'soup-live-query');+ });const unsubscribeChanges = host.onCacheChanged((revision) => {cacheObservation += 1;@@ -331,7 +339,8 @@ export function createSoupLiveQuery(staleFallbackStartedAt = performance.now();recordAuthority('stale-fallback');}- setCurrentCacheRevision(revision);+ latestRevision = revision;+ deferral.request();},// The authority watermark must observe the same writes as the live view.{ includeHydration: true }@@ -340,12 +349,14 @@ export function createSoupLiveQuery(soupCacheTelemetry.record('generation');cacheGeneration += 1;invalidateGeneration();- fireAndForget(observeCurrentRevision(), 'soup-live-query');+ latestRevision = undefined;+ deferral.request();});fireAndForget(observeCurrentRevision(), 'soup-live-query');onCleanup(() => {finishStaleFallback(true);cacheGeneration += 1;+ deferral.dispose();unsubscribeChanges();unsubscribeGeneration();});diff --git a/apps/web/src/lib/queries/soup/graphql/items.test.ts b/apps/web/src/lib/queries/soup/graphql/items.test.tsindex 28e76fc5b2..3726d39f90 100644--- a/apps/web/src/lib/queries/soup/graphql/items.test.ts+++ b/apps/web/src/lib/queries/soup/graphql/items.test.ts@@ -4425,6 +4425,76 @@ describe('createGraphqlSoupAstItemsQuery', () => {dispose();});+ it('skips local evaluation on cache changes while hidden and catches up once', async () => {+ const fake = makeFakeClient();+ getGraphqlSoupClientMock.mockReturnValue(fake.client);+ let currentRevision = REVISION_1;+ let notifyCacheChanged!: (revision: string) => void;+ let notifyGenerationChanged!: () => void;+ getGraphqlSoupCacheHostMock.mockReturnValue({+ currentRevision: async () => currentRevision,+ onCacheChanged: (callback: (revision: string) => void) => {+ notifyCacheChanged = callback;+ return () => undefined;+ },+ onCacheGenerationChanged: (callback: () => void) => {+ notifyGenerationChanged = callback;+ return () => undefined;+ },+ entityFilter: entityFilterMock,+ });+ entityFilterMock.mockImplementation(async () => ({+ kind: 'reconciled',+ retainedKeys: [],+ revision: currentRevision,+ keys: [],+ optimistic: false,+ }));+ readRecordsByKeysMock.mockImplementation(async () => ({+ revision: currentRevision,+ records: [],+ }));+ const visibility = vi.spyOn(document, 'visibilityState', 'get');+ let dispose!: () => void;+ createRoot((rootDispose) => {+ dispose = rootDispose;+ createGraphqlSoupAstItemsQuery(+ () => ({ params: {}, body: {} }) as never,+ () => ({ enabled: true })+ );+ });+ try {+ fake.executions[0]?.next(+ graphqlSoupPage({+ items: [{ id: 'item-0', type: 'document', name: 'Network item' }],+ next_cursor: null,+ }),+ { source: 'live-network', revision: REVISION_1 }+ );+ await Promise.resolve();+ entityFilterMock.mockClear();++ visibility.mockReturnValue('hidden');+ currentRevision = REVISION_2;+ notifyCacheChanged(REVISION_2);+ currentRevision = '3';+ notifyCacheChanged('3');+ notifyGenerationChanged();+ currentRevision = '4';+ notifyCacheChanged('4');+ await Promise.resolve();+ await Promise.resolve();+ expect(entityFilterMock).not.toHaveBeenCalled();++ visibility.mockReturnValue('visible');+ document.dispatchEvent(new Event('visibilitychange'));+ await vi.waitFor(() => expect(entityFilterMock).toHaveBeenCalledTimes(1));+ } finally {+ dispose();+ visibility.mockRestore();+ }+ });+it('merges baseline survivors with candidates without resetting server pagination', async () => {const fake = makeFakeClient();getGraphqlSoupClientMock.mockReturnValue(fake.client);diff --git a/apps/web/src/lib/queries/visible-refresh.test.ts b/apps/web/src/lib/queries/visible-refresh.test.tsnew file mode 100644index 0000000000..9d62b44a57--- /dev/null+++ b/apps/web/src/lib/queries/visible-refresh.test.ts@@ -0,0 +1,48 @@+import { afterEach, expect, it, vi } from 'vitest';+import { createHiddenDeferral } from './visible-refresh';++const setVisibility = (value: DocumentVisibilityState) => {+ vi.spyOn(document, 'visibilityState', 'get').mockReturnValue(value);+};+const dispatch = () => document.dispatchEvent(new Event('visibilitychange'));++afterEach(() => vi.restoreAllMocks());++it('runs every request synchronously while visible', () => {+ const run = vi.fn();+ const deferral = createHiddenDeferral(run);+ deferral.request();+ deferral.request();+ expect(run).toHaveBeenCalledTimes(2);+ deferral.dispose();+});++it('coalesces hidden requests into one run on becoming visible', () => {+ setVisibility('hidden');+ const run = vi.fn();+ const deferral = createHiddenDeferral(run);+ deferral.request();+ deferral.request();+ dispatch();+ expect(run).not.toHaveBeenCalled();++ setVisibility('visible');+ dispatch();+ dispatch();+ expect(run).toHaveBeenCalledTimes(1);+ deferral.dispose();+});++it('stays quiet when shown with nothing deferred or after disposal', () => {+ const run = vi.fn();+ const deferral = createHiddenDeferral(run);+ dispatch();+ expect(run).not.toHaveBeenCalled();++ setVisibility('hidden');+ deferral.request();+ deferral.dispose();+ setVisibility('visible');+ dispatch();+ expect(run).not.toHaveBeenCalled();+});diff --git a/apps/web/src/lib/queries/visible-refresh.ts b/apps/web/src/lib/queries/visible-refresh.tsindex 4c8631acbf..0e115725ae 100644--- a/apps/web/src/lib/queries/visible-refresh.ts+++ b/apps/web/src/lib/queries/visible-refresh.ts@@ -73,3 +73,29 @@ export function createVisibleRefresh(},};}++/**+ * Runs immediately while visible, with no throttle. A hidden tab keeps one dirty+ * bit and runs once when it becomes visible, for a source whose own reads+ * already coalesce.+ *+ * The caller must dispose it.+ */+export function createHiddenDeferral(run: () => void): {+ request: () => void;+ dispose: () => void;+} {+ let deferred = false;+ const dispose = makeEventListener(document, 'visibilitychange', () => {+ if (!deferred || document.visibilityState === 'hidden') return;+ deferred = false;+ run();+ });+ return {+ request: () => {+ deferred = document.visibilityState === 'hidden';+ if (!deferred) run();+ },+ dispose,+ };+}diff --git a/apps/web/src/lib/service-clients/service-storage/cache-error-throttle.test.ts b/apps/web/src/lib/service-clients/service-storage/cache-error-throttle.test.tsnew file mode 100644index 0000000000..6a16f094bc--- /dev/null+++ b/apps/web/src/lib/service-clients/service-storage/cache-error-throttle.test.ts@@ -0,0 +1,43 @@+import { describe, expect, it } from 'vitest';+import { createCacheErrorThrottle } from './cache-error-throttle';++describe('createCacheErrorThrottle', () => {+ it('reports the first failure, then the count dropped in that minute', () => {+ let time = 0;+ const throttle = createCacheErrorThrottle(() => time);+ const error = new Error('cache worker timeout: read');++ expect(throttle.admit(error, 'query')).toEqual({+ report: true,+ suppressed: 0,+ });+ expect(throttle.admit(error, 'query').report).toBe(false);+ expect(throttle.admit(error, 'query').report).toBe(false);++ time = 60_000;+ expect(throttle.admit(error, 'query')).toEqual({+ report: true,+ suppressed: 2,+ });+ });++ it('treats failures that differ only by a number as one kind', () => {+ const throttle = createCacheErrorThrottle(() => 0);++ expect(+ throttle.admit(new Error('owner epoch 81 was lost'), 'query').report+ ).toBe(true);+ expect(+ throttle.admit(new Error('owner epoch 82 was lost'), 'query').report+ ).toBe(false);+ });++ it('keeps different failures and operation kinds separate', () => {+ const throttle = createCacheErrorThrottle(() => 0);+ const error = new Error('cache worker timeout: read');++ expect(throttle.admit(error, 'query').report).toBe(true);+ expect(throttle.admit(error, 'subscription').report).toBe(true);+ expect(throttle.admit(new Error('other'), 'query').report).toBe(true);+ });+});diff --git a/apps/web/src/lib/service-clients/service-storage/cache-error-throttle.ts b/apps/web/src/lib/service-clients/service-storage/cache-error-throttle.tsnew file mode 100644index 0000000000..410dd46565--- /dev/null+++ b/apps/web/src/lib/service-clients/service-storage/cache-error-throttle.ts@@ -0,0 +1,31 @@+const REPORT_INTERVAL_MS = 60_000;+const MAX_TRACKED_ERRORS = 100;++const errorMessage = (error: unknown): string =>+ error instanceof Error ? error.message : String(error);++/**+ * Admits one report per minute for each kind of cache failure. Failures that+ * differ only by a number, such as an owner epoch, count as one kind. The next+ * admitted report carries how many were dropped since the last one.+ */+export function createCacheErrorThrottle(now: () => number = Date.now) {+ const seen = new Map<string, { reportedAt: number; suppressed: number }>();+ return {+ admit(+ error: unknown,+ operationKind?: string+ ): { report: boolean; suppressed: number } {+ const key = `${operationKind ?? ''}:${errorMessage(error).replace(/\d+/g, '#')}`;+ const entry = seen.get(key);+ const at = now();+ if (entry && at - entry.reportedAt < REPORT_INTERVAL_MS) {+ entry.suppressed += 1;+ return { report: false, suppressed: 0 };+ }+ if (!entry && seen.size >= MAX_TRACKED_ERRORS) seen.clear();+ seen.set(key, { reportedAt: at, suppressed: 0 });+ return { report: true, suppressed: entry?.suppressed ?? 0 };+ },+ };+}diff --git a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts b/apps/web/src/lib/service-clients/service-storage/graphql-soup.tsindex 4c4c85fe0a..1ec4fdcbd2 100644--- a/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts+++ b/apps/web/src/lib/service-clients/service-storage/graphql-soup.ts@@ -88,6 +88,7 @@ import { match } from 'ts-pattern';import { delegateChannelNotificationRefresh } from '../../queries/channel/notification-refresh';import { soupOptimisticResolvers } from '../../queries/optimistic-resolvers';import { resolveCrmExternalWriteTypes } from '../../queries/soup/graphql/external-write-scope';+import { createCacheErrorThrottle } from './cache-error-throttle';import { createCacheRecovery } from './cache-recovery';import { emailCacheDeletionKeys } from './email-cache-deletions';import { emailThreadSortTs } from './email-thread-sort';@@ -751,6 +752,7 @@ export function getGraphqlSoupClient(): Client {if (cachedClient) return cachedClient;disposeUncachedRealtimeClient();cachedClient = (() => {+ const cacheErrorThrottle = createCacheErrorThrottle();const reportCacheError = (error: unknown,phase: 'initialization' | 'operation',@@ -768,6 +770,12 @@ export function getGraphqlSoupClient(): Client {isOwnerLockUnavailableError(error))return;+ // One owner loss rejects every queued operation at once.+ const throttled =+ phase === 'operation'+ ? cacheErrorThrottle.admit(error, operationKind)+ : { report: true, suppressed: 0 };+ if (!throttled.report) return;// Caught cache failures never reach window.unhandledrejection. Report// them through the Datadog-bound exporter without query/variable data.Telemetry.error(error, {@@ -775,6 +783,9 @@ export function getGraphqlSoupClient(): Client {'cache.backend': native ? 'native' : 'turso-wasm-opfs','cache.phase': phase,...(operationKind ? { 'cache.operation_kind': operationKind } : {}),+ ...(throttled.suppressed > 0+ ? { 'cache.suppressed_count': throttled.suppressed }+ : {}),});} catch {// Observability must not prevent network fallback or cache cleanup.