@pmate/chat-sdk 0.12.0-next.61 → 0.12.0-next.63

package/README.md

@@ -128,133 +128,116 @@ The handler leaves text-only pastes and events already handled by the host untou
 
 Only send on explicit submission: block send while `pending`, deliver each ready attachment's `url`, and remove it after delivery succeeds. Keep unsuccessful drafts to allow retry without reuploading. For `ChatInputDesktop`, use `hasPendingContent` and `sendDisabled` with host-owned drafts. Unmount or key the draft owner when switching accounts, Teams or conversations.
 
-## Browser message and reading data
+## Browser messages
 
 ### Background
 
-Message hosts previously coordinated remote history, offline snapshots, optimistic
-sends and reading synchronization independently. The runtime now provides local
-IndexedDB storage and fixed-window scheduling primitives so those operations can
-share bounded I/O, durable confirmation and scoped subscriptions.
+App code should render messages and report actual user actions. IndexedDB,
+trusted recent windows, synchronization, recipients, retries and read rules belong
+to the SDK. The default API presents one semantic message list, including delivery,
+recalls and reactions. It never presents a partial migration as a ready window.
 
-The browser entry point is `createChat` from `@pmate/chat-sdk/runtime`:
+```ts
+import {createChat, ChatError} from "@pmate/chat-sdk/chat"
+const chat = createChat({appId, accountId, profileId, teamId, token, onError})
+await chat.start() // also handles an optional shared calls/presence connection
+
+// Existing conversations already have a threadId. For a new conversation:
+const threadId = await chat.getConversation({peerId}) // or {groupId}
+try {
+  await chat.getMessages(threadId)
+  openThread(threadId) // cold failure leaves the usable conversation list in place
+} catch (error) {
+  if (error instanceof ChatError && error.retryable) showRetry()
+}
+const off = chat.subscribe(threadId, state => render(state.messages))
+await chat.sendMessage(threadId, {text: "Hello"})
+await chat.getMessages(threadId, {earlier: true})
+off()
+await chat.close()
+```
+
+`getMessages` returns the same stable snapshot as `getSnapshot` and `subscribe`.
+It resolves with a trusted recent window, or rejects with `ChatError`; Apps do not
+check coverage or select local/remote sources. `{earlier:true}` extends the SDK's
+current window without timestamps, limits or cursors; `{all:true}` traverses
+accessible history and rejects if the scan is incomplete. A failed history scan
+can leave the already trusted recent window usable. Cache hits do not repeat
+history requests. Reconnection and browser wake reconcile newer changes.
+
+A thread snapshot contains `threadId`, one renderable `messages` list, `ready`,
+`hasEarlier`, `unread`, `group`, `readCounts`, optional `conversation` target identity,
+and optional `error`. Target identity survives recalls without exposing redacted
+message bodies. `ready` helps
+route entry and startup before the first read; it is not a cache-source indicator.
+`getSnapshot()` and `subscribe(listener)` provide conversation summaries, aggregate
+unread counts and connection state. Unknown unread counts remain `undefined`.
+Subscription always emits the current snapshot first, including with
+`{fields:["messages","unread"]}`, then meaningful changes only. Object references
+remain stable for unchanged results. Framework adapters can use
+`{emitCurrent:false}`; React can import `useChatSnapshot(chat, threadId)` from
+`@pmate/chat-sdk`. Establishing a subscription never starts a read or marks it read.
+
+Sending accepts text/mentions/quotes, images, voice, recalls, reactions and
+invitations through the same typed content union. The SDK resolves the target
+and group roster, expands @all and assigns reaction revisions. The default
+Promise resolves after durable acceptance and returns `{id,timestamp}`; outgoing
+status is part of the same message list. `{waitFor:"delivered"}` waits for the
+server acknowledgement. `retryMessage(id)` retries a failed exact wire.
 
 ```ts
-const chat = createChat({ appId, accountId, profileId, teamId, token, onError })
-await chat.start()
-const page = await chat.getMessages(threadId)
-// SDK owns the page size and history boundary; hosts need not construct a cursor.
-const earlier = await chat.getMessages(threadId, { earlier: true })
-// After an authoritative mutation (e.g. history assignment), await reconciliation.
-// Concurrent refreshes share transport; errors do not masquerade as fresh cache.
-const reconciled = await chat.getMessages(threadId, { refresh: true })
-// Explicit full-history queries reuse cached pages and internally rebase expired cursors.
-const history = await chat.getMessages(threadId, { all: true })
-const off = chat.subscribe(threadId, () => render(chat.getSnapshot(threadId)))
-const offSummary = chat.subscribe(() => renderSummary(chat.getSnapshot()))
+await chat.sendMessage(threadId, {voice:{blob,durationMs}})
+await chat.sendMessage(threadId, {reaction:{messageId,emojiId,active:true}})
+await chat.sendMessage(threadId, {recall:{messageId}}, {waitFor:"delivered"})
 await chat.observeMessages(threadId, visibleIds, "visible")
-// Report only the actual audio `playing` event.
-await chat.observeMessages(threadId, [voiceId], "played")
-const conversation = { id: threadId, kind: "dm" as const, targetId: peerId, teamId }
-await chat.sendMessage(conversation, { text: "Hello" })
-await chat.sendMessage(conversation, { image: { url: uploadedUrl, name: "photo.png" } })
-await chat.sendMessage(conversation, { voice: { blob: recording, durationMs: 1200 } })
+await chat.observeMessages(threadId, [voiceId], "played") // actual playing event
+await chat.markRead(threadId) // ordinary text only; unheard voice stays unread
 const readers = await chat.getReaders(threadId, messageId)
-off(); offSummary()
-// Ordinary navigation/shutdown preserves offline data.
-await chat.close()
 ```
 
+Voice media is acquired on demand through `getVoiceAttachment(threadId,messageId)`.
+Use its `url` and call `release()` when playback/transcription stops. Acquisition,
+clicking play, a fulfilled play Promise and transcription do not count as playing.
+The SDK persists observations locally, batches writes and synchronization, and
+preserves offline intents. It does not promise all media binaries are offline.
+
 ```ts
-// When team access is withdrawn, use this instead of ordinary close(). It hides
-// snapshots immediately, retires durable caches/outbox and closes this session.
-// Other teams' reading operations remain intact. Create a new session to recover.
-await chat.revokeAccess()
+const group = await chat.getGroup(threadId)
+const created = await chat.createGroup({title, members}) // optional groupId
+await chat.updateGroup(created.threadId, {title: "New title"})
 ```
 
