@pmate/chat-sdk 0.12.0-next.3 → 0.12.0-next.30

package/lib/runtime/chatSession.js

@@ -1,3 +1,7 @@
+import { projectMessageTimeline } from "./messageTimeline.js";
+import { projectConversationReading } from "./conversationReading.js";
+import { ReadCountsClient } from "./readCounts.js";
+import { WindowedTasks } from "./coalescer.js";
 import { MessageReadersClient } from "./messageReaders.js";
 import { MessageClient } from "./messageClient.js";
 import { DurableChatSender } from "./durableSender.js";
@@ -11,15 +15,38 @@ export class ChatSession {
     connection;
     reading;
     readers;
+    counts;
+    countsReceiver;
+    countsThread;
+    countSnapshots = new Map();
+    countClosings = new Set();
+    countTasks;
     sender;
     listeners = new Map();
     snapshots = new Map();
+    timelineDecoded = new WeakMap();
+    decodeTimeline = (message) => { if (!this.timelineDecoded.has(message))
+        this.timelineDecoded.set(message, this.options.decode(message)); return this.timelineDecoded.get(message); };
+    historyEdges = new Map();
+    earlierReads = new Map();
     off = [];
     globalListeners = new Set();
     globalSnapshot;
+    closedThread = { messages: [], timeline: [], outgoing: [], hasEarlier: false, resetVersion: 0, complete: false, unread: undefined, messageReading: {} };
+    closedSummary = { threads: [], unreadMessageCount: undefined, badgeCount: undefined, connection: "closed" };
     connectionState = "closed";
+    catchUp;
+    readingAllowed = false;
+    readingListeners = new Set();
+    acceptedReading = new Set();
+    readingAccess;
+    readingStarted = false;
+    readingStarting;
+    withdrawn = false;
+    revoking;
     closed = false;
     starting;
+    initializing;
     closing;
     constructor(options) {
         this.options = options;
@@ -32,16 +59,44 @@ export class ChatSession {
                 throw new Error("CHAT_SESSION_SCOPE_MISMATCH");
         }
         this.messages = new MessageClient(options.messages);
-        this.connection = options.sharedConnection ?? new ChatClient(options.connection);
-        this.reading = new ReadingClient({ ...options.reading, storageScope: JSON.stringify([scope.accountId, scope.teamId]) });
-        this.readers = new MessageReadersClient({ appId: scope.appId, profileId: scope.profileId, token: options.reading.sessionToken, hubHttpUrl: options.reading.hubHttpUrl, fetch: options.reading.fetch });
-        this.sender = new DurableChatSender(this.connection, scope, options.onError);
-        this.off.push(this.sender.subscribe(() => this.publishAll()), this.reading.subscribe(() => this.publishAll()));
+        this.connection = options.sharedConnection ?? new ChatClient({ ...options.connection, onReach: async (event) => {
+                const handled = await this.handleReach(event);
+                if (handled)
+                    return handled;
+                if (options.connection.onReach)
+                    return options.connection.onReach(event);
+                throw new Error("REACH_HANDLER_UNAVAILABLE");
+            } });
+        this.reading = new ReadingClient({ ...options.reading, teamId: scope.teamId, storageScope: JSON.stringify([scope.accountId]), migrateLegacy: true });
+        this.readers = new MessageReadersClient({ appId: scope.appId, profileId: scope.profileId, token: options.reading.sessionToken, scope, access: () => this.messages.scopeAccess(), onError: options.onError, hubHttpUrl: options.reading.hubHttpUrl, fetch: options.reading.fetch });
+        this.sender = new DurableChatSender(this.connection, scope, options.onError, { access: () => this.messages.scopeAccess() });
+        this.catchUp = new WindowedTasks(1000, error => { if (!this.closed)
+            options.onError(error); });
+        this.countTasks = new WindowedTasks(50, error => { if (!this.closed)
+            options.onError(error); });
+        if (typeof window !== "undefined") {
+            const wake = () => this.wakeCounts();
+            window.addEventListener("online", wake);
+            window.addEventListener("focus", wake);
+            this.off.push(() => { window.removeEventListener("online", wake); window.removeEventListener("focus", wake); });
+        }
+        this.off.push(this.messages.subscribeAccessRevoked(() => { if (!this.withdrawn && !this.closed)
+            void this.revokeAccess().catch(error => options.onError(error)); }));
+        this.off.push(this.messages.subscribeAll(thread => this.publish(thread)));
+        this.off.push(this.sender.subscribe(() => this.publishAll()), this.reading.subscribe(() => { this.publishAll(); if (this.readingAllowed)
+            this.readingListeners.forEach(listener => listener()); }));
         this.off.push(this.connection.watchMessages(message => {
             try {
                 const decoded = options.decode(message);
                 if (decoded)
-                    void this.messages.receive(decoded.threadId, [decoded]).then(() => { this.publish(decoded.threadId); return this.sender.confirm([message.hash]); }).catch(options.onError);
+                    void this.messages.receive(decoded.threadId, [decoded]).then(async () => {
+                        if (!this.closed && this.readingStarted)
+                            this.reading.refresh();
+                        await this.sender.confirm([message.hash]);
+                    }).catch(error => { if (String(error).includes("MESSAGE_PROJECTION_CHANGED"))
+                        this.messages.invalidate(decoded.threadId);
+                    else if (!this.closed)
+                        options.onError(error); });
             }
             catch (error) {
                 options.onError(error);
@@ -51,44 +106,326 @@ export class ChatSession {
             this.connectionState = state;
             this.publishGlobal();
             if (state === "connected") {
-                for (const thread of this.listeners.keys())
-                    this.messages.invalidate(thread);
-                this.reading.refresh();
+                const since = Date.now();
+                this.catchUp.schedule("scope", async () => { if (this.connectionState === "connected" && !this.closed && !this.withdrawn)
+                    await this.messages.restore(since, options.activeThreadId); });
+                if (this.readingStarted)
+                    this.reading.refresh();
+                this.wakeCounts();
             }
         }));
     }
     start() {
         this.assertOpen();
         return this.starting ??= (async () => {
-            await this.sender.initialize();
-            await this.reading.start();
+            await this.initialize();
             this.assertOpen();
             await this.connection.connect();
         })().catch(error => { this.starting = undefined; throw error; });
     }
-    assertOpen() { if (this.closed)
+    /** Initializes local state and background reading sync without opening a
+     * second transport when the host already owns calls/presence. */
+    initialize() {
+        this.assertOpen();
+        return this.initializing ??= (async () => {
+            await this.sender.initialize();
+            this.assertOpen();
+            await this.startReading();
+            this.assertOpen();
+        })().catch(error => { this.initializing = undefined; throw error; });
+    }
+    startReading() {
+        if (this.readingStarted)
+            return Promise.resolve();
+        return this.readingStarting ??= (async () => {
+            const access = await this.messages.scopeAccess();
+            if (!access.allowed)
+                return;
+            this.assertOpen();
+            await this.reading.prepareTeam(this.options.messages.scope.teamId, access.version);
+            this.setReadingAllowed(true);
+            await this.reading.start();
+            this.assertOpen();
+            this.readingStarted = true;
+        })().finally(() => { this.readingStarting = undefined; });
+    }
+    /** One-time migration only: never establishes trusted history coverage. */
+    importLegacyMessages(threadId, messages) { this.assertOpen(); return this.messages.importLegacy(threadId, messages); }
+    getReadingSnapshot() { return this.closed || this.withdrawn || !this.readingAllowed ? undefined : this.reading.getSnapshot(); }
+    subscribeReading(listener) { if (this.closed || this.withdrawn)
+        return () => { }; this.readingListeners.add(listener); return () => { this.readingListeners.delete(listener); }; }
+    setReadingAllowed(allowed) {
+        if (this.readingAllowed === allowed)
+            return;
+        const previous = this.getReadingSnapshot();
+        this.readingAllowed = allowed;
+        if (previous !== this.getReadingSnapshot())
+            this.readingListeners.forEach(listener => listener());
+        this.publishAll();
+    }
+    readingAuthority() {
+        return this.readingAccess ??= this.messages.scopeAccess().then(access => { if (!access.allowed)
+            this.setReadingAllowed(false); return access; }).finally(() => { this.readingAccess = undefined; });
+    }
+    async authorizeReading() {
+        const access = await this.readingAuthority();
+        if (this.withdrawn || !access.allowed)
+            throw new Error("CHAT_ACCESS_REVOKED");
+        await this.reading.prepareTeam(this.options.messages.scope.teamId, access.version);
+        this.setReadingAllowed(true);
+    }
+    readingOperation(run, durable = true) {
+        if (this.closed || this.withdrawn)
+            return Promise.reject(new Error(this.withdrawn ? "CHAT_ACCESS_REVOKED" : "CHAT_SESSION_CLOSED"));
+        const task = (async () => {
+            await this.authorizeReading();
+            if (this.withdrawn)
+                throw new Error("CHAT_ACCESS_REVOKED");
+            if (!durable)
+                this.assertOpen();
+            const next = await run();
+            if (this.withdrawn || !(await this.readingAuthority()).allowed)
+                throw new Error("CHAT_ACCESS_REVOKED");
+            return next;
+        })();
+        if (durable) {
+            this.acceptedReading.add(task);
+            void task.finally(() => this.acceptedReading.delete(task)).catch(() => { });
+        }
+        return task;
+    }
+    refreshReading() {
+        if (this.closed || this.withdrawn)
+            return;
+        void this.authorizeReading().then(() => { if (!this.closed && !this.withdrawn)
+            this.reading.refresh(); }).catch(error => { if (!this.closed && !this.withdrawn)
+            this.options.onError(error); });
+    }
+    synchronizeReading(cursor, profileId) { return this.readingOperation(() => this.reading.synchronize(cursor, profileId), false); }
+    /** Explicit text-history acknowledgement; unheard audio stays unread. */
+    markRead(threadId, messages = []) { return this.readingOperation(() => this.reading.markRead(threadId, messages)); }
+    updateReading(transform) { return this.readingOperation(() => this.reading.update(transform)); }
+    assertOpen() { if (this.withdrawn)
+        throw new Error("CHAT_ACCESS_REVOKED"); if (this.closed)
         throw new Error("CHAT_SESSION_CLOSED"); }
     async getMessages(threadId, options = {}) {
         this.assertOpen();
+        if (options.earlier) {
+            if (options.before || options.all || options.limit !== undefined || options.refresh)
+                throw new Error("INVALID_MESSAGE_QUERY");
+            return this.readEarlier(threadId);
+        }
+        if (options.all && (options.before || options.limit !== undefined))
+            throw new Error("INVALID_MESSAGE_QUERY");
+        // Explicit authoritative changes (for example history assignment) can invalidate
+        // even a recently cached empty window. Keep this on the existing read surface.
+        if (options.refresh)
+            await this.messages.read(threadId, options.limit ?? 100, true);
+        if (options.all) {
+            return this.readAll(threadId);
+        }
         const page = await (options.before ? this.messages.earlier(threadId, options.before, options.limit) : this.messages.read(threadId, options.limit));
-        if (!options.before)
-            this.publish(threadId);
+        this.assertOpen();
+        await this.sender.confirm(page.messages.map(message => message.id));
+        if (this.initializing && !this.readingStarted && page.complete)
+            await this.startReading();
+        this.assertOpen();
+        const edge = this.historyEdges.get(threadId);
+        if (!options.before && page.complete && (!edge || edge.version !== page.resetVersion))
+            this.rememberHistoryEdge(threadId, page);
         return page;
     }
+    rememberHistoryEdge(threadId, page) {
+        const first = page.messages[0];
+        this.historyEdges.set(threadId, { before: first ? { timestamp: first.timestamp, id: first.id } : undefined, version: page.resetVersion, hasEarlier: page.hasEarlier });
+    }
+    readEarlier(threadId) {
+        const running = this.earlierReads.get(threadId);
+        if (running)
+            return running;
+        const task = (async () => {
+            const recent = await this.getMessages(threadId);
+            if (!recent.complete)
+                throw new Error("MESSAGE_WINDOW_INCOMPLETE");
+            const edge = this.historyEdges.get(threadId);
+            if (!edge.hasEarlier)
+                return { ...recent, messages: [], hasEarlier: false };
+            if (!edge.before)
+                throw new Error("MESSAGE_SYNC_NO_PROGRESS");
+            const page = await this.getMessages(threadId, { before: edge.before });
+            this.assertOpen();
+            this.rememberHistoryEdge(threadId, page);
+            return page;
+        })().finally(() => { if (this.earlierReads.get(threadId) === task)
+            this.earlierReads.delete(threadId); });
+        this.earlierReads.set(threadId, task);
+        return task;
+    }
+    async readAll(threadId) {
+        for (let attempt = 0; attempt < 3; attempt++) {
+            const pages = [];
+            let version = 0;
+            try {
+                let page = await this.getMessages(threadId);
+                version = page.resetVersion;
+                pages.push(page.messages);
+                if (!page.complete)
+                    return { ...page, hasEarlier: true };
+                let restart = false;
+                while (page.hasEarlier) {
+                    const first = page.messages[0];
+                    if (!first)
+                        throw new Error("MESSAGE_SYNC_NO_PROGRESS");
+                    page = await this.getMessages(threadId, { before: { timestamp: first.timestamp, id: first.id } });
+                    if (page.resetVersion !== version) {
+                        restart = true;
+                        break;
+                    }
+                    pages.push(page.messages);
+                    if (!page.complete)
+                        return { messages: pages.reverse().flat(), hasEarlier: true, complete: false, resetVersion: version };
+                }
+                if (restart)
+                    continue;
+                return { messages: pages.reverse().flat(), hasEarlier: false, complete: true, resetVersion: version };
+            }
+            catch (error) {
+                this.assertOpen();
+                if ([401, 403].includes(error?.status ?? 0))
+                    throw error;
+                if (String(error).includes("MESSAGE_PROJECTION_CHANGED"))
+                    continue;
+                if (pages.length)
+                    return { messages: pages.reverse().flat(), hasEarlier: true, complete: false, resetVersion: version };
+                throw error;
+            }
+        }
+        throw new Error("MESSAGE_SYNC_RESET_REQUIRED");
+    }
     sendMessage(threadId, input) {
         this.assertOpen();
-        return this.sender.enqueue(threadId, input);
+        return this.sender.enqueue(threadId, input).then(next => { if (this.withdrawn)
+            throw new Error("CHAT_ACCESS_REVOKED"); return next; });
     }
-    getReaders(threadId, messageId, page = {}, signal) {
+    async getReaders(threadId, messageId, page = {}, signal) {
         this.assertOpen();
-        return this.readers.getReaders({ ...page, threadId, messageId }, signal);
+        const result = await this.readers.getReaders({ ...page, threadId, messageId }, signal);
+        this.assertOpen();
+        if (!result.resetRequired) {
+            const previous = this.countSnapshots.get(threadId);
+            if (!previous || previous.revision <= result.revision) {
+                this.publishCounts({ appId: result.appId, threadId, revision: result.revision, counts: { ...previous?.counts, [messageId]: result.total } });
+                this.counts?.changed(threadId, result.revision);
+            }
+        }
+        return result;
     }
     retryMessage(messageId) { this.assertOpen(); return this.sender.retry(messageId); }
-    observeMessages(threadId, ids, event) {
+    observeMessages(threadId, ids, event, clientInstanceId) {
+        if (this.closed || this.withdrawn) {
+            if (event === "receipts" && !threadId)
+                return Promise.resolve();
+            return Promise.reject(new Error(this.withdrawn ? "CHAT_ACCESS_REVOKED" : "CHAT_SESSION_CLOSED"));
+        }
+        if (event === "receipts") {
+            this.watchCounts(threadId, ids, clientInstanceId);
+            return Promise.resolve();
+        }
+        if (!threadId)
+            throw new Error("INVALID_READING_THREAD");
+        return this.readingOperation(() => event === "played" ? this.reading.recordExplicit(threadId, ids) : this.reading.recordVisible(threadId, ids));
+    }
+    /** Bridge transports can delegate social events without maintaining clients. */
+    async handleReach(event) {
         this.assertOpen();
-        return event === "played" ? this.reading.recordExplicit(threadId, ids) : this.reading.recordVisible(threadId, ids);
+        if (!["social.readCountsChanged", "social.readStateChanged"].includes(event.eventType))
+            return undefined;
+        if (event.appId !== this.options.messages.scope.appId)
+            throw new Error("UNEXPECTED_READING_APPLICATION");
+        if (event.eventType === "social.readCountsChanged") {
+            if (typeof event.payload.threadId !== "string" || !Number.isSafeInteger(event.payload.revision) || Number(event.payload.revision) < 0)
+                throw new Error("INVALID_READ_COUNTS_EVENT");
+            this.counts?.changed(event.payload.threadId, Number(event.payload.revision));
+        }
+        else {
+            if (typeof event.payload.syncCursor !== "string" || !/^v1:\d+$/.test(event.payload.syncCursor) || typeof event.payload.profileId !== "string")
+                throw new Error("INVALID_READING_EVENT");
+            if (event.payload.profileId !== this.options.messages.scope.profileId)
+                throw new Error("Reading reach identity mismatch");
+            await this.initialize();
+            await this.synchronizeReading(event.payload.syncCursor, event.payload.profileId);
+            this.assertOpen();
+        }
+        return "handled";
+    }
+    wakeCounts() {
+        if (this.counts && this.countsThread && !this.closed)
+            this.countTasks.schedule("counts", async () => { this.counts?.reconnect(); });
+    }
+    publishCountSnapshot(thread) {
+        const previous = this.snapshots.get(thread);
+        if (!previous) {
+            this.publish(thread, false);
+            return;
+        }
+        // Receipt-only updates never serialize or rebuild message bodies.
+        this.snapshots.set(thread, { ...previous, readCounts: this.countSnapshots.get(thread) });
+        this.listeners.get(thread)?.forEach(listener => listener());
+    }
+    publishCounts(value) {
+        if (this.closed || this.withdrawn)
+            return;
+        const previous = this.countSnapshots.get(value.threadId);
+        if ((previous && previous.revision > value.revision) || JSON.stringify(previous) === JSON.stringify(value))
+            return;
+        this.countSnapshots.delete(value.threadId);
+        this.countSnapshots.set(value.threadId, value);
+        if (this.countSnapshots.size > 128) {
+            const oldest = this.countSnapshots.keys().next().value;
+            this.countSnapshots.delete(oldest);
+            this.publishCountSnapshot(oldest);
+        }
+        this.publishCountSnapshot(value.threadId);
+    }
+    watchCounts(threadId, ids, receiver = this.connection.identityScope().clientInstanceId) {
+        if (!threadId || !ids.length) {
+            this.countsThread = undefined;
+            this.counts?.watch(undefined, []);
+            return;
+        }
+        if (!receiver || receiver.length > 512 || /[\x00-\x1f]/.test(receiver))
+            throw new Error("INVALID_READ_COUNTS_RECEIVER");
+        if (!this.counts || this.countsReceiver !== receiver) {
+            if (this.counts) {
+                const closing = this.counts.close().finally(() => this.countClosings.delete(closing));
+                this.countClosings.add(closing);
+            }
+            const scope = this.options.messages.scope;
+            const client = new ReadCountsClient({ appId: scope.appId, profileId: scope.profileId, scope, access: () => this.messages.scopeAccess(), token: this.options.reading.sessionToken, clientInstanceId: receiver, hubHttpUrl: this.options.reading.hubHttpUrl, fetch: this.options.reading.fetch,
+                onChange: value => { if (!this.closed && this.counts === client)
+                    this.publishCounts(value); },
+                onError: error => {
+                    if (this.closed || this.counts !== client)
+                        return;
+                    if (/READ_COUNTS_HTTP_(401|403)|RESPONSE_CACHE_(ACCESS_REVOKED|SCOPE_CHANGED|INVALIDATED)/.test(String(error))) {
+                        const threads = [...this.countSnapshots.keys()];
+                        this.countSnapshots.clear();
+                        threads.forEach(thread => this.publishCountSnapshot(thread));
+                    }
+                    this.options.onError(error);
+                } });
+            this.counts = client;
+            this.countsReceiver = receiver;
+        }
+        this.countsThread = threadId;
+        this.counts.watch(threadId, ids);
     }
     getSnapshot(threadId) {
+        if (this.closed || this.withdrawn) {
+            if (threadId === undefined)
+                return this.closedSummary;
+            return this.closedThread;
+        }
         if (threadId === undefined) {
             if (!this.globalSnapshot)
                 this.globalSnapshot = this.buildGlobal();
@@ -96,28 +433,51 @@ export class ChatSession {
         }
         let snapshot = this.snapshots.get(threadId);
         if (!snapshot) {
-            const messages = this.messages.getSnapshot(threadId);
-            const state = this.reading.getSnapshot();
-            snapshot = { messages: messages?.messages ?? [], hasEarlier: messages?.hasEarlier ?? false, outgoing: this.sender.snapshot(threadId), unread: state?.threads.some(thread => (thread.conversationId ?? thread.id) === threadId) ? unreadInConversation(state, threadId) : { unreadMessageCount: 0, unreadMentionCount: 0, badgeCount: 0 } };
+            snapshot = this.buildThreadSnapshot(threadId);
             this.snapshots.set(threadId, snapshot);
         }
         return snapshot;
     }
-    subscribe(target, listener) {
-        this.assertOpen();
+    buildThreadSnapshot(threadId, previous) {
+        const messages = this.messages.getSnapshot(threadId);
+        const state = this.getReadingSnapshot();
+        const candidates = messages?.messages.flatMap(message => { const candidate = this.options.readingCandidate?.(message); return candidate ? [candidate] : []; }) ?? [];
+        const sources = state?.threads.filter(thread => (thread.conversationId ?? thread.id) === threadId) ?? [];
+        const kind = sources[0]?.kind ?? "dm";
+        const view = projectConversationReading(state, { id: threadId, kind }, candidates);
+        const unread = previous && JSON.stringify(previous.unread) === JSON.stringify(view.unread) ? previous.unread : view.unread;
+        const messageReading = previous && JSON.stringify(previous.messageReading) === JSON.stringify(view.messageReading) ? previous.messageReading : view.messageReading;
+        const raw = messages?.messages ?? [];
+        const stableMessages = previous && previous.messages.length === raw.length && previous.messages.every((message, index) => message === raw[index]) ? previous.messages : raw;
+        const outgoing = this.sender.snapshot(threadId);
+        const timeline = projectMessageTimeline({ appId: this.options.messages.scope.appId, profileId: this.options.messages.scope.profileId, threadId, messages: stableMessages, outgoing, decode: this.decodeTimeline, reading: messageReading, previous: previous?.timeline });
+        return { timeline, messages: stableMessages, hasEarlier: messages?.hasEarlier ?? false, resetVersion: messages?.resetVersion ?? 0, complete: messages?.complete ?? false, outgoing, readCounts: this.countSnapshots.get(threadId), unread, messageReading };
+    }
+    subscribe(target, listener, fields) {
+        if (this.closed || this.withdrawn)
+            return () => { };
         if (typeof target === "function") {
             this.globalListeners.add(target);
             return () => { this.globalListeners.delete(target); };
         }
         const threadId = target;
-        const notify = listener;
+        const selected = fields ? [...fields] : undefined;
+        let values = selected?.map(field => this.getSnapshot(threadId)[field]);
+        const equal = (a, b) => a === b || (Array.isArray(a) && Array.isArray(b) && a.length === b.length && a.every((value, index) => value === b[index]));
+        const notify = selected ? () => {
+            const next = selected.map(field => this.getSnapshot(threadId)[field]);
+            const changed = next.some((value, index) => !equal(value, values[index]));
+            values = next;
+            if (changed)
+                listener();
+        } : listener;
         let listeners = this.listeners.get(threadId);
         if (!listeners) {
             listeners = new Set();
             this.listeners.set(threadId, listeners);
         }
         listeners.add(notify);
-        const off = this.messages.subscribe(threadId, () => this.publish(threadId));
+        const off = this.messages.subscribe(threadId, () => { });
         return () => {
             off();
             listeners.delete(notify);
@@ -126,26 +486,36 @@ export class ChatSession {
         };
     }
     publishAll() {
+        if (this.closed || this.withdrawn)
+            return;
         for (const threadId of [...this.snapshots.keys()])
             this.publish(threadId, false);
         this.publishGlobal();
     }
     buildGlobal() {
         const ids = new Set(this.snapshots.keys());
-        for (const thread of this.reading.getSnapshot()?.threads ?? [])
+        for (const thread of this.getReadingSnapshot()?.threads ?? [])
             if (thread.teamId === this.options.messages.scope.teamId)
                 ids.add(thread.conversationId ?? thread.id);
         for (const outgoing of this.sender.snapshot())
             ids.add(outgoing.threadId);
         const threads = [...ids].sort().map(threadId => {
             const snapshot = this.getSnapshot(threadId);
-            return { threadId, lastMessage: snapshot.messages.at(-1), unread: snapshot.unread, outgoingCount: snapshot.outgoing.length };
+            return { threadId, lastMessage: snapshot.timeline.at(-1)?.message, lastItem: snapshot.timeline.at(-1), unread: snapshot.unread, outgoingCount: snapshot.outgoing.length };
         });
-        return { threads, unreadMessageCount: threads.reduce((sum, t) => sum + t.unread.unreadMessageCount, 0), badgeCount: threads.reduce((sum, t) => sum + t.unread.badgeCount, 0), connection: this.connectionState };
+        const state = this.getReadingSnapshot();
+        const known = Boolean(state && state.syncCursor !== "0" && threads.every(thread => thread.unread !== undefined));
+        return { threads, unreadMessageCount: known ? threads.reduce((sum, t) => sum + (t.unread?.unreadMessageCount ?? 0), 0) : undefined, badgeCount: known ? threads.reduce((sum, t) => sum + (t.unread?.badgeCount ?? 0), 0) : undefined, connection: this.connectionState };
     }
     publishGlobal() {
+        if (this.closed || this.withdrawn)
+            return;
         const next = this.buildGlobal();
-        if (JSON.stringify(next) === JSON.stringify(this.globalSnapshot))
+        const previous = this.globalSnapshot;
+        if (previous && previous.connection === next.connection && previous.unreadMessageCount === next.unreadMessageCount && previous.badgeCount === next.badgeCount && previous.threads.length === next.threads.length && previous.threads.every((thread, index) => {
+            const other = next.threads[index];
+            return thread.threadId === other.threadId && thread.lastMessage === other.lastMessage && thread.lastItem === other.lastItem && thread.outgoingCount === other.outgoingCount && JSON.stringify(thread.unread) === JSON.stringify(other.unread);
+        }))
             return;
         this.globalSnapshot = next;
         this.globalListeners.forEach(listener => listener());
@@ -153,8 +523,9 @@ export class ChatSession {
     publish(threadId, notifyGlobal = true) {
         const previous = this.snapshots.get(threadId);
         this.snapshots.delete(threadId);
-        const next = this.getSnapshot(threadId);
-        if (previous && JSON.stringify(previous) === JSON.stringify(next)) {
+        const next = this.buildThreadSnapshot(threadId, previous);
+        this.snapshots.set(threadId, next);
+        if (previous && previous.messages === next.messages && previous.timeline === next.timeline && previous.outgoing.length === next.outgoing.length && previous.outgoing.every((record, index) => record === next.outgoing[index]) && previous.hasEarlier === next.hasEarlier && previous.resetVersion === next.resetVersion && previous.complete === next.complete && previous.readCounts === next.readCounts && JSON.stringify(previous.unread) === JSON.stringify(next.unread) && JSON.stringify(previous.messageReading) === JSON.stringify(next.messageReading)) {
             this.snapshots.set(threadId, previous);
             return;
         }
@@ -162,18 +533,96 @@ export class ChatSession {
         if (notifyGlobal)
             this.publishGlobal();
     }
-    close() {
+    /** Permanently retire this identity/team session. UI withdrawal is immediate;
+     * completion means all durable stores have crossed the same authority epoch. */
+    revokeAccess() {
+        if (this.revoking)
+            return this.revoking;
+        if (this.closed)
+            return Promise.reject(new Error("CHAT_SESSION_CLOSED"));
+        this.withdrawn = true;
+        const knownThreads = [...new Set([...this.snapshots.keys(), ...this.historyEdges.keys()])];
+        this.catchUp.close();
+        this.countTasks.close();
+        this.off.splice(0).forEach(off => off());
+        this.sender.withdraw();
+        this.reading.withdraw();
+        this.readers.withdraw();
+        this.counts?.watch(undefined, []);
+        this.countSnapshots.clear();
+        this.snapshots.clear();
+        this.timelineDecoded = new WeakMap();
+        this.historyEdges.clear();
+        this.earlierReads.clear();
+        this.globalSnapshot = undefined;
+        this.listeners.forEach(listeners => listeners.forEach(listener => listener()));
+        this.globalListeners.forEach(listener => listener());
+        this.readingListeners.forEach(listener => listener());
+        if (!this.options.sharedConnection)
+            this.connection.close();
+        return this.revoking = Promise.resolve().then(async () => {
+            const failures = [];
+            let version;
+            try {
+                version = await this.messages.revokeScope();
+            }
+            catch (error) {
+                failures.push(error);
+                version = 1;
+                try {
+                    version = Math.max(1, (await this.messages.scopeAccess()).version);
+                }
+                catch (failure) {
+                    failures.push(failure);
+                }
+            }
+            const results = await Promise.allSettled([
+                this.sender.revoke(version),
+                this.reading.revokeTeam(this.options.messages.scope.teamId, version, knownThreads),
+                this.readers.retireScope(version), this.counts?.retireScope(version),
+            ]);
+            for (const result of results)
+                if (result.status === "rejected")
+                    failures.push(result.reason);
+            try {
+                await this.dispose();
+            }
+            catch (error) {
+                failures.push(error);
+            }
+            if (failures.length)
+                throw new AggregateError(failures, "CHAT_ACCESS_CLEANUP_FAILED");
+        });
+    }
+    close() { return this.revoking ?? this.dispose(); }
+    dispose() {
         return this.closing ??= (async () => {
             this.closed = true;
+            this.catchUp.close();
+            this.countTasks.close();
             this.off.splice(0).forEach(off => off());
             if (!this.options.sharedConnection)
                 this.connection.close();
-            this.readers.close();
-            await Promise.all([this.sender.close(), this.reading.close(), this.messages.close()]);
-            this.listeners.clear();
-            this.globalListeners.clear();
-            this.snapshots.clear();
-            this.globalSnapshot = undefined;
+            const senderClosing = this.sender.close();
+            const readingBarrier = Promise.allSettled([...this.acceptedReading]);
+            const readingClosing = readingBarrier.then(() => this.reading.close());
+            try {
+                const results = await Promise.allSettled([this.counts?.close(), ...this.countClosings, this.readers.close(), senderClosing, readingClosing, this.messages.close(Promise.allSettled([senderClosing, readingBarrier]))]);
+                const failed = results.find((result) => result.status === "rejected");
+                if (failed)
+                    throw failed.reason;
+            }
+            finally {
+                this.listeners.clear();
+                this.globalListeners.clear();
+                this.readingListeners.clear();
+                this.snapshots.clear();
+                this.timelineDecoded = new WeakMap();
+                this.countSnapshots.clear();
+                this.historyEdges.clear();
+                this.earlierReads.clear();
+                this.globalSnapshot = undefined;
+            }
         })();
     }
 }

package/lib/runtime/connectivity.d.ts

@@ -0,0 +1,4 @@
+/** Browser connectivity is advisory: only suppress network errors while the
+ * browser explicitly reports offline. Permission and data errors stay visible. */
+export declare function isOffline(): boolean;
+export declare function isOfflineNetworkFailure(error: unknown): boolean;

package/lib/runtime/connectivity.js

@@ -0,0 +1,8 @@
+/** Browser connectivity is advisory: only suppress network errors while the
+ * browser explicitly reports offline. Permission and data errors stay visible. */
+export function isOffline() {
+    return typeof navigator !== "undefined" && navigator.onLine === false;
+}
+export function isOfflineNetworkFailure(error) {
+    return isOffline() && (error instanceof TypeError || error?.name === "AbortError");
+}