@remit/web-client 0.0.324 → 0.0.326

package/dist/src/hooks/useResultFolderIndex.js

@@ -0,0 +1,45 @@
+/**
+ * Fans out the per-account mailbox-list query (the same one `MailSidebarAdapter`
+ * and `useMailboxNameIndex` run — cached forever, react-query dedupes the
+ * identical key across call sites) and reduces it to the mailboxId → folder map
+ * search results resolve their provenance against. See `lib/result-folder.ts`.
+ *
+ * The read state travels with the index: a folder label cut on a delimiter that
+ * has not arrived is wrong rather than late, so a surface that names folders can
+ * wait for this, and say so when it fails.
+ */
+import { mailboxOperationsListMailboxesOptions } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQueries } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { buildResultFolderIndex, } from "../lib/result-folder";
+/**
+ * Hoisted, not inline: `useQueries` skips re-running `combine` when it is given
+ * the same function, so a stable reference is what makes this a memo rather than
+ * a per-render reduce. Without it the index — and every search-result memo keyed
+ * on it — rebuilds on every render.
+ */
+const combineMailboxLists = (results) => ({
+    items: results.map((result) => result.data?.items ?? []),
+    isPending: results.some((result) => result.isPending),
+    error: results.find((result) => result.error)?.error ?? null,
+});
+export function useResultFolderIndex(accounts) {
+    const mailboxLists = useQueries({
+        queries: accounts.map((account) => ({
+            ...mailboxOperationsListMailboxesOptions({
+                path: { accountId: account.accountId },
+            }),
+            staleTime: Infinity,
+        })),
+        combine: combineMailboxLists,
+    });
+    const index = useMemo(() => buildResultFolderIndex(accounts.map((account, i) => ({
+        folderAppointments: account.folderAppointments,
+        mailboxes: mailboxLists.items[i] ?? [],
+    }))), [accounts, mailboxLists]);
+    return {
+        index,
+        isPending: mailboxLists.isPending,
+        error: mailboxLists.error,
+    };
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Run `onReturn` every time the app is looked at again while it has a window
+ * out at an external identity provider.
+ *
+ * Microsoft sign-in is the one flow that leaves this origin, and where it comes
+ * back to is not ours to decide: launched from a home screen on iOS the return
+ * leg can land in the browser instead of the app window, which then holds a
+ * view of a sign-in that finished somewhere else. The window being looked at is
+ * the one that has to reconcile, so it asks the server what happened rather
+ * than trusting what it last saw.
+ *
+ * Every look, not just the first: a user who switches back mid-sign-in to read
+ * a password has not finished anything, and a check that spent itself on that
+ * look would miss the return that matters.
+ *
+ * `pageshow` covers the back-forward cache, where a restored page fires no
+ * visibility change.
+ */
+export declare const useReturnFromRedirect: (active: boolean, onReturn: () => void) => void;

package/dist/src/hooks/useReturnFromRedirect.js

@@ -0,0 +1,38 @@
+import { useEffect, useRef } from "react";
+/**
+ * Run `onReturn` every time the app is looked at again while it has a window
+ * out at an external identity provider.
+ *
+ * Microsoft sign-in is the one flow that leaves this origin, and where it comes
+ * back to is not ours to decide: launched from a home screen on iOS the return
+ * leg can land in the browser instead of the app window, which then holds a
+ * view of a sign-in that finished somewhere else. The window being looked at is
+ * the one that has to reconcile, so it asks the server what happened rather
+ * than trusting what it last saw.
+ *
+ * Every look, not just the first: a user who switches back mid-sign-in to read
+ * a password has not finished anything, and a check that spent itself on that
+ * look would miss the return that matters.
+ *
+ * `pageshow` covers the back-forward cache, where a restored page fires no
+ * visibility change.
+ */
+export const useReturnFromRedirect = (active, onReturn) => {
+    const latest = useRef(onReturn);
+    latest.current = onReturn;
+    useEffect(() => {
+        if (!active)
+            return;
+        const handle = () => {
+            if (document.visibilityState !== "visible")
+                return;
+            latest.current();
+        };
+        document.addEventListener("visibilitychange", handle);
+        window.addEventListener("pageshow", handle);
+        return () => {
+            document.removeEventListener("visibilitychange", handle);
+            window.removeEventListener("pageshow", handle);
+        };
+    }, [active]);
+};

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

@@ -0,0 +1,28 @@
+import { type PreviewCount } from "@remit/ui";
+import { type OrganizeMatchPredicate } from "../lib/organize/organize-model";
+/**
+ * The live match count for the edited rule (RFC 038 D1). Every predicate change
+ * schedules a debounced `POST /organize/preview` and, until it lands, reports
+ * the last count as stale so the count never blanks and the commit gate can
+ * hold apply. Seeded with a count already known, so opening the editor shows a
+ * settled number without an immediate re-fetch.
+ *
+ * Out-of-order responses are dropped: only the reply to the most recent request
+ * updates the count, so a slow early preview never overwrites a newer one. The
+ * server bounds the match, so a broad predicate over a large mailbox stays a
+ * single cheap request; the debounce is what keeps rapid edits from spamming it.
+ *
+ * `seedCount` is an opening count already known; omit it (as the settings
+ * editor does) to open on `loading` and preview the loaded predicate
+ * immediately.
+ *
+ * `matchedIds` are the ids that count was counted over — the server's own
+ * answer, bounded to the same cap the apply pass uses. A caller applying an
+ * action the back-apply job cannot express (a delete, a read flag) acts on
+ * exactly these rather than paging the list in the browser (#477 5.3).
+ */
+export interface RulePreview {
+    count: PreviewCount;
+    matchedIds: readonly string[];
+}
+export declare const useRulePreview: (accountId: string | undefined, predicate: OrganizeMatchPredicate, seedCount?: number) => RulePreview;

package/dist/src/hooks/useRulePreview.js

@@ -0,0 +1,77 @@
+import { organizeOperationsPreviewOrganizeMutation } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { UNCOUNTABLE_PREDICATE_REASON } from "@remit/ui";
+import { useMutation } from "@tanstack/react-query";
+import { useEffect, useRef, useState } from "react";
+import { buildOrganizeInput, } from "../lib/organize/organize-model";
+import { derivePreview, isEvaluablePredicate, PREVIEW_DEBOUNCE_MS, predicateSignature, } from "../lib/organize/rule-model";
+export const useRulePreview = (accountId, predicate, seedCount) => {
+    const mutation = useMutation(organizeOperationsPreviewOrganizeMutation());
+    const { mutateAsync } = mutation;
+    const currentSignature = predicateSignature(predicate);
+    const [state, setState] = useState(() => seedCount === undefined
+        ? {}
+        : { count: seedCount, previewedSignature: currentSignature });
+    const predicateRef = useRef(predicate);
+    predicateRef.current = predicate;
+    const latestRequested = useRef(currentSignature);
+    // A predicate the matcher rejects outright is never sent — the request would
+    // 500, and a 500 is not a count. The editor says so instead and holds the
+    // commit for the scopes that would run this same matcher.
+    const countable = isEvaluablePredicate(predicate);
+    useEffect(() => {
+        if (!accountId || !countable)
+            return;
+        if (currentSignature === state.previewedSignature)
+            return;
+        if (currentSignature === state.errorSignature)
+            return;
+        const handle = setTimeout(() => {
+            const signature = currentSignature;
+            latestRequested.current = signature;
+            mutateAsync({
+                path: { accountId },
+                body: buildOrganizeInput({ ...predicateRef.current }),
+            })
+                .then((response) => {
+                if (latestRequested.current !== signature)
+                    return;
+                setState({
+                    count: response.matchedCount,
+                    matchedIds: response.messageIds,
+                    previewedSignature: signature,
+                });
+            })
+                .catch((error) => {
+                if (latestRequested.current !== signature)
+                    return;
+                setState((previous) => ({
+                    ...previous,
+                    error: error instanceof Error
+                        ? error.message
+                        : "Couldn't count matches.",
+                    errorSignature: signature,
+                }));
+            });
+        }, PREVIEW_DEBOUNCE_MS);
+        return () => clearTimeout(handle);
+    }, [
+        accountId,
+        countable,
+        currentSignature,
+        state.previewedSignature,
+        state.errorSignature,
+        mutateAsync,
+    ]);
+    if (!countable) {
+        return {
+            count: { status: "error", reason: UNCOUNTABLE_PREDICATE_REASON },
+            matchedIds: [],
+        };
+    }
+    return {
+        count: derivePreview(state, currentSignature),
+        matchedIds: state.previewedSignature === currentSignature
+            ? (state.matchedIds ?? [])
+            : [],
+    };
+};

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

@@ -0,0 +1,31 @@
+import type { ComposeSaveState } from "@remit/ui";
+export type ImmediateSave = {
+    outcome: "saved";
+    outboxMessageId: string;
+} | {
+    outcome: "failed";
+    error: unknown;
+};
+interface DraftData {
+    accountId: string;
+    toAddresses: string[];
+    ccAddresses?: string[];
+    bccAddresses?: string[];
+    subject?: string;
+    textBody?: string;
+    htmlBody?: string;
+    inReplyTo?: string;
+    references?: string[];
+}
+interface UseSaveDraftOptions {
+    outboxMessageId?: string;
+    onDraftCreated: (id: string) => void;
+}
+export declare const useSaveDraft: ({ outboxMessageId, onDraftCreated, }: UseSaveDraftOptions) => {
+    saveState: ComposeSaveState;
+    saveError: unknown;
+    saveDraft: (data: DraftData) => void;
+    saveImmediately: (data: DraftData) => Promise<ImmediateSave>;
+    stopAutoSave: (closedOutboxMessageId?: string) => void;
+};
+export {};

package/dist/src/hooks/useSaveDraft.js

@@ -0,0 +1,183 @@
+import { outboxDetailOperationsUpdateOutboxMessageMutation, outboxOperationsCreateOutboxMessageMutation, outboxOperationsListOutboxMessagesOptions, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useRef, useState } from "react";
+import { softErrorMeta } from "../lib/error-classifier";
+/**
+ * A draft with no To address yet has nothing the create endpoint will accept —
+ * `CreateOutboxMessageInput.toAddresses` carries `@minItems(1)`, so the request
+ * comes back 400. Cc and Bcc do not stand in for it; the constraint names
+ * `toAddresses` and nothing else. Forward opens in exactly that state, with a
+ * subject and a quote and no address, and it is a normal place to be while
+ * writing rather than a failure to report. The update endpoint has no such
+ * constraint, so only a draft that does not exist yet is held back.
+ *
+ * The send guard in `outbox-queue.ts` counts Cc and Bcc, and is right to: a
+ * Bcc-only envelope is real mail. It answers a different question — whether
+ * this message has anywhere to go — from this one, which is only whether the
+ * create schema will take it.
+ */
+const nothingToCreateYet = (targetId, data) => targetId === undefined && data.toAddresses.length === 0;
+/**
+ * Held back, and naming what is actually missing. "A recipient" was a lie to
+ * anyone who had filled in Cc: they had one, and were being told to add what
+ * they could see on screen.
+ *
+ * Module scope, not a literal built in the render: this is set from inside the
+ * autosave effect, and a fresh object each time would be a new state on every
+ * render with the effect re-running on each of them.
+ */
+const NOT_SAVED_WITHOUT_A_TO_ADDRESS = {
+    status: "unsaved",
+    reason: "Not saved — add a To address to keep this draft.",
+};
+const IDLE = { status: "idle" };
+const SAVING = { status: "saving" };
+const SAVED = { status: "saved" };
+const SAVE_FAILED = { status: "error" };
+const settled = (promise) => promise.then(() => undefined, () => undefined);
+export const useSaveDraft = ({ outboxMessageId, onDraftCreated, }) => {
+    const [saveState, setSaveState] = useState(IDLE);
+    const [saveError, setSaveError] = useState(null);
+    const timerRef = useRef(undefined);
+    const closedIdsRef = useRef(new Set());
+    const queryClient = useQueryClient();
+    // The entry a save writes to. That is the prop, except between a save
+    // creating the draft and the id arriving back as the prop — reading the prop
+    // in that window creates the same draft a second time and strands one of the
+    // two in the outbox.
+    const propIdRef = useRef(outboxMessageId);
+    const targetIdRef = useRef(outboxMessageId);
+    if (propIdRef.current !== outboxMessageId) {
+        // A write waiting out the debounce holds the document that has just been
+        // left, aimed at whatever entry is current when it fires. Leaving one is
+        // therefore dropping it: otherwise it lands on the next draft, or — with
+        // no entry to land on at all — creates one holding the last message's
+        // content, which is what a second Compose press used to do.
+        //
+        // Adoption is the exception, as it is everywhere: the id arriving is this
+        // session's own draft coming back, and a save scheduled while it was in
+        // flight is still the right content for it.
+        const leavingADocument = propIdRef.current !== undefined;
+        propIdRef.current = outboxMessageId;
+        targetIdRef.current = outboxMessageId;
+        if (leavingADocument && timerRef.current)
+            clearTimeout(timerRef.current);
+    }
+    // A write that fails belongs in the composer's banner beside the message it
+    // could not save, never on the full-screen page that unmounts the composer
+    // and the message with it. A 5xx still escalates.
+    const createMutation = useMutation({
+        ...outboxOperationsCreateOutboxMessageMutation(),
+        meta: softErrorMeta,
+    });
+    const updateMutation = useMutation({
+        ...outboxDetailOperationsUpdateOutboxMessageMutation(),
+        meta: softErrorMeta,
+    });
+    const executeSave = useCallback(async (data) => {
+        setSaveState(SAVING);
+        setSaveError(null);
+        const targetId = targetIdRef.current;
+        if (targetId) {
+            const result = await updateMutation.mutateAsync({
+                path: { outboxMessageId: targetId },
+                body: {
+                    toAddresses: data.toAddresses,
+                    ccAddresses: data.ccAddresses,
+                    bccAddresses: data.bccAddresses,
+                    subject: data.subject,
+                    textBody: data.textBody,
+                    htmlBody: data.htmlBody,
+                    inReplyTo: data.inReplyTo,
+                    references: data.references,
+                },
+            });
+            setSaveState(SAVED);
+            return result;
+        }
+        const result = await createMutation.mutateAsync({
+            body: {
+                ...data,
+                sendImmediately: false,
+            },
+        });
+        targetIdRef.current = result.outboxMessageId;
+        onDraftCreated(result.outboxMessageId);
+        setSaveState(SAVED);
+        queryClient.invalidateQueries({
+            queryKey: outboxOperationsListOutboxMessagesOptions().queryKey,
+        });
+        return result;
+    }, [
+        createMutation.mutateAsync,
+        updateMutation.mutateAsync,
+        onDraftCreated,
+        queryClient,
+    ]);
+    // One entry takes one write at a time. Overlapping writes settle in whatever
+    // order the network gives them, so an older body can land last — and two of
+    // them racing while the draft has no id yet each create one.
+    const writesRef = useRef(Promise.resolve());
+    const enqueueSave = useCallback((data) => {
+        const write = writesRef.current.then(() => executeSave(data));
+        writesRef.current = settled(write);
+        return write;
+    }, [executeSave]);
+    const saveDraft = useCallback((data) => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        // Said now rather than two seconds from now: the composer is holding
+        // text nothing is going to persist, and the moment it starts holding it
+        // is the moment the user has to be able to see that.
+        if (nothingToCreateYet(targetIdRef.current, data)) {
+            setSaveState(NOT_SAVED_WITHOUT_A_TO_ADDRESS);
+            return;
+        }
+        // The sentence goes the moment its reason does, rather than standing
+        // for the two seconds until the write it is no longer true about
+        // lands. Only that sentence is cleared: a "Draft saved" from the
+        // previous write is still the truth about this document.
+        setSaveState((current) => current.status === "unsaved" ? IDLE : current);
+        timerRef.current = setTimeout(() => {
+            const targetId = targetIdRef.current;
+            if (targetId && closedIdsRef.current.has(targetId))
+                return;
+            // Keep the real error, not just a vague "error" status — the caller
+            // surfaces its detail in a banner. A fatal 5xx additionally escalates
+            // through the global MutationCache.onError sink.
+            enqueueSave(data).catch((error) => {
+                setSaveError(error);
+                setSaveState(SAVE_FAILED);
+            });
+        }, 2000);
+    }, [enqueueSave]);
+    // Whoever asks for this is acting on the draft right now and owns the
+    // outcome, so the failure is returned rather than thrown and `saveError` is
+    // left alone — the caller's own message is the accurate one, and setting
+    // `saveError` would raise a second "Couldn't save draft" banner beside it.
+    const saveImmediately = useCallback((data) => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        return enqueueSave(data)
+            .then((result) => ({
+            outcome: "saved",
+            outboxMessageId: result.outboxMessageId,
+        }))
+            .catch((error) => {
+            setSaveState(SAVE_FAILED);
+            return { outcome: "failed", error };
+        });
+    }, [enqueueSave]);
+    // Called with an id, the entry is closed to autosave for good. Sending and
+    // discarding both take the entry out of draft, and the compose effect that
+    // schedules autosaves re-runs on every mutation settling — so dropping the
+    // pending timer alone leaves the next render free to schedule another write
+    // against an entry the server will refuse (#604).
+    const stopAutoSave = useCallback((closedOutboxMessageId) => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+        if (closedOutboxMessageId)
+            closedIdsRef.current.add(closedOutboxMessageId);
+    }, []);
+    return { saveState, saveError, saveDraft, saveImmediately, stopAutoSave };
+};

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