-Conversation descriptors identify the target and optional group `memberIds`; the SDK
-checks the descriptor against its identity and team before acceptance. It builds
-text, image, quote and voice envelopes and expands group `@all`/`@所有人` to concrete
-members. Content callers do not provide `appId`, protocol `body` or `recipients`.
-The existing `sendMessage(threadId, { to, body, recipients })` form remains available
-for protocol integrations. Blob voice uploads stay in the durable sender; offline
-uploads wait for retry instead of starting HTTP.
-
-The facade owns all clients below. Message reads transparently restore IndexedDB
-windows and fetch missing ranges through the authenticated Hub. Its normalized
-messages retain the protocol body; product rendering remains with the host.
-`sendMessage` resolves after local persistence, while `outgoing` in the thread
-snapshot reports transport progress and failure. Retry uses the original message
-hash. The subscribed recent window remains 100 records regardless of individual
-query limits; history requests return their own pages and do not replace it.
-Global snapshots contain thread summaries and totals, not complete message arrays.
-Message pages report `complete`; unavailable older pages return cached records with
-`complete: false`. Authorization failures throw and never fall back to denied
-records. Thread snapshots expose `resetVersion`; hosts discard retained rows when
-it changes. Reset epochs are durable, so late cross-tab writes cannot restore a
-pre-reset payload.
-Voice visibility never acknowledges playback, including observations that arrive
-before metadata. Create a new instance and close the previous owner when the
-account or active Team changes.
-
-This facade is still under integration. Reader details currently require network
-access, global summaries do not yet replace the host's contact/thread metadata,
-and Merry's message-list/send migration and production validation are unfinished.
-The lower-level primitives remain available for custom transports:
-
-`MessageClient` reads a trusted recent window locally, coalesces concurrent misses,
-subscribes per conversation, and accepts incremental event batches. Its transport
-supplies authoritative `load`, `changes` and `older` pages. `nextBefore` tracks
-uncached older history independently of the latest synchronization checkpoint.
-A projection reset removes obsolete rows before installing a new window.
-`SocialReadClient.messagePage` implements the authenticated Hub page protocol;
-request cancellation is supported through its optional second signal argument.
-
-`ReadingClient` owns persisted visible/explicit read intents, windowed network
-synchronization and retry. A host reports actual visibility with `recordVisible`
-or explicit actions with `recordExplicit`; loading or subscribing never marks
-messages read. `getSnapshot` plus `subscribe` provide stable reading snapshots.
-`BatchedReadIndex` resolves queued writes only after their transaction commits.
-
-`IndexedDbRecordCache` is a version-aware control-event index. Call and await
-`open` before using it. An optional legacy reader runs during initialization only;
-legacy cleanup happens after durable migration. Normal reads use memory and writes
-are merged into bounded IndexedDB transactions. Cache errors must be surfaced by
-the host, and pending operations are not reported as saved before their promise
-resolves.
-Control-event batches are bounded by both 128 records and 1 MiB per transaction;
-the queue includes in-flight writes and is limited to 4096 records / 8 MiB.
-`transactionBytes` and `queueBytes` can lower these limits. Oversized operations
-fail before changing the memory snapshot. Repeating an in-flight write waits for
-that physical write, including its failure, rather than acknowledging it early.
-
-`DurableChatSender` saves the exact message created by `ChatClient.prepareChat`
-before transmitting it. `retry(hash)` uses `sendPrepared` with the original hash
-and payload. Failed sends require an explicit retry; interrupted sends can resume
-when the connection returns. Call `confirm(hashes)` only after authoritative
-messages have been durably merged. Confirmation tombstones prevent another tab's
-late transport failure from recreating an outgoing message.
-
-Custom primitive integrations must initialize them with the same authenticated
-scope, dispose them on identity changes, and wire their transport to an authorized
-server. Standard browser integrations should use the facade instead. The Merry migration and production validation
-are tracked in the unified message layer proposal.
-
-When the browser reports offline, scheduled message restoration and reading
-refreshes wait for the normal reconnect/wake path. Cached reads remain available;
-unknown receipt counts stay unknown and an uncached reader detail page rejects
-without attempting transport. A network failure arriving after the browser went
-offline does not turn background synchronization into an operation error.
-Authorization failures still revoke the corresponding cached data.
-
-Reading entry points check the message scope even before `initialize()` finishes.
-Concurrent observations share the permission lookup and batch their local writes.
-Visibility/playback operations reject another known team's conversation; a
-permission change in another team does not discard this team's observations.
-Ordinary shutdown waits for accepted local reading writes, while access withdrawal
-rejects late results. Retired asynchronous reading entries reject through promises;
-refresh/subscription teardown remains safe.
-
+Group reads restore IndexedDB metadata before background reconciliation. Mutations
+wait for confirmed delivery and a causal server version. SDK-owned requests share
+bounded queues and time windows; Apps do not poll. `watchReaders(threadId,ids,receiver)`
+selects receipt counts for the current viewport; clear with `watchReaders(undefined,[])`.
+
+`ChatError` exposes `code`, `retryable`, optional HTTP `status`, and the original
+`cause`. Recovery categories are `unavailable`, `access-denied`,
+`storage-unavailable`, `invalid-input`, `conflict`, `closed`, and `busy`.
+Permission failures never turn into trusted offline data. Dispose and recreate
+the SDK when account, profile, team or token changes.
+
+### Advanced integration and migration
+
+`chat.advanced` exposes the underlying `ChatSession` for one-time legacy imports,
+custom transports and diagnostics. Its `messages` are raw records, `timeline` is
+the semantic projection, and `complete/resetVersion` describe coverage internals.
+The older `createChat` export from `@pmate/chat-sdk/runtime` retains this low-level
+contract for compatibility. New Apps should import from `@pmate/chat-sdk/chat`
+or the package root. Do not mix the two snapshot contracts.
+
+For migration, replace `subscribe(id, () => render(getSnapshot(id).timeline))`
+with `subscribe(id, state => render(state.messages))`; replace conversation
+objects and App-supplied recipients with `threadId`; await `getMessages` before
+opening a cold thread instead of checking `page.complete`. Replace `initialize()`
+with `start()`; a shared connection is initialized without another connect call.
+Raw wire sends are available only through `advanced.sendMessage`. Group changes
+use `createGroup/updateGroup`; UI never assigns reaction versions or recipients.
+
+The advanced storage and transport classes remain exported from `/runtime`.
+They must share one authenticated scope and must not bypass scope authority.
+Normal UI code should not maintain another message cache or outbox.
 
 ### Reading storage recovery
 
@@ -282,29 +265,10 @@ Pending voice snapshots contain `voiceAttachment` metadata, without loading audi
 The outbox format upgrade renames the old canonical store without copying binary data in the schema transaction, then atomically separates inline payloads in bounded, resumable transactions. An already-open older application must reload; unsupported senders reject the new format. Original wire/hash, failed status and retry semantics are retained.
 
 
