@pmate/chat-sdk 0.12.0-next.8 → 0.12.0-next.80

package/lib/runtime/responseCache.js

@@ -1,52 +1,146 @@
+import { recoverableTransactions } from "./indexedDbRecovery.js";
 import { Dexie } from "dexie";
 import { WindowedTasks } from "./coalescer.js";
+export function isResponseCacheAuthorityError(error) {
+    return /RESPONSE_CACHE_(ACCESS_REVOKED|SCOPE_CHANGED|INVALIDATED)/.test(String(error));
+}
+export async function assertResponseCacheAccess(access, expectedVersion) {
+    if (!access)
+        return undefined;
+    const current = await access();
+    if (!current.allowed)
+        throw new Error("RESPONSE_CACHE_ACCESS_REVOKED");
+    if (expectedVersion !== undefined && current.version !== expectedVersion)
+        throw new Error("RESPONSE_CACHE_SCOPE_CHANGED");
+    return current.version;
+}
 /** Small response windows, isolated by identity. Epochs fence late writes after
  * access withdrawal. No localStorage or synchronous writes on the read path. */
 export class IndexedDbResponseCache {
     scope;
+    options;
+    transact;
     db;
     rows;
     epochs;
     pending = [];
     tasks = new WindowedTasks(16, () => { });
     running;
+    invalidations = new Set();
     closed = false;
+    closing;
     constructor(scope, options = {}) {
         this.scope = scope;
+        this.options = options;
+        for (const [value, max] of [[options.recordBytes ?? 65536, 1048576], [options.entries ?? 256, 256], [options.batchRecords ?? 128, 128]])
+            if (!Number.isSafeInteger(value) || value < 1 || value > max)
+                throw new Error("INVALID_RESPONSE_CACHE_LIMIT");
         this.db = new Dexie(options.name ?? "pmate-chat-response-windows", { indexedDB: options.indexedDB ?? globalThis.indexedDB, IDBKeyRange: globalThis.IDBKeyRange });
+        this.transact = recoverableTransactions(this.db, () => this.closed);
         this.db.version(1).stores({ windows: "[scope+key],scope", epochs: "scope" });
         this.rows = this.db.table("windows");
         this.epochs = this.db.table("epochs");
     }
+    /** Resolve shared message-scope authority before opening our transaction.
+     * A newer authority version retires response windows exactly once; delayed
+     * callers can never roll the authority backwards or delete recovered data. */
+    async synchronizeAccess() {
+        if (!this.options.access)
+            return;
+        const access = await this.options.access();
+        const stored = await this.transact("r", this.epochs, () => this.epochs.get(this.scope));
+        const storedVersion = stored?.accessVersion ?? 0;
+        if (access.version < storedVersion)
+            throw new Error("RESPONSE_CACHE_SCOPE_CHANGED");
+        // Ordinary cache reads must not take an IndexedDB write lock. Only an
+        // authority transition needs the atomic epoch bump and range deletion.
+        if (access.version > storedVersion)
+            await this.transact("rw", this.rows, this.epochs, async () => {
+                const current = await this.epochs.get(this.scope);
+                const version = current?.accessVersion ?? 0;
+                if (access.version < version)
+                    throw new Error("RESPONSE_CACHE_SCOPE_CHANGED");
+                if (access.version > version) {
+                    await this.epochs.put({ scope: this.scope, epoch: (current?.epoch ?? 0) + 1, accessVersion: access.version });
+                    await this.rows.where("[scope+key]").between([this.scope, Dexie.minKey], [this.scope, Dexie.maxKey], true, true).delete();
+                }
+            });
+        if (!access.allowed)
+            throw new Error("RESPONSE_CACHE_ACCESS_REVOKED");
+    }
     async read(key) {
         if (this.closed)
             throw new Error("RESPONSE_CACHE_CLOSED");
-        return this.db.transaction("r", this.rows, this.epochs, async () => {
+        await this.synchronizeAccess();
+        return this.transact("r", this.rows, this.epochs, async () => {
             const epoch = (await this.epochs.get(this.scope))?.epoch ?? 0;
             const row = await this.rows.get([this.scope, key]);
             return { epoch, cached: row?.epoch === epoch ? { value: row.value, time: row.time } : undefined };
         });
     }
-    write(key, value, epoch) {
+    /** Key-only callers can share one bounded metadata read transaction. */
+    async readMany(keys) {
+        if (this.closed)
+            throw new Error("RESPONSE_CACHE_CLOSED");
+        if (keys.length > 128)
+            throw new Error("RESPONSE_CACHE_SELECTION_TOO_LARGE");
+        await this.synchronizeAccess();
+        return this.transact("r", this.rows, this.epochs, async () => {
+            const epoch = (await this.epochs.get(this.scope))?.epoch ?? 0, unique = [...new Set(keys)];
+            const rows = await this.rows.bulkGet(unique.map(key => [this.scope, key]));
+            return new Map(unique.map((key, index) => { const row = rows[index]; return [key, { epoch, cached: row?.epoch === epoch ? { value: row.value, time: row.time } : undefined }]; }));
+        });
+    }
+    write(key, value, epoch, expectedRevision) {
         if (this.closed)
             return Promise.reject(new Error("RESPONSE_CACHE_CLOSED"));
+        if (expectedRevision !== undefined && !this.options.revision)
+            return Promise.reject(new Error("RESPONSE_CACHE_REVISION_UNAVAILABLE"));
         const copy = structuredClone(value), bytes = new TextEncoder().encode(JSON.stringify(copy)).byteLength;
         // Count in-flight data as well as queued data; requests cannot create an
         // unbounded backlog while IndexedDB is blocked by another tab.
-        if (bytes > 65536 || this.pending.length >= 128 || this.pending.reduce((n, w) => n + w.row.bytes, 0) + bytes > 1048576)
+        if (bytes > (this.options.recordBytes ?? 65536) || this.pending.length >= 128 || this.pending.reduce((n, w) => n + w.row.bytes, 0) + bytes > 1048576)
             return Promise.reject(new Error("RESPONSE_CACHE_BACKPRESSURE"));
-        const promise = new Promise((resolve, reject) => this.pending.push({ row: { scope: this.scope, key, epoch, time: Date.now(), bytes, value: copy }, resolve, reject }));
+        const promise = new Promise((resolve, reject) => this.pending.push({ row: { scope: this.scope, key, epoch, time: Date.now(), bytes, value: copy }, expectedRevision, resolve, reject }));
         this.tasks.schedule("write", () => this.flush());
         return promise;
     }
-    async invalidate() {
+    /** Forget one response without invalidating unrelated cached conversations. */
+    async remove(key) {
+        await this.flush();
+        await this.synchronizeAccess();
+        await this.transact("rw", this.rows, () => this.rows.delete([this.scope, key]));
+    }
+    /** Idempotent shared-scope retirement: an old cleanup cannot erase windows
+     * created after the same authority version was already recovered. */
+    retire(version) {
         if (this.closed)
-            throw new Error("RESPONSE_CACHE_CLOSED");
-        await this.db.transaction("rw", this.rows, this.epochs, async () => {
-            const epoch = ((await this.epochs.get(this.scope))?.epoch ?? 0) + 1;
-            await this.epochs.put({ scope: this.scope, epoch });
-            await this.rows.where("scope").equals(this.scope).delete();
+            return Promise.reject(new Error("RESPONSE_CACHE_CLOSED"));
+        if (!Number.isSafeInteger(version) || version < 1)
+            return Promise.reject(new Error("INVALID_RESPONSE_SCOPE_VERSION"));
+        const task = this.transact("rw", this.rows, this.epochs, async () => {
+            const current = await this.epochs.get(this.scope);
+            if ((current?.accessVersion ?? 0) >= version)
+                return;
+            await this.epochs.put({ scope: this.scope, epoch: (current?.epoch ?? 0) + 1, accessVersion: version });
+            await this.rows.where("[scope+key]").between([this.scope, Dexie.minKey], [this.scope, Dexie.maxKey], true, true).delete();
         });
+        this.invalidations.add(task);
+        return task.finally(() => this.invalidations.delete(task));
+    }
+    invalidate() {
+        if (this.closed)
+            return Promise.reject(new Error("RESPONSE_CACHE_CLOSED"));
+        const task = (async () => {
+            await this.transact("rw", this.rows, this.epochs, async () => {
+                const current = await this.epochs.get(this.scope);
+                const epoch = (current?.epoch ?? 0) + 1;
+                await this.epochs.put({ scope: this.scope, epoch, accessVersion: current?.accessVersion });
+                await this.rows.where("[scope+key]").between([this.scope, Dexie.minKey], [this.scope, Dexie.maxKey], true, true).delete();
+            });
+        })();
+        this.invalidations.add(task);
+        return task.finally(() => this.invalidations.delete(task));
     }
     async flush() {
         if (this.running) {
@@ -55,49 +149,93 @@ export class IndexedDbResponseCache {
                 return this.flush();
             return;
         }
-        const batch = [...this.pending];
-        if (!batch.length)
+        if (!this.pending.length)
             return;
         const task = (async () => {
-            try {
-                const accepted = await this.db.transaction("rw", this.rows, this.epochs, async () => {
-                    const epoch = (await this.epochs.get(this.scope))?.epoch ?? 0;
-                    const valid = batch.filter(write => write.row.epoch === epoch);
-                    const unique = new Map(valid.map(write => [write.row.key, write.row]));
-                    await this.rows.bulkPut([...unique.values()]);
-                    const stored = await this.rows.where("scope").equals(this.scope).toArray();
-                    stored.sort((a, b) => b.time - a.time || a.key.localeCompare(b.key));
-                    let bytes = 0;
-                    const evicted = [];
-                    stored.forEach((row, index) => { bytes += row.bytes; if (index >= 256 || bytes > 1048576)
-                        evicted.push([this.scope, row.key]); });
-                    await this.rows.bulkDelete(evicted);
-                    return new Set(valid);
-                });
-                batch.forEach(write => accepted.has(write) ? write.resolve() : write.reject(new Error("RESPONSE_CACHE_INVALIDATED")));
-            }
-            catch (error) {
-                batch.forEach(write => write.reject(error));
-                throw error;
-            }
-            finally {
-                this.pending.splice(0, batch.length);
+            let failed = false, failure;
+            // Each batch commits and resolves independently. A configured smaller
+            // batch still drains all accepted requests, including during close.
+            while (this.pending.length) {
+                const batch = this.pending.slice(0, this.options.batchRecords ?? 128);
+                try {
+                    await this.synchronizeAccess();
+                    const outcome = await this.transact("rw", this.rows, this.epochs, async () => {
+                        const epoch = (await this.epochs.get(this.scope))?.epoch ?? 0;
+                        const valid = batch.filter(write => write.row.epoch === epoch);
+                        const conditional = valid.filter(write => write.expectedRevision !== undefined);
+                        const keys = [...new Set(conditional.map(write => write.row.key))];
+                        const current = conditional.length ? await this.rows.bulkGet(keys.map(key => [this.scope, key])) : [];
+                        const projected = new Map(keys.map((key, index) => [key, current[index]?.epoch === epoch ? current[index] : undefined]));
+                        const accepted = new Set(), changed = new Set(), unique = new Map();
+                        for (const write of valid) {
+                            if (write.expectedRevision !== undefined) {
+                                const previous = projected.get(write.row.key);
+                                const revision = previous ? this.options.revision(previous.value) : null;
+                                if (revision !== write.expectedRevision) {
+                                    // Another document may have already committed this exact
+                                    // revision; it is an idempotent success, never an overwrite.
+                                    if (revision === this.options.revision(write.row.value) && JSON.stringify(previous.value) === JSON.stringify(write.row.value))
+                                        accepted.add(write);
+                                    else
+                                        changed.add(write);
+                                    continue;
+                                }
+                            }
+                            unique.set(write.row.key, write.row);
+                            projected.set(write.row.key, write.row);
+                            accepted.add(write);
+                        }
+                        if (unique.size) {
+                            await this.rows.bulkPut([...unique.values()]);
+                            if (!this.options.retainAll) {
+                                const stored = await this.rows.where("scope").equals(this.scope).toArray();
+                                stored.sort((a, b) => b.time - a.time || a.key.localeCompare(b.key));
+                                let bytes = 0;
+                                const evicted = [];
+                                stored.forEach((row, index) => { bytes += row.bytes; if (index >= (this.options.entries ?? 256) || bytes > 1048576)
+                                    evicted.push([this.scope, row.key]); });
+                                if (evicted.length)
+                                    await this.rows.bulkDelete(evicted);
+                            }
+                        }
+                        return { accepted, changed };
+                    });
+                    for (const write of batch) {
+                        if (outcome.accepted.has(write))
+                            write.resolve();
+                        else
+                            write.reject(new Error(outcome.changed.has(write) ? "RESPONSE_CACHE_CHANGED" : "RESPONSE_CACHE_INVALIDATED"));
+                    }
+                }
+                catch (error) {
+                    batch.forEach(write => write.reject(error));
+                    if (!failed)
+                        failure = error;
+                    failed = true;
+                }
+                finally {
+                    this.pending.splice(0, batch.length);
+                }
             }
+            if (failed)
+                throw failure;
         })().finally(() => { if (this.running === task)
             this.running = undefined; });
         this.running = task;
         return task;
     }
-    async close() {
-        if (this.closed)
-            return;
+    close() {
+        if (this.closing)
+            return this.closing;
         this.closed = true;
         this.tasks.close();
-        try {
-            await this.flush();
-        }
-        finally {
-            this.db.close();
-        }
+        return this.closing = (async () => {
+            try {
+                await Promise.all([this.flush(), ...this.invalidations]);
+            }
+            finally {
+                this.db.close();
+            }
+        })();
     }
 }

package/lib/runtime/socialReadClient.d.ts

@@ -18,10 +18,14 @@ export type SocialGroup = {
     groupId: string;
     teamId?: string | null;
     ownerId: string;
-    members: string[];
-    title: string;
+    members?: readonly string[];
+    title?: string;
     avatar?: string | null;
     revision: string;
+    versionNumber?: number;
+    status?: "active" | "dissolved";
+    dissolvedBy?: string;
+    dissolvedAt?: number;
 };
 export type SocialRelationship = {
     appId: string;
@@ -45,7 +49,7 @@ export declare class SocialReadClient {
     private readonly options;
     constructor(options: SocialReadClientOptions);
     /** Without teamId includes current Teams and unassigned contact metadata for migration. */
-    contacts(teamId?: string): Promise<ChatReaderContact[]>;
+    contacts(teamId?: string, signal?: AbortSignal): Promise<ChatReaderContact[]>;
     unread(teamId?: string): Promise<ChatReaderUnread[]>;
     messages(input: {
         threadId: string;
@@ -57,11 +61,12 @@ export declare class SocialReadClient {
         limit?: number;
         before?: string;
         after?: string;
+        messageId?: string;
     }, signal?: AbortSignal): Promise<SocialMessagePage>;
     group(input: {
         groupId: string;
         teamId?: string;
-    }): Promise<SocialGroup>;
+    }, signal?: AbortSignal): Promise<SocialGroup>;
     relationship(input: {
         peerId: string;
         teamId?: string;

package/lib/runtime/socialReadClient.js

@@ -14,8 +14,8 @@ export class SocialReadClient {
     options;
     constructor(options) { this.options = { ...options }; }
     /** Without teamId includes current Teams and unassigned contact metadata for migration. */
-    contacts(teamId) {
-        return this.list("contacts", this.teamQuery(teamId));
+    contacts(teamId, signal) {
+        return this.list("contacts", this.teamQuery(teamId), signal);
     }
     unread(teamId) {
         return this.list("unread", this.teamQuery(teamId));
@@ -26,22 +26,26 @@ export class SocialReadClient {
     }
     async messagePage(input, signal) {
         this.requireTeam(input.teamId);
-        const limit = input.limit ?? 100;
+        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 }) }, signal);
+            ...(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"
             || value.messages.some(row => row.appId !== this.options.appId || row.threadId !== input.threadId || row.teamId !== input.teamId || !row.messageId || !Number.isFinite(row.serverCreatedAt))
             || (value.resetRequired && (value.messages.length || value.hasMoreChanges || value.nextBefore !== null)))
             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");
         return value;
     }
-    group(input) {
+    group(input, signal) {
         this.requireTeam(input.teamId);
-        return this.request("group", { groupId: input.groupId, ...this.teamQuery(input.teamId) });
+        return this.request("group", { groupId: input.groupId, ...this.teamQuery(input.teamId) }, signal);
     }
     relationship(input) {
         this.requireTeam(input.teamId);
@@ -54,8 +58,8 @@ export class SocialReadClient {
         if (this.options.appId === "pmate:merry" && !teamId)
             throw new SocialReadError(400, "TEAM_ID_REQUIRED");
     }
-    async list(action, query) {
-        const value = await this.request(action, query);
+    async list(action, query, signal) {
+        const value = await this.request(action, query, signal);
         if (!Array.isArray(value))
             throw new SocialReadError(502, "INVALID_SOCIAL_READ_RESPONSE");
         return value;

package/lib/runtime/voiceUpload.d.ts

@@ -0,0 +1,2 @@
+/** The SDK owns upload I/O; hosts configure only their service endpoint. */
+export declare function voiceUploader(profileId: string, endpoint?: string, fetcher?: typeof fetch): (blob: Blob, signal: AbortSignal) => Promise<string>;

package/lib/runtime/voiceUpload.js

@@ -0,0 +1,27 @@
+import { isOffline } from "./connectivity.js";
+/** The SDK owns upload I/O; hosts configure only their service endpoint. */
+export function voiceUploader(profileId, endpoint = "https://upload-fc.pmate.chat", fetcher = globalThis.fetch) {
+    return async (blob, signal) => {
+        if (signal.aborted)
+            throw new DOMException("Upload aborted", "AbortError");
+        if (isOffline())
+            throw new Error("VOICE_UPLOAD_OFFLINE");
+        const bytes = new Uint8Array(await blob.arrayBuffer());
+        if (signal.aborted)
+            throw new DOMException("Upload aborted", "AbortError");
+        let binary = "";
+        for (let offset = 0; offset < bytes.length; offset += 32768)
+            binary += String.fromCharCode(...bytes.subarray(offset, offset + 32768));
+        const extension = blob.type.includes("mp4") ? "m4a" : blob.type.includes("mpeg") ? "mp3" : "webm";
+        const type = extension === "m4a" ? "audio/mp4" : extension === "mp3" ? "audio/mpeg" : "audio/webm";
+        if (isOffline())
+            throw new Error("VOICE_UPLOAD_OFFLINE");
+        const response = await fetcher(`${endpoint.replace(/\/+$/, "")}/file`, { method: "POST", signal, headers: { "Content-Type": "application/json", "x-file-content-type": type }, body: JSON.stringify({ user: profileId, base64: btoa(binary), filename: `voice-${Date.now()}.${extension}` }) });
+        if (!response.ok)
+            throw new Error("VOICE_UPLOAD_FAILED");
+        const result = await response.json();
+        if (typeof result.data !== "string" || !result.data)
+            throw new Error("VOICE_UPLOAD_FAILED");
+        return result.data;
+    };
+}

package/lib/snapshot.d.ts

@@ -0,0 +1,36 @@
+import { type SocialGroup } from "./runtime/socialReadClient.js";
+import type { ChatMessage, UnreadState } from "./chatTypes.js";
+export type ConversationSnapshotOptions = {
+    appId: string;
+    accountId: string;
+    profileId: string;
+    teamId: string;
+    threadId: string;
+    token: string;
+    hubHttpUrl?: string;
+    limit?: number;
+    fetch?: typeof fetch;
+    signal?: AbortSignal;
+};
+export type ConversationSnapshot = Readonly<{
+    appId: string;
+    accountId: string;
+    profileId: string;
+    teamId: string;
+    threadId: string;
+    generatedAt: number;
+    contact: Readonly<{
+        peerId: string;
+        type: "group" | "user";
+    }>;
+    group: SocialGroup | null;
+    messages: readonly ChatMessage[];
+    hasEarlier: boolean;
+    unread: UnreadState;
+    checkpoint: string;
+    readingCursor: string;
+    serverTiming: string | null;
+}>;
+/** One network first-screen read. This does not open a socket, write a body cache,
+ * install a partial reading index, or mark anything read. Live SDK state takes over later. */
+export declare function fetchConversationSnapshot(options: ConversationSnapshotOptions): Promise<ConversationSnapshot>;

package/lib/snapshot.js

@@ -0,0 +1,50 @@
+import { SocialReadError } from "./runtime/socialReadClient.js";
+import { projectConversationReading } from "./runtime/conversationReading.js";
+import { projectMessageTimeline } from "./runtime/messageTimeline.js";
+import { createMessagePresenter } from "./messageView.js";
+const invalid = () => new SocialReadError(502, "INVALID_THREAD_SNAPSHOT_RESPONSE");
+/** One network first-screen read. This does not open a socket, write a body cache,
+ * install a partial reading index, or mark anything read. Live SDK state takes over later. */
+export async function fetchConversationSnapshot(options) {
+    const limit = options.limit ?? 30;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100)
+        throw new SocialReadError(400, "INVALID_THREAD_SNAPSHOT_LIMIT");
+    const query = new URLSearchParams({ appId: options.appId, profileId: options.profileId, teamId: options.teamId, threadId: options.threadId, limit: String(limit) });
+    const response = await (options.fetch ?? fetch)(`${(options.hubHttpUrl ?? "https://hub.pmate.chat").replace(/\/+$/, "")}/api/social/thread-snapshot?${query}`, {
+        headers: { authorization: `Bearer ${options.token}`, accept: "application/json" }, cache: "no-store", redirect: "error",
+        signal: options.signal ? AbortSignal.any([options.signal, AbortSignal.timeout(15000)]) : AbortSignal.timeout(15000),
+    });
+    const envelope = await response.json().catch(() => null);
+    if (!response.ok || envelope?.success !== true)
+        throw new SocialReadError(response.status, envelope?.message ?? "THREAD_SNAPSHOT_FAILED");
+    const value = envelope.data;
+    if (!value || value.schemaVersion !== 1 || ["appId", "accountId", "profileId", "teamId", "threadId"].some(key => value[key] !== options[key]) || !Number.isFinite(value.generatedAt))
+        throw invalid();
+    const cursor = (value) => typeof value === "string" && /^mp1:\d+:[0-9a-f]{64}$/.test(value);
+    const page = value.page, reading = value.reading;
+    if (!page || !Array.isArray(page.messages) || page.messages.length > limit || !cursor(page.checkpoint) || (page.nextBefore !== null && !cursor(page.nextBefore)) || typeof page.hasMoreChanges !== "boolean" || page.hasMoreChanges || page.resetRequired !== false)
+        throw invalid();
+    if (page.messages.some(row => row.appId !== options.appId || row.teamId !== options.teamId || row.threadId !== options.threadId || !row.messageId || !Number.isFinite(row.serverCreatedAt)))
+        throw invalid();
+    if (!value.contact || !["group", "user"].includes(value.contact.type) || !value.contact.peerId)
+        throw invalid();
+    if (value.contact.type === "group" && (!value.group || value.group.appId !== options.appId || value.group.teamId !== options.teamId || value.group.groupId !== value.contact.peerId || !["active", "dissolved"].includes(value.group.status ?? "")))
+        throw invalid();
+    if (!reading || reading.schemaVersion !== 1 || reading.appId !== options.appId || reading.profileId !== options.profileId || reading.scope !== "thread-window" || typeof reading.syncCursor !== "string" || !Array.isArray(reading.threads) || reading.threads.length > 1 || reading.threads.some(thread => thread.id !== options.threadId || thread.teamId !== options.teamId || !Array.isArray(thread.messages) || !Array.isArray(thread.explicitReadMessageIds) || !Number.isSafeInteger(thread.readThroughSeq)))
+        throw invalid();
+    const summary = reading.summary;
+    if (!summary || [summary.unreadMessageCount, summary.unreadMentionCount, summary.badgeCount].some(count => !Number.isSafeInteger(count) || count < 0))
+        throw invalid();
+    const ids = new Set(page.messages.map(row => row.messageId));
+    if (reading.threads.some(thread => thread.messages.some(fact => !ids.has(fact.id) || !Number.isSafeInteger(fact.seq) || !Array.isArray(fact.recipients) || !Array.isArray(fact.mentions) || !["visible", "explicit"].includes(fact.readPolicy))))
+        throw invalid();
+    const facts = new Map(reading.threads.flatMap(thread => thread.messages).map(fact => [fact.id, fact]));
+    const messages = page.messages.map(row => ({ ...row, id: row.messageId, timestamp: row.serverCreatedAt, ...(facts.get(row.messageId)?.recalled ? { recalled: true } : {}) }));
+    const kind = value.contact.type === "group" ? "group" : "dm";
+    const state = { ...reading, pending: [] };
+    const projected = projectConversationReading(state, { id: options.threadId, kind });
+    const present = createMessagePresenter();
+    const timeline = projectMessageTimeline({ appId: options.appId, profileId: options.profileId, threadId: options.threadId, messages, outgoing: [], decode: () => undefined, reading: projected.messageReading });
+    return { appId: value.appId, accountId: value.accountId, profileId: value.profileId, teamId: value.teamId, threadId: value.threadId, generatedAt: value.generatedAt, contact: value.contact, group: value.group,
+        messages: timeline.map(present), hasEarlier: page.nextBefore !== null, unread: summary, checkpoint: page.checkpoint, readingCursor: reading.syncCursor, serverTiming: response.headers.get("server-timing") };
+}

package/lib/types/chatInput.d.ts

@@ -1,3 +1,4 @@
+import type { ChatCommandConfig } from "../commands";
 import type { MentionConfig, ChatMention } from "../mentions/model";
 import type { ClipboardEventHandler, ComponentType, DragEventHandler, ReactNode } from "react";
 import type { ChatAttachment } from "./attachment";
@@ -121,6 +122,8 @@ export type ChatImageConfig = {
     uploadImage?: (file: File) => Promise<ChatImageUploadResult>;
 };
 export type ChatInputBaseProps = {
+    /** Host-provided slash commands; omit to disable command suggestions. Selection never sends. */
+    commands?: ChatCommandConfig;
     /** Group members supplied by the host; omit for ordinary text input. */
     mentions?: MentionConfig;
     /** Use a taller composer with actions in a bottom toolbar. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.12.0-next.8",
-  "description": "Cross-platform PMate chat input components, voice input primitives, and ASR helpers",
+  "version": "0.12.0-next.80",
+  "description": "Local-first chat SDK, message subscriptions, reading state, and shared chat UI primitives",
   "type": "module",
   "main": "./lib/index.js",
   "types": "./lib/index.d.ts",
@@ -19,10 +19,40 @@
       "import": "./lib/index.js",
       "default": "./lib/index.js"
     },
+    "./bootstrap": {
+      "types": "./lib/runtime/messageLaunch.d.ts",
+      "import": "./lib/runtime/messageLaunch.js",
+      "default": "./lib/runtime/messageLaunch.js"
+    },
     "./runtime": {
       "types": "./lib/runtime/index.d.ts",
       "import": "./lib/runtime/index.js",
       "default": "./lib/runtime/index.js"
+    },
+    "./chat": {
+      "types": "./lib/chat.d.ts",
+      "import": "./lib/chat.js",
+      "default": "./lib/chat.js"
+    },
+    "./advanced": {
+      "types": "./lib/advanced.d.ts",
+      "import": "./lib/advanced.js",
+      "default": "./lib/advanced.js"
+    },
+    "./framework": {
+      "types": "./lib/framework.d.ts",
+      "import": "./lib/framework.js",
+      "default": "./lib/framework.js"
+    },
+    "./history": {
+      "types": "./lib/history.d.ts",
+      "import": "./lib/history.js",
+      "default": "./lib/history.js"
+    },
+    "./snapshot": {
+      "types": "./lib/snapshot.d.ts",
+      "import": "./lib/snapshot.js",
+      "default": "./lib/snapshot.js"
     }
   },
   "publishConfig": {