@@ -0,0 +1,15 @@
+import type { RemitImapAccountResponse } from "@remit/api-http-client/types.gen.ts";
+import { type SearchScopeState } from "../lib/search-scope";
+/**
+ * The scope chip for the active route and the way off it.
+ *
+ * `clearScope` navigates to the daily brief carrying the current query, which
+ * is what "search everything" means here — the brief is the unscoped
+ * cross-account view. It is a navigation rather than a query edit because the
+ * chip mirrors the route (see `lib/search-scope.ts`); editing the text would
+ * leave the chip in place and the list still narrowed.
+ */
+export declare function useSearchScope(accounts: RemitImapAccountResponse[]): {
+    scope: SearchScopeState;
+    clearScope: (chipId: string) => void;
+};

package/dist/src/hooks/useSearchScope.js

@@ -0,0 +1,30 @@
+import { useCallback, useMemo } from "react";
+import { useMailContext } from "../lib/mail-context";
+import { SEARCH_SCOPE_CHIP_ID, searchScopeForRoute, } from "../lib/search-scope";
+import { useBrowsedList, useSearchEverything } from "../routing";
+import { useCurrentMailboxName } from "./useCurrentMailboxName";
+/**
+ * The scope chip for the active route and the way off it.
+ *
+ * `clearScope` navigates to the daily brief carrying the current query, which
+ * is what "search everything" means here — the brief is the unscoped
+ * cross-account view. It is a navigation rather than a query edit because the
+ * chip mirrors the route (see `lib/search-scope.ts`); editing the text would
+ * leave the chip in place and the list still narrowed.
+ */
+export function useSearchScope(accounts) {
+    const searchEverything = useSearchEverything();
+    const { searchInput } = useMailContext();
+    const mailboxName = useCurrentMailboxName({ accounts });
+    const browsed = useBrowsedList();
+    const scope = useMemo(() => searchScopeForRoute(browsed, mailboxName), [browsed, mailboxName]);
+    // Takes the chip id the field removed rather than assuming which chip that
+    // was. The bar owns one chip today; keying on the id means a second one
+    // added later cannot silently drop the user out of their scope.
+    const clearScope = useCallback((chipId) => {
+        if (chipId !== SEARCH_SCOPE_CHIP_ID)
+            return;
+        searchEverything(searchInput);
+    }, [searchEverything, searchInput]);
+    return { scope, clearScope };
+}

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