-Control messages use the same send API:
-
-```ts
-await chat.sendMessage(conversation, {recall: {messageId}})
-await chat.sendMessage(conversation, {reaction: {messageId, emojiId, active: true}})
-await chat.sendMessage(conversation, {invitation: {message: "Hello"}})
-await chat.sendMessage(group, {groupCreate: {title, members}})
-await chat.sendMessage(group, {groupUpdate: {expectedRevision, addMembers}})
-```
-
-These calls retain durable-acceptance semantics. Recall and reaction validate the target against the current scoped timeline or canonical local cache; the App does not supply protocol bodies or reaction versions. Reaction counters and exact wires commit in one IndexedDB transaction, including across documents. Validation ordering does not wait for each preceding commit, so a same-key burst still reaches the bounded acceptance batches. Pass `{waitFor:"delivered"}` as the third argument when an action requires server confirmation; the default still resolves after durable acceptance.
-
-
-Group metadata uses the same identity, cache and subscriptions:
-
-```ts
-const group = await chat.getGroup(conversation)
-const off = chat.subscribe(conversation.id, () => {
-  renderGroup(chat.getSnapshot(conversation.id).group)
-}, ["group"])
-await chat.createGroup(conversation, {title, members})
-await chat.updateGroup(conversation, {title: "New title"})
-off()
-```
-
-Reads restore trusted IndexedDB metadata before background revalidation. Creation and updates wait for confirmed delivery and a causal server version, including newer concurrent revisions; Apps do not poll for an exact message hash. Group events and browser recovery share a 200ms window. At most four metadata requests run concurrently, with 128 queued requests, a five-second request timeout, and at most five read-after-write attempts. Per-scope persistent metadata is capped at 64 groups / 1MiB, with 128KiB records, 32-record write batches, conditional cross-document writes and bounded pruning. Cached metadata does not bypass scope withdrawal or server membership checks. Binary media remains on demand.
+SDK group metadata uses a 200ms merge window, four concurrent requests, a bounded
+128-request queue, five-second timeout and at most five read-after-write attempts.
+The persistent group cache is capped at 64 groups / 1MiB, with 128KiB records,
+32-record write batches, conditional writes and bounded pruning. Conversation
+identities are stored separately without rosters; repeated registrations share
+one write, concurrent lookups use bulk reads, and a concurrent memory-hit burst
+shares one fresh authority read without retaining authorization across bursts. Scope withdrawal retires both.

package/lib/chat.d.ts

@@ -0,0 +1,113 @@
+import { type CreateChatOptions } from "./runtime/createChat.js";
+import type { ChatSession, ChatSummarySnapshot as SessionSummary, ChatThreadSnapshot as SessionThread } from "./runtime/chatSession.js";
+import type { CachedChatMessage } from "./runtime/cachedMessage.js";
+import type { TimelineItem } from "./runtime/messageTimeline.js";
+import type { ConversationTarget } from "./runtime/conversationDirectory.js";
+import type { OutgoingContent as RuntimeContent } from "./runtime/outgoingContent.js";
+import { ChatError } from "./runtime/chatError.js";
+export { ChatError } from "./runtime/chatError.js";
+export type { ChatErrorCode } from "./runtime/chatError.js";
+export type { CreateChatOptions, ConversationTarget };
+export type OutgoingContent = Exclude<RuntimeContent, {
+    groupCreate: unknown;
+} | {
+    groupUpdate: unknown;
+}>;
+export type { ChatGroup } from "./runtime/groupClient.js";
+export type ChatMessage = Readonly<TimelineItem<CachedChatMessage>>;
+export type ConversationInfo = Readonly<{
+    kind: "dm" | "group";
+    targetId: string;
+}>;
+export type ChatThreadSnapshot = Readonly<{
+    threadId: string;
+    messages: readonly ChatMessage[];
+    ready: boolean;
+    hasEarlier: boolean;
+    conversation?: ConversationInfo;
+    unread: SessionThread<CachedChatMessage>["unread"];
+    group: SessionThread<CachedChatMessage>["group"];
+    readCounts: SessionThread<CachedChatMessage>["readCounts"];
+    error?: ChatError;
+}>;
+export type ChatSnapshot = Readonly<{
+    threads: readonly {
+        threadId: string;
+        lastMessage?: ChatMessage;
+        group: SessionThread<CachedChatMessage>["group"];
+        unread: ChatThreadSnapshot["unread"];
+        outgoingCount: number;
+    }[];
+    unreadMessageCount: number | undefined;
+    badgeCount: number | undefined;
+    connection: SessionSummary<CachedChatMessage>["connection"];
+}>;
+export type MessageQuery = {
+    earlier?: boolean;
+    all?: boolean;
+    refresh?: boolean;
+};
+export type SendOptions = {
+    waitFor?: "accepted" | "delivered";
+};
+export type SentMessage = Readonly<{
+    id: string;
+    timestamp: number;
+}>;
+type SubscribeOptions<T> = {
+    fields?: readonly (keyof T)[];
+    emitCurrent?: boolean;
+};
+/** App-facing API. Cache coverage, raw protocol and synchronization stay in advanced. */
+export declare class Chat {
+    readonly advanced: ChatSession<CachedChatMessage>;
+    private options;
+    private views;
+    private summary?;
+    private targets;
+    private errors;
+    private listeners;
+    private closed;
+    constructor(advanced: ChatSession<CachedChatMessage>, options: CreateChatOptions);
+    private operation;
+    private threadOperation;
+    start(): Promise<void>;
+    getConversation(target: ConversationTarget): Promise<string>;
+    getSnapshot(): ChatSnapshot;
+    getSnapshot(threadId: string): ChatThreadSnapshot;
+    getMessages(threadId: string, query?: MessageQuery): Promise<ChatThreadSnapshot>;
+    sendMessage(threadId: string, content: OutgoingContent, options?: SendOptions): Promise<SentMessage>;
+    retryMessage(messageId: string): Promise<SentMessage>;
+    subscribe(listener: (snapshot: ChatSnapshot) => void, options?: SubscribeOptions<ChatSnapshot>): () => void;
+    subscribe(threadId: string, listener: (snapshot: ChatThreadSnapshot) => void, options?: SubscribeOptions<ChatThreadSnapshot>): () => void;
+    private sessionFields;
+    private notify;
+    observeMessages(threadId: string, ids: string[], event: "visible" | "played"): Promise<import("./runtime/readIndex.js").ReadIndexState>;
+    markRead(threadId: string): Promise<import("./runtime/readIndex.js").ReadIndexState>;
+    getReaders(threadId: string, messageId: string, page?: Parameters<ChatSession<CachedChatMessage>["getReaders"]>[2], signal?: AbortSignal): Promise<import("./runtime/messageReaders.js").MessageReadersPage>;
+    watchReaders(threadId: string | undefined, ids: string[], receiver?: string): Promise<void>;
+    handleReach(event: Parameters<ChatSession<CachedChatMessage>["handleReach"]>[0]): Promise<"handled" | undefined>;
+    getVoiceAttachment(threadId: string, messageId: string): Promise<import("./runtime/durableSender.js").VoiceAttachmentLease>;
+    getGroup(threadId: string, options?: {
+        refresh?: boolean;
+    }): Promise<import("./chat.js").ChatGroup>;
+    createGroup(input: {
+        groupId?: string;
+        title: string;
+        members: readonly string[];
+    }): Promise<{
+        threadId: string;
+        groupId: string;
+        teamId: string;
+        ownerId: string;
+        title: string;
+        avatar?: string;
+        memberIds: readonly string[];
+        revision: string;
+        versionNumber: number;
+    }>;
+    updateGroup(threadId: string, changes: Parameters<ChatSession<CachedChatMessage>["updateGroup"]>[1]): Promise<import("./chat.js").ChatGroup>;
+    revokeAccess(): Promise<void>;
+    close(): Promise<void>;
+}
+export declare function createChat(options: CreateChatOptions): Chat;

