feat: add quiet reading with rare confirmations

Part of the quiet-user-feedback change; docs and specs land in their own repositories.

src/features/tbank-connection/model/screen-sync.test.tsx

@@ -78,7 +78,7 @@ describe("page-owned screen synchronization", () => {
 		expect(posted).toEqual(["old", "new"]);
 	});
 	it.each([false, true])(
-		"retries a failed GET without forcing the source (cached=%s)",
+		"recovers a failed GET without forcing the source (cached=%s)",
 		async (cached) => {
 			auth();
 			const modes: (null | string)[] = [];
@@ -122,26 +122,13 @@ describe("page-owned screen synchronization", () => {
 					expect(result.current.accounts.isSuccess).toBe(true),
 				);
 				isUnavailable = true;
-				await act(() => result.current.accounts.refetch());
+				void result.current.accounts.refetch();
 			}
 
-			await waitFor(() => expect(result.current.accounts.isError).toBe(true));
 			isUnavailable = false;
-			await act(() => result.current.sync.retry());
 			await waitFor(() => expect(result.current.accounts.isSuccess).toBe(true));
-			expect(result.current.accounts.meta?.dataRevision).toBe(
-				cached ? "3" : "2",
-			);
-			expect(modes).toEqual(
-				cached
-					? [
-							null,
-							null,
-							"observe",
-						]
-					: [null, "observe"],
-			);
 			expect(posts).toBe(0);
+			expect(modes.every(mode => mode === null)).toBe(true);
 			expect(result.current.disabled.data).toBeUndefined();
 			expect(
 				queryClient
@@ -157,171 +144,193 @@ describe("page-owned screen synchronization", () => {
 		["connection", false],
 		["access", false],
 	] as const)(
-		"discards recovery after %s changes (HTTP already pending=%s)",
+		"discards source recovery after %s changes (HTTP already pending=%s)",
 		async (boundary, pending) => {
 			auth();
 
 			const { promise: blocked, resolve: release }
 				= Promise.withResolvers<void>();
 
-			let isRecovering = false;
+			let recoveryRequests = 0;
 			let isChanged = false;
-			server.use(
-				http.get("*/api/v1/brokerage-accounts", async ({ request }) => {
-					if (boundary === "connection" && isChanged && !request.signal.aborted)
-						return HttpResponse.json(resource([], { dataRevision: "current" }));
-					if (!new URL(request.url).searchParams.has("sync"))
-						return isChanged
-							? HttpResponse.json(resource([], { dataRevision: "current" }))
-							: HttpResponse.json({ code: "UNAVAILABLE" }, { status: 503 });
-					isRecovering = true;
-					await blocked;
 
-					return HttpResponse.json(resource([], { dataRevision: "old" }));
-				}),
-			);
-			const { queryClient, wrapper } = createQueryWrapper();
-			const published: unknown[] = [];
+			try {
+				server.use(
+					http.get("*/api/v1/brokerage-accounts", async () => {
+						if (isChanged)
+							return HttpResponse.json(
+								resource([], { dataRevision: "current" }),
+							);
 
-			const unsubscribe = queryClient.getQueryCache().subscribe((event) => {
-				if (event.type === "updated" && event.action.type === "success")
-					published.push(event.query.state.data);
-			});
+						if (recoveryRequests > 0) {
+							recoveryRequests += 1;
+							await blocked;
 
-			const { result } = renderHook(
-				() => {
-					const accounts = useBrokerageAccounts();
+							return HttpResponse.json(resource([], { dataRevision: "old" }));
+						}
 
-					return {
-						accounts,
-						sync: useScreenSync({ screen: "accounts" }, [accounts]),
-					};
-				},
-				{ wrapper },
-			);
+						recoveryRequests += 1;
 
-			await waitFor(() => expect(result.current.accounts.isError).toBe(true));
-			let recovery!: Promise<void>;
-			act(() => {
-				recovery = result.current.sync.retry();
-			});
-			// eslint-disable-next-line vitest/no-conditional-expect -- The fixed table case selects the expected outcome; every case asserts its own branch.
-			if (pending) await waitFor(() => expect(isRecovering).toBe(true));
-			await act(async () => {
-				isChanged = true;
-
-				switch (boundary) {
-					case "access": {
-						invalidateResourceAccess(queryClient, "brokerage", {
-							code: "FORBIDDEN",
-						});
-
-						break;
-					}
-
-					case "logout": {
-						configureAuthClient();
-						queryClient.clear();
-
-						break;
-					}
-
-					case "session": {
-						auth();
-						queryClient.clear();
-
-						break;
-					}
-
-					case "connection": {
-						commitTbankConnectionBoundary(queryClient, {
-							connected: true,
-							connectedAt: "2026-09-27T00:00:00Z",
-						});
-					}
-				}
-
-				release();
-				await recovery;
-			});
-			if (boundary === "connection")
-				await waitFor(() =>
-					// eslint-disable-next-line vitest/no-conditional-expect -- The fixed table case selects the expected outcome; every case asserts its own branch.
-					expect(result.current.accounts.meta?.dataRevision).toBe("current"),
+						return HttpResponse.json(
+							resource(null, {
+								sync: {
+									errorCode: "TBANK_UNAVAILABLE",
+									id: "failed",
+									state: "failed",
+								},
+							}),
+						);
+					}),
 				);
-			expect(published).not.toContainEqual(
-				expect.objectContaining({
-					meta: expect.objectContaining({ dataRevision: "old" }) as unknown,
-				}),
-			);
-			unsubscribe();
+				const { queryClient, wrapper } = createQueryWrapper();
+				const published: unknown[] = [];
+
+				const unsubscribe = queryClient.getQueryCache().subscribe((event) => {
+					if (event.type === "updated" && event.action.type === "success")
+						published.push(event.query.state.data);
+				});
+
+				const { result } = renderHook(
+					() => {
+						const accounts = useBrokerageAccounts();
+
+						return {
+							accounts,
+							sync: useScreenSync({ screen: "accounts" }, [accounts]),
+						};
+					},
+					{ wrapper },
+				);
+
+				await waitFor(() =>
+					expect(result.current.accounts.meta?.sync.state).toBe("failed"),
+				);
+				vi.useFakeTimers();
+				if (pending)
+					await act(() => vi.advanceTimersByTimeAsync(5000));
+				expect(recoveryRequests).toBeGreaterThanOrEqual(1);
+
+				await act(async () => {
+					isChanged = true;
+
+					switch (boundary) {
+						case "access": {
+							invalidateResourceAccess(queryClient, "brokerage", {
+								code: "FORBIDDEN",
+							});
+
+							break;
+						}
+
+						case "logout": {
+							configureAuthClient();
+							queryClient.clear();
+
+							break;
+						}
+
+						case "session": {
+							auth();
+							queryClient.clear();
+
+							break;
+						}
+
+						case "connection": {
+							commitTbankConnectionBoundary(queryClient, {
+								connected: true,
+								connectedAt: "2026-09-27T00:00:00Z",
+							});
+						}
+					}
+
+					release();
+					if (!pending) await vi.advanceTimersByTimeAsync(5000);
+				});
+				vi.useRealTimers();
+				if (boundary === "connection" && !pending)
+					await waitFor(() =>
+						// eslint-disable-next-line vitest/no-conditional-expect -- The fixed table case selects the expected outcome; every case asserts its own branch.
+						expect(result.current.accounts.meta?.dataRevision).toBe("current"),
+					);
+				expect(published).not.toContainEqual(
+					expect.objectContaining({
+						meta: expect.objectContaining({ dataRevision: "old" }) as unknown,
+					}),
+				);
+				unsubscribe();
+			}
+			finally {
+				vi.useRealTimers();
+			}
 		},
 	);
 	it.each([false, true])(
-		"recovers an initial GET failure after forced sync without metadata (status retry=%s)",
+		"recovers an initial GET failure without forced sync (status retry=%s)",
 		async (retryStatus) => {
 			auth();
 			const modes: (null | string)[] = [];
+			let posts = 0;
 			let polls = 0;
-			server.use(
-				http.get("*/api/v1/brokerage-accounts", ({ request }) => {
-					modes.push(new URL(request.url).searchParams.get("sync"));
 
-					return modes.length === 1
-						? HttpResponse.json({ code: "UNAVAILABLE" }, { status: 503 })
-						: HttpResponse.json(resource([]));
-				}),
-				http.post("*/api/v1/tbank-sync", () =>
-					HttpResponse.json({ id: "recover" }, { status: 202 }),
-				),
-				http.get("*/api/v1/tbank-sync/:id", () => {
-					polls += 1;
+			try {
+				server.use(
+					http.get("*/api/v1/brokerage-accounts", ({ request }) => {
+						modes.push(new URL(request.url).searchParams.get("sync"));
 
-					return retryStatus && polls === 1
-						? HttpResponse.json({ code: "UNAVAILABLE" }, { status: 503 })
-						: HttpResponse.json({
-								id: "recover",
-								state: "succeeded",
-							});
-				}),
-			);
-			const { queryClient, wrapper } = createQueryWrapper();
+						return modes.length === 1
+							? HttpResponse.json({ code: "UNAVAILABLE" }, { status: 503 })
+							: HttpResponse.json(resource([]));
+					}),
+					http.post("*/api/v1/tbank-sync", () => {
+						posts += 1;
 
-			const { result } = renderHook(
-				() => {
-					const accounts = useBrokerageAccounts();
-					const disabled = useStockQuote("");
+						return HttpResponse.json({ id: "recover" }, { status: 202 });
+					}),
+					http.get("*/api/v1/tbank-sync/:id", () => {
+						polls += 1;
 
-					return {
-						accounts,
-						sync: useScreenSync({ screen: "accounts" }, [accounts, disabled]),
-					};
-				},
-				{ wrapper },
-			);
-
-			await waitFor(() => expect(result.current.accounts.isError).toBe(true));
-			expect(result.current.accounts.meta).toBeUndefined();
-			await act(() => result.current.sync.refresh());
-
-			if (retryStatus) {
-				await waitFor(() =>
-					// eslint-disable-next-line vitest/no-conditional-expect -- The fixed table case selects the expected outcome; every case asserts its own branch.
-					expect(result.current.sync.transportError).toBe(true),
+						return retryStatus && polls === 1
+							? HttpResponse.json({ code: "UNAVAILABLE" }, { status: 503 })
+							: HttpResponse.json({
+									id: "recover",
+									state: "succeeded",
+								});
+					}),
 				);
-				await act(() => result.current.sync.retry());
+				const { queryClient, wrapper } = createQueryWrapper();
+
+				const { result } = renderHook(
+					() => {
+						const accounts = useBrokerageAccounts();
+						const disabled = useStockQuote("");
+
+						return {
+							accounts,
+							sync: useScreenSync({ screen: "accounts" }, [accounts, disabled]),
+						};
+					},
+					{ wrapper },
+				);
+
+				await waitFor(
+					() => expect(result.current.accounts.isSuccess).toBe(true),
+					{ timeout: 3000 },
+				);
+				expect(result.current.accounts.data).toEqual([]);
+
+				expect(modes).toEqual([null, null]);
+				expect(posts).toBe(0);
+				expect(polls).toBe(0);
+				expect(
+					queryClient
+						.getQueryCache()
+						.findAll({ queryKey: ["get", "/api/v1/brokerage-accounts"] }),
+				).toHaveLength(1);
+			}
+			finally {
+				vi.useRealTimers();
 			}
-
-			await waitFor(() => expect(result.current.accounts.isSuccess).toBe(true));
-			expect(result.current.accounts.data).toEqual([]);
-
-			expect(modes[0]).toBeNull();
-			expect(modes.slice(1).every(mode => mode === "observe")).toBe(true);
-			expect(
-				queryClient
-					.getQueryCache()
-					.findAll({ queryKey: ["get", "/api/v1/brokerage-accounts"] }),
-			).toHaveLength(1);
 		},
 	);
 	it("posts only its scope once and observes completion without importing again", async () => {

src/features/tbank-connection/model/screen-sync.ts

@@ -1,4 +1,9 @@
-import { type QueryKey, useQueryClient } from "@tanstack/react-query";
+import {
+	focusManager,
+	onlineManager,
+	type QueryKey,
+	useQueryClient,
+} from "@tanstack/react-query";
 import { useEffect, useRef } from "react";
 
 import {
@@ -21,9 +26,39 @@ type ScreenResource = {
 	meta?: InvestmentResourceMeta;
 	observe: () => Promise<unknown>;
 	queryKey: QueryKey;
+	refetch: () => Promise<unknown>;
 };
 
 const STATUS_INTERVAL_MS = 1000;
+const FIRST_SOURCE_RECOVERY_DELAY_MS = 5000;
+const SECOND_SOURCE_RECOVERY_DELAY_MS = 15_000;
+
+function requiresSourceRecovery(meta?: InvestmentResourceMeta): boolean {
+	if (!meta || meta.unavailableReason) return false;
+
+	return ["cancelled", "failed"].includes(meta.sync.state)
+		|| meta.availability === "missing"
+		|| meta.freshness === "stale"
+		|| (meta.dependencies ?? []).some(dependency =>
+			requiresSourceRecovery(dependency),
+		);
+}
+
+function sourceRecoveryDelay(attempt: number): number | undefined {
+	switch (attempt) {
+		case 0: {
+			return FIRST_SOURCE_RECOVERY_DELAY_MS;
+		}
+
+		case 1: {
+			return SECOND_SOURCE_RECOVERY_DELAY_MS;
+		}
+
+		default: {
+			return undefined;
+		}
+	}
+}
 
 function useScreenSync(scope: InvestmentScreen, resources: ScreenResource[]) {
 	const mutation = apiQueryClient.useMutation("post", "/api/v1/tbank-sync", {
@@ -35,6 +70,9 @@ function useScreenSync(scope: InvestmentScreen, resources: ScreenResource[]) {
 	const scopeKey = JSON.stringify(scope);
 
 	const requestInFlightRef = useRef<null | string>(null);
+	const lifecycleRecoveryRef = useRef(new Set<string>());
+	const sourceRecoveryRef = useRef(new Map<string, number>());
+	const sourceTimersRef = useRef(new Set<ReturnType<typeof setTimeout>>());
 
 	const isCurrentMutation
 		= JSON.stringify(mutation.variables?.body) === scopeKey;
@@ -110,6 +148,73 @@ function useScreenSync(scope: InvestmentScreen, resources: ScreenResource[]) {
 				void resource.observe().catch(() => {});
 	}, [client, statuses, resources, scopeKey]);
 
+	useEffect(() => {
+		const timers = sourceTimersRef.current;
+		const attempts = sourceRecoveryRef.current;
+
+		return () => {
+			for (const timer of timers) clearTimeout(timer);
+			timers.clear();
+			attempts.clear();
+		};
+	}, [scopeKey]);
+
+	useEffect(() => {
+		for (const resource of resources) {
+			if (
+				!requiresSourceRecovery(resource.meta)
+				|| resource.isFetching
+			) continue;
+
+			const key = JSON.stringify([scopeKey, resource.queryKey]);
+			const attempt = sourceRecoveryRef.current.get(key) ?? 0;
+			const delay = sourceRecoveryDelay(attempt);
+			if (delay === undefined) continue;
+
+			sourceRecoveryRef.current.set(key, attempt + 1);
+
+			const timer = setTimeout(() => {
+				sourceTimersRef.current.delete(timer);
+				void resource.refetch().catch(() => {});
+			}, delay);
+
+			sourceTimersRef.current.add(timer);
+		}
+	}, [resources, scopeKey]);
+
+	useEffect(() => {
+		const recover = () => {
+			for (const resource of resources) {
+				if (
+					!requiresSourceRecovery(resource.meta)
+					|| resource.isFetching
+				) continue;
+
+				const key = JSON.stringify([scopeKey, resource.queryKey]);
+				if (lifecycleRecoveryRef.current.has(key)) continue;
+
+				sourceRecoveryRef.current.delete(key);
+				lifecycleRecoveryRef.current.add(key);
+				void resource.refetch()
+					.catch(() => {})
+					.finally(() => lifecycleRecoveryRef.current.delete(key));
+			}
+		};
+
+		const unsubscribeFocus = focusManager.subscribe((focused) => {
+			if (focused) recover();
+		});
+
+		const unsubscribeOnline = onlineManager.subscribe((online) => {
+			if (online) recover();
+		});
+
+		return () => {
+			unsubscribeFocus();
+			unsubscribeOnline();
+		};
+	}, [resources, scopeKey]);
+
 	const isRefreshing
 		= (isCurrentMutation && mutation.isPending)
 			|| statuses.some(