@pmate/chat-sdk 0.12.0-next.81 → 0.12.0-next.82

package/README.md

@@ -307,3 +307,34 @@ Host applications know which commands are available in a conversation. The share
 The same prop is supported by `ChatInputMobile`. Names omit the leading slash. Arrow keys navigate, Enter/Tab inserts a command and a space, Escape closes; touch selection edits the draft only. Command arguments and existing member mentions are preserved. IME composition, URLs and slashes in ordinary body text do not trigger command execution. Omit `commands` for unsupported conversations.
 
 Host-owned textareas can use `useComposerSuggestions({ value, onChange, mentions, commands, disabled })`, spread `inputProps`, render `MentionMenu` with `menuProps` and `CommandMenu` with `commandMenuProps`, and send `getMentions()` with the untrimmed value.
+
+## Message Threads
+
+### Background
+
+A conversation ID identifies a DM or group. A Message Thread is a single-level
+subdiscussion rooted in one ordinary message. Quoting a message alone does not
+create a Message Thread. Explicit `threadRootId` is the authoritative boundary.
+
+The main timeline loads main messages, while conversation unread still includes
+unread replies once. Reading main history leaves replies unread. Each discussion
+has its own visible-read cursor; voice still requires playback. Local discussion
+windows store message IDs and pagination metadata, sharing canonical message
+bodies, control proofs and permission tombstones across all windows.
+
+```ts
+const discussion = chat.openMessageThread(conversationId, rootMessageId)
+const off = discussion.subscribeThread(conversationId, renderReplies)
+await discussion.start() // reuses the parent connection
+await discussion.sendMessage(conversationId, {text: "Follow up"})
+// threadRootId is inherited by text, media, recalls and reactions.
+await discussion.markRead(conversationId) // discussion text only
+const summaries = await chat.getMessageThreads(conversationId, visibleRootIds)
+off()
+await discussion.close()
+```
+
+A discussion cannot open another discussion. Thread-internal quoted replies keep
+the same root. Close each discussion when its view closes; closing the parent
+also closes its discussions. Agents working on a platform supporting Message
+Threads should put their replies in the incoming Message Thread.

package/lib/chatContract.d.ts

