@rapidmx/web-client 0.5.0 → 0.7.0

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

@@ -0,0 +1,71 @@
+/**
+ * Main-thread Promise-based RPC wrapper around `localIndexWorker.ts`. One Worker per tab (spawned
+ * lazily, on first use, not at module load - a page that never touches search shouldn't pay for booting
+ * the WASM module at all), shared across every mailbox `init()`-ed this session - the Worker itself keeps
+ * a per-mailbox connection map (see that file's own doc comment).
+ *
+ * `postMessage` has no native request/response pairing, so every call generates its own numeric `id` and
+ * this module correlates the eventual matching response via a pending-request map.
+ *
+ * **Generations**: `nextLocalIndexGeneration()` hands out one monotonic counter shared by build passes and
+ * destroys, so the Worker can reject a build call issued before the index was destroyed (see
+ * `GenerationParams`).
+ *
+ * **Sign-out reaches every tab**: `destroyAllLocalIndexes()` broadcasts on a `BroadcastChannel`; any other
+ * tab running a Worker closes its connections and refuses further `init`s.
+ *
+ * **Failed deletions are retried**: a destroy that couldn't remove a directory (another tab held it, the page
+ * navigated away first) is recorded in `localStorage` and retried before this tab's first `init`.
+ */
+import type { ParsedSearchQuery } from "@rapidmx/react-shared/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;
+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>;
+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
+ * this tab - a later build pass prunes it instead. Never rejects: best-effort housekeeping. */
+export declare function removeLocalEntity(mailboxUid: string, entityUid: string): Promise<void>;
+/** 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 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 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 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.
+ */
+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>;

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

