@rapidmx/web-client 0.21.0 → 0.22.0

package/apps/shared/notifications/apiErrors.ts

@@ -2,8 +2,8 @@
 // Copyright (C) 2026 Jean-Philippe Steinmetz
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
-import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import { describeSendFailure } from "@rapidmx/react-shared/mail/sendFailure.js";
+import { ApiRequestError } from "../../../lib/util/api.js";
+import { describeSendFailure } from "../../../lib/mail/sendFailure.js";
 import { NotificationAction, notify } from "./store.js";
 
 /** Whether `err` is a request that was cancelled (`AbortError`) - by name, since a `DOMException` is not always an `Error` (jsdom's is not). */

package/apps/shared/notifications/pushStatus.ts

@@ -3,7 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import { useEffect } from "react";
-import { getPushClient, PushStatus } from "@rapidmx/react-shared/mail/pushClient.js";
+import { getPushClient, PushStatus } from "../../../lib/mail/pushClient.js";
 import { dismiss, notify } from "./store.js";
 
 /** How long the live connection has to be down before anyone is told: a reconnect within a few seconds is not worth a word. */

package/apps/shared/notifications/systemErrors.ts

@@ -3,7 +3,7 @@
 // SPDX-License-Identifier: MPL-2.0
 ///////////////////////////////////////////////////////////////////////////////
 import { useEffect } from "react";
-import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
+import { ApiRequestError } from "../../../lib/util/api.js";
 import { isAbortError } from "./apiErrors.js";
 import { notify } from "./store.js";
 

package/apps/shared/search/LocalIndexLifecycle.tsx

@@ -21,9 +21,11 @@
  * handles that case itself via `destroyAllLocalIndexes()`.
  */
 import { useEffect, useRef } from "react";
