@remit/web-client 0.0.324 → 0.0.326

package/dist/src/hooks/useSelectedSubjects.js

@@ -0,0 +1,62 @@
+import { threadOperationsListThreadsQueryKey, threadOperationsSearchThreadsQueryKey, unifiedThreadOperationsListAllThreadsQueryKey, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQueryClient } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { isInfiniteThreadData, isThreadItemsPage } from "../lib/thread-cache";
+/**
+ * Subjects of the selected messages, read off the thread rows already in the
+ * query cache — the rows the list rendered to let the user select them in the
+ * first place. No round-trip, and nothing to plumb through every surface that
+ * opens Organize.
+ *
+ * A message whose row is not cached contributes nothing; the prefill that
+ * consumes this treats missing subjects as an absence of evidence, not as an
+ * empty subject.
+ */
+/** Match every cached thread listing by operation, whatever mailbox, page, or
+ *  sort options it was fetched with — React Query matches keys partially. */
+const listingPrefixes = () => [
+    threadOperationsListThreadsQueryKey({ path: { mailboxId: "" } }),
+    threadOperationsSearchThreadsQueryKey({ path: { mailboxId: "" } }),
+    unifiedThreadOperationsListAllThreadsQueryKey(),
+].map((key) => [{ _id: key[0]._id }]);
+const pagesOf = (data) => {
+    if (isInfiniteThreadData(data))
+        return data.pages;
+    if (isThreadItemsPage(data))
+        return [data];
+    return [];
+};
+const isSubjectRow = (row) => typeof row === "object" &&
+    row !== null &&
+    typeof row.messageId === "string";
+/**
+ * Subjects for `messageIds`, in the order the ids were given, skipping ids with
+ * no cached row and rows with no subject.
+ */
+export const collectSubjects = (caches, messageIds) => {
+    const wanted = new Set(messageIds);
+    const bySubject = new Map();
+    for (const cache of caches) {
+        for (const page of pagesOf(cache)) {
+            for (const row of page.items) {
+                if (!isSubjectRow(row) || !wanted.has(row.messageId))
+                    continue;
+                const subject = row.subject?.trim();
+                if (subject)
+                    bySubject.set(row.messageId, subject);
+            }
+        }
+    }
+    return messageIds
+        .map((messageId) => bySubject.get(messageId))
+        .filter((subject) => subject !== undefined);
+};
+export const useSelectedSubjects = (messageIds) => {
+    const queryClient = useQueryClient();
+    const key = messageIds.join("\u0000");
+    // biome-ignore lint/correctness/useExhaustiveDependencies: the id list is compared by value through `key`; the cache is read once per selection, not subscribed to
+    return useMemo(() => {
+        const caches = listingPrefixes().flatMap((queryKey) => queryClient.getQueriesData({ queryKey }).map(([, data]) => data));
+        return collectSubjects(caches, messageIds);
+    }, [queryClient, key]);
+};

package/dist/src/hooks/useSignature.d.ts

@@ -0,0 +1,9 @@
+export interface SignatureData {
+    html: string;
+    plainText: string;
+}
+export declare const useSignature: (accountId?: string) => {
+    signature: SignatureData;
+    setSignature: (html: string, plainText: string) => void;
+    isSaving: boolean;
+};

package/dist/src/hooks/useSignature.js

