@rapidmx/web-client 0.36.0 → 0.37.0

package/apps/shared/search/zeroAccessIndexSync.ts

@@ -29,6 +29,7 @@ import {
     getSearchIndexManifest,
     getSearchIndexSegment,
     type IndexSegment,
+    type IndexWeekEntries,
     listSearchIndexEntries,
     type SegmentManifest,
     putSearchIndexSegment,
@@ -36,8 +37,13 @@ import {
     type ZeroAccessIndexDocument,
 } from "../../../lib/search/zeroAccessIndexApi.js";
 import { ApiRequestError, type ApiClient } from "../../../lib/util/api.js";
-import { getLocalCoverage, indexLocalEntities } from "./localIndexRpcClient.js";
-import type { LocalIndexEntity } from "./localIndexSchema.js";
+import { clientPlatform, isConstrainedConnection, type ClientPlatform } from "../../../lib/util/clientPlatform.js";
+import { getMessage } from "../../../lib/mail/mailApi.js";
+import { getIndexedVersions, getLocalCoverage, indexLocalEntities, moveLocalEntity } from "./localIndexRpcClient.js";
+import { type LocalIndexEntity, messageRowFlags, messageRowVersion } from "./localIndexSchema.js";
+import { forgetZeroAccessSync, zeroAccessSyncEpoch, zeroAccessSyncStateKey } from "./zeroAccessSyncState.js";
+
+export { forgetZeroAccessSync };
 
 /** The segment format this client writes and reads. */
 export const SEGMENT_SCHEMA_VERSION = 1;
@@ -48,6 +54,39 @@ export const TAIL_OVERLAP_MS = 10 * 60 * 1000;
 /** At most this many weeks are compacted per pass, so a large backlog is worked through over several passes. */
 export const MAX_COMPACTIONS_PER_PASS = 4;
 
+/** How long after a week's `compactableAt` each platform takes it (restapi `specs/search.md` §8 *Who compacts*): a computer first,
+ * a phone only when nothing else has for a day. */
+export const COMPACTION_DELAY_MS: Record<ClientPlatform, number> = { desktop: 0, web: 6 * 3_600_000, mobile: 24 * 3_600_000 };
+
+/** A mobile client declines a week whose pending entries and current segment together are larger than this. */
+export const MOBILE_COMPACTION_MAX_BYTES = 5 * 1024 * 1024;
+
+/**
+ * Whether this client should compact `week` now: it is compactable, has pending entries, and this platform's delay after its
+ * `compactableAt` has passed. A mobile client also declines on a cellular or data-saver connection, and a week larger than
+ * `MOBILE_COMPACTION_MAX_BYTES` with `segmentBytes` (its current segment's size) - or of unknown size, or from a server that
+ * doesn't say when it became compactable.
+ */
+export function shouldCompact(
+    week: IndexWeekEntries,
+    segmentBytes: number,
+    platform: ClientPlatform = clientPlatform(),
+    now: number = Date.now(),
+    constrained: boolean = isConstrainedConnection(),
+): boolean {
+    if (!week.compactable || week.pendingEntries === 0) {
+        return false;
+    }
+    const since = week.compactableAt ? Date.parse(week.compactableAt) : NaN;
+    if (platform === "mobile") {
+        if (constrained || Number.isNaN(since) || week.pendingBytes === undefined || week.pendingBytes + segmentBytes > MOBILE_COMPACTION_MAX_BYTES) {
+            return false;
+        }
+    }
+    // A server that doesn't say when the week became compactable: compactable is all there is to go on.
+    return Number.isNaN(since) || since + COMPACTION_DELAY_MS[platform] <= now;
+}
+
 /** Entities handed to the worker per call. */
 const IMPORT_BATCH = 200;
 
@@ -61,6 +100,10 @@ interface SyncState {
     segments: Record<string, string>;
     /** ISO 8601: when the last live-tail pass started. */
     tailSince?: string;
+    /** Where a live-tail pass that ended early stopped: the listing it was paging through (`since`, absent for a whole one), the page
+     * after the last one it imported, and when it started - which the pass that finishes it records as `tailSince`, so nothing written
+     * while it was interrupted is skipped. */
+    tailCursor?: { since?: string; after: string; start: string };
 }
 
 /** What a pass did, for the caller's logging and tests. */
@@ -74,11 +117,9 @@ export interface ZeroAccessSyncResult {
     unreadable: number;
 }
 
-const stateKey = (mailboxUid: string): string => `rapidmx:za-index-sync:${mailboxUid}`;
-
 function loadState(mailboxUid: string): SyncState {
     try {
-        const raw = localStorage.getItem(stateKey(mailboxUid));
+        const raw = localStorage.getItem(zeroAccessSyncStateKey(mailboxUid));
         const parsed: unknown = raw ? JSON.parse(raw) : undefined;
         if (parsed && typeof parsed === "object" && typeof (parsed as SyncState).segments === "object") {
             return parsed as SyncState;
@@ -89,20 +130,16 @@ function loadState(mailboxUid: string): SyncState {
     return { segments: {} };
 }
 
-function saveState(mailboxUid: string, state: SyncState): void {
-    try {
-        localStorage.setItem(stateKey(mailboxUid), JSON.stringify(state));
-    } catch {
-        // Not remembered: the next pass imports again, which is idempotent (entities are upserted).
+/** Remembers `state` - unless the mailbox's local index was destroyed since the pass began (`epoch`, `zeroAccessSyncEpoch()` then): what
+ * the pass imported went with it, and a new index must not be taken for it. */
+function saveState(mailboxUid: string, state: SyncState, epoch: string): void {
+    if (zeroAccessSyncEpoch(mailboxUid) !== epoch) {
+        return;
     }
-}
-
-/** Forgets what a pass remembered for `mailboxUid` (e.g. when its local index is destroyed). */
-export function forgetZeroAccessSync(mailboxUid: string): void {
     try {
-        localStorage.removeItem(stateKey(mailboxUid));
+        localStorage.setItem(zeroAccessSyncStateKey(mailboxUid), JSON.stringify(state));
     } catch {
-        // Nothing to forget.
+        // Not remembered: the next pass imports again, which is idempotent (entities are upserted).
     }
 }
 
@@ -131,8 +168,81 @@ function isDocument(value: unknown): value is ZeroAccessIndexDocument {
     return !!doc && doc.v === 1 && typeof doc.messageUid === "string" && typeof doc.subject === "string" && typeof doc.body === "string";
 }
 
-/** A document as a row of the local index. Folder and flags aren't in the document - the builder records the folder
- * (`localIndexBuilder.ts`), and the upsert keeps what is already there. */
+/** What the builder (`localIndexBuilder.ts`) knows of a zero-access message from the message list - none of it is in its document. */
+export interface ZeroAccessRowMetadata {
+    folderUid: string;
+    entityVersion: string;
+    /** `,flag,flag,` */
+    flags: string;
+}
+
+/** At most this many messages' metadata are kept per mailbox for rows not imported yet; the oldest go first. */
+export const MAX_REMEMBERED_METADATA = 50_000;
+
+/** Folder, version and flags the builder recorded for zero-access messages, by mailbox and message uid, until their row is imported. */
+const rememberedMetadata = new Map<string, Map<string, ZeroAccessRowMetadata>>();
+
+/**
+ * Remembers zero-access message `messageUid`'s folder, version and flags for when its row is imported: the builder records them on the row
+ * as it walks, which does nothing for a row that isn't there yet (the index started empty - a new device, or after a lock - and this sync
+ * imports the rows after the build).
+ */
+export function rememberZeroAccessMetadata(mailboxUid: string, messageUid: string, metadata: ZeroAccessRowMetadata): void {
+    let remembered = rememberedMetadata.get(mailboxUid);
+    if (!remembered) {
+        remembered = new Map();
+        rememberedMetadata.set(mailboxUid, remembered);
+    }
+    remembered.delete(messageUid);
+    remembered.set(messageUid, metadata);
+    if (remembered.size > MAX_REMEMBERED_METADATA) {
+        remembered.delete(remembered.keys().next().value!);
+    }
+}
+
+/** Records on the just-imported rows of `messageUids` what the builder remembered of them, once. */
+async function applyRememberedMetadata(mailboxUid: string, messageUids: string[]): Promise<void> {
+    const remembered = rememberedMetadata.get(mailboxUid);
+    for (const uid of messageUids) {
+        const metadata = remembered?.get(uid);
+        if (metadata) {
+            await moveLocalEntity(mailboxUid, uid, metadata.folderUid, metadata.entityVersion, metadata.flags);
+            remembered!.delete(uid);
+        }
+    }
+}
+
+/** At most this many live-tail rows a pass looks up (`recordTailMetadata()`); the rest get theirs from the next build pass. */
+export const MAX_TAIL_LOOKUPS = 500;
+
+/** How many of those lookups run at once. */
+const TAIL_LOOKUP_CONCURRENCY = 4;
+
+/**
+ * Gives the live tail's rows that nothing recorded yet (`docs`: rows the builder hasn't seen - mail that arrived after its walk) their
+ * folder, version and flags at import, from the message itself, so a folder or flag filter finds them before the next build pass. At
+ * most `MAX_TAIL_LOOKUPS`. Best effort: a message that is gone, moved to another mailbox or won't load is left to the builder.
+ */
+async function recordTailMetadata(mailboxUid: string, messageUids: string[], client?: ApiClient): Promise<void> {
+    const queue: string[] = messageUids.slice(0, MAX_TAIL_LOOKUPS);
+    const worker = async (): Promise<void> => {
+        for (let uid = queue.shift(); uid !== undefined; uid = queue.shift()) {
+            try {
+                const message = await getMessage(uid, client);
+                if (message.mailboxUid === mailboxUid && message.folderUid) {
+                    await moveLocalEntity(mailboxUid, uid, message.folderUid, messageRowVersion(message), messageRowFlags(message));
+                }
+            } catch {
+                // Left to the next build pass.
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(TAIL_LOOKUP_CONCURRENCY, queue.length) }, worker));
+}
+
+/** A document as a row of the local index. Folder and flags aren't in the document - the builder records them (`localIndexBuilder.ts`,
+ * here through `rememberZeroAccessMetadata()` when the row came later; a live-tail row nothing recorded is looked up,
+ * `recordTailMetadata()`), and the upsert keeps what is already there. */
 export function documentEntity(mailboxUid: string, doc: ZeroAccessIndexDocument): LocalIndexEntity {
     const participants: string = (doc.participants ?? []).join(" ");
     const attachmentText: string = [...(doc.attachmentNames ?? []), ...(doc.attachmentText ?? [])].join("\n");
@@ -153,9 +263,14 @@ export function documentEntity(mailboxUid: string, doc: ZeroAccessIndexDocument)
 
 async function importDocuments(mailboxUid: string, docs: ZeroAccessIndexDocument[]): Promise<void> {
     for (let i = 0; i < docs.length; i += IMPORT_BATCH) {
+        const batch = docs.slice(i, i + IMPORT_BATCH);
         await indexLocalEntities(
             mailboxUid,
-            docs.slice(i, i + IMPORT_BATCH).map((doc) => documentEntity(mailboxUid, doc)),
+            batch.map((doc) => documentEntity(mailboxUid, doc)),
+        );
+        await applyRememberedMetadata(
+            mailboxUid,
+            batch.map((doc) => doc.messageUid),
         );
     }
 }
@@ -254,9 +369,21 @@ export function isoWeekId(date: Date): string {
     return `${day.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
 }
 
-/** The sync state, started over when the local index is empty (nothing remembered in it is there any more). */
+/**
+ * The sync state, started over when the local index is empty (nothing remembered in it is there any more). What was stored is dropped then
+ * too: it describes an index that is gone (pruned, or discarded as corrupted, behind this module's back), and a later pass that found this
+ * index filled by the build's end-to-end mail would take it up and skip the segments it never got.
+ */
 async function currentState(mailboxUid: string): Promise<SyncState> {
-    return (await getLocalCoverage(mailboxUid)).indexedCount === 0 ? { segments: {} } : loadState(mailboxUid);
+    if ((await getLocalCoverage(mailboxUid)).indexedCount > 0) {
+        return loadState(mailboxUid);
+    }
+    try {
+        localStorage.removeItem(zeroAccessSyncStateKey(mailboxUid));
+    } catch {
+        // Nothing stored to drop.
+    }
+    return { segments: {} };
 }
 
 /**
@@ -274,8 +401,10 @@ export async function importClientSegments(
     if (!keys?.length) {
         return 0;
     }
-    const segments: IndexSegment[] = (manifest ?? (await getSearchIndexManifest(mailboxUid, client))).segments.filter((segment) => segment.origin === "client");
+    const epoch: string = zeroAccessSyncEpoch(mailboxUid);
+    // Read first, while a new index is still empty: its stale state is dropped even when the manifest can't be read.
     const state: SyncState = await currentState(mailboxUid);
+    const segments: IndexSegment[] = (manifest ?? (await getSearchIndexManifest(mailboxUid, client))).segments.filter((segment) => segment.origin === "client");
     let imported = 0;
     for (const segment of segments.sort((a, b) => b.weekId.localeCompare(a.weekId))) {
         const key = `${segment.weekId}:${segment.origin}`;
@@ -294,7 +423,7 @@ export async function importClientSegments(
             );
         }
         state.segments[key] = segment.etag;
-        saveState(mailboxUid, state);
+        saveState(mailboxUid, state, epoch);
         imported++;
     }
     return imported;
@@ -315,8 +444,14 @@ export async function uploadClientDocuments(mailboxUid: string, unlocked: Unlock
     const weeks = new Map<string, ClientIndexDocument[]>();
     for (const entity of entities) {
         const weekId: string = isoWeekId(new Date(entity.dateForSort));
-        weeks.set(weekId, [...(weeks.get(weekId) ?? []), clientDocument(entity)]);
+        let week = weeks.get(weekId);
+        if (!week) {
+            week = [];
+            weeks.set(weekId, week);
+        }
+        week.push(clientDocument(entity));
     }
+    const epoch: string = zeroAccessSyncEpoch(mailboxUid);
     const state: SyncState = loadState(mailboxUid);
     let written = 0;
     let manifest: SegmentManifest | undefined;
@@ -351,7 +486,7 @@ export async function uploadClientDocuments(mailboxUid: string, unlocked: Unlock
                 // This device already holds every document of the new generation only if it held the previous one.
                 if (current && state.segments[`${weekId}:client`] === current.etag) {
                     state.segments[`${weekId}:client`] = stored.etag;
-                    saveState(mailboxUid, state);
+                    saveState(mailboxUid, state, epoch);
                 }
                 written++;
                 break;
@@ -366,8 +501,8 @@ export async function uploadClientDocuments(mailboxUid: string, unlocked: Unlock
     return written;
 }
 
-/** Every pending entry of `week` (or, without one, written since `since`), paged through. */
-async function listAllEntries(mailboxUid: string, filter: { week?: string; since?: string }, client?: ApiClient): Promise<SealedIndexEntry[]> {
+/** Every pending entry of `week`, paged through. */
+async function listAllEntries(mailboxUid: string, filter: { week: string }, client?: ApiClient): Promise<SealedIndexEntry[]> {
     const entries: SealedIndexEntry[] = [];
     let after: string | undefined;
     do {
@@ -378,6 +513,24 @@ async function listAllEntries(mailboxUid: string, filter: { week?: string; since
     return entries;
 }
 
+/** Per mailbox, the weeks a compaction found it can't fold on this device - a segment it can't read, or pending entries sealed to a key
+ * it doesn't hold (an older key a shared mailbox's member hasn't been given yet) - with how many entries were pending then, and the
+ * zero-access keys it had. Such a week stays pending, and the oldest weeks come first: without this, a few of them would take every pass's
+ * `MAX_COMPACTIONS_PER_PASS` and no other week would ever be compacted here. A week is tried again once its count changes (new entries,
+ * or another device folded it), and every week once this device's keys do. */
+const stalled = new Map<string, { keys: string; weeks: Map<string, number> }>();
+
+/** The weeks of `mailboxUid` this device found it can't fold with `keys` (see `stalled`). */
+function stalledWeeks(mailboxUid: string, keys: ZeroAccessKeys): Map<string, number> {
+    const fingerprints: string = keys.map((key) => key.fingerprint).join(",");
+    let entry = stalled.get(mailboxUid);
+    if (entry?.keys !== fingerprints) {
+        entry = { keys: fingerprints, weeks: new Map() };
+        stalled.set(mailboxUid, entry);
+    }
+    return entry.weeks;
+}
+
 /** The documents of `entries` that open, with the uids of those entries; how many didn't. */
 async function openEntries(entries: SealedIndexEntry[], keys: ZeroAccessKeys): Promise<{ docs: ZeroAccessIndexDocument[]; uids: string[]; unreadable: number }> {
     const docs: ZeroAccessIndexDocument[] = [];
@@ -405,6 +558,7 @@ export async function syncZeroAccessIndex(mailboxUid: string, unlocked: Unlocked
     if (!keys?.length) {
         return result;
     }
+    const epoch: string = zeroAccessSyncEpoch(mailboxUid);
     const manifest = await getSearchIndexManifest(mailboxUid, client);
     let state: SyncState = await currentState(mailboxUid);
 
@@ -423,37 +577,75 @@ export async function syncZeroAccessIndex(mailboxUid: string, unlocked: Unlocked
         await importDocuments(mailboxUid, docs);
         state.segments[key] = segment.etag;
         result.segmentsImported++;
-        saveState(mailboxUid, state);
+        saveState(mailboxUid, state, epoch);
     }
 
     // End-to-end mail other devices indexed.
-    saveState(mailboxUid, state);
+    saveState(mailboxUid, state, epoch);
     result.clientSegmentsImported = await importClientSegments(mailboxUid, unlocked, client, { manifest });
     state = loadState(mailboxUid);
 
-    // The live tail.
-    const tailStart = new Date().toISOString();
+    // The live tail, a page at a time: without a `since` (a new or emptied local index) it is every pending entry of the mailbox, which
+    // after zero-access is turned on can be every message it has - never held, opened, all at once. Each page imported is remembered
+    // (`tailCursor`), so a pass that ends early is taken up where it stopped rather than from the start.
     const since = state.tailSince ? new Date(new Date(state.tailSince).getTime() - TAIL_OVERLAP_MS).toISOString() : undefined;
-    const tail = await openEntries(await listAllEntries(mailboxUid, since ? { since } : {}, client), keys);
-    await importDocuments(mailboxUid, tail.docs);
-    result.entriesImported += tail.docs.length;
-    result.unreadable += tail.unreadable;
+    const resumed = state.tailCursor?.since === since ? state.tailCursor : undefined;
+    const tailStart: string = resumed?.start ?? new Date().toISOString();
+    // Rows nothing has recorded a folder and flags for: not on this device with a version yet (the builder's mark), nor remembered by it.
+    // Asked in batches - a backlog's tail can be every message of the mailbox, past what one SQL statement may bind - and only until there
+    // are as many as a pass looks up.
+    const remembered = rememberedMetadata.get(mailboxUid);
+    const asked = new Set<string>();
+    const unrecorded: string[] = [];
+    let after: string | undefined = resumed?.after;
+    do {
+        const page = await listSearchIndexEntries(mailboxUid, { ...(since ? { since } : {}), ...(after ? { after } : {}) }, client);
+        const tail = await openEntries(page.entries, keys);
+        const tailUids: string[] = [...new Set(tail.docs.map((doc) => doc.messageUid))].filter((uid) => !asked.has(uid));
+        tailUids.forEach((uid) => asked.add(uid));
+        for (let i = 0; i < tailUids.length && unrecorded.length < MAX_TAIL_LOOKUPS; i += IMPORT_BATCH) {
+            const batch: string[] = tailUids.slice(i, i + IMPORT_BATCH);
+            const recorded: Record<string, string> = await getIndexedVersions(mailboxUid, batch);
+            unrecorded.push(...batch.filter((uid) => recorded[uid] === undefined && !remembered?.has(uid)));
+        }
+        await importDocuments(mailboxUid, tail.docs);
+        result.entriesImported += tail.docs.length;
+        result.unreadable += tail.unreadable;
+        after = page.next;
+        if (after) {
+            state.tailCursor = { ...(since ? { since } : {}), after, start: tailStart };
+            saveState(mailboxUid, state, epoch);
+        }
+    } while (after);
+    await recordTailMetadata(mailboxUid, unrecorded, client);
     state.tailSince = tailStart;
-    saveState(mailboxUid, state);
+    delete state.tailCursor;
+    saveState(mailboxUid, state, epoch);
 
-    // Compaction of closed weeks.
+    // Compaction of closed weeks, passing over those this device found it can't fold (`stalled`) while nothing has changed in them.
     const active = keys[0];
-    for (const week of manifest.weeks.filter((w) => w.compactable && w.pendingEntries > 0).slice(0, MAX_COMPACTIONS_PER_PASS)) {
-        const current: IndexSegment | undefined = zeroAccessSegments.find((segment) => segment.weekId === week.weekId);
+    const stalledHere: Map<string, number> = stalledWeeks(mailboxUid, keys);
+    const segmentOf = (weekId: string): IndexSegment | undefined => zeroAccessSegments.find((segment) => segment.weekId === weekId);
+    const weeks: IndexWeekEntries[] = manifest.weeks.filter((w) => stalledHere.get(w.weekId) !== w.pendingEntries && shouldCompact(w, segmentOf(w.weekId)?.bytes ?? 0));
+    for (const week of weeks.slice(0, MAX_COMPACTIONS_PER_PASS)) {
+        const current: IndexSegment | undefined = segmentOf(week.weekId);
         const previous: ZeroAccessIndexDocument[] | undefined = current ? await readSegment(mailboxUid, current, keys, client) : [];
         if (!previous) {
             // A generation this device can't read can't be folded into: leave the week to a device that can.
+            stalledHere.set(week.weekId, week.pendingEntries);
             continue;
         }
         const pending = await openEntries(await listAllEntries(mailboxUid, { week: week.weekId }, client), keys);
         if (pending.uids.length === 0) {
+            stalledHere.set(week.weekId, week.pendingEntries);
             continue;
         }
+        // What this device can't open stays pending once the rest is folded: the week is passed over until that count changes.
+        if (pending.unreadable > 0) {
+            stalledHere.set(week.weekId, pending.unreadable);
+        } else {
+            stalledHere.delete(week.weekId);
+        }
         const merged = new Map<string, ZeroAccessIndexDocument>(previous.map((doc) => [doc.messageUid, doc]));
         for (const doc of pending.docs) {
             merged.set(doc.messageUid, doc);
@@ -474,7 +666,7 @@ export async function syncZeroAccessIndex(mailboxUid: string, unlocked: Unlocked
             // This device already holds every document of the new generation.
             await importDocuments(mailboxUid, pending.docs);
             state.segments[`${stored.weekId}:${stored.origin}`] = stored.etag;
-            saveState(mailboxUid, state);
+            saveState(mailboxUid, state, epoch);
             result.weeksCompacted++;
         } catch (err) {
             // Another device compacted the week first: the next pass imports its generation.

package/apps/shared/search/zeroAccessSyncState.ts

@@ -0,0 +1,70 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+/**
+ * Where a zero-access sync pass (`zeroAccessIndexSync.ts`) remembers what it imported into a mailbox's local index - the segments it
+ * holds, the live tail's last read - and the forgetting of it when that index is destroyed (`localIndexRpcClient.ts`'s
+ * `destroyLocalIndex()`/`destroyAllLocalIndexes()`: a lock, sign-out; `pruneInaccessibleLocalIndexes()`; the Worker discarding a corrupted
+ * index). Apart from both so neither imports the other.
+ *
+ * What was remembered describes an index that is gone, so it must not outlive it - a new index the build fills first (decrypted
+ * end-to-end mail) would otherwise be taken for the old one, and the segments it never got skipped. A pass that started before the destroy
+ * must not write it back either: each pass reads `zeroAccessSyncEpoch()` when it starts and saves nothing once it changed.
+ */
+
+const PREFIX = "rapidmx:za-index-sync:";
+
+/** The localStorage key of `mailboxUid`'s sync state. */
+export const zeroAccessSyncStateKey = (mailboxUid: string): string => `${PREFIX}${mailboxUid}`;
+
+const epochs = new Map<string, number>();
+let allEpoch = 0;
+
+/** Changes whenever `mailboxUid`'s sync state is forgotten. */
+export function zeroAccessSyncEpoch(mailboxUid: string): string {
+    return `${allEpoch}:${epochs.get(mailboxUid) ?? 0}`;
+}
+
+/** Forgets what a pass remembered for `mailboxUid` (its local index is destroyed). */
+export function forgetZeroAccessSync(mailboxUid: string): void {
+    epochs.set(mailboxUid, (epochs.get(mailboxUid) ?? 0) + 1);
+    try {
+        localStorage.removeItem(zeroAccessSyncStateKey(mailboxUid));
+    } catch {
+        // Nothing to forget.
+    }
+}
+
+/** Forgets what passes remembered for every mailbox (every local index is destroyed). */
+export function forgetAllZeroAccessSync(): void {
+    allEpoch++;
+    try {
+        storedMailboxUids().forEach((mailboxUid) => localStorage.removeItem(zeroAccessSyncStateKey(mailboxUid)));
+    } catch {
+        // Nothing to forget.
+    }
+}
+
+/** Forgets what passes remembered for every mailbox not in `keep` (their local indexes are pruned). */
+export function forgetZeroAccessSyncExcept(keep: ReadonlySet<string>): void {
+    let stored: string[];
+    try {
+        stored = storedMailboxUids();
+    } catch {
+        return;
+    }
+    stored.filter((mailboxUid) => !keep.has(mailboxUid)).forEach(forgetZeroAccessSync);
+}
+
+/** The mailboxes some sync state is stored for. Throws when storage can't be read. */
+function storedMailboxUids(): string[] {
+    const uids: string[] = [];
+    for (let i = 0; i < localStorage.length; i++) {
+        const key = localStorage.key(i);
+        if (key?.startsWith(PREFIX)) {
+            uids.push(key.slice(PREFIX.length));
+        }
+    }
+    return uids;
+}

package/apps/shared/zeroAccess/ProtectedMark.tsx

@@ -0,0 +1,19 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import React from "react";
+import { isProtectedRecord, type SealedRecord } from "../../../lib/zeroAccess/sealedRecords.js";
+
+/** A small lock beside a calendar event, contact or task whose details zero-access encryption protects (`sealedFields`) - nothing for
+ * one it doesn't. Never says "end-to-end": the server sees what is saved while it saves it (restapi `specs/search.md` §3). */
+export default function ProtectedMark({ record }: { record: SealedRecord }) {
+    if (!isProtectedRecord(record)) {
+        return null;
+    }
+    return (
+        <span className="ml-1 text-text-muted text-xs" role="img" aria-label="Protected by zero-access encryption" title="Protected by zero-access encryption">
+            &#128274;
+        </span>
+    );
+}

package/apps/shared/zeroAccess/useKeysLocked.ts

@@ -0,0 +1,25 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useRef } from "react";
+import { subscribeKeySession } from "../../../lib/crypto/keySession.js";
+
+/**
+ * Calls `onLocked` with the mailbox whenever a mailbox's keys lock (the idle timeout, a lock from settings, signing out) - for a page that
+ * holds records it opened with them in its state: the opened-value caches are cleared on a lock, but a page's state is not, so it reloads
+ * (the reloaded records keep their placeholders) and closes what shows opened content. The latest `onLocked` is called; subscribed once.
+ */
+export function useKeysLocked(onLocked: (mailboxUid: string) => void): void {
+    const latest = useRef(onLocked);
+    latest.current = onLocked;
+    useEffect(
+        () =>
+            subscribeKeySession(({ mailboxUid, state }) => {
+                if (state === "locked") {
+                    latest.current(mailboxUid);
+                }
+            }),
+        [],
+    );
+}

package/apps/shared/zeroAccess/useOpenedRecord.ts

@@ -0,0 +1,71 @@
+///////////////////////////////////////////////////////////////////////////////
+// Copyright (C) 2026 Jean-Philippe Steinmetz
+// SPDX-License-Identifier: MPL-2.0
+///////////////////////////////////////////////////////////////////////////////
+import { useEffect, useState } from "react";
+import { subscribeKeySession } from "../../../lib/crypto/keySession.js";
+import { isProtectedRecord, openSealedRecord, type SealedRecord } from "../../../lib/zeroAccess/sealedRecords.js";
+
+/** The record's `uid`, when it has one - a new object for the same record (a live update, the page's own reload) is the same record. */
+function uidOf(record: SealedRecord | undefined): string | undefined {
+    return (record as { uid?: unknown } | undefined)?.uid as string | undefined;
+}
+
+/**
+ * `record` with all its protected fields opened (`openSealedRecord()`), for a view that shows or edits every field - a list opens only
+ * what it shows. `ready` is false while a protected record is first being opened; `record` is the one given meanwhile, and the given one
+ * again when it can't be opened (the mailbox is locked).
+ *
+ * A new object for the same record (same `uid`) keeps the opened one ready while it is opened in turn, so a form over it isn't unmounted by
+ * a live update (its in-progress edits kept); the new one - its new `version` - takes over once opened. The record's mailbox locking drops
+ * what was opened at once (nothing opened outlives its key session) and opens it again, which gives the placeholders; its unlocking opens it
+ * again too.
+ *
+ * `open` opens it, `openSealedRecord()` unless a kind of record has its own full open (a calendar event's `fullyOpenedEvent()`, which keeps
+ * the title opened from its sealed content) - a function defined once, not per render, so the record isn't opened again on every render.
+ */
+export function useOpenedRecord<T extends SealedRecord>(
+    record: T | undefined,
+    open: (record: T) => Promise<T> = openSealedRecord,
+): { record: T | undefined; ready: boolean } {
+    const [opened, setOpened] = useState<{ from: T; record: T } | undefined>(undefined);
+    const [generation, setGeneration] = useState(0);
+    const protectedRecord = isProtectedRecord(record);
+    const mailboxUid = record?.mailboxUid;
+    useEffect(() => {
+        if (!mailboxUid || !protectedRecord) {
+            return;
+        }
+        return subscribeKeySession((event) => {
+            if (event.mailboxUid !== mailboxUid) {
+                return;
+            }
+            if (event.state === "locked") {
+                setOpened(undefined);
+            }
+            setGeneration((current) => current + 1);
+        });
+    }, [mailboxUid, protectedRecord]);
+    useEffect(() => {
+        if (!record || !protectedRecord) {
+            return;
+        }
+        let cancelled = false;
+        void open(record).then((result) => {
+            if (!cancelled) {
+                setOpened({ from: record, record: result });
+            }
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [record, protectedRecord, generation, open]);
+    if (!record || !protectedRecord) {
+        return { record, ready: true };
+    }
+    if (opened?.from === record) {
+        return { record: opened.record, ready: true };
+    }
+    const uid = uidOf(record);
+    return opened && uid !== undefined && uidOf(opened.from) === uid ? { record: opened.record, ready: true } : { record, ready: false };
+}

package/apps/www/_shell.tsx

@@ -47,6 +47,7 @@ export default function WwwShell({
     pluginNav,
     branding,
     appearance,
+    signOutHost,
 }: WwwShellProps) {
     const { route, pending } = useRouter();
     const [takeovers, setTakeovers] = useState(0);
@@ -74,6 +75,7 @@ export default function WwwShell({
                 pluginNav={pluginNav}
                 branding={branding}
                 appearance={appearance}
+                signOutHost={signOutHost}
             >
                 {children}
             </AppChrome>