@remit/web-client 0.0.325 → 0.0.326

package/dist/src/lib/intelligence-pref.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Persistence for the intelligence-pane open/closed preference (#782), and the
+ * precedence between it and the address (#722).
+ *
+ * The pane opens with the thread by default; a manual collapse sticks across
+ * sessions. Storage failures (private mode / quota) fall back to the default
+ * (open) rather than crashing.
+ */
+import type { PanelFragment } from "../routing";
+export declare const INTELLIGENCE_PREF_KEY = "remit:intelligence-open";
+export declare function readIntelligencePref(): boolean;
+export declare function writeIntelligencePref(open: boolean): void;
+export interface RailVisibility {
+    /** The panels the address names. */
+    panels: readonly PanelFragment[];
+    prefersOpen: boolean;
+    /** The rail is a pane of the desktop shell; narrower tiers have a drawer. */
+    isDesktop: boolean;
+    /** The rail reads a conversation, so with none open there is nothing to be up. */
+    hasThread: boolean;
+    /** The message a transient raise was made for, if one is live. */
+    raisedFor: string | null;
+    /** The message on screen, which is what a raise is measured against. */
+    openMessage: string | null;
+}
+/**
+ * Whether the rail is up.
+ *
+ * A raise answers first, and only for the message it was made for: a DKIM
+ * mismatch or the banner's "Why?" surfaces the rail over a collapse, because
+ * the reader is being shown something about what is in front of them — and
+ * opening anything else ends it, so one mismatched signature is not the chrome
+ * of the whole session (#778). It is measured rather than stored, which is why
+ * it never reaches the address or the preference.
+ *
+ * Otherwise an address that names any panel is the only owner of what is open,
+ * so a shared link showing the shortcuts sheet is not overwritten by the
+ * recipient's own preference. The preference speaks only where the address is
+ * silent, and only with a conversation open on the tier that has a rail — it
+ * opens with the thread there (#782), while a phone would get a full-screen
+ * drawer over a message nobody asked to cover.
+ */
+export declare function resolveRailOpen({ panels, prefersOpen, isDesktop, hasThread, raisedFor, openMessage, }: RailVisibility): boolean;

package/dist/src/lib/intelligence-pref.js

@@ -0,0 +1,41 @@
+export const INTELLIGENCE_PREF_KEY = "remit:intelligence-open";
+export function readIntelligencePref() {
+    try {
+        return localStorage.getItem(INTELLIGENCE_PREF_KEY) !== "closed";
+    }
+    catch {
+        return true;
+    }
+}
+export function writeIntelligencePref(open) {
+    try {
+        localStorage.setItem(INTELLIGENCE_PREF_KEY, open ? "open" : "closed");
+    }
+    catch {
+        // Storage unavailable — the in-memory default stands.
+    }
+}
+/**
+ * Whether the rail is up.
+ *
+ * A raise answers first, and only for the message it was made for: a DKIM
+ * mismatch or the banner's "Why?" surfaces the rail over a collapse, because
+ * the reader is being shown something about what is in front of them — and
+ * opening anything else ends it, so one mismatched signature is not the chrome
+ * of the whole session (#778). It is measured rather than stored, which is why
+ * it never reaches the address or the preference.
+ *
+ * Otherwise an address that names any panel is the only owner of what is open,
+ * so a shared link showing the shortcuts sheet is not overwritten by the
+ * recipient's own preference. The preference speaks only where the address is
+ * silent, and only with a conversation open on the tier that has a rail — it
+ * opens with the thread there (#782), while a phone would get a full-screen
+ * drawer over a message nobody asked to cover.
+ */
+export function resolveRailOpen({ panels, prefersOpen, isDesktop, hasThread, raisedFor, openMessage, }) {
+    if (raisedFor !== null && raisedFor === openMessage)
+        return true;
+    if (panels.length > 0)
+        return panels.includes("intelligence");
+    return isDesktop && hasThread && prefersOpen;
+}

package/dist/src/lib/json.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Parse JSON in a Promise so a malformed string surfaces as a rejection the
+ * caller can `.catch()`, instead of a synchronous throw that would need a block
+ * try/catch. Use only where an unparseable value is an expected, recoverable
+ * outcome — a file the reader picked by mistake — never to soften an internal
+ * contract, which must stay a fatal uncaught `JSON.parse`.
+ */
+export declare const safeJsonParse: <T>(raw: string) => Promise<T>;

package/dist/src/lib/json.js

@@ -0,0 +1,10 @@
+/**
+ * Parse JSON in a Promise so a malformed string surfaces as a rejection the
+ * caller can `.catch()`, instead of a synchronous throw that would need a block
+ * try/catch. Use only where an unparseable value is an expected, recoverable
+ * outcome — a file the reader picked by mistake — never to soften an internal
+ * contract, which must stay a fatal uncaught `JSON.parse`.
+ */
+export const safeJsonParse = (raw) => new Promise((resolve) => {
+    resolve(JSON.parse(raw));
+});

package/dist/src/lib/junk-destination.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Where the Junk verb can file mail, and why it cannot when it cannot (#522).
+ * One reading, for every surface that offers the verb: the selection bar, the
+ * keyboard, the brief's own bar and the wizard's commit. A second derivation is
+ * what let the keyboard open a wizard on a verb the bar was withholding.
+ */
+export declare const NO_JUNK_FOLDER_REASON = "This account has no Junk folder appointed, so there is nowhere to file these. Appoint one under Settings \u203A Folder roles.";
+export declare const ALREADY_IN_JUNK_REASON = "These are already in Junk, so there is nowhere to file them.";
+/**
+ * The account's appointed Junk folder, and nothing at all when the account has
+ * appointed none or when that folder is the one the mail is already in.
+ */
+export declare const junkDestination: (junkMailboxId: string | undefined, currentMailboxId: string | undefined) => string | undefined;
+/** Why the verb cannot be offered here, and nothing when it can. */
+export declare const junkWithheldReason: (junkMailboxId: string | undefined, currentMailboxId: string | undefined) => string | undefined;

package/dist/src/lib/junk-destination.js

@@ -0,0 +1,24 @@
+/**
+ * Where the Junk verb can file mail, and why it cannot when it cannot (#522).
+ * One reading, for every surface that offers the verb: the selection bar, the
+ * keyboard, the brief's own bar and the wizard's commit. A second derivation is
+ * what let the keyboard open a wizard on a verb the bar was withholding.
+ */
+export const NO_JUNK_FOLDER_REASON = "This account has no Junk folder appointed, so there is nowhere to file these. Appoint one under Settings › Folder roles.";
+export const ALREADY_IN_JUNK_REASON = "These are already in Junk, so there is nowhere to file them.";
+/**
+ * The account's appointed Junk folder, and nothing at all when the account has
+ * appointed none or when that folder is the one the mail is already in.
+ */
+export const junkDestination = (junkMailboxId, currentMailboxId) => junkMailboxId !== undefined && junkMailboxId !== currentMailboxId
+    ? junkMailboxId
+    : undefined;
+/** Why the verb cannot be offered here, and nothing when it can. */
+export const junkWithheldReason = (junkMailboxId, currentMailboxId) => {
+    if (junkDestination(junkMailboxId, currentMailboxId) !== undefined) {
+        return undefined;
+    }
+    return junkMailboxId === undefined
+        ? NO_JUNK_FOLDER_REASON
+        : ALREADY_IN_JUNK_REASON;
+};

package/dist/src/lib/list-focus.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Roving-tabindex math for the message list.
+ *
+ * A virtualized list of hundreds of rows must expose exactly one tab stop:
+ * Tab then moves focus into the list at the keyboard cursor and Shift+Tab moves
+ * back out to the side panel, instead of walking every row. Pure so the rule is
+ * testable without a DOM.
+ */
+/**
+ * The id of the row that holds the list's tab stop. The keyboard cursor owns it
+ * while it points at a loaded row; otherwise the first row does, so an untouched
+ * list is still reachable with one Tab.
+ */
+export declare function tabStopId(orderedIds: string[], focusedId: string | undefined): string | undefined;

package/dist/src/lib/list-focus.js

@@ -0,0 +1,21 @@
+/**
+ * Roving-tabindex math for the message list.
+ *
+ * A virtualized list of hundreds of rows must expose exactly one tab stop:
+ * Tab then moves focus into the list at the keyboard cursor and Shift+Tab moves
+ * back out to the side panel, instead of walking every row. Pure so the rule is
+ * testable without a DOM.
+ */
+/**
+ * The id of the row that holds the list's tab stop. The keyboard cursor owns it
+ * while it points at a loaded row; otherwise the first row does, so an untouched
+ * list is still reachable with one Tab.
+ */
+export function tabStopId(orderedIds, focusedId) {
+    if (orderedIds.length === 0)
+        return undefined;
+    if (focusedId !== undefined && orderedIds.includes(focusedId)) {
+        return focusedId;
+    }
+    return orderedIds[0];
+}

package/dist/src/lib/list-header-chrome.d.ts

@@ -0,0 +1,40 @@
+import { type ReactNode } from "react";
+/**
+ * The list header's own chrome, as rendered nodes.
+ *
+ * The list header and the selection bar are one surface (#480), so the nav
+ * button, the unread count and the search affordance belong on the same row as
+ * the count and the verbs. That row is rendered by the body — the list owns the
+ * selection — while the search state it needs belongs to `MailListHeader`.
+ * Handing the built nodes down keeps one definition of the chrome and keeps the
+ * bar's two states in the same commit: nothing here is derived from a state
+ * update that lands after paint.
+ *
+ * The body is a virtualized list, so it re-renders every row when this object
+ * changes. Nothing that moves with a keystroke belongs on it (#506) — what is
+ * typed, where the caret is and what the query converts to reach their readers
+ * through their own contexts.
+ */
+export interface ListHeaderChrome {
+    /** The view's name, carried while nothing is ticked. */
+    title: string;
+    /** Hamburger for the nav slide-over; absent where the nav is a pane. */
+    navSlot: ReactNode;
+    /** Unread count, beside the title. */
+    titleMeta: ReactNode;
+    /** Magnifier that opens search, on the tiers whose header owns a field. */
+    searchSlot: ReactNode;
+    /** The expanded field, which takes the title's place for as long as it is up. */
+    searchField: ReactNode;
+    /**
+     * The read-only results panel, when a query is being typed and
+     * this view answers it with the panel rather than its own rows. The body
+     * renders it in place of its list; `MailListHeader` cannot swap the body
+     * out from above, because the header is inside it.
+     */
+    searchResults: ReactNode;
+    /** The search's make-this-a-filter row, up only while nothing is ticked. */
+    makeFilterSlot: ReactNode;
+}
+export declare const ListHeaderChromeContext: import("react").Context<ListHeaderChrome>;
+export declare const useListHeaderChrome: () => ListHeaderChrome;

package/dist/src/lib/list-header-chrome.js

@@ -0,0 +1,12 @@
+import { createContext, useContext } from "react";
+const NO_CHROME = {
+    title: "",
+    navSlot: null,
+    titleMeta: null,
+    searchSlot: null,
+    searchField: null,
+    searchResults: null,
+    makeFilterSlot: null,
+};
+export const ListHeaderChromeContext = createContext(NO_CHROME);
+export const useListHeaderChrome = () => useContext(ListHeaderChromeContext);

package/dist/src/lib/list-narrowing.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Whether a list is narrowed, and by what — one derived fact for every list.
+ *
+ * `MessageListEmpty` reads the presence of a `MessageListFilter` as "something
+ * is filtering this list". Both list panes used to build that object from the
+ * category chip alone, so a reader who had narrowed by the Unread chip, the Has
+ * attachment chip, or a typed `is:unread` was told the collection itself was
+ * empty — "No messages in Starred" over a mailbox full of starred mail (#1126).
+ *
+ * Every narrowing the two panes offer therefore lands here: the chips the view
+ * holds and the tokens parsed out of the search field. A chip beats a token
+ * where both set the same parameter, exactly as the request builders resolve
+ * them, so the sentence and the query can never disagree.
+ */
+import type { FilterReach, MessageListFilter } from "@remit/ui";
+import { type InboxFilterCriteria } from "./inbox-filters.js";
+import type { SearchToken } from "./search-tokens.js";
+/**
+ * The narrowing as the noun phrase the empty state's headline reads "No " in
+ * front of, or `undefined` when nothing narrows the list.
+ */
+export declare const narrowingLabel: (chips: InboxFilterCriteria, tokens: readonly SearchToken[]) => string | undefined;
+export interface ListNarrowing {
+    /** The chip state the view holds. */
+    chips: InboxFilterCriteria;
+    /** Every token the search field carries, sent as a parameter or not. */
+    tokens: readonly SearchToken[];
+    /** How much of the collection the request reached, read off the request. */
+    reach: FilterReach;
+    /** Drops every narrowing the label names — the chips and the query alike. */
+    onClear: () => void;
+}
+/** The filter a narrowed list hands its empty state, or `undefined` when it is
+ *  not narrowed at all. */
+export declare const listNarrowing: ({ chips, tokens, reach, onClear, }: ListNarrowing) => MessageListFilter | undefined;

package/dist/src/lib/list-narrowing.js

@@ -0,0 +1,133 @@
+/**
+ * Whether a list is narrowed, and by what — one derived fact for every list.
+ *
+ * `MessageListEmpty` reads the presence of a `MessageListFilter` as "something
+ * is filtering this list". Both list panes used to build that object from the
+ * category chip alone, so a reader who had narrowed by the Unread chip, the Has
+ * attachment chip, or a typed `is:unread` was told the collection itself was
+ * empty — "No messages in Starred" over a mailbox full of starred mail (#1126).
+ *
+ * Every narrowing the two panes offer therefore lands here: the chips the view
+ * holds and the tokens parsed out of the search field. A chip beats a token
+ * where both set the same parameter, exactly as the request builders resolve
+ * them, so the sentence and the query can never disagree.
+ */
+import { categoryLabel } from "./inbox-filters.js";
+const UNREAD = {
+    dimension: "read",
+    position: "pre",
+    text: "unread",
+};
+const READ = {
+    dimension: "read",
+    position: "pre",
+    text: "read",
+};
+const STARRED = {
+    dimension: "starred",
+    position: "pre",
+    text: "starred",
+};
+const ATTACHMENT = {
+    dimension: "attachment",
+    position: "post",
+    text: "with an attachment",
+};
+/** The attribute chips, in the order the phrase says them. */
+const ATTRIBUTE_PARTS = [
+    ["unread", UNREAD],
+    ["flagged", STARRED],
+    ["attachment", ATTACHMENT],
+];
+const tokenPart = (token) => {
+    switch (token.type) {
+        case "category":
+            return {
+                dimension: "category",
+                position: "pre",
+                text: categoryLabel(token.category) ?? token.value,
+            };
+        case "isUnread":
+            return UNREAD;
+        case "isRead":
+            return READ;
+        case "isStarred":
+            return STARRED;
+        case "hasAttachment":
+            return ATTACHMENT;
+        case "from":
+            return {
+                dimension: token.raw,
+                position: "post",
+                text: `from ${token.value}`,
+            };
+        case "subject":
+            return {
+                dimension: token.raw,
+                position: "post",
+                text: `about “${token.value}”`,
+            };
+        case "before":
+            return {
+                dimension: token.raw,
+                position: "post",
+                text: `sent before ${token.value}`,
+            };
+        case "after":
+            return {
+                dimension: token.raw,
+                position: "post",
+                text: `sent on or after ${token.value}`,
+            };
+        case "in":
+            return {
+                dimension: token.raw,
+                position: "post",
+                text: `in ${token.value}`,
+            };
+        case "account":
+            return {
+                dimension: token.raw,
+                position: "post",
+                text: `in the ${token.value} account`,
+            };
+    }
+};
+/** Everything narrowing the list, chips first, each dimension said once. */
+const narrowingParts = (chips, tokens) => {
+    const byDimension = new Map();
+    const add = (part) => {
+        if (byDimension.has(part.dimension))
+            return;
+        byDimension.set(part.dimension, part);
+    };
+    const category = categoryLabel(chips.category);
+    if (category)
+        add({ dimension: "category", position: "pre", text: category });
+    for (const [id, part] of ATTRIBUTE_PARTS) {
+        if (chips.attributes.has(id))
+            add(part);
+    }
+    for (const token of tokens)
+        add(tokenPart(token));
+    return [...byDimension.values()];
+};
+/**
+ * The narrowing as the noun phrase the empty state's headline reads "No " in
+ * front of, or `undefined` when nothing narrows the list.
+ */
+export const narrowingLabel = (chips, tokens) => {
+    const parts = narrowingParts(chips, tokens);
+    if (parts.length === 0)
+        return undefined;
+    const said = (position) => parts.filter((part) => part.position === position).map((p) => p.text);
+    return [...said("pre"), "mail", ...said("post")].join(" ");
+};
+/** The filter a narrowed list hands its empty state, or `undefined` when it is
+ *  not narrowed at all. */
+export const listNarrowing = ({ chips, tokens, reach, onClear, }) => {
+    const label = narrowingLabel(chips, tokens);
+    if (!label)
+        return undefined;
+    return { label, reach, onClear };
+};

package/dist/src/lib/list-verb-request.d.ts

@@ -0,0 +1,43 @@
+/**
+ * What a message list does with a verb the keyboard aimed at it (#477 1.4,
+ * #508, #522). Pure, so the routing is testable without the DOM, the router and
+ * the data hooks a list wires together.
+ */
+import type { Verb } from "@remit/ui";
+/**
+ * - `openWizard` — the selection walks the wizard, which is where a bulk action
+ *   is reviewed before it reaches the mail server.
+ * - `confirmDelete` — the one verb a bare cursor keeps, with its confirmation.
+ * - `withheld` — the press belongs to what is already on screen: the delete
+ *   confirmation is asking, and answering it is the Confirm button's job.
+ * - `unavailable` — the verb cannot act on this mail from here, and this is why.
+ *   The list takes the press and says so, rather than leaving a shortcut that
+ *   silently does nothing.
+ * - `declined` — not the list's press, so the pane acts on the focused row.
+ */
+export type ListVerbRequest = {
+    kind: "openWizard";
+} | {
+    kind: "confirmDelete";
+    messageId: string;
+} | {
+    kind: "withheld";
+} | {
+    kind: "unavailable";
+    reason: string;
+} | {
+    kind: "declined";
+};
+export interface ListVerbReading {
+    verb: Verb;
+    /** The delete confirmation is on screen. */
+    confirmingDelete: boolean;
+    hasSelection: boolean;
+    /** The account's appointed Junk folder, when it has appointed one. */
+    junkMailboxId: string | undefined;
+    /** The mailbox the rows are in, which the Junk destination cannot also be. */
+    currentMailboxId: string | undefined;
+    /** The row under the cursor, when this surface can delete it. */
+    deletableMessageId: string | undefined;
+}
+export declare const listVerbRequest: ({ verb, confirmingDelete, hasSelection, junkMailboxId, currentMailboxId, deletableMessageId, }: ListVerbReading) => ListVerbRequest;

package/dist/src/lib/list-verb-request.js

@@ -0,0 +1,24 @@
+/**
+ * What a message list does with a verb the keyboard aimed at it (#477 1.4,
+ * #508, #522). Pure, so the routing is testable without the DOM, the router and
+ * the data hooks a list wires together.
+ */
+import { junkWithheldReason } from "./junk-destination";
+export const listVerbRequest = ({ verb, confirmingDelete, hasSelection, junkMailboxId, currentMailboxId, deletableMessageId, }) => {
+    if (confirmingDelete)
+        return { kind: "withheld" };
+    // Junk with nowhere to file into is kept off the keyboard exactly as the bar
+    // keeps it off the screen. Opening the wizard on it instead ends on a commit
+    // that resolves no destination, whatever is ticked (#522).
+    if (verb === "junk") {
+        const reason = junkWithheldReason(junkMailboxId, currentMailboxId);
+        if (reason !== undefined)
+            return { kind: "unavailable", reason };
+    }
+    if (hasSelection)
+        return { kind: "openWizard" };
+    if (verb !== "delete" || deletableMessageId === undefined) {
+        return { kind: "declined" };
+    }
+    return { kind: "confirmDelete", messageId: deletableMessageId };
+};

package/dist/src/lib/mail-context.d.ts

@@ -0,0 +1,61 @@
+import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
+import { type ResultFolderIndex } from "./result-folder.js";
+/**
+ * Shared mail-layout context. Lives in `lib/` — NOT in `routes/mail.tsx` — on
+ * purpose: the route tree loads route files through the code splitter, so a
+ * context declared in a route file can resolve to two module instances, giving the
+ * `MailLayout` provider and a child-route consumer two different `MailContext`
+ * objects — the consumer then silently falls back to the defaults below (this
+ * bit the intelligence toggle: clicks reached a no-op handler). Keeping the
+ * context in a module that is not a route file guarantees a single instance
+ * shared by provider and consumers.
+ */
+export interface MailContextValue {
+    accounts: RemitImapAccountResponse[];
+    /**
+     * Name indexes `parseSearchTokens` resolves `in:`/`account:` chips against
+     * (#428 follow-up). Computed once here so every consumer — chip rendering,
+     * the brief/flagged token filters — agrees on the same
+     * resolution. See `lib/search-token-index.ts`.
+     */
+    mailboxNameIndex: ReadonlyMap<string, string>;
+    accountNameIndex: ReadonlyMap<string, string>;
+    /**
+     * mailboxId → the folder a search result read from that mailbox came from.
+     * Computed once here for the same reason as the name indexes: the row labels,
+     * the spam hold-out and the scope chip must agree on which folder is which.
+     * See `lib/result-folder.ts`.
+     */
+    resultFolderIndex: ResultFolderIndex;
+    searchQuery: string;
+    /** Live (pre-debounce) search input — the search field binds this. */
+    searchInput: string;
+    /**
+     * Identity of the view the current search belongs to (`lib/mail-route.ts`).
+     * It changes when the user leaves that view, which is when search ends: the
+     * query re-seeds from the new URL and any search chrome collapses (#47).
+     */
+    searchViewKey: string;
+    onSearchChange: (query: string) => void;
+    /** Full clear (X button): drops the query and any selected thread (#538). */
+    onSearchClear: () => void;
+    /** Query-only clear (Esc): drops the query, keeps the thread open (#489). */
+    onSearchClearQuery: () => void;
+    /**
+     * Whether pane 4 (intelligence) is up. Resolved once by the `/mail` layout
+     * from the address and this device's preference (`resolveRailOpen`), and
+     * handed down as the answer — a consumer re-deriving it from the fragment
+     * alone would lose the preference and disagree with the shell.
+     */
+    intelligenceOpen: boolean;
+    /** The reader's own control over pane 4, which stores what they chose. */
+    onToggleIntelligence: () => void;
+    /**
+     * Puts pane 4 up for the thread in hand without touching the stored
+     * preference: a DKIM mismatch surfacing the rail is about this message, not
+     * about where the reader wants the rail from now on (#778).
+     */
+    onRaiseIntelligence: () => void;
+}
+export declare const MailContext: import("react").Context<MailContextValue | null>;
+export declare const useMailContext: () => MailContextValue;

package/dist/src/lib/mail-context.js

@@ -0,0 +1,24 @@
+import { createContext, useContext } from "react";
+import { EMPTY_RESULT_FOLDER_INDEX, } from "./result-folder.js";
+export const MailContext = createContext(null);
+export const useMailContext = () => {
+    const context = useContext(MailContext);
+    // Return default values if context not yet available (e.g., during loading)
+    // This can happen when TanStack Router renders child routes before parent
+    // finishes.
+    return (context ?? {
+        accounts: [],
+        mailboxNameIndex: new Map(),
+        accountNameIndex: new Map(),
+        resultFolderIndex: EMPTY_RESULT_FOLDER_INDEX,
+        searchQuery: "",
+        searchInput: "",
+        searchViewKey: "",
+        onSearchChange: () => { },
+        onSearchClear: () => { },
+        onSearchClearQuery: () => { },
+        intelligenceOpen: false,
+        onToggleIntelligence: () => { },
+        onRaiseIntelligence: () => { },
+    });
+};

package/dist/src/lib/mail-freshness.d.ts

@@ -0,0 +1,57 @@
+import type { RemitImapMailboxSyncProgress } from "@remit/api-http-client/types.gen.ts";
+import { type ReactNode } from "react";
+import type { ResultFolderIndex } from "./result-folder";
+/**
+ * How often the background poll re-reads each open account's sync status.
+ * `getSyncStatus` is a DDB read with no IMAP call and no queue write (see
+ * typespec Sync Operations), so this is the cheap side of the refresh
+ * feature — the once-a-minute check that decides whether anything is worth
+ * surfacing, never a refetch of the mailbox or brief content itself.
+ */
+export declare const FRESHNESS_POLL_MS = 60000;
+/**
+ * Each watched mailbox's highest UID. A total cannot answer "did mail arrive":
+ * a message landing in the round that another one leaves nets to zero, so the
+ * arrival was invisible (#771). The read model widens that window, because a
+ * local delete does not decrement the stored count — only the next sync does,
+ * and that same sync carries the arrival. The highest UID only moves up, so it
+ * names the arrival on its own.
+ */
+type MailboxHighWaterMarks = ReadonlyMap<string, number>;
+export declare const highWaterMarksFrom: (mailboxes: readonly RemitImapMailboxSyncProgress[], resultFolderIndex: ResultFolderIndex) => MailboxHighWaterMarks;
+/**
+ * Which mailboxes took a UID above the highest one in the baseline. Pure so the
+ * "did mail arrive" call is unit-testable without a DOM or a QueryClient. A
+ * mailbox missing from the baseline (new folder, first-ever reading) counts
+ * from zero rather than being skipped, so mail landing in a folder created
+ * since the last look still counts as an arrival.
+ */
+export declare const grownMailboxIds: (baseline: MailboxHighWaterMarks, current: MailboxHighWaterMarks) => string[];
+/** Whether any mailbox took a new message at all — the dot's own question. */
+export declare const hasGrown: (baseline: MailboxHighWaterMarks, current: MailboxHighWaterMarks) => boolean;
+interface MailFreshnessContextValue {
+    /** True once any of these accounts has grown since it was last acknowledged. */
+    hasNewMail: (accountIds: readonly string[]) => boolean;
+    /** Clears the flag for these accounts and re-baselines them from whatever
+     * is currently cached — called once a refresh has shown the user current
+     * data for them. */
+    acknowledge: (accountIds: readonly string[]) => void;
+}
+export declare const useMailFreshness: () => MailFreshnessContextValue;
+interface MailFreshnessProviderProps {
+    accountIds: readonly string[];
+    children: ReactNode;
+}
+/**
+ * Watches every open account's sync status once a minute and flags which
+ * accounts have grown since they were last shown to the user (#582 clause
+ * 4). The flag is sticky until acknowledged: it lights the dot on whichever
+ * `RefreshButton` reads this context and stays lit until a refresh clears it.
+ *
+ * A tick that sees a folder take a new highest UID also invalidates that
+ * folder's thread listing. It reorders nothing and asks the mail server for
+ * nothing — the message is already on our side, so an open list showing it is a
+ * cache read, not IMAP work. The dot is still the account-level signal.
+ */
+export declare function MailFreshnessProvider({ accountIds, children, }: MailFreshnessProviderProps): import("react").JSX.Element;
+export {};