@pmate/chat-sdk 0.12.0-next.2 → 0.12.0-next.21

package/lib/runtime/chatSession.js

@@ -1,3 +1,5 @@
+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,102 +13,432 @@ export class ChatSession {
     connection;
     reading;
     readers;
+    counts;
+    countsReceiver;
+    countsThread;
+    countSnapshots = new Map();
+    countClosings = new Set();
+    countTasks;
     sender;
     listeners = new Map();
     snapshots = new Map();
+    historyEdges = new Map();
+    earlierReads = new Map();
     off = [];
+    globalListeners = new Set();
+    globalSnapshot;
+    closedThread = { messages: [], outgoing: [], hasEarlier: false, resetVersion: 0, complete: false, unread: undefined };
+    closedSummary = { threads: [], unreadMessageCount: undefined, badgeCount: undefined, connection: "closed" };
+    connectionState = "closed";
+    catchUp;
+    readingStarted = false;
+    readingStarting;
+    withdrawn = false;
+    revoking;
     closed = false;
     starting;
+    initializing;
     closing;
     constructor(options) {
         this.options = options;
         const scope = options.messages.scope;
         if (options.connection.appId !== scope.appId || options.reading.appId !== scope.appId || options.reading.profileId !== scope.profileId || options.connection.profileId !== scope.profileId || options.connection.teamId !== scope.teamId)
             throw new Error("CHAT_SESSION_SCOPE_MISMATCH");
+        if (options.sharedConnection) {
+            const shared = options.sharedConnection.identityScope();
+            if (shared.appId !== scope.appId || shared.profileId !== scope.profileId || (shared.accountId !== undefined && shared.accountId !== scope.accountId) || (shared.teamId !== undefined && shared.teamId !== scope.teamId))
+                throw new Error("CHAT_SESSION_SCOPE_MISMATCH");
+        }
         this.messages = new MessageClient(options.messages);
-        this.connection = new ChatClient(options.connection);
-        this.reading = new ReadingClient(options.reading);
-        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.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, 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()));
         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);
             }
         }));
         this.off.push(this.connection.watchConnection(state => {
+            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", () => 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);
+            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 ? undefined : this.reading.getSnapshot(); }
+    subscribeReading(listener) { this.assertOpen(); return this.reading.subscribe(listener); }
+    refreshReading() { this.assertOpen(); this.reading.refresh(); }
+    synchronizeReading(cursor, profileId) { this.assertOpen(); return this.reading.synchronize(cursor, profileId); }
+    /** Explicit text-history acknowledgement; unheard audio stays unread. */
+    markRead(threadId, messages = []) { this.assertOpen(); return this.reading.markRead(threadId, messages); }
+    updateReading(transform) { this.assertOpen(); return 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();
+        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) {
+                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);
     }
-    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 && event === "receipts" && !threadId)
+            return Promise.resolve();
         this.assertOpen();
+        if (event === "receipts") {
+            this.watchCounts(threadId, ids, clientInstanceId);
+            return Promise.resolve();
+        }
+        if (!threadId)
+            throw new Error("INVALID_READING_THREAD");
         return 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();
+        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.reading.synchronize(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();
+            return this.globalSnapshot;
+        }
         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 = { messages: messages?.messages ?? [], hasEarlier: messages?.hasEarlier ?? false, resetVersion: messages?.resetVersion ?? 0, complete: messages?.complete ?? false, outgoing: this.sender.snapshot(threadId), readCounts: this.countSnapshots.get(threadId), unread: state?.threads.some(thread => (thread.conversationId ?? thread.id) === threadId) ? unreadInConversation(state, threadId) : undefined };
             this.snapshots.set(threadId, snapshot);
         }
         return snapshot;
     }
-    subscribe(threadId, listener) {
+    subscribe(target, listener, fields) {
         this.assertOpen();
+        if (typeof target === "function") {
+            this.globalListeners.add(target);
+            return () => { this.globalListeners.delete(target); };
+        }
+        const threadId = target;
+        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(listener);
-        const off = this.messages.subscribe(threadId, () => this.publish(threadId));
+        listeners.add(notify);
+        const off = this.messages.subscribe(threadId, () => { });
         return () => {
             off();
-            listeners.delete(listener);
+            listeners.delete(notify);
             if (!listeners.size)
                 this.listeners.delete(threadId);
         };
     }
-    publishAll() { for (const threadId of [...this.snapshots.keys()])
-        this.publish(threadId); }
-    publish(threadId) {
+    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 ?? [])
+            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 };
+        });
+        const state = this.reading.getSnapshot();
+        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))
+            return;
+        this.globalSnapshot = next;
+        this.globalListeners.forEach(listener => listener());
+    }
+    publish(threadId, notifyGlobal = true) {
         const previous = this.snapshots.get(threadId);
         this.snapshots.delete(threadId);
         const next = this.getSnapshot(threadId);
@@ -115,16 +447,93 @@ export class ChatSession {
             return;
         }
         this.listeners.get(threadId)?.forEach(listener => listener());
+        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.historyEdges.clear();
+        this.earlierReads.clear();
+        this.globalSnapshot = undefined;
+        this.listeners.forEach(listeners => listeners.forEach(listener => listener()));
+        this.globalListeners.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());
-            this.connection.close();
-            this.readers.close();
-            await Promise.all([this.sender.close(), this.reading.close(), this.messages.close()]);
-            this.listeners.clear();
-            this.snapshots.clear();
+            if (!this.options.sharedConnection)
+                this.connection.close();
+            const senderClosing = this.sender.close();
+            try {
+                const results = await Promise.allSettled([this.counts?.close(), ...this.countClosings, this.readers.close(), senderClosing, this.reading.close(), this.messages.close(senderClosing)]);
+                const failed = results.find((result) => result.status === "rejected");
+                if (failed)
+                    throw failed.reason;
+            }
+            finally {
+                this.listeners.clear();
+                this.globalListeners.clear();
+                this.snapshots.clear();
+                this.countSnapshots.clear();
+                this.historyEdges.clear();
+                this.earlierReads.clear();
+                this.globalSnapshot = undefined;
+            }
         })();
     }
 }

