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

package/lib/runtime/readingClient.js

@@ -1,12 +1,21 @@
+import { isValidChatTeamId } from "./thread.js";
+import { isOffline, isOfflineNetworkFailure } from "./connectivity.js";
+import { recordConversationRead } from "./conversationRead.js";
 import { BatchedReadIndex } from "./batchedReadIndex.js";
 import { WindowedTasks } from "./coalescer.js";
-import { IndexedDbReadIndex, recordReadIntent } from "./readIndex.js";
+import { IndexedDbReadIndex, readingMetadata, recordReadIntent, assertReadIndexVersions } from "./readIndex.js";
 import { ReadSyncClient } from "./readSync.js";
 /** Owns durable local reads, network coalescing, retries and state notifications.
  * Hosts report actual visibility; loading or subscribing never marks messages read. */
 export class ReadingClient {
     options;
     storage;
+    backing;
+    closing;
+    revoking;
+    versions;
+    prepared = new Map();
+    accepted = new Set();
     persistence;
     sync;
     tasks;
@@ -19,7 +28,10 @@ export class ReadingClient {
     generation = 0;
     constructor(options) {
         this.options = options;
-        const storage = options.persistence ?? (this.storage = new IndexedDbReadIndex(globalThis.indexedDB, "pmate-social-read-index", options.storageScope));
+        if (options.teamId !== undefined && !isValidChatTeamId(options.teamId))
+            throw new Error("INVALID_READ_TEAM");
+        const storage = options.persistence ?? (this.storage = new IndexedDbReadIndex(globalThis.indexedDB, "pmate-social-read-index", options.storageScope, options.migrateLegacy, options.metadataOnly));
+        this.backing = storage;
         this.persistence = new BatchedReadIndex(storage);
         this.tasks = new WindowedTasks(1000, error => this.failed(error));
         this.sync = new ReadSyncClient({ ...options, persistence: this.persistence, onChange: state => this.publish(state) });
@@ -27,13 +39,13 @@ export class ReadingClient {
     getSnapshot = () => this.state;
     subscribe = (listener) => { this.listeners.add(listener); return () => { this.listeners.delete(listener); }; };
     publish(state) {
-        if (this.closed || JSON.stringify(state) === JSON.stringify(this.state))
+        if (this.closed || state === this.state || JSON.stringify(state) === JSON.stringify(this.state))
             return;
         this.state = state;
         this.listeners.forEach(listener => listener());
     }
     failed(error) {
-        if (this.closed)
+        if (this.closed || isOfflineNetworkFailure(error))
             return;
         this.options.onError?.(error);
         if (/HTTP_(400|401|403)/.test(String(error)) || (typeof navigator !== "undefined" && !navigator.onLine) || this.retry)
@@ -56,8 +68,9 @@ export class ReadingClient {
         this.refresh();
     }
     refresh = () => {
-        if (!this.closed)
-            this.tasks.schedule("reading", async () => { await this.synchronize(); });
+        if (!this.closed && !isOffline())
+            this.tasks.schedule("reading", async () => { if (!isOffline())
+                await this.synchronize(); });
     };
     async synchronize(targetCursor, profileId) {
         if (this.closed)
@@ -84,32 +97,131 @@ export class ReadingClient {
         }
         throw new Error("Reading projection has not reached the announced version");
     }
-    async update(transform) {
+    update(transform) {
+        // Advanced transforms may replace profile-wide state. Typed observation
+        // methods below only derive changes for their configured team.
+        return this.updateScoped(transform);
+    }
+    updateScoped(transform, teamId, observation) {
         if (this.closed)
-            throw new Error("READING_CLIENT_CLOSED");
-        const next = await this.persistence.update(this.options.appId, this.options.profileId, transform);
-        if (!this.closed) {
-            this.publish(next);
-            if (next.pending.length || next.observedReadIntents?.length)
-                this.refresh();
-        }
-        return next;
+            return Promise.reject(new Error("READING_CLIENT_CLOSED"));
+        // One shared metadata read per local authority generation, rather than one
+        // IndexedDB lookup for every viewport observation.
+        const versions = this.versions ??= this.persistence.loadVersions(this.options.appId, this.options.profileId);
+        const task = (async () => {
+            const expected = await versions;
+            const next = await this.persistence.update(this.options.appId, this.options.profileId, (state, currentVersions) => {
+                assertReadIndexVersions(expected, currentVersions, teamId);
+                const next = transform(state);
+                return this.options.metadataOnly ? readingMetadata(next) : next;
+            }, observation);
+            if (!this.closed) {
+                this.publish(next);
+                if (next.pending.length || next.observedReadIntents?.length)
+                    this.refresh();
+            }
+            return next;
+        })().catch(error => {
+            if (String(error).includes("READ_SCOPE_CHANGED")) {
+                if (teamId !== undefined)
+                    this.withdraw();
+                else
+                    this.versions = undefined;
+            }
+            throw error;
+        });
+        this.accepted.add(task);
+        void task.finally(() => this.accepted.delete(task)).catch(() => { });
+        return task;
+    }
+    prepareTeam(teamId, version) {
+        if (this.closed)
+            return Promise.reject(new Error("READING_CLIENT_CLOSED"));
+        if (!isValidChatTeamId(teamId) || !Number.isSafeInteger(version) || version < 0)
+            return Promise.reject(new Error("INVALID_READ_SCOPE_VERSION"));
+        const previous = this.prepared.get(teamId);
+        if (previous && previous.version >= version)
+            return previous.task;
+        const task = (async () => {
+            if (version > 0)
+                await this.persistence.invalidateTeam(this.options.appId, this.options.profileId, teamId, version);
+            this.versions = undefined;
+        })().catch(error => { if (this.prepared.get(teamId)?.task === task)
+            this.prepared.delete(teamId); throw error; });
+        this.prepared.set(teamId, { version, task });
+        return task;
+    }
+    assertThreadTeam(state, threadId) {
+        if (this.options.teamId !== undefined && state.threads.some(thread => (thread.id === threadId || thread.conversationId === threadId) && thread.teamId !== undefined && thread.teamId !== this.options.teamId))
+            throw new Error("READ_CONVERSATION_TEAM_MISMATCH");
+    }
+    markRead(threadId, messages = []) {
+        return this.updateScoped(state => { this.assertThreadTeam(state, threadId); return recordConversationRead(state, threadId, messages); }, this.options.teamId);
     }
     recordVisible(threadId, messageIds) { return this.record(threadId, messageIds, "visible"); }
     recordExplicit(threadId, messageIds) { return this.record(threadId, messageIds, "explicit"); }
     record(threadId, ids, readPolicy) {
         const messageIds = [...new Set(ids)];
-        return this.update(state => messageIds.reduce((next, messageId) => recordReadIntent(next, { threadId, messageId, readPolicy, operationId: crypto.randomUUID() }), state));
+        if (!messageIds.length && this.state) {
+            try {
+                this.assertThreadTeam(this.state, threadId);
+                return Promise.resolve(this.state);
+            }
+            catch (error) {
+                return Promise.reject(error);
+            }
+        }
+        return this.updateScoped(state => { this.assertThreadTeam(state, threadId); return messageIds.reduce((next, messageId) => recordReadIntent(next, { threadId, messageId, readPolicy, operationId: crypto.randomUUID() }), state); }, this.options.teamId, this.state && messageIds.length ? { base: this.state, targets: messageIds.map(messageId => ({ threadId, messageId })) } : undefined);
     }
-    async close() {
+    withdraw() { this.stop(); }
+    stop() {
+        if (this.closed)
+            return;
         this.closed = true;
         this.generation++;
         this.offWake?.();
         this.tasks.close();
         clearTimeout(this.retry);
         this.sync.stop();
+        this.state = undefined;
+        this.listeners.forEach(listener => listener());
         this.listeners.clear();
-        await this.persistence.close();
-        await this.storage?.close();
+    }
+    /** This client is retired permanently. Drain accepted local observations
+     * before deleting one team's profile-wide projection; sibling teams survive. */
+    revokeTeam(teamId, version, knownThreadIds = []) {
+        if (this.revoking)
+            return this.revoking;
+        if (this.closing)
+            return Promise.reject(new Error("READING_CLIENT_CLOSED"));
+        this.stop();
+        return this.revoking = (async () => {
+            try {
+                await Promise.allSettled([...this.accepted]);
+                await this.persistence.close();
+                if (!this.backing.invalidateTeam)
+                    throw new Error("READ_SCOPE_INVALIDATION_UNAVAILABLE");
+                await this.backing.invalidateTeam(this.options.appId, this.options.profileId, teamId, version, knownThreadIds);
+            }
+            finally {
+                await this.storage?.close();
+            }
+        })();
+    }
+    close() {
+        if (this.revoking)
+            return this.revoking;
+        if (this.closing)
+            return this.closing;
+        this.stop();
+        return this.closing = (async () => {
+            try {
+                await Promise.allSettled([...this.accepted]);
+                await this.persistence.close();
+            }
+            finally {
+                await this.storage?.close();
+            }
+        })();
     }
 }

package/lib/runtime/readingContent.d.ts

@@ -0,0 +1,5 @@
+/** Social control envelopes do not contribute to message unread counts. */
+export declare function isReadingControl(payload: unknown, appId: string): boolean;
+/** Mirrors the server's voice policy for ordinary and quoted wire envelopes. */
+export declare function messageRequiresPlayback(body: unknown): boolean;
+export declare function messageMentionsProfile(body: unknown, profileId: string): boolean;

package/lib/runtime/readingContent.js

@@ -0,0 +1,23 @@
+/** Social control envelopes do not contribute to message unread counts. */
+export function isReadingControl(payload, appId) {
+    if (!payload || typeof payload !== "object")
+        return false;
+    const value = payload;
+    if (value.body !== undefined)
+        return isReadingControl(value.body, appId);
+    return value.kind === "message" && value.content?.appId === appId && (value.content.reaction !== undefined || value.content.recall !== undefined);
+}
+/** Mirrors the server's voice policy for ordinary and quoted wire envelopes. */
+export function messageRequiresPlayback(body) {
+    if (!body || typeof body !== "object")
+        return false;
+    const value = body;
+    return value.contentKind === "voice" || value.content?.contentKind === "voice" || [value.content?.voice?.url, value.content?.content?.voice?.url].some(url => typeof url === "string" && url.length > 0);
+}
+export function messageMentionsProfile(body, profileId) {
+    if (!body || typeof body !== "object")
+        return false;
+    const content = body.content;
+    const mentions = content?.mentions !== undefined ? content.mentions : content?.content?.mentions;
+    return Array.isArray(mentions) && mentions.some(mention => mention?.id === profileId);
+}

package/lib/runtime/recordCache.d.ts

@@ -5,6 +5,8 @@ export type RecordCacheOptions<T> = {
     indexedDB?: IDBFactory;
     name?: string;
     onError?: (error: unknown) => void;
+    transactionBytes?: number;
+    queueBytes?: number;
 };
 /** In-memory control-event index backed by bounded asynchronous IndexedDB batches.
  * Legacy storage is read only during open; the hot path never uses localStorage. */
@@ -23,6 +25,11 @@ export declare class IndexedDbRecordCache<T> {
     private closing;
     private initialized;
     private running?;
+    private activeBytes;
+    private pendingBytes;
+    private activeRecords;
+    private transactionBytes;
+    private queueBytes;
     private channel?;
     private listeners;
     constructor(options: RecordCacheOptions<T>);
@@ -34,7 +41,9 @@ export declare class IndexedDbRecordCache<T> {
     subscribe(listener: () => void): () => void;
     private reload;
     upsert(incoming: T[]): Promise<void>;
+    private bytes;
     private write;
+    private writeBatch;
     flush(): Promise<void>;
     private runFlush;
     close(): Promise<void>;

package/lib/runtime/recordCache.js

@@ -17,17 +17,26 @@ export class IndexedDbRecordCache {
     closing = false;
     initialized = false;
     running;
+    activeBytes = 0;
+    pendingBytes = 0;
+    activeRecords = 0;
+    transactionBytes;
+    queueBytes;
     channel;
     listeners = new Set();
     constructor(options) {
         this.options = options;
+        this.transactionBytes = options.transactionBytes ?? 1_048_576;
+        this.queueBytes = options.queueBytes ?? 8_388_608;
+        if (!Number.isSafeInteger(this.transactionBytes) || this.transactionBytes < 1 || !Number.isSafeInteger(this.queueBytes) || this.queueBytes < this.transactionBytes)
+            throw new Error("INVALID_RECORD_CACHE_BYTE_LIMIT");
         this.db = new Dexie(options.name ?? "pmate-chat-records", { indexedDB: options.indexedDB ?? globalThis.indexedDB, IDBKeyRange: globalThis.IDBKeyRange });
         this.db.version(1).stores({ records: "[scope+id],scope", metadata: "scope" });
         this.records = this.db.table("records");
         this.metadata = this.db.table("metadata");
         this.tasks = new WindowedTasks(16, error => options.onError?.(error));
         if (typeof BroadcastChannel !== "undefined") {
-            this.channel = new BroadcastChannel(`pmate-chat-records:${options.scope}`);
+            this.channel = new BroadcastChannel(`pmate-chat-records:${options.scope}${this.db.name === "pmate-chat-records" ? "" : `:${this.db.name}`}`);
             this.channel.onmessage = () => this.tasks.schedule("reload", () => this.reload());
         }
     }
@@ -83,30 +92,70 @@ export class IndexedDbRecordCache {
         await this.ready;
         if (this.closed || this.closing)
             throw new Error("RECORD_CACHE_CLOSED");
-        if (incoming.length + this.pending.size > 4096)
+        if (incoming.length > 4096)
             throw new Error("RECORD_CACHE_BACKPRESSURE");
-        let changed = false;
+        // Plan and validate the whole operation before publishing any in-memory state.
+        const staged = new Map();
         for (const value of incoming) {
-            const key = this.options.key(value), old = this.values.get(key), next = this.options.merge(old, value);
+            const key = this.options.key(value), old = staged.get(key) ?? this.values.get(key);
+            const next = this.options.merge(old, value);
             if (JSON.stringify(old) === JSON.stringify(next))
                 continue;
+            if (this.bytes(next) > this.transactionBytes)
+                throw new Error("RECORD_CACHE_RECORD_TOO_LARGE");
+            staged.set(key, structuredClone(next));
+        }
+        let nextBytes = this.pendingBytes, nextRecords = this.pending.size;
+        for (const [key, value] of staged) {
+            const previous = this.pending.get(key);
+            nextBytes += this.bytes(value) - (previous === undefined ? 0 : this.bytes(previous));
+            if (!this.pending.has(key))
+                nextRecords++;
+        }
+        if (nextRecords + this.activeRecords > 4096 || nextBytes + this.activeBytes > this.queueBytes)
+            throw new Error("RECORD_CACHE_BACKPRESSURE");
+        let changed = false;
+        for (const [key, next] of staged) {
             this.values.set(key, next);
             this.pending.set(key, next);
             changed = true;
         }
+        this.pendingBytes = nextBytes;
         if (changed)
             this.snapshotValue = [...this.values.values()];
-        if (!changed && !this.pending.size)
+        if (!changed && !this.pending.size) {
+            await this.running;
             return;
+        }
         const committed = new Promise((resolve, reject) => this.waiters.push({ resolve, reject }));
         this.tasks.schedule("write", () => this.flush());
         return committed;
     }
+    bytes(value) { return new TextEncoder().encode(JSON.stringify({ scope: this.options.scope, id: this.options.key(value), value })).byteLength; }
     async write(values) {
+        let batch = [], bytes = 0;
+        for (const value of values) {
+            const size = this.bytes(value);
+            if (size > this.transactionBytes)
+                throw new Error("RECORD_CACHE_RECORD_TOO_LARGE");
+            if (batch.length && (batch.length === 128 || bytes + size > this.transactionBytes)) {
+                await this.writeBatch(batch);
+                batch = [];
+                bytes = 0;
+            }
+            batch.push(value);
+            bytes += size;
+        }
+        if (batch.length)
+            await this.writeBatch(batch);
+    }
+    async writeBatch(values) {
         await this.db.transaction("rw", this.records, async () => {
             const previous = await this.records.bulkGet(values.map(value => [this.options.scope, this.options.key(value)]));
             const records = values.map((value, index) => ({ scope: this.options.scope, id: this.options.key(value), value: this.options.merge(previous[index]?.value, value) }));
             const changed = records.filter((row, index) => JSON.stringify(previous[index]?.value) !== JSON.stringify(row.value));
+            if (changed.reduce((sum, row) => sum + this.bytes(row.value), 0) > this.transactionBytes)
+                throw new Error("RECORD_CACHE_MERGE_TOO_LARGE");
             if (changed.length)
                 await this.records.bulkPut(changed);
         });
@@ -126,8 +175,11 @@ export class IndexedDbRecordCache {
     async runFlush() {
         const values = [...this.pending.values()], waiters = this.waiters.splice(0);
         this.pending.clear();
+        this.pendingBytes = 0;
         if (!values.length)
             return;
+        this.activeBytes = values.reduce((sum, value) => sum + this.bytes(value), 0);
+        this.activeRecords = values.length;
         try {
             for (let offset = 0; offset < values.length; offset += 128)
                 await this.write(values.slice(offset, offset + 128));
@@ -142,9 +194,14 @@ export class IndexedDbRecordCache {
                 const key = this.options.key(value);
                 this.pending.set(key, this.options.merge(value, this.pending.get(key) ?? value));
             }
+            this.pendingBytes = [...this.pending.values()].reduce((sum, value) => sum + this.bytes(value), 0);
             waiters.forEach(waiter => waiter.reject(error));
             throw error;
         }
+        finally {
+            this.activeBytes = 0;
+            this.activeRecords = 0;
+        }
     }
     async close() {
         this.closing = true;

package/lib/runtime/responseCache.d.ts

@@ -0,0 +1,44 @@
+export type ResponseCacheAccess = () => Promise<{
+    version: number;
+    allowed: boolean;
+}>;
+export declare function isResponseCacheAuthorityError(error: unknown): boolean;
+export declare function assertResponseCacheAccess(access?: ResponseCacheAccess, expectedVersion?: number): Promise<number | undefined>;
+/** Small response windows, isolated by identity. Epochs fence late writes after
+ * access withdrawal. No localStorage or synchronous writes on the read path. */
+export declare class IndexedDbResponseCache<T> {
+    private scope;
+    private options;
+    private db;
+    private rows;
+    private epochs;
+    private pending;
+    private tasks;
+    private running?;
+    private invalidations;
+    private closed;
+    private closing?;
+    constructor(scope: string, options?: {
+        indexedDB?: IDBFactory;
+        name?: string;
+        access?: ResponseCacheAccess;
+    });
+    /** 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. */
+    private synchronizeAccess;
+    read(key: string): Promise<{
+        epoch: number;
+        cached: {
+            value: T;
+            time: number;
+        } | undefined;
+    }>;
+    write(key: string, value: T, epoch: number): Promise<void>;
+    /** Idempotent shared-scope retirement: an old cleanup cannot erase windows
+     * created after the same authority version was already recovered. */
+    retire(version: number): Promise<void>;
+    invalidate(): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}

package/lib/runtime/responseCache.js

@@ -0,0 +1,173 @@
+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;
+    db;
+    rows;
+    epochs;
+    pending = [];
+    tasks = new WindowedTasks(16, () => { });
+    running;
+    invalidations = new Set();
+    closed = false;
+    closing;
+    constructor(scope, options = {}) {
+        this.scope = scope;
+        this.options = options;
+        this.db = new Dexie(options.name ?? "pmate-chat-response-windows", { indexedDB: options.indexedDB ?? globalThis.indexedDB, IDBKeyRange: globalThis.IDBKeyRange });
+        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.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.db.transaction("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").equals(this.scope).delete();
+                }
+            });
+        if (!access.allowed)
+            throw new Error("RESPONSE_CACHE_ACCESS_REVOKED");
+    }
+    async read(key) {
+        if (this.closed)
+            throw new Error("RESPONSE_CACHE_CLOSED");
+        await this.synchronizeAccess();
+        return this.db.transaction("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) {
+        if (this.closed)
+            return Promise.reject(new Error("RESPONSE_CACHE_CLOSED"));
+        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)
+            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 }));
+        this.tasks.schedule("write", () => this.flush());
+        return promise;
+    }
+    /** Idempotent shared-scope retirement: an old cleanup cannot erase windows
+     * created after the same authority version was already recovered. */
+    retire(version) {
+        if (this.closed)
+            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.db.transaction("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").equals(this.scope).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.db.transaction("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").equals(this.scope).delete();
+            });
+        })();
+        this.invalidations.add(task);
+        return task.finally(() => this.invalidations.delete(task));
+    }
+    async flush() {
+        if (this.running) {
+            await this.running;
+            if (this.pending.length)
+                return this.flush();
+            return;
+        }
+        const batch = [...this.pending];
+        if (!batch.length)
+            return;
+        const task = (async () => {
+            try {
+                await this.synchronizeAccess();
+                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);
+            }
+        })().finally(() => { if (this.running === task)
+            this.running = undefined; });
+        this.running = task;
+        return task;
+    }
+    close() {
+        if (this.closing)
+            return this.closing;
+        this.closed = true;
+        this.tasks.close();
+        return this.closing = (async () => {
+            try {
+                await Promise.all([this.flush(), ...this.invalidations]);
+            }
+            finally {
+                this.db.close();
+            }
+        })();
+    }
+}

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,20 @@
+/** 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) => {
+        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";
+        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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.12.0-next.5",
+  "version": "0.12.0-next.51",
   "description": "Cross-platform PMate chat input components, voice input primitives, and ASR helpers",
   "type": "module",
   "main": "./lib/index.js",
@@ -19,6 +19,11 @@
       "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",