@rapidmx/web-client 0.21.0 → 0.22.0

package/dist/apps/shared/search/LocalIndexLifecycle.js

@@ -21,7 +21,8 @@
  * handles that case itself via `destroyAllLocalIndexes()`.
  */
 import { useEffect, useRef } from "react";
-import { getUnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
+import { getUnlockedKeys } from "../../../lib/crypto/keySession.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
  * megabyte) is loaded only once a mailbox is actually unlocked and a build is due, so an inbox that never unlocks - the
@@ -37,14 +38,18 @@ import { destroyLocalIndex, pruneInaccessibleLocalIndexes } from "./localIndexRp
 export const POLL_INTERVAL_MS = 5000;
 /** Renders nothing - pure side-effect component, mounted by `MailShell.tsx`. */
 export default function LocalIndexLifecycle({ mailboxUid, folders, accessibleMailboxUids }) {
+    // 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());
-    // The latest props, for the long-lived polling interval below.
-    const latestRef = useRef({ mailboxUid, folders });
-    latestRef.current = { mailboxUid, folders };
-    function startBuildIfUnlocked(targetMailboxUid, targetFolders) {
+    // 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, targetFolders, targetClient) {
         const unlocked = getUnlockedKeys(targetMailboxUid);
         if (!unlocked || targetFolders.length === 0 || trackedRef.current.get(targetMailboxUid)) {
             return;
@@ -53,14 +58,14 @@ 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(() => {
             for (const [trackedUid, wasUnlocked] of trackedRef.current) {
@@ -76,9 +81,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/dist/apps/shared/search/crossMailboxSearch.d.ts

@@ -1,4 +1,4 @@
-import type { SearchResult } from "@rapidmx/react-shared/search/searchApi.js";
+import type { SearchResult } from "../../../lib/search/searchApi.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
  * minute for a timeout; nothing else writes to it.

package/dist/apps/shared/search/crossMailboxSearch.js

@@ -10,8 +10,8 @@
  *
  * 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 { normalizeServerScores } from "@rapidmx/react-shared/search/searchScoring.js";
+import { ApiRequestError } from "../../../lib/util/api.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
  * minute for a timeout; nothing else writes to it.

package/dist/apps/shared/search/localIndexBuilder.d.ts

@@ -31,8 +31,9 @@
  * 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 { type Folder } from "@rapidmx/react-shared/mail/mailApi.js";
-import type { UnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
+import { type Folder } from "../../../lib/mail/mailApi.js";
+import type { UnlockedKeys } from "../../../lib/crypto/keySession.js";
+import type { ApiClient } from "../../../lib/util/api.js";
 /** §11's Window Sizing table's time-floor column - explicitly unvalidated starting-point default per the
  * spec's own §16 "Measurement Task" ("cannot be supplied by design work... MUST NOT be treated as
  * validated"). Used as-is rather than invented/adjusted here. Not user-adjustable today (unlike the byte
@@ -78,7 +79,7 @@ export declare const MAX_SEAL_WRITES_PER_PASS = 200;
  * preference change in Settings takes effect starting with this mailbox's next build pass (its next
  * unlock), without requiring a reload.
  */
-export declare function buildLocalIndex(mailboxUid: string, unlocked: UnlockedKeys, folders: Folder[], windowConfig?: LocalIndexWindowConfig): Promise<void>;
+export declare function buildLocalIndex(mailboxUid: string, unlocked: UnlockedKeys, folders: Folder[], windowConfig?: LocalIndexWindowConfig, client?: ApiClient): Promise<void>;
 /** Stops a mailbox's running build pass, if any (e.g. its keys were just destroyed), resolving once it has
  * wound down. The Worker independently rejects the pass's later calls once the index is destroyed (see
  * `GenerationParams`); this just stops the fetching and decrypting too. Never rejects. */

package/dist/apps/shared/search/localIndexBuilder.js

@@ -35,8 +35,8 @@
  * 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 } from "@rapidmx/react-shared/mail/mailApi.js";
-import { evaluateMessageSecurity, evaluateMessageSecurityWithSeal } from "@rapidmx/react-shared/crypto/messageSecurity.js";
+import { getMessageRawContent, listFolders, listMessages } from "../../../lib/mail/mailApi.js";
+import { evaluateMessageSecurity, evaluateMessageSecurityWithSeal } from "../../../lib/crypto/messageSecurity.js";
 import { getPinnedSignerFingerprints } from "../components/mail/pinnedSigners.js";
 import { currentVerificationSeal, readVaultGeneration, sendVerificationSeal, verificationSealPending } from "../components/mail/verificationSeals.js";
 import { getIndexedVersions, indexLocalEntities, initLocalIndex, nextLocalIndexGeneration, pruneLocalEntities, setLocalIndexBuilding, setLocalIndexWindow, } from "./localIndexRpcClient.js";
@@ -75,7 +75,7 @@ export const FETCH_CONCURRENCY = 6;
 export const SEAL_WRITE_CONCURRENCY = 2;
 /** The most verification seals one pass writes. */
 export const MAX_SEAL_WRITES_PER_PASS = 200;
-function createPassSealer(mailboxUid, unlocked, signal) {
+function createPassSealer(mailboxUid, unlocked, signal, client) {
     let generation;
     const pins = new Map();
     const queue = [];
@@ -83,12 +83,12 @@ function createPassSealer(mailboxUid, unlocked, signal) {
     let active = 0;
     let idle;
     const stopped = () => signal.aborted || !!unlocked.destroyed;
-    const vaultGeneration = () => (generation ?? (generation = readVaultGeneration(mailboxUid)));
+    const vaultGeneration = () => (generation ?? (generation = readVaultGeneration(mailboxUid, client)));
     const pinsFor = (address) => {
         const key = address.toLowerCase();
         let entry = pins.get(key);
         if (!entry) {
-            entry = getPinnedSignerFingerprints(mailboxUid, address).then((fingerprints) => (fingerprints.length > 0 ? fingerprints : undefined), () => undefined);
+            entry = getPinnedSignerFingerprints(mailboxUid, address, client).then((fingerprints) => (fingerprints.length > 0 ? fingerprints : undefined), () => undefined);
             pins.set(key, entry);
         }
         return entry;
@@ -126,7 +126,7 @@ function createPassSealer(mailboxUid, unlocked, signal) {
             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;
@@ -178,6 +178,9 @@ async function mapWithConcurrency(items, limit, fn) {
 async function buildEntity(message, sealer) {
     let rawMime;
     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 {
@@ -241,7 +244,7 @@ async function buildEntity(message, sealer) {
  * preference change in Settings takes effect starting with this mailbox's next build pass (its next
  * unlock), without requiring a reload.
  */
-export async function buildLocalIndex(mailboxUid, unlocked, folders, windowConfig = { timeFloorMonths: WEB_TIME_FLOOR_MONTHS, byteBudgetBytes: getLocalIndexByteBudget() }) {
+export async function buildLocalIndex(mailboxUid, unlocked, folders, windowConfig = { timeFloorMonths: WEB_TIME_FLOOR_MONTHS, byteBudgetBytes: getLocalIndexByteBudget() }, client) {
     // 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);
     const controller = new AbortController();
@@ -250,7 +253,7 @@ export async function buildLocalIndex(mailboxUid, unlocked, folders, windowConfi
             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 = { controller, settled: run.catch(() => undefined) };
     activeBuilds.set(mailboxUid, entry);
@@ -277,7 +280,7 @@ export async function cancelLocalIndexBuild(mailboxUid) {
 function isOlderThan(date, watermark) {
     return !!watermark && new Date(date).getTime() < new Date(watermark).getTime();
 }
-async function runBuildPass(mailboxUid, unlocked, folders, windowConfig, signal) {
+async function runBuildPass(mailboxUid, unlocked, folders, windowConfig, signal, client) {
     const generation = nextLocalIndexGeneration();
     const indexKey = await deriveLocalIndexKey(unlocked.masterKey, mailboxUid);
     signal.throwIfAborted();
@@ -295,7 +298,7 @@ async function runBuildPass(mailboxUid, unlocked, folders, windowConfig, signal)
     // 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;
@@ -309,7 +312,7 @@ async function runBuildPass(mailboxUid, unlocked, folders, windowConfig, signal)
                 signal.throwIfAborted();
                 let messages;
                 try {
-                    messages = await listMessages(folder.uid, { page, limit: PAGE_SIZE });
+                    messages = await listMessages(folder.uid, { page, limit: PAGE_SIZE }, client);
                 }
                 catch {
                     return "failed";
@@ -350,7 +353,7 @@ async function runBuildPass(mailboxUid, unlocked, folders, windowConfig, signal)
         /** Each folder's current total, or `undefined` if the listing failed. */
         async function folderTotals() {
             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/dist/apps/shared/search/localIndexKey.js

@@ -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");
 /** Derives this mailbox's local-index page-encryption key from its already-unlocked master key. Every

package/dist/apps/shared/search/localIndexRpcClient.d.ts

@@ -21,17 +21,44 @@
  * 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, IndexEntitiesResult, InitParams, LocalSearchPage, WindowState } from "./localIndexWorker.js";
 import type { LocalIndexEntity } from "./localIndexSchema.js";
-/** A fresh generation - see this module's doc comment. */
-export declare function nextLocalIndexGeneration(): number;
+import type { LocalIndexTransport, PruneLocalEntitiesOptions, SetLocalIndexBuildingCompletion } from "./localIndexTransport.js";
 export declare const SIGN_OUT_CHANNEL = "rapidmx-localsearch";
 export declare const PENDING_DELETIONS_KEY = "rapidmx-localsearch-pending-deletions";
-/** 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 declare function retryPendingLocalIndexDeletions(): Promise<void>;
+/** How long sign-out waits for local index destruction before navigating anyway. */
+export declare const DESTROY_ALL_TIMEOUT_MS = 3000;
+/**
+ * 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 declare const workerLocalIndexTransport: LocalIndexTransport;
+/**
+ * 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 declare function setLocalIndexTransport(transport: LocalIndexTransport): void;
+/** A fresh generation - see this module's doc comment. */
+export declare function nextLocalIndexGeneration(): number;
 export declare function initLocalIndex(params: InitParams): Promise<void>;
 export declare function indexLocalEntities(mailboxUid: string, entities: LocalIndexEntity[], generation?: number): Promise<IndexEntitiesResult>;
 /** Drops one message from this session's local index (a delete). A no-op for a mailbox not indexed in
@@ -41,36 +68,21 @@ export declare function removeLocalEntity(mailboxUid: string, entityUid: string)
  * local searches stay correct. Same no-op/never-rejects rules as `removeLocalEntity()`. */
 export declare function moveLocalEntity(mailboxUid: string, entityUid: string, folderUid: string): Promise<void>;
 export declare function getIndexedVersions(mailboxUid: string, entityUids: string[]): Promise<Record<string, string>>;
-export declare function pruneLocalEntities(mailboxUid: string, keepEntityUids: string[], since: string | undefined, options?: {
-    folderUids?: string[];
-    generation?: number;
-}): Promise<number>;
+export declare function pruneLocalEntities(mailboxUid: string, keepEntityUids: string[], since: string | undefined, options?: PruneLocalEntitiesOptions): Promise<number>;
 export declare function searchLocal(mailboxUid: string, parsed: ParsedSearchQuery, limit: number, offset?: number): Promise<LocalSearchPage>;
 export declare function getLocalCoverage(mailboxUid: string): Promise<Coverage>;
 export declare function setLocalIndexWindow(mailboxUid: string, timeFloorMonths: number, byteBudgetBytes: number, generation?: number): Promise<WindowState>;
-export declare function setLocalIndexBuilding(mailboxUid: string, building: boolean, completion?: {
-    complete: boolean;
-    coveredFrom?: string;
-    coveredUntil?: string;
-    generation?: number;
-}): Promise<void>;
-/** Destroys one mailbox's local index (both the SQLite connection and its on-disk OPFS storage) - 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` - 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 declare function setLocalIndexBuilding(mailboxUid: string, building: boolean, completion?: SetLocalIndexBuildingCompletion): Promise<void>;
+/** 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 declare function destroyLocalIndex(mailboxUid: string): Promise<boolean>;
-/** How long sign-out waits for local index destruction before navigating anyway. */
-export declare const DESTROY_ALL_TIMEOUT_MS = 3000;
-/**
- * Destroys **every** local index on this device - not just the mailboxes this page load opened (sign-out
- * from Calendar, say, never opened any), by enumerating OPFS for the index directory prefix - and tells every
- * other tab to close its own connections. Closes this tab's own open connections through the Worker first
- * (only if one was ever spawned - there's nothing to close otherwise, and booting one just to delete files
- * 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.
- */
+/** 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 declare function destroyAllLocalIndexes(timeoutMs?: number): Promise<boolean>;
 /** 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 declare function pruneInaccessibleLocalIndexes(accessibleMailboxUids: Iterable<string>): Promise<void>;
+/** Retries every deletion an earlier session couldn't finish. Never rejects. */
+export declare function retryPendingLocalIndexDeletions(): Promise<void>;

package/dist/apps/shared/search/localIndexRpcClient.js

@@ -8,7 +8,7 @@ const pending = new Map();
 const initializedMailboxes = new Set();
 let generationCounter = 0;
 /** A fresh generation - see this module's doc comment. */
-export function nextLocalIndexGeneration() {
+function nextLocalIndexGenerationImpl() {
     generationCounter += 1;
     return generationCounter;
 }
@@ -83,7 +83,7 @@ function listenForSignOut() {
 async function closeEverythingInThisTab() {
     signedOut = true;
     initializedMailboxes.clear();
-    await call("destroyAll", { generation: nextLocalIndexGeneration() }).catch(() => undefined);
+    await call("destroyAll", { generation: nextLocalIndexGenerationImpl() }).catch(() => undefined);
 }
 function call(method, params) {
     const id = nextRequestId++;
@@ -133,7 +133,7 @@ function updatePendingDeletions(update) {
 let pendingRetry;
 /** 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() {
+function retryPendingLocalIndexDeletionsImpl() {
     pendingRetry ?? (pendingRetry = (async () => {
         const uids = readPendingDeletions();
         if (uids.length === 0) {
@@ -153,49 +153,49 @@ export function retryPendingLocalIndexDeletions() {
     })());
     return pendingRetry;
 }
-export async function initLocalIndex(params) {
-    await retryPendingLocalIndexDeletions();
+async function initLocalIndexImpl(params) {
+    await retryPendingLocalIndexDeletionsImpl();
     if (signedOut) {
         throw new Error("Signed out - the local search index is unavailable in this tab.");
     }
     await call("init", params);
     initializedMailboxes.add(params.mailboxUid);
 }
-export function indexLocalEntities(mailboxUid, entities, generation) {
+function indexLocalEntitiesImpl(mailboxUid, entities, generation) {
     return call("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 async function removeLocalEntity(mailboxUid, entityUid) {
+async function removeLocalEntityImpl(mailboxUid, entityUid) {
     if (!initializedMailboxes.has(mailboxUid)) {
         return;
     }
     await call("removeEntity", { mailboxUid, entityUid }).catch(() => undefined);
 }
 /** 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, entityUid, folderUid) {
+ * local searches stay correct. Same no-op/never-rejects rules as `removeLocalEntityImpl()`. */
+async function moveLocalEntityImpl(mailboxUid, entityUid, folderUid) {
     if (!initializedMailboxes.has(mailboxUid)) {
         return;
     }
     await call("moveEntity", { mailboxUid, entityUid, folderUid }).catch(() => undefined);
 }
-export function getIndexedVersions(mailboxUid, entityUids) {
+function getIndexedVersionsImpl(mailboxUid, entityUids) {
     return call("indexedVersions", { mailboxUid, entityUids });
 }
-export function pruneLocalEntities(mailboxUid, keepEntityUids, since, options = {}) {
+function pruneLocalEntitiesImpl(mailboxUid, keepEntityUids, since, options) {
     return call("pruneEntities", { mailboxUid, keepEntityUids, since, ...options });
 }
-export function searchLocal(mailboxUid, parsed, limit, offset = 0) {
+function searchLocalImpl(mailboxUid, parsed, limit, offset) {
     return call("search", { mailboxUid, parsed, limit, offset });
 }
-export function getLocalCoverage(mailboxUid) {
+function getLocalCoverageImpl(mailboxUid) {
     return call("coverage", mailboxUid);
 }
-export function setLocalIndexWindow(mailboxUid, timeFloorMonths, byteBudgetBytes, generation) {
+function setLocalIndexWindowImpl(mailboxUid, timeFloorMonths, byteBudgetBytes, generation) {
     return call("setWindow", { mailboxUid, timeFloorMonths, byteBudgetBytes, generation });
 }
-export function setLocalIndexBuilding(mailboxUid, building, completion = { complete: false }) {
+function setLocalIndexBuildingImpl(mailboxUid, building, completion) {
     return call("setBuilding", { mailboxUid, building, ...completion });
 }
 /** Destroys one mailbox's local index (both the SQLite connection and its on-disk OPFS storage) - spec
@@ -203,10 +203,10 @@ export function setLocalIndexBuilding(mailboxUid, building, completion = { compl
  * 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) {
+async function destroyLocalIndexImpl(mailboxUid) {
     updatePendingDeletions((current) => current.add(mailboxUid));
     try {
-        await call("destroy", { mailboxUid, generation: nextLocalIndexGeneration() });
+        await call("destroy", { mailboxUid, generation: nextLocalIndexGenerationImpl() });
         updatePendingDeletions((current) => current.delete(mailboxUid));
         return true;
     }
@@ -229,7 +229,7 @@ export const DESTROY_ALL_TIMEOUT_MS = 3000;
  * 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) {
+async function destroyAllLocalIndexesImpl(timeoutMs) {
     signedOut = true;
     writePendingDeletions([ALL_INDEXES]);
     try {
@@ -241,7 +241,7 @@ export async function destroyAllLocalIndexes(timeoutMs = DESTROY_ALL_TIMEOUT_MS)
     const work = (async () => {
         let ok = true;
         if (worker) {
-            const { failed } = await call("destroyAll", { generation: nextLocalIndexGeneration() }).catch(() => ({
+            const { failed } = await call("destroyAll", { generation: nextLocalIndexGenerationImpl() }).catch(() => ({
                 failed: ["(worker)"],
             }));
             ok = failed.length === 0;
@@ -264,6 +264,99 @@ 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) {
+async function pruneInaccessibleLocalIndexesImpl(accessibleMailboxUids) {
     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 = {
+    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 = 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) {
+    currentTransport = transport;
+}
+/** A fresh generation - see this module's doc comment. */
+export function nextLocalIndexGeneration() {
+    return currentTransport.nextGeneration();
+}
+export function initLocalIndex(params) {
+    return currentTransport.init(params);
+}
+export function indexLocalEntities(mailboxUid, entities, generation) {
+    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, entityUid) {
+    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, entityUid, folderUid) {
+    return currentTransport.moveEntity(mailboxUid, entityUid, folderUid);
+}
+export function getIndexedVersions(mailboxUid, entityUids) {
+    return currentTransport.indexedVersions(mailboxUid, entityUids);
+}
+export function pruneLocalEntities(mailboxUid, keepEntityUids, since, options = {}) {
+    return currentTransport.pruneEntities(mailboxUid, keepEntityUids, since, options);
+}
+export function searchLocal(mailboxUid, parsed, limit, offset = 0) {
+    return currentTransport.search(mailboxUid, parsed, limit, offset);
+}
+export function getLocalCoverage(mailboxUid) {
+    return currentTransport.coverage(mailboxUid);
+}
+export function setLocalIndexWindow(mailboxUid, timeFloorMonths, byteBudgetBytes, generation) {
+    return currentTransport.setWindow(mailboxUid, timeFloorMonths, byteBudgetBytes, generation);
+}
+export function setLocalIndexBuilding(mailboxUid, building, completion = { complete: false }) {
+    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) {
+    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) {
+    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) {
+    return currentTransport.pruneInaccessible(accessibleMailboxUids);
+}
+/** Retries every deletion an earlier session couldn't finish. Never rejects. */
+export function retryPendingLocalIndexDeletions() {
+    return currentTransport.retryPendingDeletions();
+}

package/dist/apps/shared/search/localIndexTransport.d.ts

@@ -0,0 +1,77 @@
+/**
+ * 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/dist/apps/shared/search/localIndexTransport.js

@@ -0,0 +1 @@
+export {};

package/dist/apps/shared/search/localIndexWorker.d.ts

@@ -1,4 +1,4 @@
-import type { ParsedSearchQuery } from "@rapidmx/react-shared/search/queryGrammar.js";
+import type { ParsedSearchQuery } from "../../../lib/search/queryGrammar.js";
 import { LocalIndexEntity } from "./localIndexSchema.js";
 /** One request sent from the main thread. `id` correlates the eventual response - `postMessage` has no
  * native request/response pairing, so every RPC call carries its own id (see `localIndexRpcClient.ts`,