package/lib/runtime/conversationRead.d.ts

@@ -0,0 +1,13 @@
+import { type ReadIndexState } from "./readIndex.js";
+/** Optional observations whose index metadata may still be in flight. */
+export type ConversationReadMessage = {
+    id: string;
+    threadId: string;
+    mine?: boolean;
+    from?: string;
+    recalled?: boolean;
+    readPolicy?: "visible" | "explicit";
+    kind?: string;
+};
+/** Explicitly mark ordinary text history read; unheard audio stays unread. */
+export declare function recordConversationRead(state: ReadIndexState, conversationId: string, messages?: readonly ConversationReadMessage[], operationId?: () => `${string}-${string}-${string}-${string}-${string}`): ReadIndexState;

package/lib/runtime/conversationRead.js

@@ -0,0 +1,34 @@
+import { recordReadIntent, sourcesInConversation } from "./readIndex.js";
+/** Explicitly mark ordinary text history read; unheard audio stays unread. */
+export function recordConversationRead(state, conversationId, messages = [], operationId = () => crypto.randomUUID()) {
+    if (!conversationId)
+        throw new Error("INVALID_READING_THREAD");
+    const sources = sourcesInConversation(state, conversationId);
+    if (new Set(sources.map(source => source.teamId)).size > 1)
+        throw new Error("READ_CONVERSATION_TEAM_MISMATCH");
+    let next = state;
+    const indexedIds = new Set();
+    for (const source of sources) {
+        const incoming = source.messages.filter(message => {
+            indexedIds.add(message.id);
+            return !message.recalled && message.from !== state.profileId && message.recipients.includes(state.profileId);
+        });
+        const latest = incoming.filter(message => message.readPolicy === "visible" && message.seq > source.readThroughSeq)
+            .reduce((last, message) => !last || message.seq > last.seq ? message : last, undefined);
+        if (latest)
+            next = recordReadIntent(next, { operationId: operationId(), threadId: source.id, messageId: latest.id, readPolicy: "visible" });
+    }
+    // Live/history messages can precede their read-index metadata. Persist their
+    // observations so leaving the page or reloading cannot resurrect the badge.
+    const observed = new Set(next.observedReadIntents?.filter(intent => intent.threadId === conversationId).map(intent => intent.messageId));
+    for (const message of messages) {
+        if (message.threadId !== conversationId || message.mine || message.from === state.profileId || message.recalled || indexedIds.has(message.id) || observed.has(message.id))
+            continue;
+        const readPolicy = message.readPolicy ?? (message.kind === "voice" ? "explicit" : "visible");
+        if (message.kind === "voice" || readPolicy === "explicit")
+            continue;
+        next = recordReadIntent(next, { operationId: operationId(), threadId: conversationId, messageId: message.id, readPolicy });
+        observed.add(message.id);
+    }
+    return next;
+}

package/lib/runtime/createChat.d.ts

@@ -0,0 +1,26 @@
+import { ChatSession } from "./chatSession.js";
+import type { ChatReaderSocialMessage } from "./readerClient.js";
+import type { ChatClient, ChatClientOptions } from "./chatClient.js";
+export type CachedChatMessage = ChatReaderSocialMessage & {
+    id: string;
+    timestamp: number;
+};
+export type CreateChatOptions = {
+    appId: string;
+    accountId: string;
+    profileId: string;
+    teamId: string;
+    token: string;
+    /** Limit reconnect reconciliation for a dedicated conversation document. */
+    threadId?: string;
+    endpoint?: string;
+    clientInstanceId?: string;
+    fetch?: typeof fetch;
+    /** Reuse an existing transport for call/presence integrations; its owner closes it. */
+    connection?: ChatClient;
+    onError: (error: unknown) => void;
+    onNotification?: ChatClientOptions["onNotification"];
+    onReach?: ChatClientOptions["onReach"];
+};
+/** Standard browser entry: storage, paging, realtime and reading share one identity. */
+export declare function createChat(options: CreateChatOptions): ChatSession<CachedChatMessage>;