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): update list rows in place and hide done rows immediately (#7236)
teob7520f5a9bfc
diff --git a/apps/web/src/features/drive-view/queries/drive-data-source.ts b/apps/web/src/features/drive-view/queries/drive-data-source.tsindex 23fd8d51ea..bc893d1b43 100644--- a/apps/web/src/features/drive-view/queries/drive-data-source.ts+++ b/apps/web/src/features/drive-view/queries/drive-data-source.ts@@ -1,3 +1,4 @@+import { createSoupRowStore } from '@app/features/soup/collection/row-store';import { buildFlatSoupRows } from '@app/features/soup/collection/rows';import { withEntityNotifications } from '@app/features/soup/entity-notifications';import {@@ -171,7 +172,7 @@ export function createDriveDataSource(options: {);});- const items = createMemo(() => buildFlatSoupRows(entities()));+ const items = createSoupRowStore(() => buildFlatSoupRows(entities()));const isFetching = () => {if (search.isSearching())diff --git a/apps/web/src/features/email-view/queries/use-email-query.test.ts b/apps/web/src/features/email-view/queries/use-email-query.test.tsindex 8b114dba2b..7ec8976cd1 100644--- a/apps/web/src/features/email-view/queries/use-email-query.test.ts+++ b/apps/web/src/features/email-view/queries/use-email-query.test.ts@@ -27,6 +27,7 @@ const scheduledRows = vi.hoisted(() => ({vi.mock('@app/features/soup', async () => ({...(await import('@app/features/soup/filters')),...(await import('@app/features/soup/collection/rows')),+ ...(await import('@app/features/soup/collection/row-store')),...(await import('@app/features/soup/search/create-search-state')),}));// Exercise query transitions without loading UI barrels or the local-search provider.diff --git a/apps/web/src/features/email-view/queries/use-email-query.ts b/apps/web/src/features/email-view/queries/use-email-query.tsindex fd91c5720b..0d94c89655 100644--- a/apps/web/src/features/email-view/queries/use-email-query.ts+++ b/apps/web/src/features/email-view/queries/use-email-query.ts@@ -4,6 +4,7 @@ import {buildGroupedSoupRows,createSearchState,createSoupLoadMoreRow,+ createSoupRowStore,createTagFacetContext,type SoupRow,soupSearchMatchType,@@ -346,7 +347,7 @@ export function useEmailDataSource(return query.isFetchingNextPage;};- const items = createMemo<EmailDataSourceItem[]>(() => {+ const builtItems = createMemo<EmailDataSourceItem[]>(() => {// Search results keep their relevance order, so only the list page is// bucketed by date.const result: EmailDataSourceItem[] = search.isSearching()@@ -364,6 +365,7 @@ export function useEmailDataSource(return result;});+ const items = createSoupRowStore(builtItems);const isLoading = () => {if (search.isSearching() && showsFavorites() && favorites.isError)diff --git a/apps/web/src/features/home/queries/use-home-query.test.ts b/apps/web/src/features/home/queries/use-home-query.test.tsindex bf279db11a..6374f71dfe 100644--- a/apps/web/src/features/home/queries/use-home-query.test.ts+++ b/apps/web/src/features/home/queries/use-home-query.test.ts@@ -11,6 +11,7 @@ import { type HomeDataSource, useHomeDataSource } from './use-home-query';vi.mock('@app/features/soup', async () => ({...(await import('@app/features/soup/filters')),...(await import('@app/features/soup/collection/rows')),+ ...(await import('@app/features/soup/collection/row-store')),useSearchContext: () => ({ entityPool: () => [] }),createSearchState: () => ({isSearching: () => false,diff --git a/apps/web/src/features/home/queries/use-home-query.ts b/apps/web/src/features/home/queries/use-home-query.tsindex e87c05767e..4d0d1f31ba 100644--- a/apps/web/src/features/home/queries/use-home-query.ts+++ b/apps/web/src/features/home/queries/use-home-query.ts@@ -3,6 +3,7 @@ import {buildFlatSoupRows,buildGroupedSoupRows,createSearchState,+ createSoupRowStore,type SoupRow,testFacets,useSearchContext,@@ -386,7 +387,7 @@ export function useHomeDataSource(state: HomeDataSourceInput): HomeDataSource {);};- const items = createMemo<HomeDataSourceItem[]>(() => {+ const builtItems = createMemo<HomeDataSourceItem[]>(() => {let result: HomeDataSourceItem[];if (state.groupBy === 'date' && !search.isSearching()) {result = buildGroupedSoupRows(@@ -400,6 +401,7 @@ export function useHomeDataSource(state: HomeDataSourceInput): HomeDataSource {return result;});+ const items = createSoupRowStore(builtItems);const isLoading = () => {if (hasNoTypes()) return false;diff --git a/apps/web/src/features/home/queries/use-home-unread.test.ts b/apps/web/src/features/home/queries/use-home-unread.test.tsindex f6b61bb591..351f7a7c5b 100644--- a/apps/web/src/features/home/queries/use-home-unread.test.ts+++ b/apps/web/src/features/home/queries/use-home-unread.test.ts@@ -25,6 +25,7 @@ const mocks = vi.hoisted(() => ({vi.mock('@app/features/soup', async () => ({...(await import('@app/features/soup/filters')),...(await import('@app/features/soup/collection/rows')),+ ...(await import('@app/features/soup/collection/row-store')),useSearchContext: () => ({ entityPool: () => [] }),createSearchState: vi.fn(),}));diff --git a/apps/web/src/features/next-soup/utils.test.ts b/apps/web/src/features/next-soup/utils.test.tsindex 33630a21cb..6b519c26d6 100644--- a/apps/web/src/features/next-soup/utils.test.ts+++ b/apps/web/src/features/next-soup/utils.test.ts@@ -115,6 +115,12 @@ vi.mock('@queries/soup/cache', () => ({rollback: vi.fn(),})),}));+const hideGraphqlSoupEntitiesAsDone = vi.hoisted(() =>+ vi.fn(() => ({ release: vi.fn() }))+);+vi.mock('@queries/soup/graphql/optimistic-done', () => ({+ hideGraphqlSoupEntitiesAsDone,+}));vi.mock('@service-email/client', () => ({emailClient: { flagArchived: operationMocks.flagArchived },}));@@ -143,6 +149,7 @@ import { type ChannelEntityTarget, type EntityData, queryKeys } from '@entity';import type { NotificationSource, UnifiedNotification } from '@notifications';import { hydrateChannelNotificationSelection } from '@queries/channel/notification-selection';import {+ applyEntitiesDoneOptimistic,type CalendarPreviewSelection,type ChannelPreviewSelection,channelIdForPreviewNavigation,@@ -693,6 +700,31 @@ describe('mark-done orchestration', () => {});});+describe('mark-done optimism', () => {+ it('hides GraphQL rows until a rollback or undo releases them', () => {+ const context = applyEntitiesDoneOptimistic({+ entityIds: ['document-1'],+ emailIds: [],+ notificationIds: ['notification-1'],+ });+ expect(hideGraphqlSoupEntitiesAsDone).toHaveBeenCalledWith({+ entityIds: ['document-1'],+ notificationIds: ['notification-1'],+ });+ const applied = hideGraphqlSoupEntitiesAsDone.mock.results[0]?.value;++ context.rollback();+ expect(applied?.release).toHaveBeenCalledOnce();++ context.reapply();+ const reapplied = hideGraphqlSoupEntitiesAsDone.mock.results[1]?.value;+ expect(reapplied).toBeDefined();++ context.applyUndone();+ expect(reapplied?.release).toHaveBeenCalledOnce();+ });+});+describe('calendar view navigation', () => {it('opens and targets the singleton Calendar route', async () => {const openWithSplit = vi.fn(() => ({ status: 'unavailable' }));diff --git a/apps/web/src/features/next-soup/utils.ts b/apps/web/src/features/next-soup/utils.tsindex 91905a8a40..6057fba438 100644--- a/apps/web/src/features/next-soup/utils.ts+++ b/apps/web/src/features/next-soup/utils.ts@@ -129,6 +129,10 @@ import {removeSoupEntitiesFromDoneFilteredQueries,} from '@queries/soup/cache';import { refreshActiveGraphqlSoupQueries } from '@queries/soup/graphql/active-queries';+import {+ type GraphqlSoupDoneOverlay,+ hideGraphqlSoupEntitiesAsDone,+} from '@queries/soup/graphql/optimistic-done';import { emailClient } from '@service-email/client';import { isAfter } from 'date-fns';import { match } from 'ts-pattern';@@ -1467,6 +1471,7 @@ export function applyEntitiesDoneOptimistic(args: {};let soupTxn: ReturnType<typeof removeSoupEntities> | null = null;+ let graphqlDone: GraphqlSoupDoneOverlay | null = null;let emailRowTxns: { rollback: () => void }[] = [];let reminderRowTxns: { rollback: () => void }[] = [];const completedStamp = new Date().toISOString();@@ -1479,6 +1484,15 @@ export function applyEntitiesDoneOptimistic(args: {entityIds.length > 0? removeSoupEntitiesFromDoneFilteredQueries(entityIdSet): null;+ // GraphQL lists never read the REST caches patched here. The entity+ // notification mutation waits for the server, and even the optimistic+ // archive only drops a row after its durable enqueue and a list+ // re-evaluation, so hide the rows locally until the cache catches up.+ graphqlDone?.release();+ graphqlDone =+ entityIds.length > 0+ ? hideGraphqlSoupEntitiesAsDone({ entityIds, notificationIds })+ : null;// Rows that remain visible flip to the done state.emailRowTxns = emailIds.map((id) =>optimisticUpdateSoupEntity({@@ -1512,6 +1526,8 @@ export function applyEntitiesDoneOptimistic(args: {emailRowTxns = [];soupTxn?.rollback();soupTxn = null;+ graphqlDone?.release();+ graphqlDone = null;};const rollback = () => {diff --git a/apps/web/src/features/soup/collection/index.ts b/apps/web/src/features/soup/collection/index.tsindex 5caab1d30d..a09c76f32c 100644--- a/apps/web/src/features/soup/collection/index.ts+++ b/apps/web/src/features/soup/collection/index.ts@@ -1,4 +1,5 @@export { type DateBucket, dateBucket } from './date-buckets';+export { createSoupRowStore } from './row-store';export {assertUniqueSoupRowIds,type BuildFlatSoupRowsOptions,diff --git a/apps/web/src/features/soup/collection/row-store.test.ts b/apps/web/src/features/soup/collection/row-store.test.tsnew file mode 100644index 0000000000..c9de3566c8--- /dev/null+++ b/apps/web/src/features/soup/collection/row-store.test.ts@@ -0,0 +1,97 @@+import type { EntityData } from '@entity';+import { createComputed, createRoot, createSignal } from 'solid-js';+import { createStore } from 'solid-js/store';+import { describe, expect, it } from 'vitest';+import { createSoupRowStore } from './row-store';+import { buildFlatSoupRows } from './rows';++type Task = EntityData & { name: string; tags: string[] };++const task = (id: string, name: string, tags: string[] = []): Task =>+ ({ id, type: 'document', name, tags }) as Task;++describe('createSoupRowStore', () => {+ it('keeps each row object across rebuilds', () => {+ createRoot((dispose) => {+ const [tasks, setTasks] = createSignal([task('a', 'A'), task('b', 'B')]);+ const rows = createSoupRowStore(() => buildFlatSoupRows(tasks()));+ const [first, second] = rows();++ setTasks([task('a', 'A'), task('b', 'B')]);+ expect(rows()[0]).toBe(first);+ expect(rows()[1]).toBe(second);+ dispose();+ });+ });++ it('updates a changed field in place and notifies only its readers', () => {+ createRoot((dispose) => {+ const [tasks, setTasks] = createSignal([task('a', 'A'), task('b', 'B')]);+ const rows = createSoupRowStore(() => buildFlatSoupRows(tasks()));+ const first = rows()[0];+ const names: string[] = [];+ createComputed(() => {+ const row = rows()[1];+ if (row?.kind === 'entity') names.push(row.entity.name);+ });++ setTasks([task('a', 'A'), task('b', 'B renamed')]);+ expect(rows()[0]).toBe(first);+ expect(names).toEqual(['B', 'B renamed']);+ dispose();+ });+ });++ it('follows in-place updates of a query store without new rows', () => {+ createRoot((dispose) => {+ const [query, setQuery] = createStore({ tasks: [task('a', 'A', ['x'])] });+ const rows = createSoupRowStore(() => buildFlatSoupRows(query.tasks));+ const row = rows()[0];++ setQuery('tasks', 0, 'tags', ['x', 'y']);+ expect(rows()[0]).toBe(row);+ expect(row?.kind === 'entity' && [...(row.entity as Task).tags]).toEqual([+ 'x',+ 'y',+ ]);+ dispose();+ });+ });++ it('reuses surviving rows when rows are added, removed or reordered', () => {+ createRoot((dispose) => {+ const [tasks, setTasks] = createSignal([task('a', 'A'), task('b', 'B')]);+ const rows = createSoupRowStore(() => buildFlatSoupRows(tasks()));+ const [a, b] = rows();++ setTasks([task('c', 'C'), task('b', 'B'), task('a', 'A')]);+ expect(rows().map((row) => row.id)).toHaveLength(3);+ expect(rows()[1]).toBe(b);+ expect(rows()[2]).toBe(a);++ setTasks([task('a', 'A')]);+ expect(rows()).toEqual([a]);+ expect(rows()[0]).toBe(a);+ dispose();+ });+ });++ it('never writes into the objects of the store it reads from', () => {+ createRoot((dispose) => {+ const [query] = createStore({ tasks: [task('a', 'A', ['x'])] });+ const [local, setLocal] = createSignal<Task[] | undefined>();+ const rows = createSoupRowStore(() =>+ buildFlatSoupRows(local() ?? query.tasks)+ );+ const row = rows()[0];++ // Switch to a local result for the same entity with different values.+ setLocal([task('a', 'A local', ['z'])]);+ expect(rows()[0]).toBe(row);+ expect(row?.kind === 'entity' && row.entity.name).toBe('A local');+ expect(query.tasks[0]?.name).toBe('A');+ expect([...(query.tasks[0]?.tags ?? [])]).toEqual(['x']);+ dispose();+ });+ });+});diff --git a/apps/web/src/features/soup/collection/row-store.ts b/apps/web/src/features/soup/collection/row-store.tsnew file mode 100644index 0000000000..98f71dc1d3--- /dev/null+++ b/apps/web/src/features/soup/collection/row-store.ts@@ -0,0 +1,42 @@+import { type Accessor, createComputed, createMemo } from 'solid-js';+import { createStore, reconcile } from 'solid-js/store';++function isPlainObject(value: object): value is Record<string, unknown> {+ const prototype = Object.getPrototypeOf(value);+ return prototype === Object.prototype || prototype === null;+}++/** Deep copy of plain objects and arrays. Reads through Solid store proxies. */+function snapshot<T>(value: T): T {+ if (Array.isArray(value)) return value.map(snapshot) as T;+ if (value === null || typeof value !== 'object' || !isPlainObject(value)) {+ return value;+ }+ const copy: Record<string, unknown> = {};+ for (const key of Object.keys(value)) copy[key] = snapshot(value[key]);+ return copy as T;+}++/**+ * Keeps list rows in a Solid store reconciled by row id, like next-soup's row+ * store. A row keeps its object across rebuilds and its entity's fields change+ * in place, so a virtualized list (which keys rows by reference) re-renders+ * only the values that changed instead of remounting every row.+ *+ * Rows are copied before reconciling. Query results are themselves stores+ * that update in place, and a list can switch between server pages and local+ * cache results; reconciling their objects directly would make this store+ * write one source's values into objects another store owns. Reading the copy+ * also tracks nested fields, so in-place query updates reach the rows.+ */+export function createSoupRowStore<TRow extends { id: string }>(+ rows: Accessor<TRow[]>+): Accessor<TRow[]> {+ const [store, setStore] = createStore<TRow[]>([]);+ createComputed(() => {+ const next = snapshot(rows());+ setStore(reconcile(next, { key: 'id', merge: true }));+ });+ // A new array only for structural changes; row proxies update in place.+ return createMemo(() => [...store]);+}diff --git a/apps/web/src/features/soup/entity-notifications.test.ts b/apps/web/src/features/soup/entity-notifications.test.tsnew file mode 100644index 0000000000..6d0a39506f--- /dev/null+++ b/apps/web/src/features/soup/entity-notifications.test.ts@@ -0,0 +1,65 @@+import type { EntityData } from '@entity';+import type { NotificationSource } from '@notifications/notification-source';+import type { UnifiedNotification } from '@notifications/types';+import { createRoot } from 'solid-js';+import { createStore } from 'solid-js/store';+import { describe, expect, it } from 'vitest';+import { withEntityNotifications } from './entity-notifications';++type TestEntity = EntityData & { notifications?: UnifiedNotification[] };++const entity = (id: string, notificationIds: string[] = []): TestEntity =>+ ({+ id,+ type: 'document',+ notifications: notificationIds.map((nid) => ({ id: nid })),+ }) as TestEntity;++const source = {} as NotificationSource;+const ids = (notifications: UnifiedNotification[] | undefined) =>+ notifications?.map(({ id }) => id);++describe('withEntityNotifications', () => {+ it('reuses the accessor for the same entity, source and scope', () => {+ const task = entity('a', ['n1']);+ const first = withEntityNotifications(task, source);+ const second = withEntityNotifications(task, source);++ expect(second).not.toBe(first);+ expect(second.notifications).toBe(first.notifications);+ expect(ids(first.notifications?.())).toEqual(['n1']);+ });++ it('keeps separate accessors per source and per scope', () => {+ const task = entity('a');+ const plain = withEntityNotifications(task, source).notifications;++ expect(+ withEntityNotifications(task, {} as NotificationSource).notifications+ ).not.toBe(plain);+ expect(+ withEntityNotifications(task, source, { scopeChannelThreads: true })+ .notifications+ ).not.toBe(plain);+ });++ it('reads the current notifications of a store entity', () => {+ createRoot((dispose) => {+ const [store, setStore] = createStore({ tasks: [entity('a', ['n1'])] });+ const accessor = withEntityNotifications(+ store.tasks[0]!,+ source+ ).notifications;++ setStore('tasks', 0, 'notifications', [+ { id: 'n1' },+ { id: 'n2' },+ ] as UnifiedNotification[]);+ expect(ids(accessor?.())).toEqual(['n1', 'n2']);+ expect(+ withEntityNotifications(store.tasks[0]!, source).notifications+ ).toBe(accessor);+ dispose();+ });+ });+});diff --git a/apps/web/src/features/soup/entity-notifications.ts b/apps/web/src/features/soup/entity-notifications.tsindex 72c9fb5d5b..c5fa1c6fa8 100644--- a/apps/web/src/features/soup/entity-notifications.ts+++ b/apps/web/src/features/soup/entity-notifications.ts@@ -136,7 +136,45 @@ export function getEntityNotifications<T extends EntityData>(: notifications;}-/** Attach the reactive accessor expected by reusable list-entity components. */+type NotificationAccessors = {+ all?: Accessor<UnifiedNotification[]>;+ scoped?: Accessor<UnifiedNotification[]>;+};++/** One accessor per entity object, notification source and scope. */+const accessors = new WeakMap<+ object,+ WeakMap<NotificationSource, NotificationAccessors>+>();++function notificationsAccessor(+ entity: EntityWithRawNotifications<EntityData>,+ source: NotificationSource,+ options: { scopeChannelThreads?: boolean }+): Accessor<UnifiedNotification[]> {+ let bySource = accessors.get(entity);+ if (!bySource) {+ bySource = new WeakMap();+ accessors.set(entity, bySource);+ }+ let slots = bySource.get(source);+ if (!slots) {+ slots = {};+ bySource.set(source, slots);+ }+ const slot = options.scopeChannelThreads ? 'scoped' : 'all';+ const cached = slots[slot];+ if (cached) return cached;+ const accessor = () => getEntityNotifications(entity, source, options);+ slots[slot] = accessor;+ return accessor;+}++/**+ * Attach the reactive accessor expected by reusable list-entity components.+ * The accessor is reused for the same entity object, so list stores that+ * reconcile these wrappers see no change when nothing about it changed.+ */export function withEntityNotifications<T extends EntityData>(entity: EntityWithRawNotifications<T>,source: NotificationSource,@@ -144,6 +182,6 @@ export function withEntityNotifications<T extends EntityData>(): WithNotification<T> {return {...entity,- notifications: () => getEntityNotifications(entity, source, options),+ notifications: notificationsAccessor(entity, source, options),};}diff --git a/apps/web/src/features/tasks-view/queries/use-tasks-query.test.ts b/apps/web/src/features/tasks-view/queries/use-tasks-query.test.tsindex 70992c77dd..587a7efa2b 100644--- a/apps/web/src/features/tasks-view/queries/use-tasks-query.test.ts+++ b/apps/web/src/features/tasks-view/queries/use-tasks-query.test.ts@@ -6,6 +6,7 @@ const fixture = vi.hoisted(() => ({ query: {} as Record<string, unknown> }));vi.mock('@app/features/soup', async () => ({...(await import('@app/features/soup/filters')),...(await import('@app/features/soup/collection/rows')),+ ...(await import('@app/features/soup/collection/row-store')),...(await import('@app/features/soup/collection/transforms')),useSearchContext: () => ({ entityPool: () => [] }),createSearchState: () => ({diff --git a/apps/web/src/features/tasks-view/queries/use-tasks-query.ts b/apps/web/src/features/tasks-view/queries/use-tasks-query.tsindex 2dd2e0bd8e..e41065bad0 100644--- a/apps/web/src/features/tasks-view/queries/use-tasks-query.ts+++ b/apps/web/src/features/tasks-view/queries/use-tasks-query.ts@@ -3,6 +3,7 @@ import {buildFlatSoupRows,buildGroupedSoupRows,createSearchState,+ createSoupRowStore,createTagFacetContext,deduplicateSoupEntities,isSoupRowVisible,@@ -218,60 +219,64 @@ export function useTasksDataSource(return results;}, []);- const rows = createMemo<SoupRow<TaskEntityWithProperties>[]>((previous) => {- if (- !search.isSearching() &&- (query.isLoading ||- (!options.taskIds && query.isPlaceholderData && previous.length > 0))- ) {- return previous;- }+ const builtRows = createMemo<SoupRow<TaskEntityWithProperties>[]>(+ (previous) => {+ if (+ !search.isSearching() &&+ (query.isLoading ||+ (!options.taskIds && query.isPlaceholderData && previous.length > 0))+ ) {+ return previous;+ }- const groups = search.isSearching() ? undefined : query.data?.groups;- const currentTasks = tasks();- if (!groups || state.groupBy === 'none') {- return buildFlatSoupRows(currentTasks);- }+ const groups = search.isSearching() ? undefined : query.data?.groups;+ const currentTasks = tasks();+ if (!groups || state.groupBy === 'none') {+ return buildFlatSoupRows(currentTasks);+ }- const tasksById = new Map(currentTasks.map((task) => [task.id, task]));- const taskGroups: SoupGroup<TaskEntityWithProperties>[] = [];-- for (const group of groups) {- const initialTasks = group.itemIds.flatMap((id) => {- const task = tasksById.get(id);- return task ? [task] : [];- });- const continuationTasks = continuations- .entities(group.key)- .filter(- (task) =>- (!options.taskIds || options.taskIds().includes(task.id)) &&- taskMatchesView(task, viewContext())+ const tasksById = new Map(currentTasks.map((task) => [task.id, task]));+ const taskGroups: SoupGroup<TaskEntityWithProperties>[] = [];++ for (const group of groups) {+ const initialTasks = group.itemIds.flatMap((id) => {+ const task = tasksById.get(id);+ return task ? [task] : [];+ });+ const continuationTasks = continuations+ .entities(group.key)+ .filter(+ (task) =>+ (!options.taskIds || options.taskIds().includes(task.id)) &&+ taskMatchesView(task, viewContext())+ );+ const entities = sortItems(+ deduplicateSoupEntities([...initialTasks, ...continuationTasks]),+ state.sort,+ TASK_SORT_DEFINITIONS);- const entities = sortItems(- deduplicateSoupEntities([...initialTasks, ...continuationTasks]),- state.sort,- TASK_SORT_DEFINITIONS- );- const taskGroup: SoupGroup<TaskEntityWithProperties> = {- id: group.key,- label: group.label,- entities,- count: group.totalCount,- };-- if (continuations.hasMore(group.key)) {- taskGroup.loadMore = {- scopeId: `tasks:${group.key}`,- isLoading: continuations.isLoading(group.key),+ const taskGroup: SoupGroup<TaskEntityWithProperties> = {+ id: group.key,+ label: group.label,+ entities,+ count: group.totalCount,};- }- taskGroups.push(taskGroup);- }+ if (continuations.hasMore(group.key)) {+ taskGroup.loadMore = {+ scopeId: `tasks:${group.key}`,+ isLoading: continuations.isLoading(group.key),+ };+ }- return buildGroupedSoupRows(taskGroups);- }, []);+ taskGroups.push(taskGroup);+ }++ return buildGroupedSoupRows(taskGroups);+ },+ []+ );+ const rows = createSoupRowStore(builtRows);const items = createMemo(() => {if (options.enabled?.() === false) return [];diff --git a/apps/web/src/lib/queries/soup/excludes-done.ts b/apps/web/src/lib/queries/soup/excludes-done.tsnew file mode 100644index 0000000000..a0450f9169--- /dev/null+++ b/apps/web/src/lib/queries/soup/excludes-done.ts@@ -0,0 +1,72 @@+import type { QueryKey } from '@tanstack/solid-query';++/** Detect positive active-state constraints without misreading OR/NOT subtrees. */+export function soupQueryExcludesDone(+ key: QueryKey,+ incomingState?: 'unseen' | 'seen'+): boolean {+ type Match = { excludesDone: boolean; acceptsIncoming: boolean };+ const unknown: Match = { excludesDone: false, acceptsIncoming: true };+ const combine = (parts: Match[], or = false): Match => ({+ excludesDone:+ parts.length > 0 &&+ (or+ ? parts.every((p) => p.excludesDone)+ : parts.some((p) => p.excludesDone)),+ acceptsIncoming: or+ ? parts.some((p) => p.acceptsIncoming)+ : parts.every((p) => p.acceptsIncoming),+ });+ const states = (values: unknown[]): Match => ({+ excludesDone:+ values.length > 0 && values.every((v) => v === 'unseen' || v === 'seen'),+ acceptsIncoming:+ incomingState === undefined || values.includes(incomingState),+ });+ const inspect = (value: unknown): Match => {+ if (!value || typeof value !== 'object') return unknown;+ if (Array.isArray(value)) return combine(value.map(inspect));+ const node = value as Record<string, unknown>;+ // No safe positive witness can be inferred from a negated subtree.+ if ('!' in node || 'not' in node) return unknown;+ if ('|' in node)+ return Array.isArray(node['|'])+ ? combine(node['|'].map(inspect), true)+ : unknown;+ if ('or' in node) {+ const branches = node.or as { left?: unknown; right?: unknown } | null;+ return branches+ ? combine([inspect(branches.left), inspect(branches.right)], true)+ : unknown;+ }+ if ('l' in node || 'literal' in node) {+ const leaf = (node.l ?? node.literal) as Record<string, unknown> | null;+ if (!leaf || typeof leaf !== 'object') return unknown;+ const state = leaf.ns ?? leaf.NotificationState ?? leaf.notificationState;+ if (typeof state === 'string') return states([state.toLowerCase()]);+ return leaf.comp === false+ ? { excludesDone: true, acceptsIncoming: true }+ : unknown;+ }+ const matches: Match[] = [];+ if (node.emailView === 'inbox') {+ matches.push({ excludesDone: true, acceptsIncoming: true });+ }+ const filter = node.notification_filters as+ | { states?: unknown[] }+ | undefined;+ if (Array.isArray(filter?.states) && filter.states.length) {+ matches.push(states(filter.states));+ }+ // Inbox scoping and DTO selections are witnesses, not terminal nodes:+ // every sibling state constraint must also accept the arriving state.+ for (const [field, child] of Object.entries(node)) {+ if (field !== 'emailView' && field !== 'notification_filters') {+ matches.push(inspect(child));+ }+ }+ return combine(matches);+ };+ const result = inspect(key);+ return result.excludesDone && result.acceptsIncoming;+}diff --git a/apps/web/src/lib/queries/soup/graphql/grouped-items.ts b/apps/web/src/lib/queries/soup/graphql/grouped-items.tsindex c4fb251954..6a1236e0e5 100644--- a/apps/web/src/lib/queries/soup/graphql/grouped-items.ts+++ b/apps/web/src/lib/queries/soup/graphql/grouped-items.ts@@ -29,6 +29,7 @@ import {on,onCleanup,} from 'solid-js';+import { soupQueryExcludesDone } from '../excludes-done';import type { SoupAstBody, SoupAstItemsData, SoupAstParams } from '../items';import { mapSoupPageToEntityList } from '../transform-utils';import { registerGraphqlSoupRevalidations } from './active-queries';@@ -38,6 +39,10 @@ import {usePendingGraphqlSoupDeleteIds,withoutPendingGraphqlSoupDeletes,} from './optimistic-deletions';+import {+ usePendingGraphqlSoupDone,+ withPendingDoneIds,+} from './optimistic-done';export type GraphqlGroupedSoupAstItemsQueryArgs = {params: SoupAstParams;@@ -97,6 +102,8 @@ export function createGraphqlGroupedSoupAstItemsQuery(): GraphqlSoupAstItemsQuery {const instructionsIdQuery = useInstructionsMdIdQuery();const pendingDeleteIds = usePendingGraphqlSoupDeleteIds();+ const pendingDone = usePendingGraphqlSoupDone();+ const excludesDone = createMemo(() => soupQueryExcludesDone([args().body]));const input = createMemo(() => {const { params, body, groupBy } = args();if (!groupBy) return;@@ -164,7 +171,16 @@ export function createGraphqlGroupedSoupAstItemsQuery(return {data: () =>- withoutPendingGraphqlSoupDeletes(query.data, pendingDeleteIds()),+ withoutPendingGraphqlSoupDeletes(+ query.data,+ excludesDone()+ ? withPendingDoneIds(+ pendingDeleteIds(),+ query.data?.entities ?? [],+ pendingDone()+ )+ : pendingDeleteIds()+ ),error,isSupported,isEnabled: () => query.isEnabled,diff --git a/apps/web/src/lib/queries/soup/graphql/items.ts b/apps/web/src/lib/queries/soup/graphql/items.tsindex 5b58c65032..c8cc52cce3 100644--- a/apps/web/src/lib/queries/soup/graphql/items.ts+++ b/apps/web/src/lib/queries/soup/graphql/items.ts@@ -54,6 +54,7 @@ import {} from 'solid-js';import { NIL as NIL_UUID } from 'uuid';import { registerChannelNotificationRefresh } from '../../channel/register-notification-refresh';+import { soupQueryExcludesDone } from '../excludes-done';import type { SoupAstBody, SoupAstItemsData, SoupAstParams } from '../items';import { soupPageTimestamp } from '../page-timestamp';import {@@ -67,6 +68,10 @@ import {usePendingGraphqlSoupDeleteIds,withoutPendingGraphqlSoupDeletes,} from './optimistic-deletions';+import {+ usePendingGraphqlSoupDone,+ withPendingDoneIds,+} from './optimistic-done';import {materializeReconciledSoup,soupItemKey,@@ -115,6 +120,8 @@ export function createGraphqlSoupAstItemsQuery(): GraphqlSoupAstItemsQuery {const instructionsIdQuery = useInstructionsMdIdQuery();const pendingDeleteIds = usePendingGraphqlSoupDeleteIds();+ const pendingDone = usePendingGraphqlSoupDone();+ const excludesDone = createMemo(() => soupQueryExcludesDone([args().body]));const [offline, setOffline] = createSignal(typeof navigator !== 'undefined' && !navigator.onLine);@@ -836,7 +843,13 @@ export function createGraphqlSoupAstItemsQuery(...data,oldestFetchedTimestamp: query.data?.data.oldestFetchedTimestamp,},- pendingDeleteIds()+ excludesDone()+ ? withPendingDoneIds(+ pendingDeleteIds(),+ data?.entities ?? [],+ pendingDone()+ )+ : pendingDeleteIds());}),error,diff --git a/apps/web/src/lib/queries/soup/graphql/keys.ts b/apps/web/src/lib/queries/soup/graphql/keys.tsindex 286f9d0820..0fa3d2c95a 100644--- a/apps/web/src/lib/queries/soup/graphql/keys.ts+++ b/apps/web/src/lib/queries/soup/graphql/keys.ts@@ -3,4 +3,5 @@ import { createQueryKeys } from '@lukemorales/query-key-factory';/** Ephemeral client state, outside the persisted REST Soup query namespace. */export const graphqlSoupKeys = createQueryKeys('graphql-soup', {retainedDeletions: null,+ pendingDone: null,});diff --git a/apps/web/src/lib/queries/soup/graphql/optimistic-done.test.ts b/apps/web/src/lib/queries/soup/graphql/optimistic-done.test.tsnew file mode 100644index 0000000000..736f0d2e2e--- /dev/null+++ b/apps/web/src/lib/queries/soup/graphql/optimistic-done.test.ts@@ -0,0 +1,121 @@+import type { EntityData } from '@entity/types/entity';+import { QueryClient } from '@tanstack/solid-query';+import { createRoot } from 'solid-js';+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';++vi.mock('@queries/client', () => ({+ get queryClient() {+ return client;+ },+}));++import {+ GRAPHQL_SOUP_DONE_RETENTION_MS,+ hideGraphqlSoupEntitiesAsDone,+ type PendingGraphqlSoupDone,+ usePendingGraphqlSoupDone,+ withPendingDoneIds,+} from './optimistic-done';++let client: QueryClient;+let dispose: (() => void) | undefined;+beforeEach(() => {+ client = new QueryClient();+});+afterEach(() => {+ dispose?.();+ dispose = undefined;+ client.clear();+ vi.useRealTimers();+});++const entity = (+ id: string,+ notifications: { id: string; state: string }[] = []+): EntityData =>+ ({ id, type: 'email', notifications }) as unknown as EntityData;++const pending = (+ entityIds: string[],+ notificationIds: string[] = []+): PendingGraphqlSoupDone => ({+ entityIds: new Set(entityIds),+ notificationIds: new Set(notificationIds),+});++function observePending() {+ let read!: ReturnType<typeof usePendingGraphqlSoupDone>;+ dispose = createRoot((disposeRoot) => {+ read = usePendingGraphqlSoupDone();+ return disposeRoot;+ });+ return read;+}++describe('withPendingDoneIds', () => {+ it('returns the input set when nothing is pending', () => {+ const deleted = new Set(['x']);+ expect(withPendingDoneIds(deleted, [entity('a')], [])).toBe(deleted);+ });++ it('hides marked entities alongside pending deletions', () => {+ const hidden = withPendingDoneIds(+ new Set(['x']),+ [entity('a', [{ id: 'n1', state: 'unseen' }]), entity('b')],+ [pending(['a'], ['n1'])]+ );+ expect([...hidden].sort()).toEqual(['a', 'x']);+ });++ it('re-admits an entity with an active notification newer than the action', () => {+ const hidden = withPendingDoneIds(+ new Set(),+ [+ entity('a', [+ { id: 'n1', state: 'unseen' },+ { id: 'n2', state: 'unseen' },+ ]),+ ],+ [pending(['a'], ['n1'])]+ );+ expect(hidden.has('a')).toBe(false);+ });++ it('keeps hiding once the marked notifications are done', () => {+ const hidden = withPendingDoneIds(+ new Set(),+ [entity('a', [{ id: 'n1', state: 'done' }])],+ [pending(['a'], ['n1'])]+ );+ expect(hidden.has('a')).toBe(true);+ });+});++describe('hideGraphqlSoupEntitiesAsDone', () => {+ it('publishes an overlay until it is released', async () => {+ const read = observePending();+ const overlay = hideGraphqlSoupEntitiesAsDone({+ entityIds: ['a'],+ notificationIds: ['n1'],+ });+ await vi.waitFor(() =>+ expect(read().map(({ entityIds }) => [...entityIds])).toEqual([['a']])+ );++ overlay.release();+ overlay.release();+ await vi.waitFor(() => expect(read()).toEqual([]));+ });++ it('expires overlays that are never released', async () => {+ vi.useFakeTimers();+ const read = observePending();+ hideGraphqlSoupEntitiesAsDone({ entityIds: ['a'], notificationIds: [] });+ hideGraphqlSoupEntitiesAsDone({ entityIds: ['b'], notificationIds: [] });+ await vi.advanceTimersByTimeAsync(1);+ expect(read()).toHaveLength(2);++ await vi.advanceTimersByTimeAsync(GRAPHQL_SOUP_DONE_RETENTION_MS);+ expect(read()).toEqual([]);+ });+});diff --git a/apps/web/src/lib/queries/soup/graphql/optimistic-done.ts b/apps/web/src/lib/queries/soup/graphql/optimistic-done.tsnew file mode 100644index 0000000000..88ac38c942--- /dev/null+++ b/apps/web/src/lib/queries/soup/graphql/optimistic-done.ts@@ -0,0 +1,108 @@+import type { EntityData } from '@entity/types/entity';+import type { Notification } from '@entity/types/notification';+import { skipToken, useQuery } from '@tanstack/solid-query';+import type { Accessor } from 'solid-js';+import { queryClient } from '../../client';+import { graphqlSoupKeys } from './keys';++/** How long a done overlay may outlive the action that created it. */+export const GRAPHQL_SOUP_DONE_RETENTION_MS = 60_000;++/** Entities marked done, with the notifications that were active at the time. */+export type PendingGraphqlSoupDone = {+ entityIds: ReadonlySet<string>;+ notificationIds: ReadonlySet<string>;+};++export type GraphqlSoupDoneOverlay = {+ /** Stop hiding the entities, e.g. after a rollback or an undo. */+ release: () => void;+};++const PENDING_DONE_KEY = graphqlSoupKeys.pendingDone.queryKey;++/**+ * Hides entities from done-excluding GraphQL lists until the cache or server+ * reflects the done write. The entity-scoped notification mutation is not+ * cache-optimistic, and an optimistic archive still has to be durably queued+ * and re-evaluated by the list, so without this the row stays visible for a+ * worker or server round trip plus the list re-renders.+ */+export function hideGraphqlSoupEntitiesAsDone(args: {+ entityIds: readonly string[];+ notificationIds: readonly string[];+}): GraphqlSoupDoneOverlay {+ const entry: PendingGraphqlSoupDone = {+ entityIds: new Set(args.entityIds),+ notificationIds: new Set(args.notificationIds),+ };+ queryClient.setQueryData<PendingGraphqlSoupDone[]>(+ PENDING_DONE_KEY,+ (pending) => [...(pending ?? []), entry]+ );+ let released = false;+ const release = () => {+ if (released) return;+ released = true;+ clearTimeout(expiry);+ queryClient.setQueryData<PendingGraphqlSoupDone[]>(+ PENDING_DONE_KEY,+ (pending) => pending?.filter((candidate) => candidate !== entry)+ );+ };+ // Server pushes and list refreshes replace the overlay long before this. The+ // bound only keeps an overlay from outliving its action indefinitely.+ const expiry = setTimeout(release, GRAPHQL_SOUP_DONE_RETENTION_MS);+ return { release };+}++/** The done overlays currently in effect. */+export function usePendingGraphqlSoupDone(): Accessor<+ readonly PendingGraphqlSoupDone[]+> {+ const pending = useQuery(+ () => ({+ queryKey: PENDING_DONE_KEY,+ queryFn: skipToken,+ initialData: [] as PendingGraphqlSoupDone[],+ // Entries have bounded lifetimes even when no view observes this query.+ gcTime: Infinity,+ }),+ () => queryClient+ );+ return () => (pending.isSuccess ? pending.data : []);+}++function activeNotifications(entity: EntityData): Notification[] {+ const notifications = (entity as { notifications?: unknown }).notifications;+ return Array.isArray(notifications)+ ? (notifications as Notification[]).filter(+ (notification) => notification.state !== 'done'+ )+ : [];+}++/**+ * Adds the ids a done-excluding list hides to `hiddenIds`. An entity that has+ * an active notification newer than the done action (one that was not marked)+ * stays visible, so fresh activity re-admits it immediately.+ */+export function withPendingDoneIds(+ hiddenIds: ReadonlySet<string>,+ entities: readonly EntityData[],+ pending: readonly PendingGraphqlSoupDone[]+): ReadonlySet<string> {+ if (pending.length === 0) return hiddenIds;+ let hidden: Set<string> | undefined;+ for (const entity of entities) {+ const covering = pending.find(({ entityIds }) => entityIds.has(entity.id));+ if (!covering) continue;+ const readmitted = activeNotifications(entity).some(+ ({ id }) => !covering.notificationIds.has(id)+ );+ if (readmitted) continue;+ hidden ??= new Set(hiddenIds);+ hidden.add(entity.id);+ }+ return hidden ?? hiddenIds;+}diff --git a/apps/web/src/lib/queries/soup/normalized-cache/operations.ts b/apps/web/src/lib/queries/soup/normalized-cache/operations.tsindex 590a30f2f7..e9b1143b46 100644--- a/apps/web/src/lib/queries/soup/normalized-cache/operations.ts+++ b/apps/web/src/lib/queries/soup/normalized-cache/operations.ts@@ -18,6 +18,7 @@ import {import { isAfter } from 'date-fns';import { match } from 'ts-pattern';import { queryClient } from '../../client';+import { soupQueryExcludesDone } from '../excludes-done';import { refreshActiveGraphqlSoupQueries } from '../graphql/active-queries';import type { SoupAstItemsPage } from '../items';import { soupKeys } from '../keys';@@ -454,77 +455,6 @@ export function removeSoupEntitiesFromQueriesReferencing(});}-/** Detect positive active-state constraints without misreading OR/NOT subtrees. */-function soupQueryExcludesDone(- key: QueryKey,- incomingState?: 'unseen' | 'seen'-): boolean {- type Match = { excludesDone: boolean; acceptsIncoming: boolean };- const unknown: Match = { excludesDone: false, acceptsIncoming: true };- const combine = (parts: Match[], or = false): Match => ({- excludesDone:- parts.length > 0 &&- (or- ? parts.every((p) => p.excludesDone)- : parts.some((p) => p.excludesDone)),- acceptsIncoming: or- ? parts.some((p) => p.acceptsIncoming)- : parts.every((p) => p.acceptsIncoming),- });- const states = (values: unknown[]): Match => ({- excludesDone:- values.length > 0 && values.every((v) => v === 'unseen' || v === 'seen'),- acceptsIncoming:- incomingState === undefined || values.includes(incomingState),- });- const inspect = (value: unknown): Match => {- if (!value || typeof value !== 'object') return unknown;- if (Array.isArray(value)) return combine(value.map(inspect));- const node = value as Record<string, unknown>;- // No safe positive witness can be inferred from a negated subtree.- if ('!' in node || 'not' in node) return unknown;- if ('|' in node)- return Array.isArray(node['|'])- ? combine(node['|'].map(inspect), true)- : unknown;- if ('or' in node) {- const branches = node.or as { left?: unknown; right?: unknown } | null;- return branches- ? combine([inspect(branches.left), inspect(branches.right)], true)- : unknown;- }- if ('l' in node || 'literal' in node) {- const leaf = (node.l ?? node.literal) as Record<string, unknown> | null;- if (!leaf || typeof leaf !== 'object') return unknown;- const state = leaf.ns ?? leaf.NotificationState ?? leaf.notificationState;- if (typeof state === 'string') return states([state.toLowerCase()]);- return leaf.comp === false- ? { excludesDone: true, acceptsIncoming: true }- : unknown;- }- const matches: Match[] = [];- if (node.emailView === 'inbox') {- matches.push({ excludesDone: true, acceptsIncoming: true });- }- const filter = node.notification_filters as- | { states?: unknown[] }- | undefined;- if (Array.isArray(filter?.states) && filter.states.length) {- matches.push(states(filter.states));- }- // Inbox scoping and DTO selections are witnesses, not terminal nodes:- // every sibling state constraint must also accept the arriving state.- for (const [field, child] of Object.entries(node)) {- if (field !== 'emailView' && field !== 'notification_filters') {- matches.push(inspect(child));- }- }- return combine(matches);- };- const result = inspect(key);- return result.excludesDone && result.acceptsIncoming;-}-/*** Remove entities from soup queries that filter out done content, leaving* them in place everywhere else (e.g. mail "All", which shows done threads).diff --git a/docs/AGENT_GUIDE/surfaces.md b/docs/AGENT_GUIDE/surfaces.mdindex 89fedf254f..2863398f15 100644--- a/docs/AGENT_GUIDE/surfaces.md+++ b/docs/AGENT_GUIDE/surfaces.md@@ -99,6 +99,17 @@ update filter membership on the authoritative reply, not from a guessed optimiststate. Rollback restores only the failed operation's contribution. `DONE` predicates,other entity partitions, and notified-at sorting still use the network path.+The Mark done action (`e`, row menu) hides its rows at once from GraphQL lists that+exclude done items, such as Email Important/Noise and Home Signal, without waiting+for the server. Lists that show done items, such as Email All, keep the row. Undo+or a failed write brings the row back, and so does a new active notification on the+entity. To verify, mark a row done and watch it for a few seconds. It must not+reappear once the server reply lands, and it must stay gone after a reload.+In Tasks, Email, Home and Drive, rows keep their DOM when the list updates. A+property edit or a rename updates the edited row in place instead of rebuilding+every visible row. To verify, watch the row nodes with a `MutationObserver` while+editing: only moved or removed rows should be added or removed.+Channels use the same general Soup reconciliation path, not a separate local pagechain. Channel ID, type, team, organization, importance, and participant-scopedfilters operate over synchronized channel metadata. The default channel scope