Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.md
index 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 optimist
state. 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 page
chain. Channel ID, type, team, organization, importance, and participant-scoped
filters operate over synchronized channel metadata. The default channel scope