@@ -0,0 +1,47 @@
+import { accountDetailOperationsUpdateAccountMutation, configOperationsGetConfigOptions, configOperationsGetConfigQueryKey, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useMemo } from "react";
+import { useErrorBanners } from "../components/ui/ErrorBannerProvider";
+import { buildMutationErrorBanner } from "../components/ui/error-banners";
+const EMPTY_SIGNATURE = { html: "", plainText: "" };
+export const useSignature = (accountId) => {
+    const queryClient = useQueryClient();
+    const { pushError } = useErrorBanners();
+    const { data: config } = useQuery({
+        ...configOperationsGetConfigOptions(),
+        staleTime: Infinity,
+    });
+    const signature = useMemo(() => {
+        if (!accountId || !config)
+            return EMPTY_SIGNATURE;
+        const account = config.accounts.find((a) => a.accountId === accountId);
+        if (!account)
+            return EMPTY_SIGNATURE;
+        return {
+            html: account.signatureHtml ?? "",
+            plainText: account.signaturePlainText ?? "",
+        };
+    }, [accountId, config]);
+    const mutation = useMutation({
+        ...accountDetailOperationsUpdateAccountMutation(),
+        onSuccess: () => {
+            queryClient.invalidateQueries({
+                queryKey: configOperationsGetConfigQueryKey(),
+            });
+        },
+        onError: (error) => {
+            // Saving the signature failed silently before — surface it. A fatal
+            // 5xx also escalates through the global MutationCache.onError sink.
+            pushError(buildMutationErrorBanner("Couldn't save signature", "The signature wasn't saved.", error));
+        },
+    });
+    const setSignature = useCallback((html, plainText) => {
+        if (!accountId)
+            return;
+        mutation.mutate({
+            path: { accountId },
+            body: { signatureHtml: html, signaturePlainText: plainText },
+        });
+    }, [accountId, mutation]);
+    return { signature, setSignature, isSaving: mutation.isPending };
+};

package/dist/src/hooks/useSpamMatchCounts.d.ts

@@ -0,0 +1,15 @@
+import type { SpamMailboxCount } from "../lib/spam-offer";
+import type { BriefSearchCriteria } from "./useBriefSections";
+export interface UseSpamMatchCountsOptions {
+    /** The committed search, exactly as the rows beneath the offer were asked for. */
+    criteria: BriefSearchCriteria;
+    /** Every junk folder in the search's scope, in a stable order. */
+    junkMailboxIds: readonly string[];
+    /**
+     * Whether a count is worth asking for. False while the view carries a term
+     * the request cannot express — the server would count a wider set than the
+     * list shows — and every folder reports no number.
+     */
+    enabled: boolean;
+}
+export declare function useSpamMatchCounts({ criteria, junkMailboxIds, enabled, }: UseSpamMatchCountsOptions): SpamMailboxCount[];

package/dist/src/hooks/useSpamMatchCounts.js