package/lib/chat.js

@@ -0,0 +1,163 @@
+import { createChat as createSession } from "./runtime/createChat.js";
+import { asChatError, ChatError } from "./runtime/chatError.js";
+export { ChatError } from "./runtime/chatError.js";
+const emptyMessages = Object.freeze([]);
+/** App-facing API. Cache coverage, raw protocol and synchronization stay in advanced. */
+export class Chat {
+    advanced;
+    options;
+    views = new Map();
+    summary;
+    targets = new Map();
+    errors = new Map();
+    listeners = new Map();
+    closed = false;
+    constructor(advanced, options) {
+        this.advanced = advanced;
+        this.options = options;
+    }
+    async operation(run) { try {
+        return await run();
+    }
+    catch (error) {
+        throw asChatError(error);
+    } }
+    threadOperation(threadId, run) {
+        return this.operation(async () => {
+            const denied = threadId ? this.errors.get(threadId) : undefined;
+            if (denied?.code === "access-denied")
+                throw denied;
+            try {
+                return await run();
+            }
+            catch (error) {
+                const failure = asChatError(error);
+                if (threadId && failure.code === "access-denied") {
+                    this.errors.set(threadId, failure);
+                    this.targets.delete(threadId);
+                    this.notify(threadId);
+                }
+                throw failure;
+            }
+        });
+    }
+    start() { return this.operation(() => this.options.connection ? this.advanced.initialize() : this.advanced.start()); }
+    getConversation(target) {
+        return this.operation(async () => {
+            const id = await this.advanced.getConversation(target);
+            const value = target.groupId !== undefined ? { kind: "group", targetId: target.groupId } : { kind: "dm", targetId: target.peerId };
+            this.targets.delete(id);
+            this.targets.set(id, value);
+            if (this.targets.size > 256)
+                this.targets.delete(this.targets.keys().next().value);
+            this.notify(id);
+            return id;
+        });
+    }
+    getSnapshot(threadId) {
+        if (threadId === undefined) {
+            const source = this.advanced.getSnapshot(), previous = this.summary;
+            const threads = source.threads.map(thread => ({ threadId: thread.threadId, lastMessage: thread.lastItem, group: thread.group, unread: thread.unread, outgoingCount: thread.outgoingCount }));
+            if (previous && previous.connection === source.connection && previous.badgeCount === source.badgeCount && previous.unreadMessageCount === source.unreadMessageCount && previous.threads.length === threads.length && threads.every((thread, i) => { const old = previous.threads[i]; return thread.threadId === old.threadId && thread.lastMessage === old.lastMessage && thread.group === old.group && thread.unread === old.unread && thread.outgoingCount === old.outgoingCount; }))
+                return previous;
+            return this.summary = { threads, connection: source.connection, badgeCount: source.badgeCount, unreadMessageCount: source.unreadMessageCount };
+        }
+        const source = this.advanced.getSnapshot(threadId), previous = this.views.get(threadId);
+        const error = this.closed ? undefined : this.errors.get(threadId), denied = error?.code === "access-denied";
+        const target = this.closed || !this.advanced.active || denied ? undefined : this.advanced.getConversationTarget(threadId) ?? this.targets.get(threadId);
+        const conversation = previous?.conversation?.kind === target?.kind && previous?.conversation?.targetId === target?.targetId ? previous?.conversation : target ? { kind: target.kind, targetId: target.targetId } : undefined;
+        // Partial migrated rows never masquerade as a trusted recent window.
+        const next = { threadId, conversation, messages: !denied && source.complete ? source.timeline : emptyMessages, ready: !denied && source.complete, hasEarlier: !denied && source.hasEarlier, unread: denied ? undefined : source.unread, group: denied ? undefined : source.group, readCounts: denied ? undefined : source.readCounts, error };
+        if (previous && Object.keys(next).every(key => next[key] === previous[key]))
+            return previous;
+        this.views.set(threadId, next);
+        return next;
+    }
+    async getMessages(threadId, query = {}) {
+        try {
+            if (Object.keys(query).some(key => !["earlier", "all", "refresh"].includes(key)))
+                throw new ChatError("invalid-input", "Unsupported message query");
+            const page = await this.advanced.getMessages(threadId, query);
+            if (!page.complete)
+                throw new ChatError("unavailable", "Messages are not ready; retry when connected");
+            this.errors.delete(threadId);
+            this.notify(threadId);
+            return this.getSnapshot(threadId);
+        }
+        catch (error) {
+            const failure = asChatError(error);
+            if (!this.closed) {
+                this.errors.set(threadId, failure);
+                this.notify(threadId);
+            }
+            throw failure;
+        }
+    }
+    sendMessage(threadId, content, options = {}) {
+        return this.threadOperation(threadId, async () => {
+            if (content && ("groupCreate" in content || "groupUpdate" in content))
+                throw new ChatError("invalid-input", "Use createGroup or updateGroup for group changes");
+            const result = await this.advanced.sendMessage(threadId, content, options);
+            return { id: result.hash, timestamp: result.t };
+        });
+    }
+    retryMessage(messageId) { return this.operation(async () => { const result = await this.advanced.retryMessage(messageId); return { id: result.hash, timestamp: result.t }; }); }
+    subscribe(target, callback, options = {}) {
+        const global = typeof target === "function", key = global ? "" : target;
+        const config = global ? callback : options;
+        const read = () => global ? this.getSnapshot() : this.getSnapshot(key);
+        let previous = read();
+        const emit = () => {
+            const value = read();
+            const fields = config?.fields;
+            const changed = fields ? fields.some(field => previous[field] !== value[field]) : value !== previous;
+            previous = value;
+            if (changed)
+                (global ? target : callback)(value);
+        };
+        let listeners = this.listeners.get(key);
+        if (!listeners) {
+            listeners = new Set();
+            this.listeners.set(key, listeners);
+        }
+        listeners.add(emit);
+        const off = global ? this.advanced.subscribeChanges(emit) : this.advanced.subscribeChanges(key, emit, this.sessionFields(options.fields));
+        const dispose = () => { off(); listeners.delete(emit); if (!listeners.size)
+            this.listeners.delete(key); };
+        if (config?.emitCurrent !== false) {
+            try {
+                (global ? target : callback)(previous);
+            }
+            catch (error) {
+                dispose();
+                throw error;
+            }
+        }
+        return dispose;
+    }
+    sessionFields(fields) {
+        return fields ? [...new Set(fields.flatMap(field => field === "messages" ? ["timeline", "complete"] : field === "ready" ? ["complete"] : field === "conversation" ? ["messages", "group"] : field === "error" || field === "threadId" ? [] : [field]))] : undefined;
+    }
+    notify(threadId) { this.listeners.get(threadId)?.forEach(listener => listener()); }
+    observeMessages(threadId, ids, event) { return this.threadOperation(threadId, () => this.advanced.observeMessages(threadId, ids, event)); }
+    markRead(threadId) { return this.threadOperation(threadId, () => this.advanced.markRead(threadId)); }
+    getReaders(threadId, messageId, page = {}, signal) { return this.threadOperation(threadId, () => this.advanced.getReaders(threadId, messageId, page, signal)); }
+    watchReaders(threadId, ids, receiver) { return this.threadOperation(threadId, () => this.advanced.observeMessages(threadId, ids, "receipts", receiver)); }
+    handleReach(event) { return this.operation(() => this.advanced.handleReach(event)); }
+    getVoiceAttachment(threadId, messageId) { return this.threadOperation(threadId, () => this.advanced.getVoiceAttachment(threadId, messageId)); }
+    getGroup(threadId, options = {}) { return this.threadOperation(threadId, () => this.advanced.getGroup(threadId, options)); }
+    createGroup(input) {
+        return this.operation(async () => {
+            const groupId = input.groupId ?? crypto.randomUUID(), threadId = await this.getConversation({ groupId });
+            const group = await this.advanced.createGroup({ id: threadId, kind: "group", targetId: groupId, teamId: this.options.teamId }, { title: input.title, members: input.members });
+            return { ...group, threadId };
+        });
+    }
+    updateGroup(threadId, changes) { return this.threadOperation(threadId, () => this.advanced.updateGroup(threadId, changes)); }
+    revokeAccess() { return this.operation(() => this.advanced.revokeAccess()); }
+    close() { this.closed = true; return this.operation(() => this.advanced.close()).finally(() => { this.errors.clear(); this.targets.clear(); this.listeners.clear(); this.views.clear(); this.summary = undefined; }); }
+}
+export function createChat(options) {
+    const configured = { ...options, onError: (error) => options.onError(asChatError(error)) };
+    return new Chat(createSession(configured), configured);
+}