@@ -18,7 +18,9 @@ export const SIGN_OUT_CHANNEL = "rapidmx-localsearch";
 let channel;
 function getWorker() {
     if (!worker) {
-        worker = new Worker(new URL("./localIndexWorker.ts", import.meta.url), { type: "module" });
+        // Named by its compiled `.js` file, like every other relative import: tsc copies the literal into
+        // `dist` unchanged, where only the `.js` file exists, and Vite maps it back to the `.ts` source.
+        worker = new Worker(new URL("./localIndexWorker.js", import.meta.url), { type: "module" });
         worker.addEventListener("message", (event) => {
             const entry = pending.get(event.data.id);
             if (!entry) {

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

@@ -0,0 +1,111 @@
+/**
+ * The Tier 2 local index's SQLite schema (`specs/search.md` §13). One database per mailbox (see
+ * `localIndexWorker.ts`), holding both the FTS5 index and the metadata cache in the same store - the
+ * spec's own rationale for choosing SQLite over an in-memory JS index in the first place ("the index
+ * database also holds the decrypted metadata cache... so there is one local store rather than two").
+ *
+ * Bumping `SCHEMA_VERSION` is how a schema change invalidates every existing local index (§11
+ * "Invalidation... on schema version change") - `localIndexWorker.ts` compares it against `meta`'s
+ * stored value on open and discards+rebuilds on a mismatch, the same path a corruption/GCM-auth-failure
+ * takes.
+ */
+/** Bump whenever `CREATE_SCHEMA_SQL` changes in a way existing on-disk databases can't be reconciled
+ * with in place. A mismatch deletes and recreates the whole database file (not just its rows), so
+ * creation-time-only settings like `auto_vacuum` also apply to upgraded indexes.
+ *
+ * 2 - added `entities.entity_version` (incremental rebuild skip) and `auto_vacuum=INCREMENTAL`. */
+export declare const SCHEMA_VERSION = 2;
+/**
+ * `entities` is the real row store (metadata + the plaintext content fields), `entities_fts` is an FTS5
+ * *external content* table over it (`content='entities'`) - the standard SQLite pattern for keeping one
+ * copy of the text instead of duplicating it into the FTS5 shadow tables, kept in sync via the three
+ * triggers below (SQLite's own documented pattern for external-content FTS5 tables; there is no
+ * "ON CONFLICT UPDATE re-index" primitive, so update is modeled as delete-then-reinsert into the FTS
+ * index specifically, not into `entities` itself).
+ *
+ * Column order in `entities_fts` (`subject, participants, body, attachment_text`) is load-bearing: every
+ * `bm25(entities_fts, 3.0, 2.0, 1.0, 1.0)` call elsewhere in this module family assumes that exact
+ * positional order, matching `searchScoring.ts`'s `SEARCH_FIELD_WEIGHTS` (`subject: 3, participants: 2,
+ * body: 1, attachmentText: 1`) so Tier 2's local ranking agrees with the Tier 1/Tier 3 re-scoring the
+ * spec requires for one consistent ordering across tiers (§7).
+ */
+export declare const CREATE_SCHEMA_SQL = "\nCREATE TABLE IF NOT EXISTS meta (\n    key TEXT PRIMARY KEY,\n    value TEXT\n);\n\nCREATE TABLE IF NOT EXISTS entities (\n    rowid INTEGER PRIMARY KEY,\n    entity_type TEXT NOT NULL,\n    entity_uid TEXT NOT NULL UNIQUE,\n    mailbox_uid TEXT NOT NULL,\n    folder_uid TEXT,\n    date_for_sort TEXT NOT NULL,\n    participants TEXT,\n    flags TEXT,\n    has_attachments INTEGER NOT NULL DEFAULT 0,\n    subject TEXT,\n    body TEXT,\n    attachment_text TEXT,\n    byte_size INTEGER NOT NULL DEFAULT 0,\n    entity_version TEXT\n);\nCREATE INDEX IF NOT EXISTS idx_entities_date ON entities(date_for_sort);\nCREATE INDEX IF NOT EXISTS idx_entities_mailbox ON entities(mailbox_uid);\n\nCREATE VIRTUAL TABLE IF NOT EXISTS entities_fts USING fts5(\n    subject, participants, body, attachment_text,\n    content='entities', content_rowid='rowid', tokenize='unicode61'\n);\n\nCREATE TRIGGER IF NOT EXISTS entities_ai AFTER INSERT ON entities BEGIN\n    INSERT INTO entities_fts(rowid, subject, participants, body, attachment_text)\n    VALUES (new.rowid, new.subject, new.participants, new.body, new.attachment_text);\nEND;\n\nCREATE TRIGGER IF NOT EXISTS entities_ad AFTER DELETE ON entities BEGIN\n    INSERT INTO entities_fts(entities_fts, rowid, subject, participants, body, attachment_text)\n    VALUES ('delete', old.rowid, old.subject, old.participants, old.body, old.attachment_text);\nEND;\n\nCREATE TRIGGER IF NOT EXISTS entities_au AFTER UPDATE ON entities BEGIN\n    INSERT INTO entities_fts(entities_fts, rowid, subject, participants, body, attachment_text)\n    VALUES ('delete', old.rowid, old.subject, old.participants, old.body, old.attachment_text);\n    INSERT INTO entities_fts(rowid, subject, participants, body, attachment_text)\n    VALUES (new.rowid, new.subject, new.participants, new.body, new.attachment_text);\nEND;\n";
+/** The exact `bm25()` weight arguments every ranked query against `entities_fts` MUST pass, in column
+ * order - see this module's own doc comment on why the order is load-bearing. Centralized here so a
+ * future column reorder can't silently desync a query building its own literal weight list. */
+export declare const BM25_WEIGHTS_SQL = "3.0, 2.0, 1.0, 1.0";
+/** One message's decrypted content, ready to index - `localIndexBuilder.ts`'s own output shape, built
+ * from `Message` + the recovered `MessageSecurityResult` fields the same way `searchTier3.ts` already
+ * derives them for its own per-candidate matching. */
+export interface LocalIndexEntity {
+    entityType: "message";
+    entityUid: string;
+    mailboxUid: string;
+    folderUid?: string;
+    /** ISO 8601 - compares correctly as plain text since every value here is UTC. */
+    dateForSort: string;
+    participants: string;
+    /** Comma-delimited, leading/trailing commas included (`,read,flagged,`) - simplest possible substring
+     * match (`flags LIKE '%,read,%'`) without needing SQLite's JSON1 extension compiled in. */
+    flags: string;
+    hasAttachments: boolean;
+    subject?: string;
+    body?: string;
+    attachmentText?: string;
+    /** Rough on-disk cost of this entity's own content, in bytes - what `localIndexBuilder.ts`'s
+     * byte-budget accounting (spec §11) sums against the configured budget. */
+    byteSize: number;
+    /** Opaque change marker for the source entity (the builder uses the message's `version` plus its
+     * folder) - lets a rebuild skip re-fetching/decrypting anything already indexed unchanged. */
+    entityVersion?: string;
+}
+/** `entity_uid` upsert - `ON CONFLICT` (SQLite's UPSERT syntax) rather than a separate delete-then-insert,
+ * so re-indexing an already-present message (a flag changed, a folder move) updates it in place and the
+ * `entities_au` trigger keeps `entities_fts` in sync automatically. */
+export declare const UPSERT_ENTITY_SQL = "\nINSERT INTO entities (entity_type, entity_uid, mailbox_uid, folder_uid, date_for_sort, participants, flags, has_attachments, subject, body, attachment_text, byte_size, entity_version)\nVALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)\nON CONFLICT(entity_uid) DO UPDATE SET\n    folder_uid = excluded.folder_uid, date_for_sort = excluded.date_for_sort, participants = excluded.participants,\n    flags = excluded.flags, has_attachments = excluded.has_attachments, subject = excluded.subject,\n    body = excluded.body, attachment_text = excluded.attachment_text, byte_size = excluded.byte_size,\n    entity_version = excluded.entity_version\n";
+/** Bind values for `UPSERT_ENTITY_SQL`, in column order - kept alongside it so the two can never drift
+ * out of sync with each other. */
+export declare function entityBindValues(entity: LocalIndexEntity): (string | number)[];
+/** A parsed query's structured (non-free-text) fields - the subset of `ParsedSearchQuery`
+ * (`react-shared`'s `queryGrammar.ts`) this module's predicate builder reads. Typed locally rather than
+ * importing `ParsedSearchQuery` itself so this Worker-bundled module has no dependency on `@rapidmx/
+ * react-shared` beyond what it actually uses - `localIndexBuilder.ts`/`searchTier2.ts` (main-thread side)
+ * pass the real `ParsedSearchQuery` in, which structurally satisfies this. */
+export interface LocalSearchPredicateFields {
+    from?: string;
+    to?: string;
+    cc?: string;
+    subject?: string;
+    hasAttachment?: boolean;
+    before?: Date;
+    after?: Date;
+    folderUid?: string;
+    flags?: string[];
+}
+/**
+ * Builds the SQL `WHERE` predicate (and its bind params) for every *structured* operator this local
+ * index can actually evaluate. **Known simplification**: unlike Tier 1's server-side `SearchDocument`
+ * (which splits `from`/`to`/`cc` into distinct fields - confirmed already implemented server-side), this
+ * local schema keeps only the combined `participants` field (see `CREATE_SCHEMA_SQL`'s own doc comment) -
+ * `from:`/`to:`/`cc:` are therefore evaluated here as a substring match against that combined field
+ * rather than a precise per-role match. Reasonable for a bounded, best-effort recent-window cache
+ * (Tier 1 already serves the precise version for anything it indexes), but a real gap if Tier 2 is later
+ * extended to distinguish them - flagged here rather than left silently approximate.
+ */
+export declare function buildSearchPredicates(parsed: LocalSearchPredicateFields, mailboxUid: string): {
+    where: string;
+    params: (string | number)[];
+};
+/**
+ * Builds the FTS5 `MATCH` expression for a parsed query's free-text and `subject:` portions, or
+ * `undefined` when there's nothing to match on text at all (a pure operator/structured-filter query -
+ * `buildSearchPredicates()`'s `WHERE` clause alone already narrows that case correctly, no `MATCH`
+ * needed). `parsed.text` is passed through close to verbatim (quoted phrases, `OR`, `-` negation - FTS5's
+ * own query syntax supports the same shape `queryGrammar.ts`'s own doc comment says every provider's
+ * free-text engine is expected to), wrapped only enough to combine it with a `subject:`-scoped clause
+ * when both are present.
+ */
+export declare function buildMatchExpression(parsed: {
+    text: string;
+    subject?: string;
+}): string | undefined;

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

@@ -0,0 +1,27 @@
+/** §11's Window Sizing table, Web row. */
+export declare const WEB_DEFAULT_BYTE_BUDGET_BYTES: number;
+/** §11's Window Sizing table, Native desktop row - still a real, user-adjustable ceiling (not
+ * `UNBOUNDED`), just a roomier default given Electron's storage is disk-limited rather than
+ * browser-quota-limited. */
+export declare const ELECTRON_DEFAULT_BYTE_BUDGET_BYTES: number;
+export interface LocalIndexSizeOption {
+    bytes: number;
+    label: string;
+}
+/** Selectable presets for the Settings UI. `0` means "unlimited" - `applyEviction()`
+ * (`localIndexWorker.ts`) already treats a falsy byte budget as unconfigured/unenforced. */
+export declare const LOCAL_INDEX_SIZE_OPTIONS: LocalIndexSizeOption[];
+/** This device's default byte budget before any explicit preference is saved - `500 MB` in a browser
+ * tab, `1 GB` in the Electron shell. */
+export declare function getDefaultLocalIndexByteBudget(): number;
+/**
+ * Reads this device's configured local-index byte budget. Falls back to
+ * `getDefaultLocalIndexByteBudget()` for a never-configured device, a corrupted/non-numeric stored
+ * value, or a `localStorage` access that throws (private-browsing/storage-blocked contexts) - never
+ * throws itself, matching `getIdleTimeoutMinutes()`'s identical fallback posture.
+ */
+export declare function getLocalIndexByteBudget(): number;
+/** Persists this device's local-index byte-budget preference. A `localStorage` write failure is
+ * swallowed, not thrown - the setting just doesn't survive a reload in that case, same fallback-to-default
+ * behavior `getLocalIndexByteBudget()` already has for a storage-blocked context. */
+export declare function setLocalIndexByteBudget(bytes: number): void;

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

@@ -0,0 +1,28 @@
+/**
+ * The Tier 2 local index's on-disk naming and bulk-removal helpers, shared by the Worker
+ * (`localIndexWorker.ts`) and the main thread (`localIndexRpcClient.ts`). Deliberately free of any
+ * wa-sqlite import so the main thread can use it without pulling the WASM build into its own bundle.
+ *
+ * Every mailbox's index lives in its own top-level OPFS directory named `rapidmx-localsearch-<mailboxUid>`
+ * (`AccessHandlePoolVFS` creates it from the VFS name). Enumerating that prefix is how sign-out destroys
+ * *every* index on this device - including ones for mailboxes this page load never opened, which the
+ * RPC client's own session-scoped bookkeeping can't know about - and how a sign-in prunes indexes left
+ * behind for mailboxes the current user can no longer access.
+ */
+export declare const LOCAL_INDEX_POOL_PREFIX = "rapidmx-localsearch-";
+/** The OPFS directory name (and `EncryptingVFS` name) a mailbox's index lives under. */
+export declare function poolNameFor(mailboxUid: string): string;
+/** Inverse of `poolNameFor()`; `undefined` for any OPFS entry that isn't a local index directory. */
+export declare function mailboxUidFromPoolName(name: string): string | undefined;
+/** Removes one mailbox's index directory. Resolves quietly when it doesn't exist; rejects for any other
+ * failure (most commonly `NoModificationAllowedError` - another tab still holds its access handles). */
+export declare function removeLocalIndexDirectory(mailboxUid: string): Promise<void>;
+export interface LocalIndexRemovalResult {
+    removed: string[];
+    /** Mailbox uids whose directory could not be removed (e.g. still open in another tab). */
+    failed: string[];
+}
+/** Every mailbox uid that has a local index directory on this origin. */
+export declare function listLocalIndexMailboxUids(): Promise<string[]>;
+/** Removes every local index directory on this origin except those whose mailbox uid is in `keep`. */
+export declare function removeLocalIndexDirectories(keep?: ReadonlySet<string>): Promise<LocalIndexRemovalResult>;

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

@@ -0,0 +1,101 @@
+/**
+ * `EncryptingVFS` - the Tier 2 local index's at-rest encryption layer (`specs/search.md` §11
+ * "Persistence and protection", §13 "Encryption at Rest": "no official SQLCipher WASM build exists...
+ * encryption at rest requires a custom VFS that encrypts pages before they reach OPFS").
+ *
+ * Wraps (composes, does not subclass - `AccessHandlePoolVFS`'s own file-table state is private `#`
+ * fields) an `AccessHandlePoolVFS` instance and delegates every `FacadeVFS` method straight through
+ * except `jRead`/`jWrite`, which it intercepts to decrypt/encrypt pages.
+ *
+ * ## Page layout
+ *
+ * SQLite is opened with a fixed 4096-byte page size (`PRAGMA page_size=4096` - set by
+ * `localIndexWorker.ts` before the first write, since SQLite fixes a database's page size on creation).
+ * Each *logical* 4096-byte page is stored *physically* as `nonce(12) || AES-256-GCM(ciphertext(4096) ||
+ * tag(16))` = 4124 bytes, at a remapped offset (`physicalOffset(page) = page * 4124`). This block size
+ * is this class's own fixed constant, independent of whatever byte range a given `jRead`/`jWrite` call
+ * actually requests - reads/writes are handled generically over whichever physical blocks the requested
+ * logical range overlaps (including a read-modify-write for a sub-block write), not by assuming SQLite
+ * only ever issues page-aligned, page-sized I/O. That assumption holds for the *main database file* once
+ * its page size is fixed, but handling the general case costs little and removes the need to rely on it.
+ *
+ * **A fresh random nonce is generated on every write, never reused or derived from a counter** - the
+ * simplest way to make an AES-GCM (key, nonce) pair never repeat across different plaintexts, which is
+ * the one hard requirement GCM has. The nonce travels with its block, so decryption never needs any
+ * external state (a lost/corrupted counter, a persisted salt) to reconstruct it.
+ *
+ * **AAD binds each block to its logical filename and page index** (not just its own ciphertext) - GCM
+ * authenticates a block's own content but not its *position*; without this, an attacker able to write
+ * directly into this origin's OPFS storage (outside this codebase's own threat model per spec §4, which
+ * excludes a compromised client, but cheap to close off anyway) could silently swap two blocks and each
+ * would still decrypt "successfully" on its own, corrupting data instead of failing loudly. Binding to
+ * position turns a swap into a caught decryption failure - see `PageCorruptedError` below - the same
+ * "invalidate and rebuild" path a schema-version mismatch already takes (spec §11 "Invalidation").
+ *
+ * **No WAL, no rollback journal.** `localIndexWorker.ts` opens the database with `journal_mode=OFF`. A
+ * page cipher for the main database file is one encryption surface; WAL frames (their own header +
+ * checksum format) and rollback-journal records (their own, different record format) would each be a
+ * *second* one. This index has no durability requirement to justify that cost - spec §11 already
+ * requires discarding and rebuilding it on corruption, schema change, key rotation, or platform storage
+ * eviction, and eviction "MUST NOT block search" - so an interrupted write in the worst case is just
+ * caught by the same GCM-auth-failure -> rebuild path as any other corruption, never partial/torn state
+ * silently trusted.
+ *
+ * Every `jRead`/`jWrite` here is `async` (declared `async` specifically so `FacadeVFS.hasAsyncMethod()`
+ * detects it via `instanceof AsyncFunction` and awaits it) because `crypto.subtle.encrypt`/`decrypt` has
+ * no synchronous form in a browser - this is *why* `localIndexWorker.ts` boots the Asyncify SQLite build
+ * (`dist/wa-sqlite-async.mjs`), not the plain synchronous one `AccessHandlePoolVFS`'s own doc comment
+ * says it's designed for: that claim is about `AccessHandlePoolVFS`'s *own* methods (real synchronous
+ * OPFS access-handle calls), which stay synchronous and work fine wrapped underneath an async outer VFS
+ * on an Asyncify build - the build choice is driven by this class's needs, not the inner VFS's.
+ */
+import { FacadeVFS } from "@journeyapps/wa-sqlite/src/FacadeVFS.js";
+export { PageCorruptedError } from "./localIndexBlockCipher.js";
+export declare class EncryptingVFS extends FacadeVFS {
+    #private;
+    private constructor();
+    /** `rawKey` MUST be exactly 32 bytes (AES-256) - see `localIndexKey.ts`'s `deriveLocalIndexKey()`,
+     * the only intended source of this value. */
+    static create(name: string, module: unknown, rawKey: Uint8Array): Promise<EncryptingVFS>;
+    /**
+     * Releases every pooled OPFS sync access handle `AccessHandlePoolVFS` opened and holds open for its
+     * entire lifetime (not per SQLite-file-open/close - `jOpen`/`jClose` above only associate/disassociate
+     * a SQLite fileId with an already-open handle, they never open or close the handles themselves). MUST
+     * be called before creating another VFS instance against the same OPFS pool `name` - confirmed by
+     * direct reproduction: skipping this and calling `create()` again with the same `name` throws
+     * "Access Handles cannot be created if there is another open Access Handle," since the previous
+     * instance's handles are still live. `localIndexWorker.ts` calls this alongside `sqlite3.close(db)`
+     * (which closes the SQLite *connection*, a separate, shorter-lived thing from the VFS itself) whenever
+     * it tears down a mailbox's connection - on `destroy()` and in `selfTest()`'s own close/reopen check.
+     */
+    close(): void | Promise<void>;
+    jOpen(filename: string | null, pFile: number, flags: number, pOutFlags: DataView): number | Promise<number>;
+    jClose(pFile: number): number | Promise<number>;
+    jDelete(filename: string, syncDir: number): number | Promise<number>;
+    jAccess(filename: string, flags: number, pResOut: DataView): number | Promise<number>;
+    jFullPathname(filename: string, zOut: Uint8Array): number | Promise<number>;
+    jSync(pFile: number, flags: number): number | Promise<number>;
+    jSectorSize(pFile: number): number;
+    jDeviceCharacteristics(pFile: number): number;
+    /** Logical file size = physical size scaled back down to the logical block size - the inner VFS's
+     * own `jFileSize` reports the *physical* (post-remap) byte count, which is always an exact multiple
+     * of `PHYSICAL_BLOCK_SIZE` since every write here always fills whole physical blocks. */
+    jFileSize(pFile: number, pSize64: DataView): Promise<number>;
+    /** `iSize` is a logical byte size - truncates to the smallest whole number of *physical* blocks that
+     * still covers it, so a partially-truncated trailing block is never left half-written. */
+    jTruncate(pFile: number, iSize: number): Promise<number>;
+    /** Set once any block has failed to decrypt/authenticate (or the inner VFS failed a read/write outright)
+     * - `localIndexWorker.ts` checks this after a failed SQLite call to tell real corruption (discard and
+     * rebuild, spec §11 "Invalidation") apart from an ordinary error such as a malformed FTS5 query. */
+    corruptionDetected: boolean;
+    /**
+     * `jRead`/`jWrite` MUST NOT throw: with the Asyncify build, an exception escaping an async VFS method
+     * never reaches the awaiting `sqlite3.*` call - it surfaces only as an unhandled rejection and the
+     * SQLite call hangs forever (confirmed by direct reproduction in node against the real wa-sqlite build).
+     * A thrown `PageCorruptedError` therefore used to wedge the whole connection instead of triggering a
+     * rebuild. Errors are converted to an I/O error return code here, which SQLite does propagate as a
+     * normal `SQLiteError`, and recorded on `corruptionDetected`.
+     */
+    jRead(pFile: number, pData: Uint8Array, iOffset: number): Promise<number>;
+    jWrite(pFile: number, pData: Uint8Array, iOffset: number): Promise<number>;
+}

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

@@ -0,0 +1,145 @@
+import type { ParsedSearchQuery } from "@rapidmx/react-shared/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`,
+ * the main-thread counterpart that generates/awaits these). */
+export interface LocalIndexRequest {
+    id: number;
+    method: "init" | "indexEntities" | "removeEntity" | "moveEntity" | "indexedVersions" | "pruneEntities" | "search" | "coverage" | "setWindow" | "setBuilding" | "destroy" | "destroyAll" | "selfTest" | "ping";
+    params?: unknown;
+}
+export type LocalIndexResponse = {
+    id: number;
+    ok: true;
+    result: unknown;
+} | {
+    id: number;
+    ok: false;
+    error: string;
+};
+/**
+ * Carried by every call a build pass makes (`init`, `setWindow`, `setBuilding`, `indexEntities`,
+ * `pruneEntities`). Generations come from one monotonic counter on the main thread
+ * (`localIndexRpcClient.ts`), shared with `destroy`/`destroyAll`: a call whose generation is older than the
+ * last destroy of its mailbox is rejected (`StaleGenerationError`), so a build started before a lock/sign-out
+ * can't recreate the index with its captured keys or write into a rebuild that started after it. Calls
+ * without a generation (search, coverage, in-session moves) are never rejected.
+ */
+export interface GenerationParams {
+    generation?: number;
+}
+export interface InitParams extends GenerationParams {
+    mailboxUid: string;
+    /** The mailbox's already-derived local-index key (`localIndexKey.ts`'s `deriveLocalIndexKey()`) -
+     * this Worker never touches the master key itself, only this one purpose-derived value, matching
+     * every other MK-derived-key boundary already established elsewhere in this codebase. */
+    indexKey: Uint8Array;
+}
+export interface IndexEntitiesParams extends GenerationParams {
+    mailboxUid: string;
+    entities: LocalIndexEntity[];
+}
+export interface IndexEntitiesResult {
+    /** `true` when this call's eviction pass had to delete anything to get back under the byte budget. */
+    budgetReached: boolean;
+    /** The eviction watermark after this call - see `WindowState.evictedBefore`. */
+    evictedBefore?: string;
+}
+export interface WindowState {
+    /** Set once the byte budget has forced an eviction: messages dated strictly before this were evicted (or
+     * would be, on insert), so a build pass neither re-fetches them nor walks past them. Cleared by
+     * `setWindow` once the index has comfortably shrunk back under budget (or the budget was raised). */
+    evictedBefore?: string;
+}
+export interface DestroyParams extends GenerationParams {
+    mailboxUid: string;
+}
+export interface RemoveEntityParams {
+    mailboxUid: string;
+    entityUid: string;
+}
+export interface MoveEntityParams {
+    mailboxUid: string;
+    entityUid: string;
+    folderUid: string;
+}
+export interface IndexedVersionsParams {
+    mailboxUid: string;
+    entityUids: string[];
+}
+export interface PruneEntitiesParams extends GenerationParams {
+    mailboxUid: string;
+    /** Every entity uid a build pass saw on the server. */
+    keepEntityUids: string[];
+    /** Only rows at or after this `date_for_sort` are candidates (the walk's own time floor - anything
+     * older was never re-listed, so its absence proves nothing). `undefined` means no floor. */
+    since?: string;
+    /** Only rows currently filed in one of these folders are candidates - folders whose listing was reliable
+     * for the whole walk. `undefined` means every folder. */
+    folderUids?: string[];
+}
+export interface SearchParams {
+    mailboxUid: string;
+    parsed: ParsedSearchQuery;
+    limit: number;
+    /** How many matches to skip before returning `limit` more - §8's composite pagination cursor's own
+     * "the local index position consumed so far" component, threaded straight through to SQL `OFFSET`.
+     * Defaults to `0` for a first page. */
+    offset?: number;
+}
+export interface LocalSearchHit {
+    entityUid: string;
+    /** Raw `bm25()` score - more negative is a better match, per SQLite's own convention. Normalized by
+     * `searchTier2.ts` (main thread) before merging (spec §7). */
+    score: number;
+    snippet?: string;
+}
+export interface LocalSearchPage {
+    hits: LocalSearchHit[];
+    /** `true` when at least one more match exists beyond this page - detected by fetching `limit + 1`
+     * rows and trimming the extra one, rather than a separate `COUNT(*)` query. */
+    hasMore: boolean;
+}
+export interface Coverage {
+    /** The oldest date the index is known to cover. While `complete`, every indexable message at least
+     * this recent is present; otherwise it is only the oldest row that happens to be present. `undefined`
+     * for an empty index. */
+    indexedFrom?: string;
+    indexedCount: number;
+    building: boolean;
+    /** `true` only once a build pass *in this connection's lifetime* has walked every mail folder all the
+     * way back to its time floor with no errors and no budget cut-off - reset whenever the index is opened,
+     * so a completion persisted by an earlier session never counts. Callers MUST NOT treat `indexedFrom` as
+     * a coverage guarantee (e.g. to narrow Tier 3) unless this is `true` and `building` is `false`. */
+    complete: boolean;
+    /** Only set while `complete`: the guarantee ends here. Nothing indexes mail that arrives after a pass
+     * started, so everything dated after this (ISO) is NOT covered and must still be searched elsewhere. */
+    indexedUntil?: string;
+}
+export interface SetWindowParams extends GenerationParams {
+    mailboxUid: string;
+    timeFloorMonths: number;
+    byteBudgetBytes: number;
+}
+export interface SetBuildingParams extends GenerationParams {
+    mailboxUid: string;
+    building: boolean;
+    /** Only meaningful with `building: false` - whether the pass that just ended walked everything. */
+    complete?: boolean;
+    /** Only meaningful with `complete: true` - the pass's time floor (ISO), or `undefined` for none. */
+    coveredFrom?: string;
+    /** Only meaningful with `complete: true` - when the pass started (ISO, minus a clock-skew margin). */
+    coveredUntil?: string;
+}
+/** Runs `task` after every previously queued task for `mailboxUid` has settled. Exported for tests. */
+export declare function runExclusive<T>(mailboxUid: string, task: () => Promise<T>): Promise<T>;
+/** Rejects a build-pass call issued before its mailbox's index was last destroyed. */
+export declare class StaleGenerationError extends Error {
+    constructor(mailboxUid: string);
+}
+/** Thrown by `init` when another tab already holds this mailbox's index open. */
+export declare class LocalIndexBusyError extends Error {
+    constructor(mailboxUid: string);
+}
+/** Routes one request to its handler, inside the owning mailbox's serial queue. Exported for tests. */
+export declare function handleRequest(method: LocalIndexRequest["method"], params: unknown): Promise<unknown>;

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

@@ -0,0 +1,30 @@
+/**
+ * Tier 2 (`specs/search.md` §6) - the local encrypted index's public entry point, mirroring
+ * `@rapidmx/react-shared`'s `searchTier3.ts#searchEncryptedCandidates()` in shape: given a parsed query
+ * and this session's unlocked keys, return already-scored, already-sourced results plus how much of the
+ * mailbox the local index actually covers right now.
+ *
+ * Returns `{ results: [], coverage: undefined }` - never throws, never rejects - both when `unlocked` is
+ * absent (nothing is indexed without a master key to derive the index key from, the same "silently
+ * contributes nothing" degradation `searchTier3.ts`'s own doc comment describes for its identical case)
+ * and when anything about the local index itself fails (Worker/WASM/OPFS unsupported or unavailable in
+ * this browser, a corrupted index mid-rebuild, a query timeout). This tier's own storage engine is
+ * strictly best-effort infrastructure Tier 1 doesn't depend on - a caller `Promise.all()`-ing this
+ * alongside Tier 1/Tier 3 (`apps/www/index.tsx`'s own search orchestration) must never see the *whole
+ * search* fail just because this one, most novel piece had a bad moment.
+ */
+import type { UnlockedKeys } from "@rapidmx/react-shared/crypto/keySession.js";
+import type { ParsedSearchQuery } from "@rapidmx/react-shared/search/queryGrammar.js";
+import type { SearchResult } from "@rapidmx/react-shared/search/searchApi.js";
+import type { Coverage } from "./localIndexWorker.js";
+export interface Tier2SearchOutcome {
+    results: SearchResult[];
+    /** `undefined` when `unlocked` was absent - there's no local index to report coverage for at all in
+     * that case, distinct from a real, empty (just-built) index. */
+    coverage?: Coverage;
+    /** `true` when at least one more match exists beyond `results` - §8's composite pagination cursor's
+     * own per-tier continuation signal. Always `false` alongside the `unlocked`-absent/error
+     * degradations below - there is nothing more to page through either way. */
+    hasMore: boolean;
+}
+export declare function searchLocalIndex(mailboxUid: string, parsed: ParsedSearchQuery, unlocked: UnlockedKeys | undefined, limit?: number, offset?: number): Promise<Tier2SearchOutcome>;

package/dist/apps/shared/styles/app.css

@@ -12,11 +12,24 @@
 
 /*
  * Tailwind v4's automatic content scanning excludes `node_modules` by default, which is exactly where
- * `@rapidmx/react-shared`'s components live from every consumer's perspective (a `link:`-ed sibling) -
- * without this, none of its Tailwind classnames (Modal/Drawer/Button/Alert/Skeleton/FormField/
- * PopoverPortal/ContactAvatar/MiniDatePicker/BottomTabBar) would ever be scanned.
+ * `@rapidmx/react-shared`'s components live - without these, none of its Tailwind classnames (Modal/
+ * Drawer/Button/Alert/Skeleton/FormField/PopoverPortal/ContactAvatar/MiniDatePicker/BottomTabBar) are
+ * generated, and e.g. a Modal renders with no overlay, position or width. The published package ships
+ * only its compiled `dist` (no `src`), and `@source` paths resolve from this file's directory
+ * (`apps/shared/styles/`), so both install layouts are listed; a path that doesn't exist is skipped:
+ * - `../../../node_modules/...`: react-shared under this package's own `node_modules` - this repo's
+ *   checkout, or a consumer install that nests it under web-client.
+ * - `../../../../react-shared/dist`: react-shared hoisted beside this package, i.e. this file at
+ *   `<consumer>/node_modules/@rapidmx/web-client/apps/shared/styles/` and react-shared at
+ *   `<consumer>/node_modules/@rapidmx/react-shared` - how `server` installs both, for its pages and
+ *   for the plugin pages' `plugin-ui.css`, which imports this file from there.
+ * `electron-client` links `node_modules/@rapidmx/web-client` to a checkout of this repo, so one of the
+ * two matches whether this file is reached through the link or its real path. From a checkout, the
+ * second path can also find a sibling `react-shared` checkout's build, which only adds classes
+ * react-shared itself uses.
  */
-@source "../../node_modules/@rapidmx/react-shared/src";
+@source "../../../node_modules/@rapidmx/react-shared/dist";
+@source "../../../../react-shared/dist";
 
 /*
  * `server`'s own build (unlike `electron-client`, which already explicitly sourced this same tree in
@@ -30,7 +43,7 @@
  * silently absent from the built stylesheet, even though `AdminShell.tsx` itself was very much in the
  * bundle - verified directly by diffing every classname `AdminShell.tsx` uses against the actual built
  * CSS. An explicit `@source` here makes the scan independent of Vite's per-entry chunking, the same
- * fix this file already applies to `react-shared`, just for this package's own source too.
+ * fix this file applies to `react-shared` above, just for this package's own source too.
  */
 @source "../../";
 
@@ -263,3 +276,13 @@ h5,
 h6 {
     font-family: var(--rr-font-display);
 }
+
+/* The compose editor's quoted original (`composeQuoting.ts`'s blockquote). TipTap keeps the element but not the
+ * inline style it was seeded with, and Tailwind's preflight resets the browser's own blockquote indent - without
+ * this the quote under a reply reads as if it were part of the new message. */
+.tiptap blockquote {
+    margin: 0;
+    padding-left: 1em;
+    border-left: 2px solid var(--rr-color-border);
+    color: var(--rr-color-text-muted);
+}

package/dist/apps/www/_404.d.ts

@@ -0,0 +1,2 @@
+import React from "react";
+export default function NotFoundPage(): React.JSX.Element;

package/dist/apps/www/_500.d.ts

@@ -0,0 +1,2 @@
+import React from "react";
+export default function ErrorPage(): React.JSX.Element;

package/dist/apps/www/_layout.d.ts

@@ -0,0 +1,14 @@
+import React, { PropsWithChildren } from "react";
+import { Branding } from "@rapidmx/react-shared/branding/brandingApi.js";
+export interface LayoutProps {
+    /**
+     * Supplied by `WwwRoute`'s `fetchProps()` override (`src/mongo/routes/wwwRoute.ts`/
+     * `src/sql/routes/wwwRoute.ts`) - `@rapidrest/react` spreads the same merged page props onto this
+     * layout as onto the page it wraps, so it renders correctly server-side on the very first byte of the
+     * response: no client-side flash from the stock defaults below, and a crawler reading the raw HTML
+     * sees the real branding too. `undefined` only on the framework's unwrapped `_500` fallback path,
+     * which doesn't receive props at all - falling back to the stock defaults there is acceptable.
+     */
+    branding?: Branding;
+}
+export default function Layout({ children, branding }: PropsWithChildren<LayoutProps>): React.JSX.Element;

package/dist/apps/www/calendar/index.d.ts

@@ -0,0 +1,3 @@
+import React from "react";
+import { CalendarShellProps } from "../../shared/components/calendar/layout/CalendarShell.js";
+export default function CalendarPage(props: CalendarShellProps): React.JSX.Element;

package/dist/apps/www/contacts/[uid].d.ts

@@ -0,0 +1,13 @@
+import React from "react";
+import { ContactsShellProps } from "../../shared/components/contacts/layout/ContactsShell.js";
+/**
+ * Only reached on mobile (below the `md` breakpoint) — desktop's `apps/www/contacts/index.tsx` keeps its
+ * existing inline detail pane and never navigates here; see that file's `handleSelectRow`. There is no
+ * equivalent "new contact" route — an unsaved contact has no uid to route on, so creation stays an
+ * in-place mode-switch on every device (see `apps/www/contacts/index.tsx`'s `handleNew`).
+ */
+export default function ContactDetailPage(props: ContactsShellProps & {
+    params: {
+        uid: string;
+    };
+}): React.JSX.Element;