@@ -0,0 +1,12 @@
+import type { Suggestion } from "@remit/ui";
+/** How long typing settles before the address lookup fires. */
+export declare const SEARCH_CONTACT_DEBOUNCE_MS = 250;
+export interface SearchSuggestionsInput {
+    /** The query exactly as typed. */
+    query: string;
+    /** Where the caret sits in it. */
+    cursor: number;
+    /** Offer nothing while the field is not being typed in. */
+    enabled: boolean;
+}
+export declare function useSearchSuggestions({ query, cursor, enabled, }: SearchSuggestionsInput): Suggestion[];

package/dist/src/hooks/useSearchSuggestions.js

@@ -0,0 +1,77 @@
+/**
+ * What the search box offers for the term under the caret (#428 follow-up).
+ *
+ * The decisions are all in `lib/search-suggestions.ts`; this is the wiring that
+ * gets them their data. A caret position names exactly one lookup — token names
+ * for a bare word, one token's values once its name is committed — so only that
+ * lookup runs, and the address search behind `from:` runs on a debounce rather
+ * than per keystroke.
+ *
+ * Folders and accounts are already loaded: the mailbox lists come from the same
+ * per-account query `useMailboxNameIndex` and `useResultFolderIndex` take, on
+ * the same key with the same infinite stale time, so react-query serves them
+ * from cache and nothing is fetched a second time.
+ *
+ * `in:` is offered only where the route resolves it. On a scoped view the parser
+ * leaves the token as free text (see `useSearchTokenContext`), so offering
+ * folders there would advertise a filter that does nothing.
+ */
+import { addressOperationsSearchAddressesOptions, mailboxOperationsListMailboxesOptions, } from "@remit/api-http-client/@tanstack/react-query.gen.ts";
+import { useQueries, useQuery } from "@tanstack/react-query";
+import { useMemo } from "react";
+import { useMailContext } from "../lib/mail-context";
+import { buildSearchSuggestions, contactSuggestionValue, SEARCH_SUGGESTION_LIMIT, searchSuggestionRequest, } from "../lib/search-suggestions";
+import { buildAccountSuggestionValues, buildMailboxSuggestionValues, } from "../lib/search-token-index";
+import { useDebouncedValue } from "./useDebouncedValue";
+import { useSearchTokenContext } from "./useSearchTokenContext";
+/** How long typing settles before the address lookup fires. */
+export const SEARCH_CONTACT_DEBOUNCE_MS = 250;
+/** The shortest contact query worth a round-trip. */
+const MIN_CONTACT_QUERY_LENGTH = 2;
+export function useSearchSuggestions({ query, cursor, enabled, }) {
+    const { accounts } = useMailContext();
+    const { mailboxesByName } = useSearchTokenContext();
+    const offersFolders = mailboxesByName !== undefined;
+    const request = enabled ? searchSuggestionRequest(query, cursor) : undefined;
+    const contactQuery = request?.source === "contact" ? request.query.trim() : "";
+    const debouncedContactQuery = useDebouncedValue(contactQuery, SEARCH_CONTACT_DEBOUNCE_MS);
+    const { data: addresses } = useQuery({
+        ...addressOperationsSearchAddressesOptions({
+            query: { q: debouncedContactQuery, limit: SEARCH_SUGGESTION_LIMIT },
+        }),
+        enabled: debouncedContactQuery.length >= MIN_CONTACT_QUERY_LENGTH,
+    });
+    const mailboxQueries = useQueries({
+        queries: accounts.map((account) => ({
+            ...mailboxOperationsListMailboxesOptions({
+                path: { accountId: account.accountId },
+            }),
+            staleTime: Infinity,
+        })),
+    });
+    const mailboxes = useMemo(() => offersFolders
+        ? buildMailboxSuggestionValues(mailboxQueries.map((mailboxQuery) => mailboxQuery.data?.items ?? []), accounts)
+        : [], [offersFolders, mailboxQueries, accounts]);
+    const accountValues = useMemo(() => buildAccountSuggestionValues(accounts), [accounts]);
+    const contacts = useMemo(() => (addresses?.items ?? []).map(contactSuggestionValue), [addresses]);
+    return useMemo(() => {
+        if (!enabled)
+            return [];
+        const suggestions = buildSearchSuggestions(query, cursor, {
+            mailboxes,
+            accounts: accountValues,
+            contacts,
+        });
+        if (offersFolders)
+            return suggestions;
+        return suggestions.filter((suggestion) => suggestion.value !== "in:");
+    }, [
+        enabled,
+        query,
+        cursor,
+        mailboxes,
+        accountValues,
+        contacts,
+        offersFolders,
+    ]);
+}

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