package/lib/hooks/useChatSnapshot.d.ts

@@ -0,0 +1,4 @@
+import type { Chat, ChatSnapshot, ChatThreadSnapshot } from "../chat.js";
+/** React consumes the same stable view as callback subscribers. No App-side cache. */
+export declare function useChatSnapshot(chat: Chat | undefined): ChatSnapshot;
+export declare function useChatSnapshot(chat: Chat | undefined, threadId: string): ChatThreadSnapshot;

package/lib/hooks/useChatSnapshot.js

@@ -0,0 +1,8 @@
+import { useCallback, useSyncExternalStore } from "react";
+const emptySummary = Object.freeze({ threads: [], unreadMessageCount: undefined, badgeCount: undefined, connection: "closed" });
+const emptyThread = Object.freeze({ threadId: "", messages: [], ready: false, hasEarlier: false, unread: undefined, group: undefined, readCounts: undefined });
+export function useChatSnapshot(chat, threadId) {
+    const subscribe = useCallback((notify) => !chat ? () => { } : threadId === undefined ? chat.subscribe(notify, { emitCurrent: false }) : chat.subscribe(threadId, notify, { emitCurrent: false }), [chat, threadId]);
+    const snapshot = useCallback(() => threadId === undefined ? chat?.getSnapshot() ?? emptySummary : chat?.getSnapshot(threadId) ?? emptyThread, [chat, threadId]);
+    return useSyncExternalStore(subscribe, snapshot, () => threadId === undefined ? emptySummary : emptyThread);
+}

package/lib/index.d.ts

@@ -41,3 +41,5 @@ export * from "./runtime/socialReadClient";
 export * from "./ux/imagePaste";
 export * from "./hooks/useImageAttachments";
 export * from "./components/ImageAttachmentTray";
+export { createChat, Chat, ChatError, type ChatThreadSnapshot, type ChatMessage as MessageView, type ChatErrorCode, type ConversationTarget, type OutgoingContent, type CreateChatOptions, type ChatSnapshot, type SentMessage, type MessageQuery } from "./chat.js";
+export { useChatSnapshot } from "./hooks/useChatSnapshot.js";

package/lib/index.js

@@ -41,3 +41,5 @@ export * from "./runtime/socialReadClient";
 export * from "./ux/imagePaste";
 export * from "./hooks/useImageAttachments";
 export * from "./components/ImageAttachmentTray";
+export { createChat, Chat, ChatError } from "./chat.js";
+export { useChatSnapshot } from "./hooks/useChatSnapshot.js";

package/lib/runtime/chatError.d.ts

@@ -0,0 +1,12 @@
+export type ChatErrorCode = "unavailable" | "access-denied" | "storage-unavailable" | "invalid-input" | "conflict" | "closed" | "busy";
+/** Stable recovery categories. The original failure remains available as cause. */
+export declare class ChatError extends Error {
+    readonly code: ChatErrorCode;
+    readonly retryable: boolean;
+    readonly status?: number;
+    constructor(code: ChatErrorCode, message: string, options?: {
+        cause?: unknown;
+        status?: number;
+    });
+}
+export declare function asChatError(error: unknown): ChatError;

package/lib/runtime/chatError.js

