@pmate/chat-sdk 0.12.0-next.5 → 0.12.0-next.51

package/lib/runtime/durableSender.js

@@ -5,8 +5,24 @@ import { messageScopeKey } from "./messageStore.js";
 export class DurableChatSender {
     client;
     onError;
+    options;
     db;
     outbox;
+    epochs;
+    localUrls = new Map();
+    localViews = new WeakMap();
+    uploads = new Set();
+    uploadTail = Promise.resolve();
+    uploadWaiting = 0;
+    confirmationQueue = [];
+    confirmationTimer;
+    confirmationRunning;
+    confirmationSize = 0;
+    version = 0;
+    withdrawn = false;
+    revoking;
+    channel;
+    accepted = new Set();
     scope;
     identity;
     values = new Map();
@@ -14,33 +30,198 @@ export class DurableChatSender {
     listeners = new Set();
     running = new Map();
     closed = false;
+    closing = false;
+    empty = [];
     offConnection;
     ready;
     constructor(client, scope, onError, options = {}) {
         this.client = client;
         this.onError = onError;
+        this.options = options;
         this.scope = messageScopeKey(scope);
         this.identity = { ...scope };
         this.db = new Dexie(options.name ?? "pmate-chat-outbox", { indexedDB: options.indexedDB ?? globalThis.indexedDB, IDBKeyRange: globalThis.IDBKeyRange });
         this.db.version(1).stores({ outbox: "[scope+hash],scope,[scope+threadId]" });
+        this.db.version(2).stores({ scopeEpochs: "scope" });
+        this.db.version(3).stores({ outbox: "[scope+hash],scope,[scope+threadId],[scope+pendingState+hash]" });
         this.outbox = this.db.table("outbox");
-        this.ready = this.outbox.where("scope").equals(this.scope).toArray().then(records => {
-            if (this.closed)
-                return;
-            records.filter(record => !record.confirmed).forEach(record => this.values.set(record.hash, record));
-            this.emit();
-        });
+        this.epochs = this.db.table("scopeEpochs");
+        this.outbox.hook("creating", (_key, row) => { row.pendingState = row.confirmed ? 0 : 1; });
+        this.outbox.hook("updating", (changes, _key, row) => ({ pendingState: (Object.hasOwn(changes, "confirmed") ? changes.confirmed : row.confirmed) ? 0 : 1 }));
+        this.db.on("versionchange", () => { this.db.close({ disableAutoOpen: false }); return false; });
+        this.ready = this.restore();
+        void this.ready.catch(() => { });
+        if (typeof BroadcastChannel !== "undefined") {
+            this.channel = new BroadcastChannel(`pmate-chat-outbox:${this.scope}:${this.db.name}`);
+            this.channel.onmessage = event => { if (Number.isSafeInteger(event.data?.version) && event.data.version > this.version)
+                this.withdraw(); };
+        }
         this.offConnection = client.watchConnection(state => {
             if (state === "connected")
                 void this.resume().catch(onError);
         });
     }
+    /** Read only the selected durable rows, without restoring or delivering an outbox. */
+    static async readSelected(scope, threadId, ids, version, options = {}) {
+        if (ids.length > 100)
+            throw new Error("INVALID_OUTBOX_SELECTION");
+        const key = messageScopeKey(scope), db = new Dexie(options.name ?? "pmate-chat-outbox", { indexedDB: options.indexedDB ?? globalThis.indexedDB, IDBKeyRange: globalThis.IDBKeyRange });
+        db.version(1).stores({ outbox: "[scope+hash],scope,[scope+threadId]" });
+        db.version(2).stores({ scopeEpochs: "scope" });
+        db.version(3).stores({ outbox: "[scope+hash],scope,[scope+threadId],[scope+pendingState+hash]" });
+        try {
+            return await db.transaction("r", db.table("outbox"), db.table("scopeEpochs"), async () => {
+                if (((await db.table("scopeEpochs").get(key))?.version ?? 0) !== version)
+                    return [];
+                const rows = await db.table("outbox").bulkGet(ids.map(id => [key, id]));
+                return rows.flatMap(row => row && row.scope === key && row.threadId === threadId && !row.confirmed && (row.accessVersion ?? 0) === version ? [row] : []);
+            });
+        }
+        finally {
+            db.close();
+        }
+    }
+    async readAccess() {
+        const access = await this.options.access?.();
+        if (access && (!Number.isSafeInteger(access.version) || access.version < 0 || typeof access.allowed !== "boolean"))
+            throw new Error("INVALID_OUTBOX_ACCESS");
+        return access;
+    }
+    async restore() {
+        const access = await this.readAccess();
+        const loaded = await this.db.transaction("rw", this.outbox, this.epochs, async () => {
+            const current = (await this.epochs.get(this.scope))?.version ?? 0;
+            const version = access?.version ?? current;
+            if (version < current)
+                throw new Error("OUTBOX_SCOPE_CHANGED");
+            if (version > current) {
+                await this.epochs.put({ scope: this.scope, version });
+                await this.deleteRows();
+            }
+            const total = await this.outbox.where("scope").equals(this.scope).count();
+            const indexed = await this.outbox.where("[scope+pendingState+hash]").between([this.scope, 0, Dexie.minKey], [this.scope, 1, Dexie.maxKey], true, true).count();
+            return { version, advanced: version > current, legacy: total !== indexed };
+        });
+        this.version = loaded.version;
+        if (loaded.advanced)
+            this.channel?.postMessage({ version: this.version });
+        if (this.closed || this.withdrawn)
+            return;
+        const current = await this.readAccess();
+        if (current && (!current.allowed || current.version !== this.version))
+            return;
+        if (access?.allowed === false)
+            return;
+        let after;
+        const restored = new Map();
+        while (!this.closed && !this.withdrawn) {
+            const batch = await this.db.transaction("rw", this.outbox, this.epochs, async () => {
+                if (((await this.epochs.get(this.scope))?.version ?? 0) !== this.version)
+                    throw new Error("OUTBOX_SCOPE_CHANGED");
+                const keys = await (loaded.legacy
+                    ? this.outbox.where("[scope+hash]").between([this.scope, after ?? Dexie.minKey], [this.scope, Dexie.maxKey], after === undefined, true)
+                    : this.outbox.where("[scope+pendingState+hash]").between([this.scope, 1, after ?? Dexie.minKey], [this.scope, 1, Dexie.maxKey], after === undefined, true)).limit(128).primaryKeys();
+                if (!keys.length)
+                    return { last: undefined, records: [] };
+                const last = keys.at(-1)[1];
+                // Key-only metadata covers confirmed history without reading wire bodies.
+                // Missing metadata identifies rows written by an older SDK after upgrade.
+                const confirmed = loaded.legacy ? await this.outbox.where("[scope+pendingState+hash]").between([this.scope, 0, keys[0][1]], [this.scope, 0, last], true, true).primaryKeys() : [];
+                const confirmedHashes = new Set(confirmed.map(key => key[1]));
+                const needed = keys.filter(key => !confirmedHashes.has(key[1]));
+                const rows = (await this.outbox.bulkGet(needed)).filter((row) => Boolean(row));
+                const repairs = rows.filter(row => row.pendingState !== (row.confirmed ? 0 : 1));
+                if (repairs.length)
+                    await this.outbox.bulkPut(repairs.map(row => ({ ...row, pendingState: row.confirmed ? 0 : 1 })));
+                return { last, records: rows.filter(row => !row.confirmed && (row.accessVersion ?? 0) === this.version) };
+            });
+            for (const row of batch.records)
+                restored.set(row.hash, row);
+            if (batch.last === undefined)
+                break;
+            after = batch.last;
+            // Leave the database transaction before yielding to input/rendering work.
+            await new Promise(resolve => setTimeout(resolve, 0));
+        }
+        if (this.closed || this.withdrawn)
+            return;
+        const latest = await this.readAccess();
+        if (latest && (!latest.allowed || latest.version !== this.version))
+            return;
+        this.values = restored;
+        this.emit();
+    }
+    async checkAccess() {
+        if (this.closed)
+            throw new Error("CHAT_SENDER_CLOSED");
+        if (this.withdrawn)
+            throw new Error("OUTBOX_ACCESS_REVOKED");
+        const access = await this.readAccess();
+        if (access && access.version !== this.version) {
+            this.withdraw();
+            throw new Error("OUTBOX_SCOPE_CHANGED");
+        }
+        if (access && !access.allowed)
+            throw new Error("OUTBOX_ACCESS_REVOKED");
+    }
+    async withEpoch(mode, operation) {
+        await this.checkAccess();
+        try {
+            return await this.db.transaction(mode, this.outbox, this.epochs, async () => {
+                if (this.closed || this.withdrawn)
+                    throw new Error("OUTBOX_ACCESS_REVOKED");
+                if (((await this.epochs.get(this.scope))?.version ?? 0) !== this.version)
+                    throw new Error("OUTBOX_SCOPE_CHANGED");
+                return operation();
+            });
+        }
+        catch (error) {
+            if (String(error).includes("OUTBOX_SCOPE_CHANGED"))
+                this.withdraw();
+            throw error;
+        }
+    }
+    deleteRows() { return this.outbox.where("[scope+hash]").between([this.scope, Dexie.minKey], [this.scope, Dexie.maxKey], true, true).delete(); }
+    /** Stop disclosure immediately; durable invalidation is coordinated separately. */
+    withdraw() {
+        this.withdrawn = true;
+        this.failConfirmations(new Error("OUTBOX_ACCESS_REVOKED"));
+        this.uploads.forEach(controller => controller.abort());
+        this.releaseUrls();
+        this.values.clear();
+        this.emit();
+    }
+    revoke(targetVersion) {
+        if (this.closed || this.closing)
+            return Promise.reject(new Error("CHAT_SENDER_CLOSED"));
+        if (this.revoking)
+            return this.revoking;
+        this.withdraw();
+        return this.revoking = (async () => {
+            await this.ready.catch(error => { if (!String(error).includes("OUTBOX_SCOPE_CHANGED"))
+                throw error; });
+            const version = await this.db.transaction("rw", this.outbox, this.epochs, async () => {
+                const current = (await this.epochs.get(this.scope))?.version ?? 0;
+                const target = targetVersion ?? this.version + 1;
+                if (!Number.isSafeInteger(target) || target < 0)
+                    throw new Error("INVALID_OUTBOX_EPOCH");
+                if (current >= target)
+                    return current;
+                await this.epochs.put({ scope: this.scope, version: target });
+                await this.deleteRows();
+                return target;
+            });
+            this.channel?.postMessage({ version });
+        })();
+    }
     initialize() { return this.ready; }
     subscribe(listener) { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; }
     snapshot(threadId) {
+        if (this.closed || this.closing || this.withdrawn)
+            return this.empty;
         let snapshot = this.snapshots.get(threadId);
         if (!snapshot) {
-            snapshot = [...this.values.values()].filter(record => threadId === undefined || record.threadId === threadId);
+            snapshot = [...this.values.values()].filter(record => threadId === undefined || record.threadId === threadId).map(record => this.localView(record));
             this.snapshots.set(threadId, snapshot);
         }
         return snapshot;
@@ -50,7 +231,8 @@ export class DurableChatSender {
     /** Resolves after the exact wire message is durable, independently of network delivery. */
     async enqueue(threadId, input) {
         const message = await this.persistOutgoing(threadId, input);
-        void this.retry(message.hash).catch(error => this.onError(error));
+        if (!this.closed && !this.closing && !this.withdrawn)
+            void this.retry(message.hash).catch(error => this.onError(error));
         return message;
     }
     /** Compatibility API: resolves only after transport delivery. */
@@ -58,23 +240,32 @@ export class DurableChatSender {
         const message = await this.persistOutgoing(threadId, input);
         return this.retry(message.hash);
     }
-    async persistOutgoing(threadId, input) {
-        await this.ready;
-        if (this.closed)
-            throw new Error("CHAT_SENDER_CLOSED");
-        const message = this.client.prepareChat(input.to, withChatTeam(input.body, this.identity.teamId), input.recipients);
-        if (message.from !== this.identity.profileId)
-            throw new Error("OUTGOING_MESSAGE_IDENTITY_MISMATCH");
-        const record = { scope: this.scope, threadId, hash: message.hash, message, status: "sending" };
-        await this.outbox.put(record);
-        if (this.closed)
-            throw new Error("CHAT_SENDER_CLOSED");
-        this.values.set(record.hash, record);
-        this.emit();
-        return message;
+    persistOutgoing(threadId, input) {
+        if (this.closed || this.closing || this.withdrawn)
+            return Promise.reject(new Error("OUTBOX_ACCESS_REVOKED"));
+        const pending = (async () => {
+            await this.ready;
+            await this.checkAccess();
+            const message = this.client.prepareChat(input.to, withChatTeam(input.body, this.identity.teamId), input.recipients);
+            if (message.from !== this.identity.profileId)
+                throw new Error("OUTGOING_MESSAGE_IDENTITY_MISMATCH");
+            if (input.voiceBlob) {
+                const body = message.body;
+                if (!(input.voiceBlob instanceof Blob) || input.voiceBlob.size === 0 || input.voiceBlob.size > 16 * 1024 * 1024 || body.kind !== "message" || !validVoice(body.content.voice))
+                    throw new Error("INVALID_VOICE_ATTACHMENT");
+            }
+            const record = { ...(input.voiceBlob ? { voiceData: { bytes: await input.voiceBlob.arrayBuffer(), type: input.voiceBlob.type } } : {}), scope: this.scope, threadId, hash: message.hash, message, status: "sending", accessVersion: this.version };
+            await this.withEpoch("rw", async () => { await this.outbox.put(record); });
+            await this.checkAccess();
+            this.values.set(record.hash, record);
+            this.emit();
+            return message;
+        })().finally(() => this.accepted.delete(pending));
+        this.accepted.add(pending);
+        return pending;
     }
     retry(hash) {
-        if (this.closed)
+        if (this.closed || this.closing || this.withdrawn)
             return Promise.reject(new Error("CHAT_SENDER_CLOSED"));
         const running = this.running.get(hash);
         if (running)
@@ -85,8 +276,8 @@ export class DurableChatSender {
     }
     async transmit(hash) {
         await this.ready;
-        const record = await this.outbox.get([this.scope, hash]);
-        if (!record || this.closed)
+        let record = await this.withEpoch("r", async () => this.outbox.get([this.scope, hash]));
+        if (!record || this.closed || this.withdrawn)
             throw new Error("OUTGOING_MESSAGE_UNAVAILABLE");
         if (record.status === "sent" || record.confirmed)
             return record.message;
@@ -96,15 +287,24 @@ export class DurableChatSender {
             if (!latest || latest.confirmed || latest.status === "sent")
                 return latest?.message ?? record.message;
         }
+        await this.checkAccess();
         if (this.values.get(hash)?.status !== "sending") {
             this.values.set(hash, sending);
             this.emit();
         }
         try {
+            if (hasVoice(record)) {
+                record = await this.prepareVoice(record);
+                if (record.confirmed || record.status === "sent")
+                    return record.message;
+            }
+            await this.checkAccess();
+            if (this.closing)
+                throw new Error("CHAT_SENDER_CLOSED");
             const message = await this.client.sendPrepared(record.message);
             const sent = { ...record, message, status: "sent" };
             const committed = await this.save(sent);
-            if (!this.closed) {
+            if (!this.closed && !this.withdrawn) {
                 if (committed?.confirmed || !committed)
                     this.values.delete(hash);
                 else
@@ -114,7 +314,7 @@ export class DurableChatSender {
             return message;
         }
         catch (error) {
-            if (!this.closed) {
+            if (!this.closed && !this.withdrawn) {
                 const failed = { ...record, status: "failed" };
                 const committed = await this.save(failed);
                 if (committed?.confirmed || committed?.status === "sent") {
@@ -131,42 +331,196 @@ export class DurableChatSender {
             throw error;
         }
     }
+    releaseUrl(hash) { const value = this.localUrls.get(hash); if (value) {
+        URL.revokeObjectURL(value.url);
+        this.localUrls.delete(hash);
+    } }
+    releaseUrls() { for (const hash of this.localUrls.keys())
+        this.releaseUrl(hash); }
+    localView(record) {
+        if (!hasVoice(record) || typeof URL.createObjectURL !== "function")
+            return record;
+        let cached = this.localViews.get(record);
+        if (cached)
+            return cached;
+        const blob = voiceBlob(record);
+        let local = this.localUrls.get(record.hash);
+        if (!local || local.blob !== blob) {
+            this.releaseUrl(record.hash);
+            local = { blob, url: URL.createObjectURL(blob) };
+            this.localUrls.set(record.hash, local);
+        }
+        cached = { ...record, voiceBlob: blob, message: withVoiceUrl(record.message, local.url) };
+        this.localViews.set(record, cached);
+        return cached;
+    }
+    async prepareVoice(record) {
+        if (this.uploadWaiting >= 32)
+            throw new Error("VOICE_UPLOAD_BACKPRESSURE");
+        this.uploadWaiting++;
+        const previous = this.uploadTail;
+        let release;
+        this.uploadTail = new Promise(resolve => { release = resolve; });
+        try {
+            await previous;
+            await this.checkAccess();
+            if (this.closing)
+                throw new Error("CHAT_SENDER_CLOSED");
+            const latest = await this.withEpoch("r", () => this.outbox.get([this.scope, record.hash]));
+            if (!latest)
+                throw new Error("OUTGOING_MESSAGE_UNAVAILABLE");
+            if (!hasVoice(latest) || latest.confirmed || latest.status === "sent")
+                return latest;
+            if (!this.options.uploadVoice)
+                throw new Error("VOICE_UPLOAD_UNAVAILABLE");
+            const controller = new AbortController();
+            this.uploads.add(controller);
+            const timeout = setTimeout(() => controller.abort(), 30_000);
+            let url;
+            try {
+                url = await this.options.uploadVoice(voiceBlob(latest), controller.signal);
+            }
+            finally {
+                clearTimeout(timeout);
+                this.uploads.delete(controller);
+            }
+            const parsed = new URL(url);
+            if (!["https:", "http:"].includes(parsed.protocol) || parsed.username || parsed.password)
+                throw new Error("INVALID_VOICE_UPLOAD_URL");
+            await this.checkAccess();
+            if (this.closing)
+                throw new Error("CHAT_SENDER_CLOSED");
+            const { voiceBlob: _blob, voiceData: _data, ...uploaded } = latest;
+            const committed = await this.withEpoch("rw", async () => {
+                const current = await this.outbox.get([this.scope, record.hash]);
+                if (!current || current.confirmed || current.status === "sent" || !hasVoice(current))
+                    return current;
+                const next = { ...uploaded, message: withVoiceUrl(latest.message, url) };
+                await this.outbox.put(next);
+                return next;
+            });
+            if (!committed)
+                throw new Error("OUTGOING_MESSAGE_UNAVAILABLE");
+            this.values.set(record.hash, committed);
+            this.emit();
+            return committed;
+        }
+        finally {
+            this.uploadWaiting--;
+            release();
+        }
+    }
     async save(record) {
-        return this.db.transaction("rw", this.outbox, async () => {
+        return this.withEpoch("rw", async () => {
             const previous = await this.outbox.get([this.scope, record.hash]);
             if (!previous || previous.confirmed || previous.status === "sent")
                 return previous;
+            // A second document may already have durably replaced the Blob with its URL.
+            if (hasVoice(record) && !hasVoice(previous))
+                return previous;
             await this.outbox.put(record);
             return record;
         });
     }
     /** Confirm only after the authoritative message has been durably merged.
      * A tombstone prevents another tab's late failure from recreating the outbox. */
-    async confirm(hashes) {
+    confirm(hashes) {
         hashes = [...new Set(hashes)];
         if (!hashes.length)
+            return Promise.resolve();
+        if (this.closed || this.closing || this.withdrawn)
+            return Promise.reject(new Error("OUTBOX_ACCESS_REVOKED"));
+        if (this.confirmationSize + hashes.length > 4096)
+            return Promise.reject(new Error("OUTBOX_CONFIRM_BACKPRESSURE"));
+        const pending = new Promise((resolve, reject) => this.confirmationQueue.push({ hashes, resolve, reject }));
+        this.confirmationSize += hashes.length;
+        this.scheduleConfirmations();
+        return pending;
+    }
+    scheduleConfirmations() {
+        if (this.confirmationTimer !== undefined || this.confirmationRunning || !this.confirmationQueue.length)
             return;
-        await this.ready;
-        await this.db.transaction("rw", this.outbox, async () => {
-            const previous = await this.outbox.bulkGet(hashes.map(hash => [this.scope, hash]));
-            const confirmed = previous.filter((record) => Boolean(record && !record.confirmed)).map(record => ({ ...record, status: "sent", confirmed: true }));
-            if (confirmed.length)
-                await this.outbox.bulkPut(confirmed);
+        this.confirmationTimer = setTimeout(() => { this.confirmationTimer = undefined; void this.drainConfirmations(); }, 16);
+    }
+    drainConfirmations() {
+        if (this.confirmationRunning)
+            return this.confirmationRunning;
+        const batch = this.confirmationQueue.splice(0);
+        if (!batch.length)
+            return Promise.resolve();
+        const size = batch.reduce((sum, item) => sum + item.hashes.length, 0);
+        return this.confirmationRunning = (async () => {
+            let failed = false, error;
+            try {
+                await this.confirmNow([...new Set(batch.flatMap(item => item.hashes))]);
+            }
+            catch (reason) {
+                failed = true;
+                error = reason;
+            }
+            this.confirmationSize -= size;
+            for (const item of batch)
+                if (failed)
+                    item.reject(error);
+                else
+                    item.resolve();
+        })().finally(() => {
+            this.confirmationRunning = undefined;
+            this.scheduleConfirmations();
         });
+    }
+    failConfirmations(error) {
+        clearTimeout(this.confirmationTimer);
+        this.confirmationTimer = undefined;
+        for (const item of this.confirmationQueue.splice(0)) {
+            this.confirmationSize -= item.hashes.length;
+            item.reject(error);
+        }
+    }
+    async flushConfirmations() {
+        while (this.confirmationRunning || this.confirmationQueue.length) {
+            clearTimeout(this.confirmationTimer);
+            this.confirmationTimer = undefined;
+            await (this.confirmationRunning ?? this.drainConfirmations());
+        }
+    }
+    async confirmNow(hashes) {
+        await this.ready;
         let changed = false;
-        for (const hash of hashes)
-            changed = this.values.delete(hash) || changed;
-        if (changed)
-            this.emit();
+        try {
+            for (let offset = 0; offset < hashes.length; offset += 128) {
+                const batch = hashes.slice(offset, offset + 128);
+                await this.withEpoch("rw", async () => {
+                    const previous = await this.outbox.bulkGet(batch.map(hash => [this.scope, hash]));
+                    const confirmed = previous.filter((record) => Boolean(record && !record.confirmed)).map(record => ({ ...record, voiceBlob: undefined, voiceData: undefined, status: "sent", confirmed: true }));
+                    if (confirmed.length)
+                        await this.outbox.bulkPut(confirmed);
+                });
+                // Retire only committed rows. A later failed transaction leaves the
+                // remaining sends retryable, including after a browser restart.
+                for (const hash of batch) {
+                    changed = this.values.delete(hash) || changed;
+                    this.releaseUrl(hash);
+                }
+                if (offset + batch.length < hashes.length)
+                    await new Promise(resolve => setTimeout(resolve, 0));
+            }
+        }
+        finally {
+            // One confirmation operation publishes at most once, also on partial
+            // failure so consumers see exactly the progress that was committed.
+            if (changed)
+                this.emit();
+        }
     }
     async resume() {
         await this.ready;
-        if (this.closed)
+        if (this.closed || this.closing || this.withdrawn)
             return;
         // Only interrupted, unconfirmed sends resume automatically; failed sends require retry.
         for (const record of this.values.values())
             if (record.status === "sending") {
-                if (this.closed)
+                if (this.closed || this.withdrawn)
                     return;
                 try {
                     await this.retry(record.hash);
@@ -177,11 +531,31 @@ export class DurableChatSender {
             }
     }
     async close() {
-        this.closed = true;
+        this.closing = true;
+        this.uploads.forEach(controller => controller.abort());
         this.offConnection();
         this.listeners.clear();
-        await this.ready;
-        await Promise.allSettled([...this.running.values()]);
-        this.db.close();
+        this.channel?.close();
+        this.channel = undefined;
+        try {
+            await this.ready;
+            await this.flushConfirmations();
+            await Promise.allSettled([...this.accepted, ...this.running.values(), ...(this.revoking ? [this.revoking] : [])]);
+        }
+        finally {
+            this.closed = true;
+            this.failConfirmations(new Error("CHAT_SENDER_CLOSED"));
+            this.releaseUrls();
+            this.values.clear();
+            this.snapshots.clear();
+            this.db.close();
+        }
     }
 }
+function validVoice(value) { const voice = value; return Boolean(voice && typeof voice.url === "string" && Number.isFinite(voice.durationMs) && voice.durationMs > 0); }
+function withVoiceUrl(message, url) {
+    const body = message.body;
+    return { ...message, body: { ...body, content: { ...body.content, voice: { ...body.content.voice, url } } } };
+}
+function hasVoice(record) { return Boolean(record.voiceBlob || record.voiceData); }
+function voiceBlob(record) { return record.voiceBlob ?? new Blob([record.voiceData.bytes], { type: record.voiceData.type }); }

package/lib/runtime/index.d.ts

@@ -29,3 +29,7 @@ export * from "./durableSender.js";
 export * from "./chatSession.js";
 export * from "./messageReaders.js";
 export * from "./createChat.js";
+export * from "./conversationRead.js";
+export { projectConversationReading, type ReadingCandidate, type MessageReadingState, type ConversationReadingView } from "./conversationReading.js";
+export { projectMessageTimeline, type TimelineItem, type TimelineReaction, type TimelineReactionEvent } from "./messageTimeline.js";
+export * from "./messageLaunch.js";

package/lib/runtime/index.js

@@ -29,3 +29,7 @@ export * from "./durableSender.js";
 export * from "./chatSession.js";
 export * from "./messageReaders.js";
 export * from "./createChat.js";
+export * from "./conversationRead.js";
+export { projectConversationReading } from "./conversationReading.js";
+export { projectMessageTimeline } from "./messageTimeline.js";
+export * from "./messageLaunch.js";

package/lib/runtime/messageClient.d.ts

@@ -36,6 +36,9 @@ export declare class MessageClient<T extends StoredMessage> {
     private options;
     private storage;
     private watches;
+    private windowEdges;
+    private accessListeners;
+    private allListeners;
     private reads;
     private syncing;
     private paging;
@@ -53,12 +56,32 @@ export declare class MessageClient<T extends StoredMessage> {
     private queueBytes;
     private pendingBytes;
     private pendingRecords;
+    private legacyImports;
+    private revokingScope?;
+    private scopeReady?;
+    private scopeVersion;
+    private scopeAllowed;
+    private scopeDenied;
+    private enqueuing;
+    private ensureScope;
     constructor(options: MessageClientOptions<T>);
+    /** Shared guard for sibling caches; it never authorizes a denied old instance. */
+    subscribeAccessRevoked(listener: () => void): () => void;
+    scopeAccess(): Promise<{
+        version: number;
+        allowed: boolean;
+    }>;
     getSnapshot(thread: string): MessageSnapshot<T> | undefined;
     subscribe(thread: string, listener: () => void): () => void;
-    read(thread: string, limit?: number): Promise<MessageSnapshot<T>>;
+    subscribeAll(listener: (threadId: string) => void): () => void;
+    /** Close the connection gap for saved windows with four bounded background lanes. */
+    restore(since: number, threadId?: string): Promise<void>;
+    read(thread: string, limit?: number, refresh?: boolean): Promise<MessageSnapshot<T>>;
     /** Application connection/wake events invalidate, rather than fetching directly. */
     invalidate(thread: string): void;
+    private fallback;
+    /** Migration batches remain separate from authoritative message coverage. */
+    importLegacy(thread: string, messages: T[]): Promise<void>;
     private reload;
     /** Events are visible only after their atomic batch commits. */
     receive(thread: string, messages: T[]): Promise<void>;
@@ -67,17 +90,18 @@ export declare class MessageClient<T extends StoredMessage> {
     private release;
     private flushWrites;
     private runWrites;
+    private assertNetworkAvailable;
     synchronize(thread: string): Promise<void>;
+    /** Keep an explicitly requested history range in the shared subscribed view. */
+    expandWindow(thread: string, page: MessageSnapshot<T>): Promise<void>;
     earlier(thread: string, before: {
         timestamp: number;
         id: string;
-    }, limit?: number): Promise<{
-        messages: T[];
-        hasEarlier: boolean;
-        resetVersion: number;
-        complete: boolean;
-    }>;
+    }, limit?: number, expand?: boolean): Promise<MessageSnapshot<T>>;
     private fillWindow;
+    private denyView;
+    private denyScope;
+    revokeScope(): Promise<number>;
     revoke(thread: string): Promise<void>;
-    close(): Promise<void>;
+    close(beforeDispose?: Promise<unknown>): Promise<void>;
 }