@@ -0,0 +1,16 @@
+import type { SearchTokenContext } from "../lib/search-tokens";
+/**
+ * The one context every search engine parses the query through.
+ *
+ * `in:` is recognized only where the route carries no scope. On a scoped view
+ * the top bar's chip already answers "which mailbox", and a typed `in:` is a
+ * second, competing answer that no engine there acts on — the search is pinned
+ * to the route's mailbox. Leaving the term unresolved means it stays ordinary words: it is
+ * matched as text and never chipped, so the field can't advertise a filter that
+ * does nothing. To search another folder, drop the scope chip or go to it.
+ *
+ * Every call site takes this hook rather than building its own context, because
+ * the guarantee is that they agree. Two of them disagreeing is what made the
+ * same query behave one way on `/mail/flagged` and another on a mailbox.
+ */
+export declare function useSearchTokenContext(): SearchTokenContext;

package/dist/src/hooks/useSearchTokenContext.js

@@ -0,0 +1,26 @@
+import { useMailContext } from "../lib/mail-context";
+import { isScopedRoute } from "../lib/search-scope";
+import { useBrowsedList } from "../routing";
+/**
+ * The one context every search engine parses the query through.
+ *
+ * `in:` is recognized only where the route carries no scope. On a scoped view
+ * the top bar's chip already answers "which mailbox", and a typed `in:` is a
+ * second, competing answer that no engine there acts on — the search is pinned
+ * to the route's mailbox. Leaving the term unresolved means it stays ordinary words: it is
+ * matched as text and never chipped, so the field can't advertise a filter that
+ * does nothing. To search another folder, drop the scope chip or go to it.
+ *
+ * Every call site takes this hook rather than building its own context, because
+ * the guarantee is that they agree. Two of them disagreeing is what made the
+ * same query behave one way on `/mail/flagged` and another on a mailbox.
+ */
+export function useSearchTokenContext() {
+    const { mailboxNameIndex, accountNameIndex } = useMailContext();
+    const browsed = useBrowsedList();
+    const scoped = isScopedRoute(browsed);
+    return {
+        ...(scoped ? {} : { mailboxesByName: mailboxNameIndex }),
+        accountsByName: accountNameIndex,
+    };
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Subjects for `messageIds`, in the order the ids were given, skipping ids with
+ * no cached row and rows with no subject.
+ */
+export declare const collectSubjects: (caches: readonly unknown[], messageIds: readonly string[]) => string[];
+export declare const useSelectedSubjects: (messageIds: readonly string[]) => string[];