@@ -0,0 +1,26 @@
+/** Stable recovery categories. The original failure remains available as cause. */
+export class ChatError extends Error {
+    code;
+    retryable;
+    status;
+    constructor(code, message, options = {}) {
+        super(message, { cause: options.cause });
+        this.code = code;
+        this.name = "ChatError";
+        this.status = options.status;
+        this.retryable = ["unavailable", "storage-unavailable", "busy"].includes(code);
+    }
+}
+export function asChatError(error) {
+    if (error instanceof ChatError)
+        return error;
+    const value = error;
+    const status = value?.status, message = value?.message ?? String(error);
+    const code = status === 401 || status === 403 || /ACCESS_REVOKED|ACCESS_DENIED|SCOPE_CHANGED/.test(message) ? "access-denied"
+        : /CLOSED/.test(message) ? "closed"
+            : status === 409 || /REVISION_CONFLICT|PROJECTION_CHANGED/.test(message) ? "conflict"
+                : /BACKPRESSURE|TOO_LARGE/.test(message) ? "busy"
+                    : status === 400 || /INVALID_|CONVERSATION_MISMATCH|NOT_OWNED/.test(message) ? "invalid-input"
+                        : /QuotaExceeded|DatabaseClosed|UnknownError|AbortError/.test(value?.name ?? "") || /STORAGE_|DATABASE_|CACHE_WRITE/.test(message) ? "storage-unavailable" : "unavailable";
+    return new ChatError(code, message, { cause: error, status });
+}

package/lib/runtime/chatSession.d.ts

@@ -1,3 +1,4 @@
+import { type ConversationTarget } from "./conversationDirectory.js";
 import { type ChatGroup } from "./groupClient.js";
 import type { SocialGroup } from "./socialReadClient.js";
 import { type ChatConversation, type OutgoingContent } from "./outgoingContent.js";