@@ -0,0 +1,74 @@
+/**
+ * How much of a search sits in Spam: one `listAllThreads` count per junk folder
+ * the search reached, under the search's own criteria.
+ *
+ * One request per folder rather than one for all of them, because the scope
+ * parameter names a single mailbox — and because the offer needs the folders
+ * apart as well as together: the sum is what it states, the largest is where its
+ * button goes. Accounts have one junk folder each, so this is one request per
+ * account and it is issued when the committed criteria change, never on a
+ * keystroke.
+ *
+ * `accountId` rides along on the criteria whenever the account pill is set, and
+ * the server intersects the two scopes: a junk folder of another account counts
+ * nothing. That is what keeps the sum the size of the list the reader is looking
+ * at rather than of every account they have.
+ *
+ * A count that has not arrived, failed, or came back absent is `unknown` for
+ * that folder, and `spamOfferFromCounts` turns any one of those into an unknown
+ * total. Nothing here substitutes a page length for a count the server did not
+ * give (#313).
+ *
+ * A failure is reported apart from the rest, because the three are not the same
+ * answer: a folder that could not be counted has not said it holds nothing, and
+ * an offer that vanished on a failed request is indistinguishable from a search
+ * that reaches no spam. These queries carry no `meta.softError` and must not:
+ * a 401 or 403 here escalates on the fail-fast contract (`shouldEscalate`,
+ * #1059) and puts the reader in front of the signed-out surface, which is the
+ * one thing a read must never answer with an empty result.
+ */
+import { unifiedThreadOperationsListAllThreadsQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { unifiedThreadOperationsListAllThreads } from "@remit/api-http-client/sdk.gen.ts";
+import { useQueries } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { toResultCount } from "../lib/result-count";
+/** Half a minute, matching the searched brief's own rows. */
+const SPAM_COUNT_STALE_TIME_MS = 30_000;
+const UNCOUNTED = { kind: "unknown" };
+// No `limit` and no cursor: the count is a property of the criteria, so no page
+// of mail is paid for and no expansion can ask for it again.
+const spamCountQuery = (criteria, mailboxId) => ({
+    ...criteria,
+    mailboxId,
+    order: "desc",
+    count: true,
+    results: false,
+});
+export function useSpamMatchCounts({ criteria, junkMailboxIds, enabled, }) {
+    const countQueries = useQueries({
+        queries: junkMailboxIds.map((mailboxId) => {
+            const query = spamCountQuery(criteria, mailboxId);
+            return {
+                queryKey: unifiedThreadOperationsListAllThreadsQueryKey({ query }),
+                queryFn: async () => {
+                    const { data } = await unifiedThreadOperationsListAllThreads({
+                        query,
+                        throwOnError: true,
+                    });
+                    return data;
+                },
+                enabled,
+                staleTime: SPAM_COUNT_STALE_TIME_MS,
+            };
+        }),
+    });
+    return useMemo(() => junkMailboxIds.map((mailboxId, index) => ({
+        mailboxId,
+        // `enabled` gates the request, not the cache: an uncounted view must
+        // not state the number an earlier, differently-scoped one left behind.
+        count: enabled
+            ? toResultCount(countQueries[index]?.data?.count)
+            : UNCOUNTED,
+        failed: enabled ? (countQueries[index]?.isError ?? false) : false,
+    })), [junkMailboxIds, countQueries, enabled]);
+}

package/dist/src/hooks/useStaleAccountSync.d.ts

@@ -0,0 +1,101 @@
+import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
+/**
+ * Mailboxes are considered stale 15 minutes after the last successful sync.
+ * Exposed for unit tests and possible future tuning.
+ */
+export declare const STALENESS_THRESHOLD_MS: number;
+/**
+ * Floor for the poll interval.
+ *
+ * This poll uses POST /sync, the same endpoint as a person pressing refresh,
+ * and that endpoint's triggers skip the server's per-mailbox freshness gate
+ * (`MAILBOX_FRESHNESS_MS`, 60s). A timer is not a person: every tick is a full
+ * folder-by-folder re-enumeration for every open account, so the interval is
+ * what bounds that work. Thirty seconds is the answer to how stale an open
+ * tab's mail may be, and buys it at twice the fan-out the gate's own window
+ * would allow. `mailboxPollIntervalSeconds` can lengthen the interval, never
+ * shorten it past this.
+ */
+export declare const MIN_POLL_INTERVAL_MS: number;
+/**
+ * Resolve the configured poll interval, never returning less than
+ * {@link MIN_POLL_INTERVAL_MS}.
+ */
+export declare const resolvePollIntervalMs: (configuredSeconds: string | undefined) => number;
+/**
+ * Client-side online-poll interval (#1251): while an account's mail is open,
+ * the tab re-triggers the same sync the pull-to-refresh path uses on this
+ * cadence — the replacement for the server's removed "online tier".
+ */
+export declare const POLL_INTERVAL_MS: number;
+/**
+ * The interval this tab is currently due on: the hot one while a refresh press
+ * is still recent, the configured ambient one otherwise. A deployment that has
+ * lengthened `mailboxPollIntervalSeconds` still gets the hot cadence for the
+ * few minutes after a press, which is what makes a press mean "and keep
+ * looking".
+ */
+export declare const currentPollIntervalMs: (now?: number, ambientMs?: number) => number;
+/**
+ * Bounded concurrency for the per-poll fan-out across open accounts —
+ * mirrors `SCHEDULER_ENQUEUE_CONCURRENCY` in
+ * remit-imap-worker/src/scheduler/config.ts (never an unbounded
+ * `Promise.all`, see doc/rules/coding-standards.md). A browser tab realistically
+ * has a handful of accounts open at once, so this is a ceiling, not a tuned
+ * throughput target.
+ */
+export declare const POLL_CONCURRENCY = 5;
+interface AccountLike {
+    accountId: string;
+    lastSyncAt?: number;
+}
+/**
+ * Pure selector: given a list of accounts and the current time, return
+ * the accountIds whose mailbox-list is stale and should be refreshed.
+ * `null`/`undefined` `lastSyncAt` is treated as stale unconditionally.
+ */
+export declare const selectStaleAccountIds: (accounts: AccountLike[], now: number, thresholdMs?: number) => string[];
+/**
+ * Pure predicate: has at least one full poll interval elapsed since the last
+ * poll? Shared by the recurring timer and the visibility-regain catch-up
+ * check so both use the exact same due-ness rule.
+ */
+export declare const hasPollIntervalElapsed: (now: number, lastPollAt: number, intervalMs?: number) => boolean;
+/**
+ * Pure selector: drop any accountId already mid-flight so a poll tick never
+ * stacks a second request onto one still in progress.
+ */
+export declare const selectPollableAccountIds: (accountIds: string[], inFlight: ReadonlySet<string>) => string[];
+/**
+ * Test-only helpers. Not exported from the public hook surface; consumers
+ * should never reach into the module-level Set directly.
+ */
+export declare const __resetStaleAccountSyncGuard: () => void;
+export declare const __peekStaleAccountSyncGuard: () => ReadonlySet<string>;
+/**
+ * Handle a failed background mailbox-sync trigger. This is a best-effort, direct
+ * SDK probe (not a React Query call), so we apply the same fail-fast decision by
+ * hand with the `softError` meta the call site owns: its non-5xx failures (the
+ * account's own 4xx, a statusless connectivity blip) stay soft — we drop the
+ * per-account guard so a later remount can retry, then log and move on. But a
+ * 5xx is OUR API broken, and per the contract (#1059) that always escalates to
+ * the full-screen overlay — even from a background trigger.
+ *
+ * Nobody is waiting on this one. It fires on mount, so escalating its 401 would
+ * put the full-screen page up on load for anyone whose session had lapsed,
+ * ahead of the sign-in the shell is already about to ask for.
+ */
+export declare const handleBackgroundSyncFailure: (accountId: string, error: unknown) => void;
+/**
+ * Auto-trigger a background mailbox-list sync for every stale account the
+ * first time MailLayout mounts in a session, then keep it fresh with a
+ * recurring online poll for as long as the mail app stays open (#1251) —
+ * the client-side replacement for the server's removed "online" sync tier.
+ * The poll runs on the ambient interval, or the hot one for the few minutes
+ * after somebody presses refresh, and only while the tab is visible.
+ * Fire-and-forget: does not block render, and silently logs failures (this
+ * is a best-effort background refresh — the user-visible UI for triggering
+ * is the "Refresh mailboxes" button in Settings).
+ */
+export declare const useStaleAccountSync: (accounts: RemitImapAccountResponse[]) => void;
+export {};

package/dist/src/hooks/useStaleAccountSync.js

@@ -0,0 +1,252 @@
+import { mailboxOperationsListMailboxesQueryKey } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { syncOperationsTriggerSync } from "@remit/api-http-client/sdk.gen.ts";
+import { useQueryClient } from "@tanstack/react-query";
+import pMap from "p-map";
+import { useEffect, useRef } from "react";
+import { shouldEscalate } from "../lib/error-classifier";
+import { reportFatalError } from "../lib/fatal-error";
+import { HOT_POLL_INTERVAL_MS, isHotSyncWindowActive, subscribeHotSyncWindow, } from "../lib/hot-sync-window";
+import { getRuntimeConfig } from "../runtime-config";
+/**
+ * Mailboxes are considered stale 15 minutes after the last successful sync.
+ * Exposed for unit tests and possible future tuning.
+ */
+export const STALENESS_THRESHOLD_MS = 15 * 60 * 1000;
+const DEFAULT_POLL_INTERVAL_SECONDS = 30;
+const parsePositiveIntSeconds = (raw, fallback) => {
+    if (!raw)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
+/**
+ * Floor for the poll interval.
+ *
+ * This poll uses POST /sync, the same endpoint as a person pressing refresh,
+ * and that endpoint's triggers skip the server's per-mailbox freshness gate
+ * (`MAILBOX_FRESHNESS_MS`, 60s). A timer is not a person: every tick is a full
+ * folder-by-folder re-enumeration for every open account, so the interval is
+ * what bounds that work. Thirty seconds is the answer to how stale an open
+ * tab's mail may be, and buys it at twice the fan-out the gate's own window
+ * would allow. `mailboxPollIntervalSeconds` can lengthen the interval, never
+ * shorten it past this.
+ */
+export const MIN_POLL_INTERVAL_MS = 30 * 1000;
+/**
+ * Resolve the configured poll interval, never returning less than
+ * {@link MIN_POLL_INTERVAL_MS}.
+ */
+export const resolvePollIntervalMs = (configuredSeconds) => Math.max(parsePositiveIntSeconds(configuredSeconds, DEFAULT_POLL_INTERVAL_SECONDS) *
+    1000, MIN_POLL_INTERVAL_MS);
+/**
+ * Client-side online-poll interval (#1251): while an account's mail is open,
+ * the tab re-triggers the same sync the pull-to-refresh path uses on this
+ * cadence — the replacement for the server's removed "online tier".
+ */
+export const POLL_INTERVAL_MS = resolvePollIntervalMs(getRuntimeConfig().mailboxPollIntervalSeconds);
+/**
+ * The interval this tab is currently due on: the hot one while a refresh press
+ * is still recent, the configured ambient one otherwise. A deployment that has
+ * lengthened `mailboxPollIntervalSeconds` still gets the hot cadence for the
+ * few minutes after a press, which is what makes a press mean "and keep
+ * looking".
+ */
+export const currentPollIntervalMs = (now = Date.now(), ambientMs = POLL_INTERVAL_MS) => isHotSyncWindowActive(now)
+    ? Math.min(HOT_POLL_INTERVAL_MS, ambientMs)
+    : ambientMs;
+/**
+ * Bounded concurrency for the per-poll fan-out across open accounts —
+ * mirrors `SCHEDULER_ENQUEUE_CONCURRENCY` in
+ * remit-imap-worker/src/scheduler/config.ts (never an unbounded
+ * `Promise.all`, see doc/rules/coding-standards.md). A browser tab realistically
+ * has a handful of accounts open at once, so this is a ceiling, not a tuned
+ * throughput target.
+ */
+export const POLL_CONCURRENCY = 5;
+/**
+ * Module-level guard: which accounts have already had a background sync
+ * fired in this browser tab's session. Survives layout re-mounts (route
+ * changes) so re-mounting MailLayout does not spam SQS.
+ */
+const triggeredAccountIds = new Set();
+/**
+ * Pure selector: given a list of accounts and the current time, return
+ * the accountIds whose mailbox-list is stale and should be refreshed.
+ * `null`/`undefined` `lastSyncAt` is treated as stale unconditionally.
+ */
+export const selectStaleAccountIds = (accounts, now, thresholdMs = STALENESS_THRESHOLD_MS) => accounts
+    .filter((account) => {
+    const last = account.lastSyncAt;
+    if (last === undefined || last === null)
+        return true;
+    return now - last > thresholdMs;
+})
+    .map((account) => account.accountId);
+/**
+ * Pure predicate: has at least one full poll interval elapsed since the last
+ * poll? Shared by the recurring timer and the visibility-regain catch-up
+ * check so both use the exact same due-ness rule.
+ */
+export const hasPollIntervalElapsed = (now, lastPollAt, intervalMs = POLL_INTERVAL_MS) => now - lastPollAt >= intervalMs;
+/**
+ * Pure selector: drop any accountId already mid-flight so a poll tick never
+ * stacks a second request onto one still in progress.
+ */
+export const selectPollableAccountIds = (accountIds, inFlight) => accountIds.filter((id) => !inFlight.has(id));
+/**
+ * Test-only helpers. Not exported from the public hook surface; consumers
+ * should never reach into the module-level Set directly.
+ */
+export const __resetStaleAccountSyncGuard = () => {
+    triggeredAccountIds.clear();
+};
+export const __peekStaleAccountSyncGuard = () => triggeredAccountIds;
+/**
+ * Handle a failed background mailbox-sync trigger. This is a best-effort, direct
+ * SDK probe (not a React Query call), so we apply the same fail-fast decision by
+ * hand with the `softError` meta the call site owns: its non-5xx failures (the
+ * account's own 4xx, a statusless connectivity blip) stay soft — we drop the
+ * per-account guard so a later remount can retry, then log and move on. But a
+ * 5xx is OUR API broken, and per the contract (#1059) that always escalates to
+ * the full-screen overlay — even from a background trigger.
+ *
+ * Nobody is waiting on this one. It fires on mount, so escalating its 401 would
+ * put the full-screen page up on load for anyone whose session had lapsed,
+ * ahead of the sign-in the shell is already about to ask for.
+ */
+export const handleBackgroundSyncFailure = (accountId, error) => {
+    triggeredAccountIds.delete(accountId);
+    if (shouldEscalate(error, { softError: true }, "nobody")) {
+        reportFatalError(error);
+        return;
+    }
+    console.warn("[remit] background mailbox sync failed", {
+        accountId,
+        error,
+    });
+};
+/**
+ * Trigger the same sync the pull-to-refresh path uses and invalidate the
+ * mailbox-list query on success. `throwOnError: true` so a server failure
+ * rejects instead of silently resolving with `{ error }` (the default),
+ * which would let a 500 look like a successful sync and invalidate queries
+ * anyway.
+ */
+const runBackgroundSync = (accountId, queryClient) => syncOperationsTriggerSync({ path: { accountId }, throwOnError: true }).then(() => {
+    queryClient.invalidateQueries({
+        queryKey: mailboxOperationsListMailboxesQueryKey({
+            path: { accountId },
+        }),
+    });
+});
+/**
+ * Auto-trigger a background mailbox-list sync for every stale account the
+ * first time MailLayout mounts in a session, then keep it fresh with a
+ * recurring online poll for as long as the mail app stays open (#1251) —
+ * the client-side replacement for the server's removed "online" sync tier.
+ * The poll runs on the ambient interval, or the hot one for the few minutes
+ * after somebody presses refresh, and only while the tab is visible.
+ * Fire-and-forget: does not block render, and silently logs failures (this
+ * is a best-effort background refresh — the user-visible UI for triggering
+ * is the "Refresh mailboxes" button in Settings).
+ */
+export const useStaleAccountSync = (accounts) => {
+    const queryClient = useQueryClient();
+    // Hold the latest accounts in a ref so both effects can read them without
+    // re-running on every render; they re-run only when the joined accountId
+    // list actually changes (account added / removed).
+    const accountsRef = useRef(accounts);
+    accountsRef.current = accounts;
+    const stableKey = accounts.map((a) => a.accountId).join(",");
+    // biome-ignore lint/correctness/useExhaustiveDependencies: stableKey is a serialized account list used to trigger re-sync on account changes; adding it would cause issues without also referencing accountsRef
+    useEffect(() => {
+        const now = Date.now();
+        const stale = selectStaleAccountIds(accountsRef.current, now);
+        const fresh = stale.filter((id) => !triggeredAccountIds.has(id));
+        if (fresh.length === 0)
+            return;
+        for (const accountId of fresh) {
+            triggeredAccountIds.add(accountId);
+            runBackgroundSync(accountId, queryClient).catch((err) => {
+                handleBackgroundSyncFailure(accountId, err);
+            });
+        }
+    }, [stableKey, queryClient]);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: stableKey re-runs the poll loop when the account list changes; accountsRef supplies the live list each tick
+    useEffect(() => {
+        let lastPollAt = Date.now();
+        let timeoutId;
+        const inFlight = new Set();
+        const poll = () => {
+            lastPollAt = Date.now();
+            const ids = selectPollableAccountIds(accountsRef.current.map((a) => a.accountId), inFlight);
+            // Mark every selected id in flight before dispatch (not as pMap
+            // starts each one) so a concurrency-queued id still counts as
+            // "already polling" for the next tick's `selectPollableAccountIds`
+            // check — no stacked requests even while waiting for a free slot.
+            for (const accountId of ids)
+                inFlight.add(accountId);
+            void pMap(ids, (accountId) => runBackgroundSync(accountId, queryClient)
+                .catch((err) => {
+                handleBackgroundSyncFailure(accountId, err);
+            })
+                .finally(() => {
+                inFlight.delete(accountId);
+            }), { concurrency: POLL_CONCURRENCY });
+        };
+        const tick = () => {
+            if (document.visibilityState === "visible") {
+                poll();
+                timeoutId = setTimeout(tick, currentPollIntervalMs());
+                return;
+            }
+            // Hidden: don't reschedule. `handleVisibilityChange` resumes the loop
+            // (with an immediate catch-up poll if one is due) once the tab is
+            // visible again. A hot window running out while the tab is away costs
+            // nothing — there is nobody watching a list to keep current.
+        };
+        // A tick that fired while the tab was hidden left no timer behind, so
+        // coming back is the only thing that can re-arm the loop — it does so
+        // unconditionally. Due-ness decides whether this tab polls *now*, never
+        // whether a next tick exists: a tab that went to sleep on the hot cadence
+        // and came back after the window lapsed is not due against a longer
+        // ambient interval, and used to stop polling for good (#1031).
+        const handleVisibilityChange = () => {
+            if (document.visibilityState !== "visible")
+                return;
+            if (timeoutId !== undefined)
+                clearTimeout(timeoutId);
+            const now = Date.now();
+            const intervalMs = currentPollIntervalMs(now);
+            if (hasPollIntervalElapsed(now, lastPollAt, intervalMs)) {
+                poll();
+                timeoutId = setTimeout(tick, intervalMs);
+                return;
+            }
+            timeoutId = setTimeout(tick, lastPollAt + intervalMs - now);
+        };
+        // A press opens the hot window, but this loop may already be asleep on a
+        // long ambient interval — reschedule onto the hot one rather than sit
+        // out the rest of that wait. The press has just triggered its own sync,
+        // so this only moves the *next* tick: never a poll on the press itself,
+        // and never a tighter loop than the interval (POST /sync is deliberately
+        // never coalesced, #37).
+        const handleHotWindow = () => {
+            if (document.visibilityState !== "visible")
+                return;
+            if (timeoutId !== undefined)
+                clearTimeout(timeoutId);
+            lastPollAt = Date.now();
+            timeoutId = setTimeout(tick, currentPollIntervalMs());
+        };
+        timeoutId = setTimeout(tick, currentPollIntervalMs());
+        document.addEventListener("visibilitychange", handleVisibilityChange);
+        const unsubscribeHotWindow = subscribeHotSyncWindow(handleHotWindow);
+        return () => {
+            if (timeoutId !== undefined)
+                clearTimeout(timeoutId);
+            document.removeEventListener("visibilitychange", handleVisibilityChange);
+            unsubscribeHotWindow();
+        };
+    }, [stableKey, queryClient]);
+};

package/dist/src/hooks/useStarredThreads.d.ts

@@ -0,0 +1,42 @@
+import type { RemitImapThreadMessageResponse } from "@remit/api-http-client/types.gen.ts";
+import type { ThreadSearchTokenParams } from "../lib/thread-search-tokens";
+/** The criteria the Flagged view narrows its listing by, all server-applied. */
+export interface StarredCriteria extends ThreadSearchTokenParams {
+    /**
+     * Free text, matched against subject, From and the body preview over the
+     * whole collection.
+     */
+    query?: string;
+}
+export declare const starredThreadsQueryKey: (criteria?: StarredCriteria) => [Pick<import("@remit/api-http-client").Options<import("@remit/api-http-client").UnifiedThreadOperationsListAllThreadsData>, "query" | "body" | "headers" | "path" | "baseUrl"> & {
+    _id: string;
+    _infinite?: boolean;
+    tags?: ReadonlyArray<string>;
+}];
+interface StarredThreads {
+    /** Every matching starred thread across the pages loaded so far, newest first. */
+    threads: RemitImapThreadMessageResponse[];
+    isLoading: boolean;
+    isError: boolean;
+    error: unknown;
+    refetch: () => void;
+    fetchNextPage: () => void;
+    hasNextPage: boolean;
+    isFetchingNextPage: boolean;
+}
+export declare function useStarredThreads(criteria?: StarredCriteria): StarredThreads;
+/**
+ * How many of the matching starred messages are unread, counted by the server.
+ *
+ * Its own request, so no cursor enters the key and pressing "load more" cannot
+ * move the number — the count is over the whole collection under the active
+ * criteria, which is what the header claims it is. A page-length count grows
+ * with every press and reads as a total, which is the defect this replaces
+ * (#308). `results: false` reads the count alone: no rows are fetched or
+ * enriched to answer it.
+ *
+ * Undefined until the server answers, and undefined when it cannot. The header
+ * shows no number rather than a made-up one.
+ */
+export declare function useStarredUnreadCount(criteria?: StarredCriteria): number | undefined;
+export {};