-import { getUnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
-import type { PublicKey } from "@rapidmx/react-shared/crypto/keyvaultApi.js";
-import type { Folder } from "@rapidmx/react-shared/mail/mailApi.js";
+import { getUnlockedKeys } from "../../../lib/crypto/keySession.js";
+import type { PublicKey } from "../../../lib/crypto/keyvaultApi.js";
+import type { Folder } from "../../../lib/mail/mailApi.js";
+import type { ApiClient } from "../../../lib/util/api.js";
+import { useApiClient } from "../../../lib/util/apiClientContext.js";
 
 /**
  * The index builder (with the message security code it decrypts through - PKI.js and the ASN.1/X.509 libraries, over half a
@@ -52,15 +54,19 @@ export interface LocalIndexLifecycleProps {
 
 /** Renders nothing - pure side-effect component, mounted by `MailShell.tsx`. */
 export default function LocalIndexLifecycle({ mailboxUid, folders, accessibleMailboxUids }: LocalIndexLifecycleProps) {
+    // The explicit ApiClient (from useApiClient()) this component is rendered under - undefined for every existing caller (the SSR web/admin
+    // apps, Electron), which keeps building the index against the default global cookie-based session exactly as before. A native,
+    // multi-account host that renders this under an ApiClientContext.Provider gets its own account's client threaded through instead.
+    const client = useApiClient();
     // mailboxUid -> whether it was unlocked at the last check. An entry exists for every mailbox whose
     // build this component started; only ever changed by a real observed transition, never reset by an
     // effect re-run.
     const trackedRef = useRef(new Map<string, boolean>());
-    // The latest props, for the long-lived polling interval below.
-    const latestRef = useRef({ mailboxUid, folders });
-    latestRef.current = { mailboxUid, folders };
+    // The latest props (and client), for the long-lived polling interval below.
+    const latestRef = useRef({ mailboxUid, folders, client });
+    latestRef.current = { mailboxUid, folders, client };
 
-    function startBuildIfUnlocked(targetMailboxUid: string, targetFolders: Folder[]) {
+    function startBuildIfUnlocked(targetMailboxUid: string, targetFolders: Folder[], targetClient: ApiClient | undefined) {
         const unlocked = getUnlockedKeys(targetMailboxUid);
         if (!unlocked || targetFolders.length === 0 || trackedRef.current.get(targetMailboxUid)) {
             return;
@@ -69,15 +75,15 @@ export default function LocalIndexLifecycle({ mailboxUid, folders, accessibleMai
         // Never an unhandled rejection - a broken local index is best-effort infrastructure, not a build
         // the rest of the app depends on.
         loadBuilder()
-            .then(({ buildLocalIndex }) => buildLocalIndex(targetMailboxUid, unlocked, targetFolders))
+            .then(({ buildLocalIndex }) => buildLocalIndex(targetMailboxUid, unlocked, targetFolders, undefined, targetClient))
             .catch(() => undefined);
     }
 
     useEffect(() => {
         if (mailboxUid) {
-            startBuildIfUnlocked(mailboxUid, folders);
+            startBuildIfUnlocked(mailboxUid, folders, client);
         }
-    }, [mailboxUid, folders]);
+    }, [mailboxUid, folders, client]);
 
     useEffect(() => {
         const interval = setInterval(() => {
@@ -94,9 +100,9 @@ export default function LocalIndexLifecycle({ mailboxUid, folders, accessibleMai
                 }
             }
             // The active mailbox was (re-)unlocked since the last check, e.g. via an on-demand unlock prompt.
-            const { mailboxUid: activeUid, folders: activeFolders } = latestRef.current;
+            const { mailboxUid: activeUid, folders: activeFolders, client: activeClient } = latestRef.current;
             if (activeUid) {
-                startBuildIfUnlocked(activeUid, activeFolders);
+                startBuildIfUnlocked(activeUid, activeFolders, activeClient);
             }
         }, POLL_INTERVAL_MS);
         return () => clearInterval(interval);

package/apps/shared/search/crossMailboxSearch.ts

@@ -10,9 +10,9 @@
  *
  * A search of one mailbox is the same code with a list of one: nothing here changes what that returns.
  */
-import { ApiRequestError } from "@rapidmx/react-shared/util/api.js";
-import type { SearchResult } from "@rapidmx/react-shared/search/searchApi.js";
-import { normalizeServerScores } from "@rapidmx/react-shared/search/searchScoring.js";
+import { ApiRequestError } from "../../../lib/util/api.js";
+import type { SearchResult } from "../../../lib/search/searchApi.js";
+import { normalizeServerScores } from "../../../lib/search/searchScoring.js";
 
 /**
  * How far a cross-mailbox search fans out. Exported (and mutable) so a test can shrink them instead of building 26 mailboxes or waiting a

package/apps/shared/search/localIndexBuilder.ts

@@ -35,9 +35,10 @@
  * seals nothing. Signed-only (unencrypted) messages aren't sealed here: this pass never fetches their raw MIME (see
  * above), and fetching it only to seal would cost a download per message; they are sealed when opened.
  */
-import { getMessageRawContent, listFolders, listMessages, type Folder, type Message } from "@rapidmx/react-shared/mail/mailApi.js";
-import { type MessageSecurityResult, evaluateMessageSecurity, evaluateMessageSecurityWithSeal } from "@rapidmx/react-shared/crypto/messageSecurity.js";
-import type { UnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
+import { getMessageRawContent, listFolders, listMessages, type Folder, type Message } from "../../../lib/mail/mailApi.js";
+import { type MessageSecurityResult, evaluateMessageSecurity, evaluateMessageSecurityWithSeal } from "../../../lib/crypto/messageSecurity.js";
+import type { UnlockedKeys } from "../../../lib/crypto/keySession.js";
+import type { ApiClient } from "../../../lib/util/api.js";
 import { getPinnedSignerFingerprints } from "../components/mail/pinnedSigners.js";
 import { currentVerificationSeal, readVaultGeneration, sendVerificationSeal, verificationSealPending } from "../components/mail/verificationSeals.js";
 import type { LocalIndexEntity } from "./localIndexSchema.js";
@@ -111,7 +112,7 @@ interface PassSealer {
     drain(): Promise<void>;
 }
 
-function createPassSealer(mailboxUid: string, unlocked: UnlockedKeys, signal: AbortSignal): PassSealer {
+function createPassSealer(mailboxUid: string, unlocked: UnlockedKeys, signal: AbortSignal, client: ApiClient | undefined): PassSealer {
     let generation: Promise<number | undefined> | undefined;
     const pins = new Map<string, Promise<string[] | undefined>>();
     const queue: (() => Promise<unknown>)[] = [];
@@ -120,13 +121,13 @@ function createPassSealer(mailboxUid: string, unlocked: UnlockedKeys, signal: Ab
     let idle: (() => void) | undefined;
     const stopped = () => signal.aborted || !!unlocked.destroyed;
 
-    const vaultGeneration = () => (generation ??= readVaultGeneration(mailboxUid));
+    const vaultGeneration = () => (generation ??= readVaultGeneration(mailboxUid, client));
 
     const pinsFor = (address: string) => {
         const key = address.toLowerCase();
         let entry = pins.get(key);
         if (!entry) {
-            entry = getPinnedSignerFingerprints(mailboxUid, address).then(
+            entry = getPinnedSignerFingerprints(mailboxUid, address, client).then(
                 (fingerprints) => (fingerprints.length > 0 ? fingerprints : undefined),
                 () => undefined,
             );
@@ -169,7 +170,7 @@ function createPassSealer(mailboxUid: string, unlocked: UnlockedKeys, signal: Ab
             const sealToWrite = result.sealToWrite;
             if (sealToWrite && queued < MAX_SEAL_WRITES_PER_PASS) {
                 queued++;
-                queue.push(() => sendVerificationSeal(message.uid, sealToWrite));
+                queue.push(() => sendVerificationSeal(message.uid, sealToWrite, client));
                 pump();
             }
             return result;
@@ -229,6 +230,9 @@ async function mapWithConcurrency<T, R>(items: T[], limit: number, fn: (item: T)
 async function buildEntity(message: Message, sealer: PassSealer): Promise<LocalIndexEntity | undefined | typeof FETCH_FAILED> {
     let rawMime: Awaited<ReturnType<typeof getMessageRawContent>>;
     try {
+        // getMessageRawContent() bypasses apiFetch() entirely (it streams message/rfc822, not JSON - see its own doc comment) and does not
+        // yet accept an explicit ApiClient at all; threading a per-account client through it is out of scope here (mailApi.ts is not one of
+        // this task's files). It still falls back to the default global session even under an ApiClientContext.Provider.
         rawMime = await getMessageRawContent(message.uid);
     } catch {
         // Distinct from "undecryptable": a message that couldn't even be fetched may well be searchable,
@@ -296,6 +300,7 @@ export async function buildLocalIndex(
     unlocked: UnlockedKeys,
     folders: Folder[],
     windowConfig: LocalIndexWindowConfig = { timeFloorMonths: WEB_TIME_FLOOR_MONTHS, byteBudgetBytes: getLocalIndexByteBudget() },
+    client?: ApiClient,
 ): Promise<void> {
     // At most one pass per mailbox: a newer one cancels the older and waits for it to wind down first.
     const previous = activeBuilds.get(mailboxUid);
@@ -305,7 +310,7 @@ export async function buildLocalIndex(
             previous.controller.abort();
             await previous.settled;
         }
-        await runBuildPass(mailboxUid, unlocked, folders, windowConfig, controller.signal);
+        await runBuildPass(mailboxUid, unlocked, folders, windowConfig, controller.signal, client);
     })();
     const entry: ActiveBuild = { controller, settled: run.catch(() => undefined) };
     activeBuilds.set(mailboxUid, entry);
@@ -350,7 +355,14 @@ type WalkOutcome =
     /** A listing failed - nothing can be concluded about the rest of the folder. */
     | "failed";
 
-async function runBuildPass(mailboxUid: string, unlocked: UnlockedKeys, folders: Folder[], windowConfig: LocalIndexWindowConfig, signal: AbortSignal): Promise<void> {
+async function runBuildPass(
+    mailboxUid: string,
+    unlocked: UnlockedKeys,
+    folders: Folder[],
+    windowConfig: LocalIndexWindowConfig,
+    signal: AbortSignal,
+    client: ApiClient | undefined,
+): Promise<void> {
     const generation = nextLocalIndexGeneration();
     const indexKey = await deriveLocalIndexKey(unlocked.masterKey, mailboxUid);
     signal.throwIfAborted();
@@ -368,7 +380,7 @@ async function runBuildPass(mailboxUid: string, unlocked: UnlockedKeys, folders:
     // count, no listing/fetch failure and no budget cut-off - the only case where coverage can be used to
     // narrow Tier 3.
     let complete = true;
-    const sealer = createPassSealer(mailboxUid, unlocked, signal);
+    const sealer = createPassSealer(mailboxUid, unlocked, signal, client);
     try {
         if (folders.some((f) => !MESSAGE_FOLDER_TYPES.has(f.type) && !NON_MESSAGE_FOLDER_TYPES.has(f.type))) {
             complete = false;
@@ -383,7 +395,7 @@ async function runBuildPass(mailboxUid: string, unlocked: UnlockedKeys, folders:
                 signal.throwIfAborted();
                 let messages: Message[];
                 try {
-                    messages = await listMessages(folder.uid, { page, limit: PAGE_SIZE });
+                    messages = await listMessages(folder.uid, { page, limit: PAGE_SIZE }, client);
                 } catch {
                     return "failed";
                 }
@@ -427,7 +439,7 @@ async function runBuildPass(mailboxUid: string, unlocked: UnlockedKeys, folders:
         /** Each folder's current total, or `undefined` if the listing failed. */
         async function folderTotals(): Promise<Map<string, number> | undefined> {
             try {
-                return new Map((await listFolders(mailboxUid)).map((f) => [f.uid, f.totalCount]));
+                return new Map((await listFolders(mailboxUid, client)).map((f) => [f.uid, f.totalCount]));
             } catch {
                 return undefined;
             }

package/apps/shared/search/localIndexKey.ts

@@ -14,7 +14,7 @@
  * already uniformly random) and avoids needing to persist, transmit, or ever lose a random salt just to
  * re-derive the same key on the next unlock.
  */
-import { hkdfDerive } from "@rapidmx/react-shared/crypto/masterKey.js";
+import { hkdfDerive } from "../../../lib/crypto/masterKey.js";
 
 /** Fixed, non-secret HKDF salt - see this module's own doc comment for why a fixed salt is fine here. */
 const FIXED_SALT = new TextEncoder().encode("rapidmx-local-search-index-v1");

package/apps/shared/search/localIndexRpcClient.ts

@@ -25,8 +25,20 @@
  * every pending request and drops the module-level `worker` reference so the next `call()` spawns a
  * replacement. `searchTier2.ts` additionally races its own calls against a timeout, since a Worker that's
  * merely stuck (not crashed) posts no `error` event at all.
+ *
+ * **Swappable transport**: everything above is specific to this one implementation - the Worker/OPFS-backed
+ * default. Every function this module exports below (`initLocalIndex`, `searchLocal`, `destroyLocalIndex`, ...)
+ * is a thin delegator to whichever `LocalIndexTransport` (`localIndexTransport.ts`) is "current," which defaults
+ * to `workerLocalIndexTransport` - this file's own implementation, wrapped - and can be swapped once, at startup,
+ * via `setLocalIndexTransport()`. A host app with a different storage backend (no Worker, no OPFS, no WASM at
+ * all - `tauri-client`'s native SQLCipher/`rusqlite` index) installs its own transport there; every call site
+ * that already goes through this file's exports (`searchTier2.ts`, `LocalIndexLifecycle.tsx`,
+ * `localIndexBuilder.ts`, and the rest) then runs against that backend instead, unmodified. The three
+ * module-level constants below (`SIGN_OUT_CHANNEL`, `PENDING_DELETIONS_KEY`, `DESTROY_ALL_TIMEOUT_MS`) remain
+ * plain exports, not part of the swappable interface - they name this one transport's own cross-tab/localStorage
+ * mechanics, which a different transport has no reason to share.
  */
-import type { ParsedSearchQuery } from "@rapidmx/react-shared/search/queryGrammar.js";
+import type { ParsedSearchQuery } from "../../../lib/search/queryGrammar.js";
 import type {
     Coverage,
     DestroyParams,
@@ -48,6 +60,7 @@ import type {
 } from "./localIndexWorker.js";
 import type { LocalIndexEntity } from "./localIndexSchema.js";
 import { removeLocalIndexDirectories, removeLocalIndexDirectory } from "./localIndexStorage.js";
+import type { LocalIndexTransport, PruneLocalEntitiesOptions, SetLocalIndexBuildingCompletion } from "./localIndexTransport.js";
 
 let worker: Worker | undefined;
 let nextRequestId = 1;
@@ -61,7 +74,7 @@ const initializedMailboxes = new Set<string>();
 let generationCounter = 0;
 
 /** A fresh generation - see this module's doc comment. */
-export function nextLocalIndexGeneration(): number {
+function nextLocalIndexGenerationImpl(): number {
     generationCounter += 1;
     return generationCounter;
 }
@@ -141,7 +154,7 @@ function listenForSignOut(): void {
 async function closeEverythingInThisTab(): Promise<void> {
     signedOut = true;
     initializedMailboxes.clear();
-    await call("destroyAll", { generation: nextLocalIndexGeneration() } satisfies GenerationParams).catch(() => undefined);
+    await call("destroyAll", { generation: nextLocalIndexGenerationImpl() } satisfies GenerationParams).catch(() => undefined);
 }
 
 function call<T>(method: LocalIndexRequest["method"], params?: unknown): Promise<T> {
@@ -194,7 +207,7 @@ let pendingRetry: Promise<void> | undefined;
 
 /** Retries every deletion an earlier page load couldn't finish. Runs once per page load (memoized), before
  * this tab's first `init` - so it never races an index this tab itself opens. Never rejects. */
-export function retryPendingLocalIndexDeletions(): Promise<void> {
+function retryPendingLocalIndexDeletionsImpl(): Promise<void> {
     pendingRetry ??= (async () => {
         const uids = readPendingDeletions();
         if (uids.length === 0) {
@@ -214,8 +227,8 @@ export function retryPendingLocalIndexDeletions(): Promise<void> {
     return pendingRetry;
 }
 
-export async function initLocalIndex(params: InitParams): Promise<void> {
-    await retryPendingLocalIndexDeletions();
+async function initLocalIndexImpl(params: InitParams): Promise<void> {
+    await retryPendingLocalIndexDeletionsImpl();
     if (signedOut) {
         throw new Error("Signed out - the local search index is unavailable in this tab.");
     }
@@ -223,13 +236,13 @@ export async function initLocalIndex(params: InitParams): Promise<void> {
     initializedMailboxes.add(params.mailboxUid);
 }
 
-export function indexLocalEntities(mailboxUid: string, entities: LocalIndexEntity[], generation?: number): Promise<IndexEntitiesResult> {
+function indexLocalEntitiesImpl(mailboxUid: string, entities: LocalIndexEntity[], generation?: number): Promise<IndexEntitiesResult> {
     return call("indexEntities", { mailboxUid, entities, generation } satisfies IndexEntitiesParams);
 }
 
 /** Drops one message from this session's local index (a delete). A no-op for a mailbox not indexed in
  * this tab - a later build pass prunes it instead. Never rejects: best-effort housekeeping. */
-export async function removeLocalEntity(mailboxUid: string, entityUid: string): Promise<void> {
+async function removeLocalEntityImpl(mailboxUid: string, entityUid: string): Promise<void> {
     if (!initializedMailboxes.has(mailboxUid)) {
         return;
     }
@@ -237,44 +250,35 @@ export async function removeLocalEntity(mailboxUid: string, entityUid: string):
 }
 
 /** Re-points one indexed message at its new folder (archive, cancel-scheduled-send) so `folder:`-scoped
- * local searches stay correct. Same no-op/never-rejects rules as `removeLocalEntity()`. */
-export async function moveLocalEntity(mailboxUid: string, entityUid: string, folderUid: string): Promise<void> {
+ * local searches stay correct. Same no-op/never-rejects rules as `removeLocalEntityImpl()`. */
+async function moveLocalEntityImpl(mailboxUid: string, entityUid: string, folderUid: string): Promise<void> {
     if (!initializedMailboxes.has(mailboxUid)) {
         return;
     }
     await call("moveEntity", { mailboxUid, entityUid, folderUid } satisfies MoveEntityParams).catch(() => undefined);
 }
 
-export function getIndexedVersions(mailboxUid: string, entityUids: string[]): Promise<Record<string, string>> {
+function getIndexedVersionsImpl(mailboxUid: string, entityUids: string[]): Promise<Record<string, string>> {
     return call("indexedVersions", { mailboxUid, entityUids } satisfies IndexedVersionsParams);
 }
 
-export function pruneLocalEntities(
-    mailboxUid: string,
-    keepEntityUids: string[],
-    since: string | undefined,
-    options: { folderUids?: string[]; generation?: number } = {},
-): Promise<number> {
+function pruneLocalEntitiesImpl(mailboxUid: string, keepEntityUids: string[], since: string | undefined, options: PruneLocalEntitiesOptions): Promise<number> {
     return call("pruneEntities", { mailboxUid, keepEntityUids, since, ...options } satisfies PruneEntitiesParams);
 }
 
-export function searchLocal(mailboxUid: string, parsed: ParsedSearchQuery, limit: number, offset = 0): Promise<LocalSearchPage> {
+function searchLocalImpl(mailboxUid: string, parsed: ParsedSearchQuery, limit: number, offset: number): Promise<LocalSearchPage> {
     return call("search", { mailboxUid, parsed, limit, offset } satisfies SearchParams);
 }
 
-export function getLocalCoverage(mailboxUid: string): Promise<Coverage> {
+function getLocalCoverageImpl(mailboxUid: string): Promise<Coverage> {
     return call("coverage", mailboxUid);
 }
 
-export function setLocalIndexWindow(mailboxUid: string, timeFloorMonths: number, byteBudgetBytes: number, generation?: number): Promise<WindowState> {
+function setLocalIndexWindowImpl(mailboxUid: string, timeFloorMonths: number, byteBudgetBytes: number, generation?: number): Promise<WindowState> {
     return call("setWindow", { mailboxUid, timeFloorMonths, byteBudgetBytes, generation } satisfies SetWindowParams);
 }
 
-export function setLocalIndexBuilding(
-    mailboxUid: string,
-    building: boolean,
-    completion: { complete: boolean; coveredFrom?: string; coveredUntil?: string; generation?: number } = { complete: false },
-): Promise<void> {
+function setLocalIndexBuildingImpl(mailboxUid: string, building: boolean, completion: SetLocalIndexBuildingCompletion): Promise<void> {
     return call("setBuilding", { mailboxUid, building, ...completion } satisfies SetBuildingParams);
 }
 
@@ -283,10 +287,10 @@ export function setLocalIndexBuilding(
  * lifecycle hooks where a failure mustn't block key destruction) but resolves `false` - and logs why -
  * when the index could not be removed, e.g. because another tab still has it open; the deletion is then
  * retried on the next page load. */
-export async function destroyLocalIndex(mailboxUid: string): Promise<boolean> {
+async function destroyLocalIndexImpl(mailboxUid: string): Promise<boolean> {
     updatePendingDeletions((current) => current.add(mailboxUid));
     try {
-        await call("destroy", { mailboxUid, generation: nextLocalIndexGeneration() } satisfies DestroyParams);
+        await call("destroy", { mailboxUid, generation: nextLocalIndexGenerationImpl() } satisfies DestroyParams);
         updatePendingDeletions((current) => current.delete(mailboxUid));
         return true;
     } catch (err) {
@@ -309,7 +313,7 @@ export const DESTROY_ALL_TIMEOUT_MS = 3_000;
  * would be waste), then removes the directories. Anything left behind is retried on the next load. Resolves
  * `true` when everything was removed within `timeoutMs`; never rejects.
  */
-export async function destroyAllLocalIndexes(timeoutMs = DESTROY_ALL_TIMEOUT_MS): Promise<boolean> {
+async function destroyAllLocalIndexesImpl(timeoutMs: number): Promise<boolean> {
     signedOut = true;
     writePendingDeletions([ALL_INDEXES]);
     try {
@@ -320,7 +324,7 @@ export async function destroyAllLocalIndexes(timeoutMs = DESTROY_ALL_TIMEOUT_MS)
     const work = (async () => {
         let ok = true;
         if (worker) {
-            const { failed } = await call<{ failed: string[] }>("destroyAll", { generation: nextLocalIndexGeneration() } satisfies GenerationParams).catch(() => ({
+            const { failed } = await call<{ failed: string[] }>("destroyAll", { generation: nextLocalIndexGenerationImpl() } satisfies GenerationParams).catch(() => ({
                 failed: ["(worker)"],
             }));
             ok = failed.length === 0;
@@ -344,6 +348,122 @@ export async function destroyAllLocalIndexes(timeoutMs = DESTROY_ALL_TIMEOUT_MS)
 
 /** Removes local indexes for mailboxes outside `accessibleMailboxUids` - e.g. left behind by a different
  * user who signed in on this device without signing out. Never rejects. */
-export async function pruneInaccessibleLocalIndexes(accessibleMailboxUids: Iterable<string>): Promise<void> {
+async function pruneInaccessibleLocalIndexesImpl(accessibleMailboxUids: Iterable<string>): Promise<void> {
     await removeLocalIndexDirectories(new Set(accessibleMailboxUids)).catch(() => undefined);
 }
+
+/**
+ * This file's own Worker/OPFS-backed implementation, wrapping the functions above - see this module's own doc
+ * comment ("Swappable transport"). The default `LocalIndexTransport` (`localIndexTransport.ts`); every export
+ * below delegates to whichever transport `setLocalIndexTransport()` has made current, which starts out as this
+ * one.
+ */
+export const workerLocalIndexTransport: LocalIndexTransport = {
+    nextGeneration: nextLocalIndexGenerationImpl,
+    init: initLocalIndexImpl,
+    indexEntities: indexLocalEntitiesImpl,
+    removeEntity: removeLocalEntityImpl,
+    moveEntity: moveLocalEntityImpl,
+    indexedVersions: getIndexedVersionsImpl,
+    pruneEntities: pruneLocalEntitiesImpl,
+    search: searchLocalImpl,
+    coverage: getLocalCoverageImpl,
+    setWindow: setLocalIndexWindowImpl,
+    setBuilding: setLocalIndexBuildingImpl,
+    destroy: destroyLocalIndexImpl,
+    destroyAll: destroyAllLocalIndexesImpl,
+    pruneInaccessible: pruneInaccessibleLocalIndexesImpl,
+    retryPendingDeletions: retryPendingLocalIndexDeletionsImpl,
+};
+
+let currentTransport: LocalIndexTransport = workerLocalIndexTransport;
+
+/**
+ * Swaps the `LocalIndexTransport` every export below delegates to - see this module's own doc comment
+ * ("Swappable transport"). Defaults to `workerLocalIndexTransport`; a host app with a different storage backend
+ * (e.g. `tauri-client`'s native SQLCipher/`rusqlite` index) calls this once, at startup, before any of this
+ * module's other exports are used, so every call site already wired through them runs against that backend
+ * instead - unmodified.
+ */
+export function setLocalIndexTransport(transport: LocalIndexTransport): void {
+    currentTransport = transport;
+}
+
+/** A fresh generation - see this module's doc comment. */
+export function nextLocalIndexGeneration(): number {
+    return currentTransport.nextGeneration();
+}
+
+export function initLocalIndex(params: InitParams): Promise<void> {
+    return currentTransport.init(params);
+}
+
+export function indexLocalEntities(mailboxUid: string, entities: LocalIndexEntity[], generation?: number): Promise<IndexEntitiesResult> {
+    return currentTransport.indexEntities(mailboxUid, entities, generation);
+}
+
+/** Drops one message from this session's local index (a delete). A no-op for a mailbox not indexed in
+ * this tab - a later build pass prunes it instead. Never rejects: best-effort housekeeping. */
+export function removeLocalEntity(mailboxUid: string, entityUid: string): Promise<void> {
+    return currentTransport.removeEntity(mailboxUid, entityUid);
+}
+
+/** Re-points one indexed message at its new folder (archive, cancel-scheduled-send) so `folder:`-scoped
+ * local searches stay correct. Same no-op/never-rejects rules as `removeLocalEntity()`. */
+export function moveLocalEntity(mailboxUid: string, entityUid: string, folderUid: string): Promise<void> {
+    return currentTransport.moveEntity(mailboxUid, entityUid, folderUid);
+}
+
+export function getIndexedVersions(mailboxUid: string, entityUids: string[]): Promise<Record<string, string>> {
+    return currentTransport.indexedVersions(mailboxUid, entityUids);
+}
+
+export function pruneLocalEntities(
+    mailboxUid: string,
+    keepEntityUids: string[],
+    since: string | undefined,
+    options: PruneLocalEntitiesOptions = {},
+): Promise<number> {
+    return currentTransport.pruneEntities(mailboxUid, keepEntityUids, since, options);
+}
+
+export function searchLocal(mailboxUid: string, parsed: ParsedSearchQuery, limit: number, offset = 0): Promise<LocalSearchPage> {
+    return currentTransport.search(mailboxUid, parsed, limit, offset);
+}
+
+export function getLocalCoverage(mailboxUid: string): Promise<Coverage> {
+    return currentTransport.coverage(mailboxUid);
+}
+
+export function setLocalIndexWindow(mailboxUid: string, timeFloorMonths: number, byteBudgetBytes: number, generation?: number): Promise<WindowState> {
+    return currentTransport.setWindow(mailboxUid, timeFloorMonths, byteBudgetBytes, generation);
+}
+
+export function setLocalIndexBuilding(mailboxUid: string, building: boolean, completion: SetLocalIndexBuildingCompletion = { complete: false }): Promise<void> {
+    return currentTransport.setBuilding(mailboxUid, building, completion);
+}
+
+/** Destroys one mailbox's local index - spec §11 "MUST be destroyed on the same events that destroy private
+ * keys." Never rejects (it's called from lifecycle hooks where a failure mustn't block key destruction) but
+ * resolves `false` when the index could not be removed - see the current transport's own doc comment for what
+ * that means for it (the Worker transport also logs why, and retries on the next page load). */
+export function destroyLocalIndex(mailboxUid: string): Promise<boolean> {
+    return currentTransport.destroy(mailboxUid);
+}
+
+/** Destroys **every** local index this transport knows of - not just the mailboxes this session opened - e.g.
+ * on sign-out. Never rejects. Resolves `true` only if everything was removed within `timeoutMs`. */
+export function destroyAllLocalIndexes(timeoutMs = DESTROY_ALL_TIMEOUT_MS): Promise<boolean> {
+    return currentTransport.destroyAll(timeoutMs);
+}
+
+/** Removes local indexes for mailboxes outside `accessibleMailboxUids` - e.g. left behind by a different
+ * user who signed in on this device without signing out. Never rejects. */
+export function pruneInaccessibleLocalIndexes(accessibleMailboxUids: Iterable<string>): Promise<void> {
+    return currentTransport.pruneInaccessible(accessibleMailboxUids);
+}
+
+/** Retries every deletion an earlier session couldn't finish. Never rejects. */
+export function retryPendingLocalIndexDeletions(): Promise<void> {
+    return currentTransport.retryPendingDeletions();
+}

package/apps/shared/search/localIndexTransport.ts

@@ -0,0 +1,84 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * The Tier 2 local index's transport contract - every operation `localIndexRpcClient.ts`'s public functions perform
+ * against whatever actually stores and queries the index. Type-only: this module declares the shape, it never runs
+ * anything itself.
+ *
+ * The browser/Electron path is backed by `workerLocalIndexTransport` (`localIndexRpcClient.ts`, exported from that
+ * same file) - a Promise/RPC wrapper around a Worker running `@journeyapps/wa-sqlite` over OPFS. That module's own
+ * doc comment covers the Worker/RPC mechanics this interface abstracts away (generations, cross-tab sign-out,
+ * retried deletions, Worker-crash recovery); none of that is part of this contract - it is that transport's own
+ * implementation detail, not something a second implementation needs to reproduce.
+ *
+ * A host app with no Worker/OPFS/WASM at all - `tauri-client`, backed instead by real SQLCipher-encrypted SQLite
+ * via a Rust `rusqlite` `invoke()` command - implements this same shape and installs it once at startup via
+ * `localIndexRpcClient.ts`'s `setLocalIndexTransport()`. Every call site already going through that file's exported
+ * functions (`searchTier2.ts`, `LocalIndexLifecycle.tsx`, `localIndexBuilder.ts`, and the rest) then runs against
+ * the native backend instead, unmodified - those exports are thin delegators to whichever transport is current.
+ *
+ * Method names mirror the Worker's own RPC method names (`localIndexWorker.ts`'s `LocalIndexRequest["method"]`),
+ * not `localIndexRpcClient.ts`'s public function names - a second implementation has no reason to repeat that
+ * file's "Local"-infixed naming (`indexLocalEntities`, `getLocalCoverage`, ...) for its own methods.
+ *
+ * Every method takes exactly the arguments its `localIndexRpcClient.ts` counterpart already resolves down to -
+ * where that file's own export has a default parameter (`offset = 0`, `options = {}`, `timeoutMs = DESTROY_ALL_TIMEOUT_MS`),
+ * this interface takes the resolved value as required, so an implementation never has to reproduce that default
+ * itself.
+ */
+import type { ParsedSearchQuery } from "../../../lib/search/queryGrammar.js";
+import type { Coverage, IndexEntitiesResult, InitParams, LocalSearchPage, WindowState } from "./localIndexWorker.js";
+import type { LocalIndexEntity } from "./localIndexSchema.js";
+
+/** `LocalIndexTransport.pruneEntities()`'s options - which folders' unseen rows may be pruned (see
+ * `localIndexBuilder.ts`'s own "reliable" folders), and this pass's generation tag. */
+export interface PruneLocalEntitiesOptions {
+    folderUids?: string[];
+    generation?: number;
+}
+
+/** `LocalIndexTransport.setBuilding()`'s completion summary - whether a build pass just finished, and how much of
+ * the mailbox it covered (`Coverage.complete`/`coveredFrom`/`coveredUntil`'s own source). */
+export interface SetLocalIndexBuildingCompletion {
+    complete: boolean;
+    coveredFrom?: string;
+    coveredUntil?: string;
+    generation?: number;
+}
+
+/** See this module's own doc comment. */
+export interface LocalIndexTransport {
+    /** A fresh, monotonic generation from this transport's own counter. */
+    nextGeneration(): number;
+    /** Opens (or reuses) this mailbox's index connection. */
+    init(params: InitParams): Promise<void>;
+    /** Indexes (inserts or updates) the given entities, applying byte-budget eviction as needed. */
+    indexEntities(mailboxUid: string, entities: LocalIndexEntity[], generation?: number): Promise<IndexEntitiesResult>;
+    /** Drops one indexed entity. */
+    removeEntity(mailboxUid: string, entityUid: string): Promise<void>;
+    /** Re-points one indexed entity at its new folder. */
+    moveEntity(mailboxUid: string, entityUid: string, folderUid: string): Promise<void>;
+    /** The indexed version marker (`Message.version` + folder) currently stored for each of the given entity uids. */
+    indexedVersions(mailboxUid: string, entityUids: string[]): Promise<Record<string, string>>;
+    /** Removes indexed rows outside `keepEntityUids` (and `since`/`options.folderUids`'s own scope). Returns how many rows were pruned. */
+    pruneEntities(mailboxUid: string, keepEntityUids: string[], since: string | undefined, options: PruneLocalEntitiesOptions): Promise<number>;
+    /** Runs a parsed query against the index, already scored and paginated. */
+    search(mailboxUid: string, parsed: ParsedSearchQuery, limit: number, offset: number): Promise<LocalSearchPage>;
+    /** How much of the mailbox the index currently covers. */
+    coverage(mailboxUid: string): Promise<Coverage>;
+    /** Sets this mailbox's window (time floor + byte budget), applying eviction immediately if it shrank. */
+    setWindow(mailboxUid: string, timeFloorMonths: number, byteBudgetBytes: number, generation?: number): Promise<WindowState>;
+    /** Flags whether a build pass is running, and - once it finishes - how much of the mailbox it covered. */
+    setBuilding(mailboxUid: string, building: boolean, completion: SetLocalIndexBuildingCompletion): Promise<void>;
+    /** Destroys one mailbox's index. Never rejects; resolves `false` (logging why) when it could not be removed. */
+    destroy(mailboxUid: string): Promise<boolean>;
+    /** Destroys every index this transport knows of, e.g. on sign-out. Never rejects; resolves `true` only if
+     * everything was removed within `timeoutMs`. */
+    destroyAll(timeoutMs: number): Promise<boolean>;
+    /** Removes indexes for mailboxes outside `accessibleMailboxUids`. Never rejects. */
+    pruneInaccessible(accessibleMailboxUids: Iterable<string>): Promise<void>;
+    /** Retries any deletion an earlier session couldn't finish. Never rejects. */
+    retryPendingDeletions(): Promise<void>;
+}

package/apps/shared/search/localIndexWorker.ts

@@ -31,7 +31,7 @@
  */
 import SQLiteESMFactory from "@journeyapps/wa-sqlite/dist/wa-sqlite-async.mjs";
 import * as SQLite from "@journeyapps/wa-sqlite";
-import type { ParsedSearchQuery } from "@rapidmx/react-shared/search/queryGrammar.js";
+import type { ParsedSearchQuery } from "../../../lib/search/queryGrammar.js";
 import { EncryptingVFS } from "./localIndexVFS.js";
 import { listLocalIndexMailboxUids, poolNameFor, removeLocalIndexDirectory } from "./localIndexStorage.js";
 import {