@@ -55,6 +56,7 @@ export type ChatSummarySnapshot<T> = {
 /** Owns all browser message clients. Hosts subscribe to stable thread snapshots. */
 export declare class ChatSession<T extends StoredMessage> {
     private options;
+    private conversations;
     private messages;
     private connection;
     private reading;
@@ -132,26 +134,35 @@ export declare class ChatSession<T extends StoredMessage> {
     private readEarlier;
     private readAll;
     /** Reads trusted local group metadata immediately; SDK refreshes it in the background. */
-    getGroup(thread: ChatConversation, options?: {
+    getGroup(thread: ChatConversation | string, options?: {
         refresh?: boolean;
     }): Promise<ChatGroup>;
     createGroup(thread: ChatConversation, content: {
         title: string;
         members: readonly string[];
     }): Promise<ChatGroup>;
-    updateGroup(thread: ChatConversation, changes: {
+    updateGroup(target: ChatConversation | string, changes: {
         expectedRevision?: string;
         addMembers?: readonly string[];
         removeMembers?: readonly string[];
         title?: string;
         avatar?: string;
     }): Promise<ChatGroup>;
+    sendMessage(threadId: string, input: OutgoingContent, options?: {
+        waitFor?: "accepted" | "delivered";
+    }): Promise<ChatRuntimeMessage>;
     sendMessage(thread: ChatConversation, input: OutgoingContent, options?: {
         waitFor?: "accepted" | "delivered";
     }): Promise<ChatRuntimeMessage>;
     sendMessage(threadId: string, input: SendMessageInput, options?: {
         waitFor?: "accepted" | "delivered";
     }): Promise<ChatRuntimeMessage>;
+    private sendWire;
+    getConversation(target: ConversationTarget): Promise<string>;
+    private sendContent;
+    private resolveConversation;
+    /** Validated target identity survives content redaction; no roster is exposed. */
+    getConversationTarget(threadId: string): ChatConversation | undefined;
     private sendControl;
     getReaders(threadId: string, messageId: string, page?: Omit<MessageReadersQuery, "threadId" | "messageId">, signal?: AbortSignal): Promise<import("./messageReaders.js").MessageReadersPage>;
     /** Resolve voice media uniformly; pending local bytes are loaded only on demand. */
@@ -168,8 +179,12 @@ export declare class ChatSession<T extends StoredMessage> {
     getSnapshot(): ChatSummarySnapshot<T>;
     getSnapshot(threadId: string): ChatThreadSnapshot<T>;
     private buildThreadSnapshot;
-    subscribe(listener: () => void): () => void;
-    subscribe(threadId: string, listener: () => void, fields?: readonly (keyof ChatThreadSnapshot<T>)[]): () => void;
+    /** Delivers the current stable snapshot immediately, then only meaningful changes. */
+    subscribe(listener: (snapshot: ChatSummarySnapshot<T>) => void): () => void;
+    subscribe(threadId: string, listener: (snapshot: ChatThreadSnapshot<T>) => void, fields?: readonly (keyof ChatThreadSnapshot<T>)[]): () => void;
+    /** Change-only bridge for useSyncExternalStore and other framework adapters. */
+    subscribeChanges(listener: () => void): () => void;
+    subscribeChanges(threadId: string, listener: () => void, fields?: readonly (keyof ChatThreadSnapshot<T>)[]): () => void;
     private publishAll;
     private buildGlobal;
     private publishGlobal;
@@ -177,6 +192,7 @@ export declare class ChatSession<T extends StoredMessage> {
     /** Permanently retire this identity/team session. UI withdrawal is immediate;
      * completion means all durable stores have crossed the same authority epoch. */
     revokeAccess(): Promise<void>;
+    get active(): boolean;
     close(): Promise<void>;
     private dispose;
 }

package/lib/runtime/chatSession.js

@@ -1,7 +1,8 @@
+import { ConversationDirectory } from "./conversationDirectory.js";
 import { groupThreadId } from "./thread.js";
 import { GroupClient } from "./groupClient.js";
 import { isReadingControl } from "./readingContent.js";
-import { outgoingContent } from "./outgoingContent.js";
+import { outgoingContent, validateConversation } from "./outgoingContent.js";
 import { projectMessageTimeline } from "./messageTimeline.js";
 import { projectConversationReading } from "./conversationReading.js";
 import { ReadCountsClient } from "./readCounts.js";
@@ -15,6 +16,7 @@ import { unreadInConversation } from "./readIndex.js";
 /** Owns all browser message clients. Hosts subscribe to stable thread snapshots. */
 export class ChatSession {
     options;
+    conversations;
     messages;
     connection;
     reading;
@@ -68,6 +70,7 @@ export class ChatSession {
                 throw new Error("CHAT_SESSION_SCOPE_MISMATCH");
         }
         this.messages = new MessageClient(options.messages);
+        this.conversations = new ConversationDirectory(scope, () => this.messages.scopeAccess());
         this.connection = options.sharedConnection ?? new ChatClient({ ...options.connection, onReach: async (event) => {
                 const handled = await this.handleReach(event);
                 if (handled)
@@ -379,11 +382,11 @@ export class ChatSession {
         throw new Error("MESSAGE_SYNC_RESET_REQUIRED");
     }
     /** Reads trusted local group metadata immediately; SDK refreshes it in the background. */
-    getGroup(thread, options = {}) {
+    async getGroup(thread, options = {}) {
         this.assertOpen();
         if (!this.groups)
             throw new Error("GROUP_METADATA_UNAVAILABLE");
-        return this.groups.get(thread, options);
+        return this.groups.get(typeof thread === "string" ? await this.resolveConversation(thread) : thread, options);
     }
     async createGroup(thread, content) {
         this.assertOpen();
@@ -392,7 +395,8 @@ export class ChatSession {
         await this.sendMessage(thread, { groupCreate: content }, { waitFor: "delivered" });
         return this.groups.after(thread, 1);
     }
-    async updateGroup(thread, changes) {
+    async updateGroup(target, changes) {
+        const thread = typeof target === "string" ? await this.resolveConversation(target) : target;
         const previous = await this.getGroup(thread);
         if (previous.versionNumber >= Number.MAX_SAFE_INTEGER)
             throw new Error("INVALID_GROUP_VERSION");
@@ -403,14 +407,61 @@ export class ChatSession {
         this.assertOpen();
         if (options.waitFor !== undefined && !["accepted", "delivered"].includes(options.waitFor))
             throw new Error("INVALID_MESSAGE_WAIT");
-        const threadId = typeof thread === "string" ? thread : thread.id;
-        const wire = typeof thread === "string" ? input : outgoingContent(this.options.messages.scope, thread, input);
-        const delivered = options.waitFor === "delivered";
-        if (typeof thread !== "string" && (input.recall || input.reaction))
-            return this.sendControl({ id: thread.id, kind: thread.kind, targetId: thread.targetId, teamId: thread.teamId, memberIds: wire.recipients }, wire, delivered);
+        if (typeof thread === "string" && Object.hasOwn(input, "body"))
+            return this.sendWire(thread, input, options.waitFor === "delivered");
+        return this.sendContent(thread, input, options.waitFor === "delivered");
+    }
+    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; });
     }
+    getConversation(target) { this.assertOpen(); return this.conversations.create(target); }
+    async sendContent(target, input, delivered) {
+        let thread = typeof target === "string" ? await this.resolveConversation(target) : target;
+        validateConversation(this.options.messages.scope, thread);
+        await this.conversations.put(thread);
+        this.assertOpen();
+        // Recipients are SDK-owned metadata, never an App-supplied roster.
+        if (thread.kind === "group" && !input.groupCreate && !input.groupUpdate) {
+            const group = await this.getGroup(thread);
+            this.assertOpen();
+            thread = { ...thread, memberIds: group.memberIds };
+        }
+        const wire = outgoingContent(this.options.messages.scope, thread, input);
+        if (input.recall || input.reaction)
+            return this.sendControl({ ...thread, memberIds: wire.recipients }, wire, delivered);
+        return this.sendWire(thread.id, wire, delivered);
+    }
+    async resolveConversation(threadId) {
+        const known = await this.conversations.get(threadId);
+        if (known)
+            return known;
+        const inferred = this.getConversationTarget(threadId);
+        if (!inferred)
+            throw new Error("MESSAGE_CONVERSATION_UNKNOWN");
+        return inferred;
+    }
+    /** Validated target identity survives content redaction; no roster is exposed. */
+    getConversationTarget(threadId) {
+        const scope = this.options.messages.scope;
+        const group = this.getSnapshot(threadId).group;
+        if (group)
+            return { id: threadId, kind: "group", targetId: group.groupId, teamId: scope.teamId };
+        for (const value of this.getSnapshot(threadId).messages) {
+            const row = value;
+            const kind = row.threadKind ?? row.body?.threadKind;
+            if ((kind !== "group" && kind !== "dm") || !row.to || !row.from)
+                continue;
+            const thread = { id: threadId, kind, targetId: kind === "group" || row.from === scope.profileId ? row.to : row.from, teamId: scope.teamId };
+            // A stored row is only a hint; validate the canonical scoped identifier.
+            try {
+                validateConversation(scope, thread);
+                return thread;
+            }
+            catch { }
+        }
+        return undefined;
+    }
     sendControl(thread, wire, delivered = false) {
         const content = wire.body.content;
         const recall = content.recall, reaction = content.reaction;
@@ -643,6 +694,33 @@ export class ChatSession {
         return { group: this.groups?.snapshot(threadId).data, timeline, messages, hasEarlier: source?.hasEarlier ?? false, resetVersion: source?.resetVersion ?? 0, complete: source?.complete ?? false, outgoing, readCounts: this.countSnapshots.get(threadId), unread, messageReading };
     }
     subscribe(target, listener, fields) {
+        if (typeof target === "function") {
+            const notify = () => target(this.getSnapshot());
+            const off = this.subscribeChanges(notify);
+            try {
+                notify();
+            }
+            catch (error) {
+                off();
+                throw error;
+            }
+            return off;
+        }
+        const notify = () => listener(this.getSnapshot(target));
+        const off = this.subscribeChanges(target, notify, fields);
+        // The deprecated field-array form retains change-only behavior during migration.
+        if (!fields) {
+            try {
+                notify();
+            }
+            catch (error) {
+                off();
+                throw error;
+            }
+        }
+        return off;
+    }
+    subscribeChanges(target, listener, fields) {
         if (this.closed || this.withdrawn)
             return () => { };
         if (typeof target === "function") {
@@ -771,7 +849,7 @@ export class ChatSession {
             const results = await Promise.allSettled([
                 this.sender.revoke(version),
                 this.reading.revokeTeam(this.options.messages.scope.teamId, version, knownThreads),
-                this.readers.retireScope(version), this.counts?.retireScope(version), this.groups?.retire(version),
+                this.readers.retireScope(version), this.counts?.retireScope(version), this.groups?.retire(version), this.conversations.retire(version),
             ]);
             for (const result of results)
                 if (result.status === "rejected")
@@ -786,6 +864,7 @@ export class ChatSession {
                 throw new AggregateError(failures, "CHAT_ACCESS_CLEANUP_FAILED");
         });
     }
+    get active() { return !this.closed && !this.withdrawn; }
     close() { return this.revoking ?? this.dispose(); }
     dispose() {
         return this.closing ??= (async () => {
@@ -799,7 +878,7 @@ export class ChatSession {
             const readingBarrier = Promise.allSettled([...this.acceptedReading, ...this.acceptedControls]);
             const readingClosing = readingBarrier.then(() => this.reading.close());
             try {
-                const results = await Promise.allSettled([this.counts?.close(), ...this.countClosings, this.readers.close(), groupsClosing, senderClosing, readingClosing, this.messages.close(Promise.allSettled([senderClosing, groupsClosing, readingBarrier]))]);
+                const results = await Promise.allSettled([this.counts?.close(), ...this.countClosings, this.readers.close(), this.conversations.close(), groupsClosing, senderClosing, readingClosing, this.messages.close(Promise.allSettled([senderClosing, groupsClosing, readingBarrier]))]);
                 const failed = results.find((result) => result.status === "rejected");
                 if (failed)
                     throw failed.reason;

package/lib/runtime/conversationDirectory.d.ts

@@ -0,0 +1,36 @@
+import type { ResponseCacheAccess } from "./responseCache.js";
+import { type MessageScope } from "./messageStore.js";
+import { type ChatConversation } from "./outgoingContent.js";
+export type ConversationTarget = {
+    peerId: string;
+    groupId?: never;
+} | {
+    groupId: string;
+    peerId?: never;
+};
+/** Canonical target identities only; rosters always belong to GroupClient. */
+export declare class ConversationDirectory {
+    private scope;
+    private access;
+    private cache;
+    private memory;
+    private pending;
+    private queue;
+    private writes;
+    private version;
+    private authority;
+    private scheduled;
+    private closed;
+    private retired;
+    constructor(scope: MessageScope, access: ResponseCacheAccess);
+    private authorize;
+    private assertOpen;
+    private remember;
+    create(target: ConversationTarget): Promise<string>;
+    put(thread: ChatConversation): Promise<ChatConversation>;
+    private persist;
+    get(id: string): Promise<ChatConversation | undefined>;
+    private flush;
+    retire(version: number): Promise<void>;
+    close(): Promise<void>;
+}

package/lib/runtime/conversationDirectory.js

@@ -0,0 +1,116 @@
+import { IndexedDbResponseCache } from "./responseCache.js";
+import { messageScopeKey } from "./messageStore.js";
+import { validateConversation } from "./outgoingContent.js";
+import { dmThreadId, groupThreadId } from "./thread.js";
+/** Canonical target identities only; rosters always belong to GroupClient. */
+export class ConversationDirectory {
+    scope;
+    access;
+    cache;
+    memory = new Map();
+    pending = new Map();
+    queue = [];
+    writes = new Map();
+    version;
+    authority;
+    scheduled = false;
+    closed = false;
+    retired = false;
+    constructor(scope, access) {
+        this.scope = scope;
+        this.access = access;
+        this.cache = new IndexedDbResponseCache(`conversations:${messageScopeKey(scope)}`, { access: () => this.authorize(), entries: 256, recordBytes: 4096 });
+    }
+    authorize() { return this.authority ??= this.access().finally(() => { this.authority = undefined; }); }
+    assertOpen() { if (this.retired)
+        throw new Error("CHAT_ACCESS_REVOKED"); if (this.closed)
+        throw new Error("CHAT_SESSION_CLOSED"); }
+    remember(thread) {
+        this.memory.delete(thread.id);
+        this.memory.set(thread.id, thread);
+        if (this.memory.size > 256)
+            this.memory.delete(this.memory.keys().next().value);
+        return thread;
+    }
+    async create(target) {
+        const kind = target.groupId !== undefined ? "group" : "dm", targetId = target.groupId ?? target.peerId;
+        if (target.groupId !== undefined && target.peerId !== undefined)
+            throw new Error("INVALID_MESSAGE_CONVERSATION");
+        const id = kind === "group" ? groupThreadId(this.scope.appId, targetId, this.scope.teamId) : dmThreadId(this.scope.appId, this.scope.profileId, targetId, this.scope.teamId);
+        await this.put({ id, kind, targetId, teamId: this.scope.teamId });
+        return id;
+    }
+    put(thread) {
+        this.assertOpen();
+        validateConversation(this.scope, thread);
+        const existing = this.writes.get(thread.id);
+        if (existing)
+            return existing;
+        if (this.writes.size >= 128)
+            return Promise.reject(new Error("CONVERSATION_BACKPRESSURE"));
+        const task = this.persist(thread).finally(() => this.writes.delete(thread.id));
+        this.writes.set(thread.id, task);
+        return task;
+    }
+    async persist(thread) {
+        this.assertOpen();
+        validateConversation(this.scope, thread);
+        const value = { id: thread.id, kind: thread.kind, targetId: thread.targetId, teamId: this.scope.teamId };
+        const previous = await this.get(thread.id);
+        if (previous) {
+            if (previous.kind !== value.kind || previous.targetId !== value.targetId)
+                throw new Error("MESSAGE_CONVERSATION_MISMATCH");
+            return previous;
+        }
+        const row = await this.cache.read(thread.id);
+        await this.cache.write(thread.id, value, row.epoch);
+        this.assertOpen();
+        return this.remember(value);
+    }
+    async get(id) {
+        this.assertOpen();
+        const authority = await this.authorize();
+        this.assertOpen();
+        if (!authority.allowed)
+            throw new Error("CHAT_ACCESS_REVOKED");
+        if (this.version !== undefined && this.version !== authority.version)
+            this.memory.clear();
+        this.version = authority.version;
+        const known = this.memory.get(id);
+        if (known)
+            return this.remember(known);
+        const existing = this.pending.get(id);
+        if (existing)
+            return existing;
+        if (this.pending.size >= 128)
+            throw new Error("CONVERSATION_BACKPRESSURE");
+        const task = new Promise((resolve, reject) => this.queue.push({ id, resolve, reject })).finally(() => this.pending.delete(id));
+        this.pending.set(id, task);
+        if (!this.scheduled) {
+            this.scheduled = true;
+            queueMicrotask(() => { this.scheduled = false; void this.flush(); });
+        }
+        return task;
+    }
+    async flush() {
+        const batch = this.queue.splice(0, 128);
+        try {
+            const rows = await this.cache.readMany(batch.map(item => item.id));
+            this.assertOpen();
+            for (const item of batch) {
+                const value = rows.get(item.id)?.cached?.value;
+                if (value) {
+                    if (value.id !== item.id)
+                        throw new Error("MESSAGE_CONVERSATION_MISMATCH");
+                    validateConversation(this.scope, value);
+                }
+                item.resolve(value ? this.remember(value) : undefined);
+            }
+        }
+        catch (error) {
+            batch.forEach(item => item.reject(error));
+        }
+    }
+    retire(version) { this.retired = true; this.memory.clear(); return this.cache.retire(version); }
+    async close() { this.closed = true; this.memory.clear(); await Promise.allSettled([...this.pending.values(), ...this.writes.values()]); await this.cache.close(); }
+}

package/lib/runtime/index.d.ts

@@ -35,3 +35,4 @@ export { projectMessageTimeline, type TimelineItem, type TimelineReaction, type
 export * from "./messageLaunch.js";
 export * from "./outgoingContent.js";
 export type { ChatGroup } from "./groupClient.js";
+export type { ConversationTarget } from "./conversationDirectory.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.12.0-next.61",
-  "description": "Cross-platform PMate chat input components, voice input primitives, and ASR helpers",
+  "version": "0.12.0-next.63",
+  "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",
@@ -28,6 +28,11 @@
       "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"
     }
   },
   "publishConfig": {