@rapidmx/web-client 0.36.0 → 0.37.0

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

@@ -26,21 +26,49 @@ import { fromBase64, toBase64 } from "../../../lib/crypto/encoding.js";
 import { decryptEnvelopedDataWithKeys, encryptForRecipients } from "../../../lib/crypto/smime.js";
 import { getSearchIndexManifest, getSearchIndexSegment, listSearchIndexEntries, putSearchIndexSegment, } from "../../../lib/search/zeroAccessIndexApi.js";
 import { ApiRequestError } from "../../../lib/util/api.js";
-import { getLocalCoverage, indexLocalEntities } from "./localIndexRpcClient.js";
+import { clientPlatform, isConstrainedConnection } from "../../../lib/util/clientPlatform.js";
+import { getMessage } from "../../../lib/mail/mailApi.js";
+import { getIndexedVersions, getLocalCoverage, indexLocalEntities, moveLocalEntity } from "./localIndexRpcClient.js";
+import { 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;
 /** How far before its last pass the live tail asks again, so an entry committed late is never skipped. */
 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 = { desktop: 0, web: 6 * 3600000, mobile: 24 * 3600000 };
+/** 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, segmentBytes, platform = clientPlatform(), now = Date.now(), constrained = isConstrainedConnection()) {
+    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;
 /** How many times `uploadClientDocuments()` re-reads a week's client segment after another device replaced it first. */
 export const CLIENT_UPLOAD_ATTEMPTS = 3;
-const stateKey = (mailboxUid) => `rapidmx:za-index-sync:${mailboxUid}`;
 function loadState(mailboxUid) {
     try {
-        const raw = localStorage.getItem(stateKey(mailboxUid));
+        const raw = localStorage.getItem(zeroAccessSyncStateKey(mailboxUid));
         const parsed = raw ? JSON.parse(raw) : undefined;
         if (parsed && typeof parsed === "object" && typeof parsed.segments === "object") {
             return parsed;
@@ -51,21 +79,17 @@ function loadState(mailboxUid) {
     }
     return { segments: {} };
 }
-function saveState(mailboxUid, state) {
-    try {
-        localStorage.setItem(stateKey(mailboxUid), JSON.stringify(state));
+/** 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, state, epoch) {
+    if (zeroAccessSyncEpoch(mailboxUid) !== epoch) {
+        return;
     }
-    catch {
-        // Not remembered: the next pass imports again, which is idempotent (entities are upserted).
-    }
-}
-/** Forgets what a pass remembered for `mailboxUid` (e.g. when its local index is destroyed). */
-export function forgetZeroAccessSync(mailboxUid) {
     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).
     }
 }
 async function transform(bytes, stream) {
@@ -87,8 +111,67 @@ function isDocument(value) {
     const doc = value;
     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. */
+/** At most this many messages' metadata are kept per mailbox for rows not imported yet; the oldest go first. */
+export const MAX_REMEMBERED_METADATA = 50000;
+/** 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();
+/**
+ * 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, messageUid, metadata) {
+    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, messageUids) {
+    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, messageUids, client) {
+    const queue = messageUids.slice(0, MAX_TAIL_LOOKUPS);
+    const worker = async () => {
+        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, doc) {
     const participants = (doc.participants ?? []).join(" ");
     const attachmentText = [...(doc.attachmentNames ?? []), ...(doc.attachmentText ?? [])].join("\n");
@@ -108,7 +191,9 @@ export function documentEntity(mailboxUid, doc) {
 }
 async function importDocuments(mailboxUid, docs) {
     for (let i = 0; i < docs.length; i += IMPORT_BATCH) {
-        await indexLocalEntities(mailboxUid, docs.slice(i, i + IMPORT_BATCH).map((doc) => documentEntity(mailboxUid, doc)));
+        const batch = docs.slice(i, i + IMPORT_BATCH);
+        await indexLocalEntities(mailboxUid, batch.map((doc) => documentEntity(mailboxUid, doc)));
+        await applyRememberedMetadata(mailboxUid, batch.map((doc) => doc.messageUid));
     }
 }
 /** The documents of a segment generation that pass `accept`, or `undefined` when it won't open or is a format this client doesn't read. */
@@ -174,9 +259,22 @@ export function isoWeekId(date) {
     const week = Math.ceil(((day.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
     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) {
-    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: {} };
 }
 /**
  * Imports the client segments of `mailboxUid` (end-to-end mail indexed by another device - see this module's comment) not yet imported in
@@ -188,8 +286,10 @@ export async function importClientSegments(mailboxUid, unlocked, client, { manif
     if (!keys?.length) {
         return 0;
     }
-    const segments = (manifest ?? (await getSearchIndexManifest(mailboxUid, client))).segments.filter((segment) => segment.origin === "client");
+    const epoch = 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 = await currentState(mailboxUid);
+    const segments = (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}`;
@@ -204,7 +304,7 @@ export async function importClientSegments(mailboxUid, unlocked, client, { manif
             await indexLocalEntities(mailboxUid, docs.slice(i, i + IMPORT_BATCH).map((doc) => clientDocumentEntity(mailboxUid, doc)), generation);
         }
         state.segments[key] = segment.etag;
-        saveState(mailboxUid, state);
+        saveState(mailboxUid, state, epoch);
         imported++;
     }
     return imported;
@@ -224,8 +324,14 @@ export async function uploadClientDocuments(mailboxUid, unlocked, entities, clie
     const weeks = new Map();
     for (const entity of entities) {
         const weekId = 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 = zeroAccessSyncEpoch(mailboxUid);
     const state = loadState(mailboxUid);
     let written = 0;
     let manifest;
@@ -255,7 +361,7 @@ export async function uploadClientDocuments(mailboxUid, unlocked, entities, clie
                 // 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;
@@ -270,7 +376,7 @@ export async function uploadClientDocuments(mailboxUid, unlocked, entities, clie
     }
     return written;
 }
-/** Every pending entry of `week` (or, without one, written since `since`), paged through. */
+/** Every pending entry of `week`, paged through. */
 async function listAllEntries(mailboxUid, filter, client) {
     const entries = [];
     let after;
@@ -281,6 +387,22 @@ async function listAllEntries(mailboxUid, filter, client) {
     } while (after);
     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();
+/** The weeks of `mailboxUid` this device found it can't fold with `keys` (see `stalled`). */
+function stalledWeeks(mailboxUid, keys) {
+    const fingerprints = 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, keys) {
     const docs = [];
@@ -308,6 +430,7 @@ export async function syncZeroAccessIndex(mailboxUid, unlocked, client) {
     if (!keys?.length) {
         return result;
     }
+    const epoch = zeroAccessSyncEpoch(mailboxUid);
     const manifest = await getSearchIndexManifest(mailboxUid, client);
     let state = await currentState(mailboxUid);
     // Segments, newest week first.
@@ -325,34 +448,73 @@ export async function syncZeroAccessIndex(mailboxUid, unlocked, client) {
         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 = 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();
+    const unrecorded = [];
+    let after = resumed?.after;
+    do {
+        const page = await listSearchIndexEntries(mailboxUid, { ...(since ? { since } : {}), ...(after ? { after } : {}) }, client);
+        const tail = await openEntries(page.entries, keys);
+        const tailUids = [...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 = tailUids.slice(i, i + IMPORT_BATCH);
+            const recorded = 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);
-    // Compaction of closed weeks.
+    delete state.tailCursor;
+    saveState(mailboxUid, state, epoch);
+    // 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 = zeroAccessSegments.find((segment) => segment.weekId === week.weekId);
+    const stalledHere = stalledWeeks(mailboxUid, keys);
+    const segmentOf = (weekId) => zeroAccessSegments.find((segment) => segment.weekId === weekId);
+    const weeks = 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 = segmentOf(week.weekId);
         const previous = 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(previous.map((doc) => [doc.messageUid, doc]));
         for (const doc of pending.docs) {
             merged.set(doc.messageUid, doc);
@@ -368,7 +530,7 @@ export async function syncZeroAccessIndex(mailboxUid, unlocked, client) {
             // 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) {

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

@@ -0,0 +1,20 @@
+/**
+ * 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.
+ */
+/** The localStorage key of `mailboxUid`'s sync state. */
+export declare const zeroAccessSyncStateKey: (mailboxUid: string) => string;
+/** Changes whenever `mailboxUid`'s sync state is forgotten. */
+export declare function zeroAccessSyncEpoch(mailboxUid: string): string;
+/** Forgets what a pass remembered for `mailboxUid` (its local index is destroyed). */
+export declare function forgetZeroAccessSync(mailboxUid: string): void;
+/** Forgets what passes remembered for every mailbox (every local index is destroyed). */
+export declare function forgetAllZeroAccessSync(): void;
+/** Forgets what passes remembered for every mailbox not in `keep` (their local indexes are pruned). */
+export declare function forgetZeroAccessSyncExcept(keep: ReadonlySet<string>): void;

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

@@ -0,0 +1,65 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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) => `${PREFIX}${mailboxUid}`;
+const epochs = new Map();
+let allEpoch = 0;
+/** Changes whenever `mailboxUid`'s sync state is forgotten. */
+export function zeroAccessSyncEpoch(mailboxUid) {
+    return `${allEpoch}:${epochs.get(mailboxUid) ?? 0}`;
+}
+/** Forgets what a pass remembered for `mailboxUid` (its local index is destroyed). */
+export function forgetZeroAccessSync(mailboxUid) {
+    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() {
+    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) {
+    let stored;
+    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() {
+    const uids = [];
+    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/dist/apps/shared/zeroAccess/ProtectedMark.d.ts

@@ -0,0 +1,7 @@
+import React from "react";
+import { 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;
+}): React.JSX.Element | null;

package/dist/apps/shared/zeroAccess/ProtectedMark.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { isProtectedRecord } 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 }) {
+    if (!isProtectedRecord(record)) {
+        return null;
+    }
+    return (_jsx("span", { className: "ml-1 text-text-muted text-xs", role: "img", "aria-label": "Protected by zero-access encryption", title: "Protected by zero-access encryption", children: "\uD83D\uDD12" }));
+}

package/dist/apps/shared/zeroAccess/useKeysLocked.d.ts

@@ -0,0 +1,6 @@
+/**
+ * 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 declare function useKeysLocked(onLocked: (mailboxUid: string) => void): void;

package/dist/apps/shared/zeroAccess/useKeysLocked.js

@@ -0,0 +1,20 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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) {
+    const latest = useRef(onLocked);
+    latest.current = onLocked;
+    useEffect(() => subscribeKeySession(({ mailboxUid, state }) => {
+        if (state === "locked") {
+            latest.current(mailboxUid);
+        }
+    }), []);
+}

package/dist/apps/shared/zeroAccess/useOpenedRecord.d.ts

@@ -0,0 +1,18 @@
+import { type SealedRecord } from "../../../lib/zeroAccess/sealedRecords.js";
+/**
+ * `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 declare function useOpenedRecord<T extends SealedRecord>(record: T | undefined, open?: (record: T) => Promise<T>): {
+    record: T | undefined;
+    ready: boolean;
+};

package/dist/apps/shared/zeroAccess/useOpenedRecord.js

@@ -0,0 +1,66 @@
+///////////////////////////////////////////////////////////////////////////////
+// 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 } 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) {
+    return record?.uid;
+}
+/**
+ * `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(record, open = openSealedRecord) {
+    const [opened, setOpened] = useState(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/dist/apps/www/_shell.d.ts

@@ -23,4 +23,4 @@ export type WwwShellProps = PropsWithChildren<Omit<AppShellProps, "active">>;
  * app. Anything else - Mail's `/` and `/messages/:uid` - is Mail.
  */
 export declare function activeAppOf(route: string): AppShellActive;
-export default function WwwShell({ children, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, branding, appearance, }: WwwShellProps): React.JSX.Element;
+export default function WwwShell({ children, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, branding, appearance, signOutHost, }: WwwShellProps): React.JSX.Element;

package/dist/apps/www/_shell.js

@@ -16,7 +16,7 @@ export function activeAppOf(route) {
     const app = route.split("/")[1];
     return app === "calendar" || app === "contacts" || app === "tasks" || app === "settings" ? app : "mail";
 }
-export default function WwwShell({ children, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, branding, appearance, }) {
+export default function WwwShell({ children, userUid, authServerUrl, impersonating, impersonationBaseUrl, trusted, trustedRoles, pluginNav, branding, appearance, signOutHost, }) {
     const { route, pending } = useRouter();
     const [takeovers, setTakeovers] = useState(0);
     const enterTakeover = useCallback(() => {
@@ -27,5 +27,5 @@ export default function WwwShell({ children, userUid, authServerUrl, impersonati
     // The content region is what a page load would have started at: focus it (it is only focusable by script), start at the top, and say the
     // page's title - without the unread count that the tab's title carries in front of it.
     useNavigationEffects({ focus: "#app-content", scroll: "top", announce: ({ title }) => titleWithUnread(title, 0) });
-    return (_jsx(AppFrameContext.Provider, { value: frame, children: _jsx(AppChrome, { active: activeAppOf(route), busy: pending, hideChrome: takeovers > 0, userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, trustedRoles: trustedRoles, pluginNav: pluginNav, branding: branding, appearance: appearance, children: children }) }));
+    return (_jsx(AppFrameContext.Provider, { value: frame, children: _jsx(AppChrome, { active: activeAppOf(route), busy: pending, hideChrome: takeovers > 0, userUid: userUid, authServerUrl: authServerUrl, impersonating: impersonating, impersonationBaseUrl: impersonationBaseUrl, trusted: trusted, trustedRoles: trustedRoles, pluginNav: pluginNav, branding: branding, appearance: appearance, signOutHost: signOutHost, children: children }) }));
 }