@@ -114,12 +114,19 @@ type ContentChoices = {
     };
 };
 export type OutgoingContent = {
+    threadRootId?: string;
+} & {
     [K in keyof ContentChoices]: ContentChoices[K] & {
         [P in Exclude<keyof ContentChoices, K>]?: never;
     };
 }[keyof ContentChoices];
 /** Default public client. Protocol and synchronous store internals are separate entry points. */
 export interface Chat {
+    openMessageThread(threadId: string, threadRootId: string): Chat;
+    getMessageThreads(threadId: string, rootMessageIds: readonly string[], options?: ReadOptions): Promise<{
+        revision: number;
+        items: import("./runtime/socialReadClient.js").MessageThreadSummary[];
+    }>;
     start(): Promise<void>;
     close(): Promise<void>;
     resolveThreadId(target: ConversationTarget, options?: ReadOptions): Promise<string>;

package/lib/chatTypes.d.ts

@@ -6,6 +6,7 @@ import type { ChatMention } from "./mentions/model.js";
 export type ChatMessage = Readonly<{
     id: string;
     threadId: string;
+    threadRootId?: string;
     timestamp: number;
     from?: string;
     mine: boolean;

package/lib/index.d.ts

@@ -46,3 +46,4 @@ export { useChatSnapshot } from "./hooks/useChatSnapshot.js";
 export * from "./commands";
 export * from "./components/CommandMenu";
 export * from "./hooks/useComposerSuggestions";
+export * from "./runtime/messageThread.js";

package/lib/index.js

@@ -46,3 +46,4 @@ export { useChatSnapshot } from "./hooks/useChatSnapshot.js";
 export * from "./commands";
 export * from "./components/CommandMenu";
 export * from "./hooks/useComposerSuggestions";
+export * from "./runtime/messageThread.js";

package/lib/internal/createPublicChat.d.ts

@@ -1,4 +1,4 @@
 import type { Chat } from "../chatContract.js";
 import { type CreateChatOptions } from "../runtime/createChat.js";
 /** Build only the public capabilities; no aliases or engine fields on the returned object. */
-export declare function createPublicChat(options: CreateChatOptions): Chat;
+export declare function createPublicChat(options: CreateChatOptions, onClosed?: () => void): Chat;

package/lib/internal/createPublicChat.js

@@ -1,3 +1,4 @@
+import { validMessageThreadRoot } from "../runtime/messageThread.js";
 import { waitForCaller } from "../credentials.js";
 import { ChatEngine } from "./chatEngine.js";
 import { registerChat } from "./chatRegistry.js";
@@ -5,7 +6,7 @@ import { createChat as createSession } from "../runtime/createChat.js";
 import { asChatError } from "../runtime/chatError.js";
 import { ChatError } from "../chatError.js";
 /** Build only the public capabilities; no aliases or engine fields on the returned object. */
-export function createPublicChat(options) {
+export function createPublicChat(options, onClosed) {
     const configured = { ...options, onError: (error) => options.onError?.(asChatError(error)) };
     let session;
     try {
@@ -27,8 +28,17 @@ export function createPublicChat(options) {
             return Promise.reject(error);
         }
     };
+    const discussions = new Set();
     const chat = Object.freeze({
-        start: () => engine.start(), close: () => engine.close(),
+        openMessageThread: (threadId, threadRootId) => {
+            if (configured.threadRootId !== undefined || !validMessageThreadRoot(threadRootId))
+                throw new ChatError("invalid-input", "Nested Message Threads are not supported");
+            const child = createPublicChat({ ...configured, threadId, threadRootId, connection: session.sharedTransport() }, () => discussions.delete(child));
+            discussions.add(child);
+            return child;
+        },
+        getMessageThreads: (id, roots, options = {}) => read(() => session.getMessageThreads(id, roots, options.signal), options),
+        start: () => engine.start(), close: async () => { await Promise.all([...discussions].map(child => child.close())); discussions.clear(); await engine.close(); onClosed?.(); },
         resolveThreadId: (target, options = {}) => read(() => engine.resolveThreadId(target), options),
         getThread: (id, options) => read(() => engine.getThread(id), options), loadEarlier: (id, options) => read(() => engine.loadEarlier(id), options), refreshThread: (id, options) => read(() => engine.refreshThread(id), options),
         subscribeThread: (id, listener, options = {}) => { keys(options, ["fields"]); return engine.subscribeThread(id, listener, options); }, subscribeChat: (listener, options = {}) => { keys(options, ["fields"]); return engine.subscribe(listener, options); },

package/lib/messageView.js

@@ -96,7 +96,7 @@ export function createMessagePresenter() {
             value = bodies.get(item.message) ?? content(item.message);
             bodies.set(item.message, value);
         }
-        const result = { id: item.id, threadId: item.threadId, timestamp: item.timestamp, from: item.from, mine: item.mine, status: item.status, recalled: item.recalled, unread: item.unread, attentionEligible: item.attentionEligible, reading: item.reading, reactions: item.reactions, ...value };
+        const result = { id: item.id, threadId: item.threadId, ...(item.threadRootId === undefined ? {} : { threadRootId: item.threadRootId }), timestamp: item.timestamp, from: item.from, mine: item.mine, status: item.status, recalled: item.recalled, unread: item.unread, attentionEligible: item.attentionEligible, reading: item.reading, reactions: item.reactions, ...value };
         items.set(item, result);
         return result;
     };

package/lib/runtime/chatSession.d.ts

@@ -1,3 +1,4 @@
+import { type MessageThreadScope } from "./messageThread.js";
 import { type ConversationTarget } from "./conversationDirectory.js";
 import { type ChatGroup } from "./groupClient.js";
 import type { SocialGroup } from "./socialReadClient.js";
@@ -16,6 +17,11 @@ import { unreadInConversation } from "./readIndex.js";
 import type { StoredMessage } from "./messageStore.js";
 import type { ChatRuntimeMessage } from "./protocol.js";
 export type ChatSessionOptions<T extends StoredMessage> = {
+    discussion?: MessageThreadScope;
+    messageThreads?: (threadId: string, roots: readonly string[], signal?: AbortSignal) => Promise<{
+        items: import("./socialReadClient.js").MessageThreadSummary[];
+        revision: number;
+    }>;
     onDispose?: () => void;
     messages: MessageClientOptions<T>;
     connection: ChatClientOptions;
@@ -161,6 +167,11 @@ export declare class ChatSession<T extends StoredMessage> {
     sendMessage(threadId: string, input: SendMessageInput, options?: {
         waitFor?: "accepted" | "delivered";
     }): Promise<ChatRuntimeMessage>;
+    sharedTransport(): ChatClient;
+    getMessageThreads(threadId: string, roots: readonly string[], signal?: AbortSignal): Promise<{
+        items: import("./socialReadClient.js").MessageThreadSummary[];
+        revision: number;
+    }>;
     private sendWire;
     getConversation(target: ConversationTarget): Promise<string>;
     private sendContent;

package/lib/runtime/chatSession.js

@@ -1,3 +1,4 @@
+import { messageThreadRoot } from "./messageThread.js";
 import { asChatError } from "./chatError.js";
 import { scopedGroupDenial, isScopedGroupDenial } from "./groupDenial.js";
 import { threadChatError } from "./chatError.js";
@@ -285,9 +286,9 @@ export class ChatSession {
             if (item.recalled || !item.message)
                 return [];
             const candidate = this.options.readingCandidate?.(item.message);
-            return candidate ? [{ id: item.id, threadId, from: item.from, mine: item.mine, recalled: item.recalled, readPolicy: candidate.readPolicy }] : [];
+            return candidate ? [{ id: item.id, threadId, threadRootId: item.threadRootId, from: item.from, mine: item.mine, recalled: item.recalled, readPolicy: candidate.readPolicy }] : [];
         });
-        return this.readingOperation(() => this.reading.markRead(threadId, cached));
+        return this.readingOperation(() => this.reading.markRead(threadId, cached, this.options.discussion?.threadRootId));
     }
     updateReading(transform) { return this.readingOperation(() => this.reading.update(transform)); }
     assertOpen() { if (this.withdrawn)
@@ -445,6 +446,13 @@ export class ChatSession {
             return this.sendWire(thread, input, options.waitFor === "delivered");
         return this.sendContent(thread, input, options.waitFor === "delivered");
     }
+    sharedTransport() { this.assertOpen(); return this.connection; }
+    async getMessageThreads(threadId, roots, signal) {
+        this.assertOpen();
+        if (!this.options.messageThreads)
+            throw new Error("MESSAGE_THREADS_UNAVAILABLE");
+        return this.options.messageThreads(threadId, roots, signal);
+    }
     sendWire(threadId, wire, delivered) {
         return (delivered ? this.sender.send(threadId, wire) : this.sender.enqueue(threadId, wire)).then(next => { if (this.withdrawn)
             throw new Error("CHAT_ACCESS_REVOKED"); return next; });
@@ -463,6 +471,11 @@ export class ChatSession {
         }
     }
     async sendContent(target, input, delivered) {
+        if (this.options.discussion?.threadRootId !== undefined) {
+            if (input.threadRootId !== undefined && input.threadRootId !== this.options.discussion.threadRootId)
+                throw new Error("MESSAGE_THREAD_SCOPE_MISMATCH");
+            input = { ...input, threadRootId: this.options.discussion.threadRootId };
+        }
         let thread = typeof target === "string" ? await this.resolveConversation(target) : target;
         validateConversation(this.options.messages.scope, thread);
         await this.conversations.put(thread);
@@ -736,7 +749,8 @@ export class ChatSession {
     buildThreadSnapshot(threadId, previous) {
         const source = this.messages.getSnapshot(threadId), raw = source?.messages ?? [];
         const messages = previous && previous.messages.length === raw.length && previous.messages.every((message, index) => message === raw[index]) ? previous.messages : raw;
-        const outgoing = this.sender.snapshot(threadId);
+        const allOutgoing = this.sender.snapshot(threadId);
+        const outgoing = this.options.discussion ? allOutgoing.filter(record => messageThreadRoot(record.message.body) === this.options.discussion.threadRootId) : allOutgoing;
         const sameSource = previous && previous.messages === messages && previous.outgoing.length === outgoing.length && previous.outgoing.every((record, index) => record === outgoing[index]);
         const candidates = new Map(messages.flatMap(message => { const candidate = this.options.readingCandidate?.(message); return candidate ? [[candidate.id, candidate]] : []; }));
         const semanticReading = previous?.messageReading ?? {};
@@ -746,7 +760,7 @@ export class ChatSession {
                 candidates.set(item.id, { ...candidates.get(item.id), id: item.id, threadId, from: item.from, mine: item.mine, recalled: true });
         const state = this.getReadingSnapshot();
         const kind = state?.threads.find(thread => (thread.conversationId ?? thread.id) === threadId)?.kind ?? "dm";
-        const view = projectConversationReading(state, { id: threadId, kind }, [...candidates.values()]);
+        const view = projectConversationReading(state, { id: threadId, kind, threadRootId: this.options.discussion?.threadRootId }, [...candidates.values()]);
         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 timeline = messageReading === semanticReading ? semantics : projectMessageTimeline({ appId: this.options.messages.scope.appId, profileId: this.options.messages.scope.profileId, threadId, messages, outgoing, candidates, decode: this.decodeTimeline, reading: messageReading, previous: previous?.timeline });

package/lib/runtime/conversationRead.d.ts

@@ -1,6 +1,7 @@
 import { type ReadIndexState } from "./readIndex.js";
 /** Optional observations whose index metadata may still be in flight. */
 export type ConversationReadMessage = {
+    threadRootId?: string | null;
     id: string;
     threadId: string;
     mine?: boolean;
@@ -10,4 +11,4 @@ export type ConversationReadMessage = {
     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;
+export declare function recordConversationRead(state: ReadIndexState, conversationId: string, messages?: readonly ConversationReadMessage[], operationId?: () => `${string}-${string}-${string}-${string}-${string}`, threadRootId?: string): ReadIndexState;

package/lib/runtime/conversationRead.js

@@ -1,6 +1,6 @@
-import { recordReadIntent, sourcesInConversation } from "./readIndex.js";
+import { readingCursor, recordReadIntent, sourcesInConversation } from "./readIndex.js";
 /** Explicitly mark ordinary text history read; unheard audio stays unread. */
-export function recordConversationRead(state, conversationId, messages = [], operationId = () => crypto.randomUUID()) {
+export function recordConversationRead(state, conversationId, messages = [], operationId = () => crypto.randomUUID(), threadRootId) {
     if (!conversationId)
         throw new Error("INVALID_READING_THREAD");
     const sources = sourcesInConversation(state, conversationId);
@@ -11,9 +11,9 @@ export function recordConversationRead(state, conversationId, messages = [], ope
     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);
+            return (message.threadRootId ?? undefined) === threadRootId && !message.recalled && message.from !== state.profileId && message.recipients.includes(state.profileId);
         });
-        const latest = incoming.filter(message => message.readPolicy === "visible" && message.seq > source.readThroughSeq)
+        const latest = incoming.filter(message => message.readPolicy === "visible" && message.seq > readingCursor(source, threadRootId))
             .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" });
@@ -22,7 +22,7 @@ export function recordConversationRead(state, conversationId, messages = [], ope
     // 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))
+        if ((message.threadRootId ?? undefined) !== threadRootId || 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")

package/lib/runtime/conversationReading.d.ts

@@ -2,6 +2,7 @@ import { unreadInConversation, type ReadIndexState } from "./readIndex.js";
 export type ReadingCandidate = {
     id: string;
     threadId: string;
+    threadRootId?: string;
     from?: string;
     mine?: boolean;
     recalled?: boolean;
@@ -25,4 +26,5 @@ export declare function projectConversationReading(state: ReadIndexState | undef
     id: string;
     kind: "dm" | "group";
     badgeCount?: number;
+    threadRootId?: string;
 }, candidates?: readonly ReadingCandidate[]): ConversationReadingView;

package/lib/runtime/conversationReading.js

@@ -1,4 +1,4 @@
-import { sourcesInConversation, unreadInConversation } from "./readIndex.js";
+import { readingCursor, sourcesInConversation, unreadInConversation } from "./readIndex.js";
 /** One projection for indexed authority and observations awaiting indexing. A
  * directory badge is optional compatibility metadata, never proof of coverage. */
 export function projectConversationReading(state, conversation, candidates = []) {
@@ -13,7 +13,7 @@ export function projectConversationReading(state, conversation, candidates = [])
     for (const source of sources)
         for (const message of source.messages) {
             indexed.add(message.id);
-            messageReading[message.id] = { seq: message.seq, readPolicy: message.readPolicy, read: message.recalled || hidden.get(message.id)?.has(message.from) === true || message.from === state.profileId || !message.recipients.includes(state.profileId) || (message.readPolicy === "explicit" ? source.explicitReadMessageIds.includes(message.id) : message.seq <= source.readThroughSeq) };
+            messageReading[message.id] = { seq: message.seq, readPolicy: message.readPolicy, read: message.recalled || hidden.get(message.id)?.has(message.from) === true || message.from === state.profileId || !message.recipients.includes(state.profileId) || (message.readPolicy === "explicit" ? source.explicitReadMessageIds.includes(message.id) : message.seq <= readingCursor(source, message.threadRootId)) };
         }
     const observed = new Map();
     for (const intent of state?.observedReadIntents ?? [])
@@ -40,7 +40,7 @@ export function projectConversationReading(state, conversation, candidates = [])
         if (message.attentionEligible === true)
             pendingMentions++;
     }
-    const authoritative = sources.length && state ? unreadInConversation(state, conversation.id, hidden) : undefined;
+    const authoritative = sources.length && state ? unreadInConversation(state, conversation.id, hidden, conversation.threadRootId) : undefined;
     const unread = authoritative ? { unreadMessageCount: authoritative.unreadMessageCount + pendingMessages, unreadMentionCount: authoritative.unreadMentionCount + pendingMentions, badgeCount: authoritative.badgeCount + (conversation.kind === "group" ? pendingMentions : pendingMessages) } : undefined;
     const pendingBadge = conversation.kind === "group" ? pendingMentions : pendingMessages;
     return { messageReading, unread, badgeCount: unread?.badgeCount ?? (conversation.badgeCount === undefined ? undefined : Math.max(Math.max(0, conversation.badgeCount - observedBadges), pendingBadge)) };

package/lib/runtime/createChat.d.ts

@@ -11,6 +11,7 @@ export type CreateChatOptions = {
     token?: string;
     getToken?: TokenProvider;
     /** Limit reconnect reconciliation for a dedicated conversation document. */
+    threadRootId?: string;
     threadId?: string;
     uploadEndpoint?: string;
     endpoint?: string;

package/lib/runtime/createChat.js

@@ -1,3 +1,6 @@
+import { IndexedDbDiscussionStore } from "./messageDiscussionStore.js";
+import { mergeStoredMessage } from "./messageStore.js";
+import { messageThreadRoot } from "./messageThread.js";
 import { ChatCredentials } from "../credentials.js";
 import { voiceUploader } from "./voiceUpload.js";
 import { isOffline } from "./connectivity.js";
@@ -9,6 +12,8 @@ import { decodeCachedChatMessage } from "./cachedMessage.js";
 /** Standard browser entry: storage, paging, realtime and reading share one identity. */
 export function createChatSession(options) {
     const { appId, accountId, profileId, teamId, onError } = options;
+    if (options.threadRootId !== undefined && !options.threadId)
+        throw new Error("MESSAGE_THREAD_CONVERSATION_REQUIRED");
     const token = options.token ?? "";
     if (!token && !options.getToken)
         throw new Error("INVALID_CHAT_CREDENTIALS");
@@ -20,11 +25,13 @@ export function createChatSession(options) {
     const fetcher = credentials?.fetch ?? options.fetch;
     const reader = new SocialReadClient({ appId, profileId, token, hubHttpUrl: http, fetch: fetcher });
     const page = async (threadId, signal, cursor = {}) => {
-        const result = await reader.messagePage({ threadId, teamId, limit: 100, ...cursor }, signal);
+        const result = await reader.messagePage({ threadId, teamId, limit: 100, ...(options.threadRootId === undefined ? { mainOnly: true } : { threadRootId: options.threadRootId }), ...cursor }, signal);
         return { ...result, messages: result.messages.map(message => ({ ...message, id: message.messageId, timestamp: message.serverCreatedAt })) };
     };
     return new ChatSession({
         sharedConnection: options.connection,
+        discussion: { threadRootId: options.threadRootId },
+        messageThreads: (threadId, roots, signal) => reader.messageThreads({ threadId, teamId, rootMessageIds: roots }, signal),
         onDispose: () => credentials?.close(),
         uploadVoice: voiceUploader(profileId, options.uploadEndpoint, fetcher),
         reconcileOutgoing: async (record, signal) => {
@@ -41,7 +48,7 @@ export function createChatSession(options) {
         },
         loadGroup: (groupId, signal) => reader.group({ groupId, teamId }, signal),
         activeThreadId: options.threadId,
-        messages: { scope: { appId, accountId, profileId, teamId }, transport: { authorizeScope: async (signal) => { await reader.contacts(teamId, signal); }, load: (thread, signal) => page(thread, signal), changes: (thread, after, signal) => page(thread, signal, { after }), older: (thread, before, signal) => page(thread, signal, { before }) }, onError },
+        messages: { scope: { appId, accountId, profileId, teamId }, storage: new IndexedDbDiscussionStore({ appId, accountId, profileId, teamId }, mergeStoredMessage, { threadRootId: options.threadRootId }), transport: { authorizeScope: async (signal) => { await reader.contacts(teamId, signal); }, load: (thread, signal) => page(thread, signal), changes: (thread, after, signal) => page(thread, signal, { after }), older: (thread, before, signal) => page(thread, signal, { before }) }, onError },
         reading: { appId, profileId, sessionToken: token, hubHttpUrl: http, fetch: fetcher, onError },
         connection: { appId, profileId, teamId, hubUrl: ws, clientInstanceId: options.clientInstanceId, fetchImpl: fetcher,
             getToken: credentials?.getToken,
@@ -52,7 +59,7 @@ export function createChatSession(options) {
             const body = message.body;
             if (!body || !["message", "quote"].includes(String(body.kind)) && !(body.kind === "contact" && ["friendRequest", "requestFriend"].includes(String(body.action))))
                 return undefined;
-            return { id: message.id, threadId: message.threadId, from: message.from, mine: message.from === profileId, recalled: message.recalled, unread: message.from !== profileId,
+            return { id: message.id, threadId: message.threadId, threadRootId: messageThreadRoot(message.body), from: message.from, mine: message.from === profileId, recalled: message.recalled, unread: message.from !== profileId,
                 readPolicy: message.readPolicy === "explicit" || message.legacyDisplay?.kind === "voice" || messageRequiresPlayback(body) ? "explicit" : "visible", attentionEligible: messageMentionsProfile(body, profileId) };
         },
         decode: message => decodeCachedChatMessage(message, { appId, profileId, teamId }), onError,

package/lib/runtime/index.d.ts

@@ -36,3 +36,4 @@ export * from "./messageLaunch.js";
 export * from "./outgoingContent.js";
 export type { ChatGroup } from "./groupClient.js";
 export type { ConversationTarget } from "./conversationDirectory.js";
+export * from "./messageThread.js";

package/lib/runtime/index.js

@@ -34,3 +34,4 @@ export { projectConversationReading } from "./conversationReading.js";
 export { projectMessageTimeline } from "./messageTimeline.js";
 export * from "./messageLaunch.js";
 export * from "./outgoingContent.js";
+export * from "./messageThread.js";

package/lib/runtime/messageDiscussionStore.d.ts

@@ -0,0 +1,63 @@
+import { IndexedDbMessageStore, type MessageScope, type MessageCoverage, type StoredMessage } from "./messageStore.js";
+/** Discussion windows contain IDs only. The existing canonical store owns every
+ * body, control proof, permission tombstone and conversation reset epoch.
+ * Source writes precede pointer checkpoints: an interrupted commit can require
+ * replay, but can never claim body coverage that was not durably accepted. */
+export declare class IndexedDbDiscussionStore<T extends StoredMessage> extends IndexedDbMessageStore<T> {
+    private pointerDb;
+    private membership;
+    private discussionWindows;
+    private initialized;
+    private migrations;
+    private owner;
+    private root;
+    constructor(scope: MessageScope, merge: (previous: T | undefined, incoming: T) => T, options?: {
+        indexedDB?: IDBFactory;
+        name?: string;
+        threadRootId?: string;
+    });
+    private initializePointers;
+    private source;
+    private pointerKey;
+    private window;
+    read(thread: string, limit?: number, before?: {
+        timestamp: number;
+        id: string;
+    }): Promise<{
+        messages: T[];
+        hasEarlier: boolean;
+        coverage: MessageCoverage | undefined;
+    }>;
+    readFallback(thread: string, limit?: number, before?: {
+        timestamp: number;
+        id: string;
+    }): Promise<{
+        messages: T[];
+        hasEarlier: boolean;
+        coverage: MessageCoverage | undefined;
+    }>;
+    commit(thread: string, messages: T[], coverage?: MessageCoverage, guard?: {
+        version: number;
+        authoritative?: boolean;
+        scopeVersion?: number;
+    }): Promise<number>;
+    importLegacy(thread: string, messages: T[]): Promise<number>;
+    windows(): Promise<{
+        scope: string;
+        checkpoint?: string;
+        complete: boolean;
+        nextBefore?: string | null;
+        syncedAt?: number;
+        resetVersion?: number;
+        revoked?: boolean;
+        scopeVersion?: number;
+        owner: string;
+        thread: string;
+        root: string;
+        sourceVersion: number;
+    }[]>;
+    resetThread(thread: string, revoked?: boolean, scopeVersion?: number): Promise<number>;
+    removeThread(thread: string): Promise<void>;
+    clear(): Promise<void>;
+    close(): void;
+}

package/lib/runtime/messageDiscussionStore.js

@@ -0,0 +1,147 @@
+import { Dexie } from "dexie";
+import { IndexedDbMessageStore, messageScopeKey } from "./messageStore.js";
+import { messageThreadRoot, validMessageThreadRoot } from "./messageThread.js";
+/** Discussion windows contain IDs only. The existing canonical store owns every
+ * body, control proof, permission tombstone and conversation reset epoch.
+ * Source writes precede pointer checkpoints: an interrupted commit can require
+ * replay, but can never claim body coverage that was not durably accepted. */
+export class IndexedDbDiscussionStore extends IndexedDbMessageStore {
+    pointerDb;
+    membership;
+    discussionWindows;
+    initialized;
+    migrations = new Map();
+    owner;
+    root;
+    constructor(scope, merge, options = {}) {
+        super(scope, merge, options);
+        if (options.threadRootId !== undefined && !validMessageThreadRoot(options.threadRootId))
+            throw new Error("INVALID_MESSAGE_THREAD_ROOT");
+        this.owner = messageScopeKey(scope);
+        this.root = options.threadRootId ?? "";
+        this.pointerDb = new Dexie(`${options.name ?? "pmate-chat-messages"}:discussions`, { indexedDB: options.indexedDB ?? globalThis.indexedDB, IDBKeyRange: globalThis.IDBKeyRange });
+        this.pointerDb.version(1).stores({ membership: "[owner+thread+root+id],[owner+thread+root+time+id],[owner+thread],owner", windows: "[owner+thread+root],[owner+thread],owner", initialized: "[owner+thread],owner" });
+        this.initialized = this.pointerDb.table("initialized");
+        this.membership = this.pointerDb.table("membership");
+        this.discussionWindows = this.pointerDb.table("windows");
+        this.pointerDb.on("versionchange", () => { this.pointerDb.close({ disableAutoOpen: false }); return false; });
+    }
+    async initializePointers(thread) {
+        const running = this.migrations.get(thread);
+        if (running)
+            return running;
+        const task = (async () => {
+            const source = await this.source(thread);
+            if (source?.revoked)
+                return;
+            const version = source?.resetVersion ?? 0, scopeVersion = source?.scopeVersion ?? 0;
+            const known = await this.initialized.get([this.owner, thread]);
+            if (known?.version === version && known.scopeVersion === scopeVersion)
+                return;
+            let before;
+            for (;;) {
+                const page = await super.readFallback(thread, 100, before);
+                if (page.coverage?.revoked || (page.coverage?.resetVersion ?? 0) !== version || (page.coverage?.scopeVersion ?? 0) !== scopeVersion)
+                    throw new Error("MESSAGE_PROJECTION_CHANGED");
+                const rows = page.messages.filter(message => {
+                    const body = message.body;
+                    return !body?.content?.reaction && !body?.content?.recall;
+                }).map(message => ({ owner: this.owner, thread, root: messageThreadRoot(message.body) ?? "", id: message.id, time: message.timestamp }));
+                if (rows.length)
+                    await this.membership.bulkPut(rows);
+                if (!page.hasEarlier || !page.messages.length)
+                    break;
+                const first = page.messages[0];
+                before = { timestamp: first.timestamp, id: first.id };
+            }
+            const current = await this.source(thread);
+            if (current?.revoked || (current?.resetVersion ?? 0) !== version || (current?.scopeVersion ?? 0) !== scopeVersion)
+                throw new Error("MESSAGE_PROJECTION_CHANGED");
+            await this.initialized.put({ owner: this.owner, thread, version, scopeVersion });
+        })().finally(() => this.migrations.delete(thread));
+        this.migrations.set(thread, task);
+        return task;
+    }
+    async source(thread) { return (await super.read(thread, 1)).coverage; }
+    pointerKey(thread) { return [this.owner, thread, this.root]; }
+    async window(thread, source) {
+        if (source?.revoked)
+            return source;
+        const window = await this.discussionWindows.get(this.pointerKey(thread));
+        if (!window || window.sourceVersion !== (source?.resetVersion ?? 0) || (window.scopeVersion ?? 0) !== (source?.scopeVersion ?? 0))
+            return { ...source, complete: false, checkpoint: undefined, nextBefore: undefined };
+        return { ...window, resetVersion: source?.resetVersion ?? 0, scopeVersion: source?.scopeVersion ?? 0 };
+    }
+    async read(thread, limit = 100, before) {
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            throw new Error("INVALID_MESSAGE_LIMIT");
+        await this.initializePointers(thread);
+        const source = await this.source(thread), coverage = await this.window(thread, source);
+        if (coverage?.revoked)
+            return { messages: [], hasEarlier: false, coverage };
+        const prefix = [this.owner, thread, this.root];
+        const members = await this.membership.where("[owner+thread+root+time+id]").between([...prefix, Dexie.minKey, Dexie.minKey], [...prefix, before?.timestamp ?? Dexie.maxKey, before?.id ?? Dexie.maxKey], true, !before).reverse().limit(limit + 1).toArray();
+        const ids = members.slice(0, limit).reverse().map(row => row.id), messages = [];
+        let legacyFallback = false;
+        for (let offset = 0; offset < ids.length; offset += 100) {
+            const selected = await super.readSelectedFallback(thread, ids.slice(offset, offset + 100));
+            if (selected.coverage?.revoked || (selected.coverage?.resetVersion ?? 0) !== (source?.resetVersion ?? 0) || (selected.coverage?.scopeVersion ?? 0) !== (source?.scopeVersion ?? 0))
+                return { messages: [], hasEarlier: false, coverage: { ...selected.coverage, complete: false } };
+            messages.push(...selected.messages);
+            legacyFallback ||= selected.legacyFallback;
+        }
+        return { messages, hasEarlier: members.length > limit, coverage: !legacyFallback && messages.length === Math.min(members.length, limit) ? coverage : { ...coverage, complete: false, checkpoint: undefined } };
+    }
+    async readFallback(thread, limit = 100, before) { return this.read(thread, limit, before); }
+    async commit(thread, messages, coverage, guard) {
+        const changed = await super.commit(thread, messages, guard?.authoritative ? { complete: false, resetVersion: guard.version, revoked: false } : undefined, guard);
+        const source = await this.source(thread);
+        if (source?.revoked || guard && ((source?.resetVersion ?? 0) !== guard.version || (source?.scopeVersion ?? 0) !== (guard.scopeVersion ?? 0)))
+            throw new Error("MESSAGE_PROJECTION_CHANGED");
+        const rows = messages.filter(message => {
+            const body = message.body;
+            return !body?.content?.reaction && !body?.content?.recall;
+        }).map(message => ({ owner: this.owner, thread, root: messageThreadRoot(message.body) ?? "", id: message.id, time: message.timestamp }));
+        await this.pointerDb.transaction("rw", this.membership, this.discussionWindows, async () => {
+            if (rows.length)
+                await this.membership.bulkPut(rows);
+            if (coverage)
+                await this.discussionWindows.put({ ...coverage, owner: this.owner, thread, root: this.root, sourceVersion: source?.resetVersion ?? 0, scopeVersion: source?.scopeVersion ?? 0 });
+        });
+        return changed;
+    }
+    async importLegacy(thread, messages) {
+        const changed = await super.importLegacy(thread, messages);
+        const rows = messages.map(message => ({ owner: this.owner, thread, root: messageThreadRoot(message.body) ?? "", id: message.id, time: message.timestamp }));
+        if (rows.length)
+            await this.membership.bulkPut(rows);
+        return changed;
+    }
+    async windows() {
+        const access = await this.scopeAccess();
+        if (access.revoked)
+            return [];
+        return (await this.discussionWindows.where("owner").equals(this.owner).toArray()).filter(row => row.root === this.root).map(row => ({ ...row, scope: this.owner }));
+    }
+    async resetThread(thread, revoked = false, scopeVersion = 0) {
+        const version = await super.resetThread(thread, revoked, scopeVersion);
+        await this.membership.where("[owner+thread]").equals([this.owner, thread]).delete();
+        // All discussion windows notice the canonical epoch change on their next read.
+        return version;
+    }
+    async removeThread(thread) {
+        await super.removeThread(thread);
+        await this.pointerDb.transaction("rw", this.membership, this.discussionWindows, async () => {
+            await this.membership.where("[owner+thread]").equals([this.owner, thread]).delete();
+            await this.discussionWindows.where("[owner+thread]").equals([this.owner, thread]).delete();
+        });
+    }
+    async clear() {
+        await super.clear();
+        await this.pointerDb.transaction("rw", this.membership, this.discussionWindows, async () => {
+            await this.membership.where("owner").equals(this.owner).delete();
+            await this.discussionWindows.where("owner").equals(this.owner).delete();
+        });
+    }
+    close() { super.close(); this.pointerDb.close(); }
+}

package/lib/runtime/messageStore.d.ts

@@ -64,6 +64,14 @@ export declare class IndexedDbMessageStore<T extends StoredMessage> {
         hasEarlier: boolean;
         coverage: MessageCoverage | undefined;
     }>;
+    /** Exact fallback for SDK-owned discussion pointers. Legacy rows remain
+     * display-only and never establish authoritative delivery or history coverage. */
+    readSelectedFallback(thread: string, ids: readonly string[]): Promise<{
+        legacyFallback: boolean;
+        messages: T[];
+        hasEarlier: boolean;
+        coverage: MessageCoverage | undefined;
+    }>;
     /** Migration records never claim coverage or overwrite authoritative rows. */
     importLegacy(thread: string, messages: T[]): Promise<number>;
     /** Bounded fallback only; callers must report an incomplete window. */

package/lib/runtime/messageStore.js

@@ -74,6 +74,22 @@ export class IndexedDbMessageStore {
         });
         return this.finishPage(thread, page);
     }
+    /** Exact fallback for SDK-owned discussion pointers. Legacy rows remain
+     * display-only and never establish authoritative delivery or history coverage. */
+    async readSelectedFallback(thread, ids) {
+        if (ids.length > 100 || ids.some(id => !id || id.length > 256))
+            throw new Error("INVALID_MESSAGE_SELECTION");
+        const page = await this.transact("r", [this.rows, this.legacy, this.coverage, this.accessRows, this.controls], async () => {
+            const access = await this.scopeAccess(), coverage = this.scopedCoverage(await this.coverage.get([this.key, thread]), access);
+            if (access.revoked || coverage?.revoked)
+                return { messages: [], hasEarlier: false, coverage: { ...coverage, complete: false, revoked: true, scopeVersion: access.version }, legacyFallback: false };
+            const keys = [...new Set(ids)].map(id => [this.key, thread, id]);
+            const canonical = await this.rows.bulkGet(keys), legacy = await this.legacy.bulkGet(keys);
+            const fallback = canonical.some((row, index) => !row && legacy[index]);
+            return { ...await this.controlPage({ messages: canonical.flatMap((row, index) => row ? [row.value] : legacy[index] ? [legacy[index].value] : []), hasEarlier: false, coverage: fallback ? { ...coverage, complete: false } : coverage }), legacyFallback: fallback };
+        });
+        return { ...await this.finishPage(thread, page), legacyFallback: page.legacyFallback };
+    }
     /** Migration records never claim coverage or overwrite authoritative rows. */
     async importLegacy(thread, messages) {
         if (messages.length > 128)

package/lib/runtime/messageThread.d.ts

@@ -0,0 +1,9 @@
+/** Conversation IDs identify rooms; Message Thread roots identify discussions
+ * within a room. Quoted replies never implicitly create discussion membership. */
+export type MessageThreadScope = {
+    threadRootId?: string;
+};
+export declare function validMessageThreadRoot(value: unknown): value is string;
+export declare function messageThreadRoot(body: unknown): string | undefined;
+/** Never use this discussion key as an individual message/action dedup key. */
+export declare function messageDiscussionKey(conversationId: string, scope?: MessageThreadScope): string;

package/lib/runtime/messageThread.js

@@ -0,0 +1,17 @@
+export function validMessageThreadRoot(value) {
+    return typeof value === "string" && new TextEncoder().encode(value).byteLength > 0
+        && new TextEncoder().encode(value).byteLength <= 256 && !/[\u0000-\u001f\u007f-\u009f]/u.test(value);
+}
+export function messageThreadRoot(body) {
+    if (!body || typeof body !== "object")
+        return;
+    const content = body.content;
+    if (!content || typeof content !== "object")
+        return;
+    const root = content.threadRootId;
+    return validMessageThreadRoot(root) ? root : undefined;
+}
+/** Never use this discussion key as an individual message/action dedup key. */
+export function messageDiscussionKey(conversationId, scope = {}) {
+    return JSON.stringify([conversationId, scope.threadRootId ?? null]);
+}

package/lib/runtime/messageTimeline.d.ts

@@ -13,6 +13,7 @@ export type TimelineReaction = {
 export type TimelineItem<T> = {
     id: string;
     threadId: string;
+    threadRootId?: string;
     timestamp: number;
     from?: string;
     mine: boolean;

package/lib/runtime/messageTimeline.js

@@ -1,3 +1,4 @@
+import { messageThreadRoot } from "./messageThread.js";
 import { isReadingControl } from "./readingContent.js";
 function content(message, appId) {
     const body = message.body;
@@ -107,7 +108,7 @@ export function projectMessageTimeline(input) {
         const mine = envelope.from === input.profileId, reading = input.reading[message.id];
         const withdrawn = Boolean(tombstones.has(message.id) || message.recalled || envelope.legacyDisplay?.recalled || envelope.from && recalled.get(message.id)?.has(envelope.from));
         const candidate = input.candidates?.get(message.id);
-        const item = { id: message.id, threadId: message.threadId, timestamp: message.timestamp, from: envelope.from, mine, status: !mine && reading ? (reading.read ? "read" : status === "read" ? "sent" : status) : status, recalled: withdrawn, ...(candidate ? { unread: !mine && !withdrawn && (reading ? !reading.read : candidate.unread), attentionEligible: candidate.attentionEligible } : {}),
+        const item = { id: message.id, threadId: message.threadId, ...(messageThreadRoot(envelope.body) === undefined ? {} : { threadRootId: messageThreadRoot(envelope.body) }), timestamp: message.timestamp, from: envelope.from, mine, status: !mine && reading ? (reading.read ? "read" : status === "read" ? "sent" : status) : status, recalled: withdrawn, ...(candidate ? { unread: !mine && !withdrawn && (reading ? !reading.read : candidate.unread), attentionEligible: candidate.attentionEligible } : {}),
             message: withdrawn ? undefined : message, reading, reactionEvents: withdrawn ? [] : groupedEvents.get(message.id) ?? [], reactions: withdrawn ? [] : [...(grouped.get(message.id) ?? [])].sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0).map(([emojiId, users]) => { const userIds = [...users].sort(); return { emojiId, userIds, mine: userIds.includes(input.profileId) }; }) };
         const old = previous.get(item.id);
         const sameReading = old?.reading === item.reading || old?.reading?.seq === item.reading?.seq && old?.reading?.read === item.reading?.read && old?.reading?.readPolicy === item.reading?.readPolicy;

package/lib/runtime/outgoingContent.d.ts

@@ -1,3 +1,4 @@
+import { type MessageThreadScope } from "./messageThread.js";
 import { type ChatFile } from "../fileMetadata.js";
 import type { ChatMention } from "../mentions/model.js";
 import type { MessageScope } from "./messageStore.js";
@@ -79,7 +80,7 @@ type ContentChoices = {
         };
     };
 };
-export type OutgoingContent = {
+export type OutgoingContent = MessageThreadScope & {
     [K in keyof ContentChoices]: ContentChoices[K] & {
         [P in Exclude<keyof ContentChoices, K>]?: never;
     };

package/lib/runtime/outgoingContent.js

@@ -1,3 +1,4 @@
+import { validMessageThreadRoot } from "./messageThread.js";
 import { parseChatFile } from "../fileMetadata.js";
 import { dmThreadId, groupThreadId } from "./thread.js";
 const contentKeys = ["text", "file", "image", "voice", "recall", "reaction", "invitation", "groupCreate", "groupUpdate", "groupDissolve"];
@@ -39,7 +40,9 @@ export function outgoingContent(scope, thread, input) {
     validateConversation(scope, thread);
     if (!input || typeof input !== "object" || contentKeys.filter(key => Object.hasOwn(input, key)).length !== 1)
         throw new Error("INVALID_MESSAGE_CONTENT");
-    const identity = { appId: scope.appId, teamId: scope.teamId };
+    if (input.threadRootId !== undefined && (!validMessageThreadRoot(input.threadRootId) || input.invitation || input.groupCreate || input.groupUpdate || input.groupDissolve))
+        throw new Error("INVALID_MESSAGE_THREAD_ROOT");
+    const identity = { appId: scope.appId, teamId: scope.teamId, ...(input.threadRootId === undefined ? {} : { threadRootId: input.threadRootId }) };
     if (input.invitation) {
         if (typeof input.invitation !== "object" || Array.isArray(input.invitation) || thread.kind !== "dm" || input.invitation.message !== undefined && typeof input.invitation.message !== "string")
             throw new Error("INVALID_MESSAGE_INVITATION");

package/lib/runtime/readIndex.d.ts

@@ -2,6 +2,7 @@
 export type IndexedReadMessage = {
     id: string;
     seq: number;
+    threadRootId?: string | null;
     from: string;
     recipients: string[];
     mentions: string[];
@@ -18,6 +19,7 @@ export declare function readingMetadata<T extends {
     threads: IndexedReadThread[];
 }>(state: T): T;
 export type ReadingOperation = {
+    threadRootId?: string;
     operationId: string;
     threadId: string;
     readThroughSeq: number;
@@ -33,6 +35,7 @@ export type IndexedReadThread = {
     kind: "dm" | "group";
     messages: IndexedReadMessage[];
     readThroughSeq: number;
+    messageThreadReadThrough?: Record<string, number> | null;
     explicitReadMessageIds: string[];
 };
 export type ObservedReadIntent = {
@@ -65,6 +68,7 @@ export declare class ReadSyncGap extends Error {
     constructor(cursor: string);
 }
 export declare function createReadIndex(appId: string, profileId: string): ReadIndexState;
+export declare function readingCursor(thread: Pick<IndexedReadThread, "readThroughSeq" | "messageThreadReadThrough">, root?: string | null): number;
 /** A snapshot is authoritative for server state, never for unsent local operations. */
 export declare function installReadSnapshot(current: ReadIndexState, snapshot: ReadSnapshot): ReadIndexState;
 /** Cursor positions are opaque; only exact predecessor matching proves continuity. */
@@ -80,7 +84,7 @@ export declare function coalesceReadOperations(current: ReadIndexState): (Readin
     operationIds: string[];
 })[];
 /** Counts are over the indexed message coverage, not an estimate of missing history. */
-export declare function unreadInThread(state: ReadIndexState, threadId: string, hidden?: ReadonlyMap<string, ReadonlySet<string>>): {
+export declare function unreadInThread(state: ReadIndexState, threadId: string, hidden?: ReadonlyMap<string, ReadonlySet<string>>, threadRootId?: string): {
     unreadMessageCount: number;
     unreadMentionCount: number;
     badgeCount: number;
@@ -158,7 +162,7 @@ export declare class IndexedDbReadIndex implements ReadIndexPersistence {
 }
 export declare function sourcesInConversation(state: ReadIndexState, conversationId: string): IndexedReadThread[];
 /** Aggregate logical history while each original source retains its own read cursor. */
-export declare function unreadInConversation(state: ReadIndexState, conversationId: string, hidden?: ReadonlyMap<string, ReadonlySet<string>>): {
+export declare function unreadInConversation(state: ReadIndexState, conversationId: string, hidden?: ReadonlyMap<string, ReadonlySet<string>>, threadRootId?: string): {
     unreadMessageCount: number;
     unreadMentionCount: number;
     badgeCount: number;

package/lib/runtime/readIndex.js

@@ -1,3 +1,4 @@
+import { validMessageThreadRoot } from "./messageThread.js";
 import { prepareReadSchema } from "./readSchema.js";
 import { ReadBatchJournal, lockReadOwner } from "./readBatchJournal.js";
 import { Dexie } from "dexie";
@@ -31,6 +32,17 @@ export class ReadSyncGap extends Error {
 export function createReadIndex(appId, profileId) {
     return { schemaVersion: 1, appId, profileId, syncCursor: "0", threads: [], pending: [] };
 }
+export function readingCursor(thread, root) {
+    return root == null ? thread.readThroughSeq : Object.hasOwn(thread.messageThreadReadThrough ?? {}, root) ? thread.messageThreadReadThrough[root] : 0;
+}
+function mergeDiscussionCursors(a, b) {
+    if (!a.messageThreadReadThrough && !b.messageThreadReadThrough)
+        return {};
+    const entries = new Map(Object.entries(a.messageThreadReadThrough ?? {}));
+    for (const [root, seq] of Object.entries(b.messageThreadReadThrough ?? {}))
+        entries.set(root, Math.max(entries.get(root) ?? 0, seq));
+    return { messageThreadReadThrough: Object.fromEntries(entries) };
+}
 function validateThread(thread) {
     if (!thread.id || !["dm", "group"].includes(thread.kind) || !Number.isSafeInteger(thread.readThroughSeq) || thread.readThroughSeq < 0)
         throw new Error("INVALID_READ_THREAD");
@@ -38,9 +50,11 @@ function validateThread(thread) {
         throw new Error("INVALID_READ_TEAM");
     if (thread.conversationId !== undefined && (!thread.conversationId || !thread.teamId))
         throw new Error("INVALID_READ_CONVERSATION");
+    if (Object.entries(thread.messageThreadReadThrough ?? {}).some(([root, seq]) => !validMessageThreadRoot(root) || !Number.isSafeInteger(seq) || seq < 0))
+        throw new Error("INVALID_MESSAGE_THREAD_READING");
     const ids = new Set(), positions = new Set();
     for (const message of thread.messages) {
-        if (!message.id || !Number.isSafeInteger(message.seq) || message.seq < 1 || ids.has(message.id) || positions.has(message.seq)
+        if (message.threadRootId != null && !validMessageThreadRoot(message.threadRootId) || !message.id || !Number.isSafeInteger(message.seq) || message.seq < 1 || ids.has(message.id) || positions.has(message.seq)
             || !["visible", "explicit"].includes(message.readPolicy))
             throw new Error("INVALID_READ_MESSAGE");
         ids.add(message.id);
@@ -52,11 +66,11 @@ function cloneThread(thread) {
     return structuredClone({ ...thread, messages: [...thread.messages].sort((a, b) => a.seq - b.seq), explicitReadMessageIds: [...new Set(thread.explicitReadMessageIds)] });
 }
 function applyOperation(thread, operation) {
-    return { ...thread, readThroughSeq: Math.max(thread.readThroughSeq, operation.readThroughSeq),
+    return { ...thread, ...(operation.threadRootId === undefined ? { readThroughSeq: Math.max(thread.readThroughSeq, operation.readThroughSeq) } : { messageThreadReadThrough: { ...thread.messageThreadReadThrough, [operation.threadRootId]: Math.max(readingCursor(thread, operation.threadRootId), operation.readThroughSeq) } }),
         explicitReadMessageIds: [...new Set([...thread.explicitReadMessageIds, ...operation.explicitReadMessageIds])] };
 }
 function covered(thread, operation) {
-    return thread.readThroughSeq >= operation.readThroughSeq
+    return readingCursor(thread, operation.threadRootId) >= operation.readThroughSeq
         && operation.explicitReadMessageIds.every(id => thread.explicitReadMessageIds.includes(id));
 }
 /** A snapshot is authoritative for server state, never for unsent local operations. */
@@ -80,7 +94,7 @@ export function installReadSnapshot(current, snapshot) {
     for (const previous of current.threads) {
         const thread = byId.get(previous.id);
         if (thread)
-            byId.set(thread.id, { ...thread, readThroughSeq: Math.max(thread.readThroughSeq, previous.readThroughSeq),
+            byId.set(thread.id, { ...thread, ...mergeDiscussionCursors(thread, previous), readThroughSeq: Math.max(thread.readThroughSeq, previous.readThroughSeq),
                 explicitReadMessageIds: [...new Set([...thread.explicitReadMessageIds, ...previous.explicitReadMessageIds])] });
     }
     return resolveObservedReads({ ...snapshot, threads: [...byId.values()], pending, observedReadIntents: current.observedReadIntents ?? [] });
@@ -96,7 +110,7 @@ export function applyReadChange(current, change) {
     const incoming = cloneThread(change.thread);
     const pending = current.pending.filter(operation => operation.threadId !== incoming.id || !covered(incoming, operation));
     const previous = current.threads.find(thread => thread.id === incoming.id);
-    const merged = previous ? { ...incoming, readThroughSeq: Math.max(incoming.readThroughSeq, previous.readThroughSeq),
+    const merged = previous ? { ...incoming, ...mergeDiscussionCursors(incoming, previous), readThroughSeq: Math.max(incoming.readThroughSeq, previous.readThroughSeq),
         explicitReadMessageIds: [...new Set([...incoming.explicitReadMessageIds, ...previous.explicitReadMessageIds])] } : incoming;
     const projected = pending.filter(operation => operation.threadId === incoming.id).reduce(applyOperation, merged);
     return resolveObservedReads({ ...current, syncCursor: change.syncCursor, pending, threads: [...current.threads.filter(t => t.id !== incoming.id), projected] });
@@ -140,9 +154,9 @@ export function recordVisibleRead(current, threadId, messageId, operationId) {
     const message = thread?.messages.find(m => m.id === messageId);
     if (!thread || !message || message.readPolicy !== "visible")
         throw new Error("INVALID_VISIBLE_READ");
-    if (message.seq <= thread.readThroughSeq)
+    if (message.seq <= readingCursor(thread, message.threadRootId))
         return current;
-    return enqueue(current, { operationId, threadId: thread.id, readThroughSeq: message.seq, readThroughMessageId: message.id, explicitReadMessageIds: [] });
+    return enqueue(current, { operationId, threadId: thread.id, ...(message.threadRootId == null ? {} : { threadRootId: message.threadRootId }), readThroughSeq: message.seq, readThroughMessageId: message.id, explicitReadMessageIds: [] });
 }
 export function recordExplicitRead(current, threadId, messageId, operationId) {
     const thread = readSource(current, threadId, messageId);
@@ -151,7 +165,7 @@ export function recordExplicitRead(current, threadId, messageId, operationId) {
         throw new Error("INVALID_EXPLICIT_READ");
     if (thread.explicitReadMessageIds.includes(messageId))
         return current;
-    return enqueue(current, { operationId, threadId: thread.id, readThroughSeq: 0, explicitReadMessageIds: [messageId] });
+    return enqueue(current, { operationId, threadId: thread.id, ...(message.threadRootId == null ? {} : { threadRootId: message.threadRootId }), readThroughSeq: 0, explicitReadMessageIds: [messageId] });
 }
 function enqueue(current, operation) {
     if (!operation.operationId || current.pending.some(p => p.operationId === operation.operationId))
@@ -162,9 +176,10 @@ function enqueue(current, operation) {
 export function coalesceReadOperations(current) {
     const batches = new Map();
     for (const operation of current.pending) {
-        const batch = batches.get(operation.threadId);
+        const key = JSON.stringify([operation.threadId, operation.threadRootId ?? null]);
+        const batch = batches.get(key);
         if (!batch) {
-            batches.set(operation.threadId, { ...structuredClone(operation), operationIds: [operation.operationId] });
+            batches.set(key, { ...structuredClone(operation), operationIds: [operation.operationId] });
             continue;
         }
         batch.operationIds.push(operation.operationId);
@@ -177,13 +192,13 @@ export function coalesceReadOperations(current) {
     return [...batches.values()];
 }
 /** Counts are over the indexed message coverage, not an estimate of missing history. */
-export function unreadInThread(state, threadId, hidden) {
+export function unreadInThread(state, threadId, hidden, threadRootId) {
     const thread = state.threads.find(t => t.id === threadId);
     if (!thread)
         throw new Error("UNKNOWN_READ_THREAD");
     const explicit = new Set(thread.explicitReadMessageIds);
-    const messages = thread.messages.filter(message => !message.recalled && !hidden?.get(message.id)?.has(message.from) && !(message.readingControl || isReadingControl(message.payload, state.appId)) && message.from !== state.profileId && message.recipients.includes(state.profileId)
-        && (message.readPolicy === "explicit" ? !explicit.has(message.id) : message.seq > thread.readThroughSeq));
+    const messages = thread.messages.filter(message => (threadRootId === undefined || message.threadRootId === threadRootId) && !message.recalled && !hidden?.get(message.id)?.has(message.from) && !(message.readingControl || isReadingControl(message.payload, state.appId)) && message.from !== state.profileId && message.recipients.includes(state.profileId)
+        && (message.readPolicy === "explicit" ? !explicit.has(message.id) : message.seq > readingCursor(thread, message.threadRootId)));
     const unreadMessageCount = messages.length;
     const unreadMentionCount = messages.filter(message => message.mentions.includes(state.profileId)).length;
     return { unreadMessageCount, unreadMentionCount, badgeCount: thread.kind === "group" ? unreadMentionCount : unreadMessageCount };
@@ -358,7 +373,7 @@ export class IndexedDbReadIndex {
                                 throw new Error("READ_STORAGE_INCOMPLETE");
                             return message.value;
                         });
-                    return { ...row.value, readThroughSeq: position.readThroughSeq, explicitReadMessageIds: position.explicitReadMessageIds, messages };
+                    return { ...row.value, readThroughSeq: position.readThroughSeq, messageThreadReadThrough: position.messageThreadReadThrough, explicitReadMessageIds: position.explicitReadMessageIds, messages };
                 }) };
             this.normalizedStates.add(result);
             if ((threadOrder ?? []).every(id => byId.get(id)?.messageCount !== undefined && !byId.get(id).messageIds.length && [...(byThread.get(id)?.values() ?? [])].every(row => Number.isSafeInteger(row.ordinal))))
@@ -532,7 +547,7 @@ export class IndexedDbReadIndex {
                 if (message)
                     messages.push(previous);
             }
-            partialThreads.push({ ...source.cached, messages, readThroughSeq: position.readThroughSeq, explicitReadMessageIds: position.explicitReadMessageIds });
+            partialThreads.push({ ...source.cached, messages, readThroughSeq: position.readThroughSeq, messageThreadReadThrough: position.messageThreadReadThrough, explicitReadMessageIds: position.explicitReadMessageIds });
         }
         const partial = { schemaVersion: 1, appId, profileId, syncCursor: header.syncCursor, pending: header.pending, observedReadIntents: header.observedReadIntents, threads: partialThreads };
         const result = transform(partial, (await this.versions.get(key))?.teams ?? {});
@@ -543,8 +558,8 @@ export class IndexedDbReadIndex {
         const writes = [];
         for (let i = 0; i < result.threads.length; i++) {
             const thread = result.threads[i], before = positions[i];
-            if (thread.readThroughSeq !== before.readThroughSeq || JSON.stringify(thread.explicitReadMessageIds) !== JSON.stringify(before.explicitReadMessageIds))
-                writes.push({ owner, id: thread.id, readThroughSeq: thread.readThroughSeq, explicitReadMessageIds: thread.explicitReadMessageIds });
+            if (thread.readThroughSeq !== before.readThroughSeq || JSON.stringify(thread.messageThreadReadThrough) !== JSON.stringify(before.messageThreadReadThrough) || JSON.stringify(thread.explicitReadMessageIds) !== JSON.stringify(before.explicitReadMessageIds))
+                writes.push({ owner, id: thread.id, readThroughSeq: thread.readThroughSeq, messageThreadReadThrough: thread.messageThreadReadThrough, explicitReadMessageIds: thread.explicitReadMessageIds });
         }
         if (writes.length > 126)
             return undefined;
@@ -557,10 +572,10 @@ export class IndexedDbReadIndex {
         let changed = false;
         const threads = base.threads.map(thread => {
             const position = byId.get(thread.id);
-            if (!position || thread.readThroughSeq === position.readThroughSeq && JSON.stringify(thread.explicitReadMessageIds) === JSON.stringify(position.explicitReadMessageIds))
+            if (!position || thread.readThroughSeq === position.readThroughSeq && JSON.stringify(thread.messageThreadReadThrough) === JSON.stringify(position.messageThreadReadThrough) && JSON.stringify(thread.explicitReadMessageIds) === JSON.stringify(position.explicitReadMessageIds))
                 return thread;
             changed = true;
-            return { ...thread, readThroughSeq: position.readThroughSeq, explicitReadMessageIds: position.explicitReadMessageIds };
+            return { ...thread, readThroughSeq: position.readThroughSeq, messageThreadReadThrough: position.messageThreadReadThrough, explicitReadMessageIds: position.explicitReadMessageIds };
         });
         if (!changed && JSON.stringify(base.pending) === JSON.stringify(result.pending) && JSON.stringify(base.observedReadIntents) === JSON.stringify(result.observedReadIntents))
             return base;
@@ -622,11 +637,11 @@ export class IndexedDbReadIndex {
             const old = oldThreads.get(thread.id);
             if (old === thread && modern)
                 continue;
-            const { messages, readThroughSeq, explicitReadMessageIds, ...value } = thread;
-            if (!modern || !old || old.readThroughSeq !== readThroughSeq || JSON.stringify(old.explicitReadMessageIds) !== JSON.stringify(explicitReadMessageIds))
-                yield { table: "readingPositions", key: [owner, thread.id], value: { owner, id: thread.id, readThroughSeq, explicitReadMessageIds } };
+            const { messages, readThroughSeq, messageThreadReadThrough, explicitReadMessageIds, ...value } = thread;
+            if (!modern || !old || old.readThroughSeq !== readThroughSeq || JSON.stringify(old.messageThreadReadThrough) !== JSON.stringify(messageThreadReadThrough) || JSON.stringify(old.explicitReadMessageIds) !== JSON.stringify(explicitReadMessageIds))
+                yield { table: "readingPositions", key: [owner, thread.id], value: { owner, id: thread.id, readThroughSeq, messageThreadReadThrough, explicitReadMessageIds } };
             const metadata = { owner, id: thread.id, value, messageIds: [], messageCount: messages.length };
-            const oldMetadata = old ? { owner, id: old.id, value: (({ messages: _m, readThroughSeq: _r, explicitReadMessageIds: _e, ...rest }) => rest)(old), messageIds: modern ? [] : old.messages.map(message => message.id), ...(modern ? { messageCount: old.messages.length } : {}) } : undefined;
+            const oldMetadata = old ? { owner, id: old.id, value: (({ messages: _m, readThroughSeq: _r, messageThreadReadThrough: _mt, explicitReadMessageIds: _e, ...rest }) => rest)(old), messageIds: modern ? [] : old.messages.map(message => message.id), ...(modern ? { messageCount: old.messages.length } : {}) } : undefined;
             if (JSON.stringify(metadata) !== JSON.stringify(oldMetadata))
                 yield { table: "readingThreads", key: [owner, thread.id], value: metadata };
             if (old?.messages === messages && modern)
@@ -669,14 +684,14 @@ function readSource(state, conversationId, messageId) {
     return sources[0];
 }
 /** Aggregate logical history while each original source retains its own read cursor. */
-export function unreadInConversation(state, conversationId, hidden) {
+export function unreadInConversation(state, conversationId, hidden, threadRootId) {
     const sources = sourcesInConversation(state, conversationId);
     if (!sources.length)
         throw new Error("UNKNOWN_READ_CONVERSATION");
     if (new Set(sources.map(source => source.teamId)).size > 1)
         throw new Error("READ_CONVERSATION_TEAM_MISMATCH");
     return sources.reduce((total, source) => {
-        const unread = unreadInThread(state, source.id, hidden);
+        const unread = unreadInThread(state, source.id, hidden, threadRootId);
         return { unreadMessageCount: total.unreadMessageCount + unread.unreadMessageCount, unreadMentionCount: total.unreadMentionCount + unread.unreadMentionCount, badgeCount: total.badgeCount + unread.badgeCount };
     }, { unreadMessageCount: 0, unreadMentionCount: 0, badgeCount: 0 });
 }

package/lib/runtime/readSync.js

@@ -63,11 +63,12 @@ export class ReadSyncClient {
         for (const operation of current.pending) {
             if (operation.explicitReadMessageIds.length || operation.readThroughSeq <= 0)
                 continue;
-            const previous = latest.get(operation.threadId);
+            const key = JSON.stringify([operation.threadId, operation.threadRootId ?? null]);
+            const previous = latest.get(key);
             if (!previous || operation.readThroughSeq > previous.readThroughSeq)
-                latest.set(operation.threadId, operation);
+                latest.set(key, operation);
         }
-        const outgoing = current.pending.filter(operation => operation.explicitReadMessageIds.length || operation.readThroughSeq <= 0 || latest.get(operation.threadId) === operation);
+        const outgoing = current.pending.filter(operation => operation.explicitReadMessageIds.length || operation.readThroughSeq <= 0 || latest.get(JSON.stringify([operation.threadId, operation.threadRootId ?? null])) === operation);
         for (const operation of outgoing) {
             if (persistence.loadVersions)
                 assertReadIndexVersions(versions, await persistence.loadVersions(appId, profileId));

package/lib/runtime/readingClient.d.ts

@@ -47,7 +47,7 @@ export declare class ReadingClient {
     private updateScoped;
     prepareTeam(teamId: string, version: number): Promise<void>;
     private assertThreadTeam;
-    markRead(threadId: string, messages?: readonly ConversationReadMessage[]): Promise<ReadIndexState>;
+    markRead(threadId: string, messages?: readonly ConversationReadMessage[], threadRootId?: string): Promise<ReadIndexState>;
     recordVisible(threadId: string, messageIds: string[]): Promise<ReadIndexState>;
     recordExplicit(threadId: string, messageIds: string[]): Promise<ReadIndexState>;
     private record;

package/lib/runtime/readingClient.js

@@ -155,8 +155,8 @@ export class ReadingClient {
         if (this.options.teamId !== undefined && state.threads.some(thread => (thread.id === threadId || thread.conversationId === threadId) && thread.teamId !== undefined && thread.teamId !== this.options.teamId))
             throw new Error("READ_CONVERSATION_TEAM_MISMATCH");
     }
-    markRead(threadId, messages = []) {
-        return this.updateScoped(state => { this.assertThreadTeam(state, threadId); return recordConversationRead(state, threadId, messages); }, this.options.teamId);
+    markRead(threadId, messages = [], threadRootId) {
+        return this.updateScoped(state => { this.assertThreadTeam(state, threadId); return recordConversationRead(state, threadId, messages, undefined, threadRootId); }, this.options.teamId);
     }
     recordVisible(threadId, messageIds) { return this.record(threadId, messageIds, "visible"); }
     recordExplicit(threadId, messageIds) { return this.record(threadId, messageIds, "explicit"); }

package/lib/runtime/socialReadClient.d.ts

@@ -13,6 +13,14 @@ export type SocialMessagePage = {
     hasMoreChanges: boolean;
     resetRequired: boolean;
 };
+export type MessageThreadSummary = {
+    rootMessageId: string;
+    replyCount: number;
+    unreadCount: number;
+    lastReplyId: string | null;
+    lastReplyAt: number | null;
+    participantProfileIds: string[];
+};
 export type SocialGroup = {
     appId: string;
     groupId: string;
@@ -62,7 +70,19 @@ export declare class SocialReadClient {
         before?: string;
         after?: string;
         messageId?: string;
+        threadRootId?: string;
+        mainOnly?: boolean;
     }, signal?: AbortSignal): Promise<SocialMessagePage>;
+    messageThreads(input: {
+        threadId: string;
+        teamId?: string;
+        rootMessageIds: readonly string[];
+    }, signal?: AbortSignal): Promise<{
+        appId: string;
+        threadId: string;
+        revision: number;
+        items: MessageThreadSummary[];
+    }>;
     group(input: {
         groupId: string;
         teamId?: string;

package/lib/runtime/socialReadClient.js

@@ -1,3 +1,4 @@
+import { messageThreadRoot, validMessageThreadRoot } from "./messageThread.js";
 export class SocialReadError extends Error {
     status;
     constructor(status, message) {
@@ -26,13 +27,15 @@ export class SocialReadClient {
     }
     async messagePage(input, signal) {
         this.requireTeam(input.teamId);
+        if (input.threadRootId !== undefined && !validMessageThreadRoot(input.threadRootId) || input.threadRootId !== undefined && input.mainOnly || input.messageId !== undefined && (input.threadRootId !== undefined || input.mainOnly))
+            throw new SocialReadError(400, "INVALID_MESSAGE_THREAD_SELECTOR");
         const limit = input.limit ?? (input.messageId === undefined ? 100 : 1);
         if (!Number.isSafeInteger(limit) || limit < 1 || limit > 500 || (input.before !== undefined && input.after !== undefined))
             throw new SocialReadError(400, "INVALID_MESSAGE_PAGE");
         if (input.messageId !== undefined && (!input.messageId || input.messageId.length > 256 || /[\u0000-\u001f\u007f]/.test(input.messageId) || limit !== 1 || input.before !== undefined || input.after !== undefined))
             throw new SocialReadError(400, "INVALID_MESSAGE_LOOKUP");
         const value = await this.request("messages", { threadId: input.threadId, ...this.teamQuery(input.teamId), limit: String(limit),
-            ...(input.before === undefined ? {} : { before: input.before }), ...(input.after === undefined ? {} : { after: input.after }), ...(input.messageId === undefined ? {} : { messageId: input.messageId }) }, signal);
+            ...(input.threadRootId === undefined ? {} : { threadRootId: input.threadRootId }), ...(input.mainOnly === undefined ? {} : { mainOnly: String(input.mainOnly) }), ...(input.before === undefined ? {} : { before: input.before }), ...(input.after === undefined ? {} : { after: input.after }), ...(input.messageId === undefined ? {} : { messageId: input.messageId }) }, signal);
         const cursor = (token) => typeof token === "string" && /^mp1:\d+:[0-9a-f]{64}$/.test(token);
         if (!value || !Array.isArray(value.messages) || value.messages.length > limit || !cursor(value.checkpoint)
             || (value.nextBefore !== null && !cursor(value.nextBefore)) || typeof value.hasMoreChanges !== "boolean" || typeof value.resetRequired !== "boolean"
@@ -41,6 +44,26 @@ export class SocialReadClient {
             throw new SocialReadError(502, "INVALID_MESSAGE_PAGE_RESPONSE");
         if (input.messageId !== undefined && (value.messages.some(row => row.messageId !== input.messageId) || value.nextBefore !== null || value.hasMoreChanges || value.resetRequired))
             throw new SocialReadError(502, "INVALID_MESSAGE_LOOKUP_RESPONSE");
+        if (value.messages.some(row => {
+            const root = messageThreadRoot(row.body);
+            const content = row.body?.content;
+            return input.mainOnly && root !== undefined || input.threadRootId !== undefined && root !== input.threadRootId && !content?.reaction && !content?.recall;
+        }))
+            throw new SocialReadError(502, "INVALID_MESSAGE_THREAD_PAGE_RESPONSE");
+        return value;
+    }
+    async messageThreads(input, signal) {
+        this.requireTeam(input.teamId);
+        if (!input.rootMessageIds.length || input.rootMessageIds.length > 100 || !input.rootMessageIds.every(validMessageThreadRoot))
+            throw new SocialReadError(400, "INVALID_MESSAGE_THREAD_ROOTS");
+        const value = await this.request("message-threads", { threadId: input.threadId, ...this.teamQuery(input.teamId), rootMessageIds: JSON.stringify(input.rootMessageIds) }, signal);
+        const roots = new Set(input.rootMessageIds), seen = new Set();
+        if (!value || value.appId !== this.options.appId || value.threadId !== input.threadId || !Number.isSafeInteger(value.revision) || value.revision < 0 || !Array.isArray(value.items) || value.items.length !== roots.size || value.items.some(item => {
+            const invalid = !roots.has(item.rootMessageId) || seen.has(item.rootMessageId) || !Number.isSafeInteger(item.replyCount) || item.replyCount < 0 || !Number.isSafeInteger(item.unreadCount) || item.unreadCount < 0 || item.unreadCount > item.replyCount || !Array.isArray(item.participantProfileIds);
+            seen.add(item.rootMessageId);
+            return invalid;
+        }))
+            throw new SocialReadError(502, "INVALID_MESSAGE_THREAD_SUMMARY_RESPONSE");
         return value;
     }
     group(input, signal) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.12.0-next.81",
+  "version": "0.12.0-next.82",
   "description": "Local-first chat SDK, message subscriptions, reading state, and shared chat UI primitives",
   "type": "module",
   "main": "./lib/index.js",