@pmate/chat-sdk 0.6.2 → 0.7.0

package/README.md

@@ -32,3 +32,11 @@ must preserve the text offsets if transforming the message before transport.
 Storybook: `GroupMentions`, `MobileGroupMentions`, and `DarkGroupMentions` use the
 production components, include duplicate names and scrolling, and support empty
 results by typing an unmatched query.
+
+## Connection recovery
+
+A dropped socket (including a network change or a suspended laptop) previously required callers to recreate the client. The runtime now reconnects with capped exponential backoff, probes the Hub with its binary heartbeat, and authenticates each replacement socket before sending chat traffic.
+
+`client.watchConnection(handler)` immediately reports the current state and returns an unsubscribe function. States are `connecting`, `reconnecting`, `authenticating`, `connected`, `authentication_required`, and `closed`. Only `connected` means the Hub acknowledged authentication. A rejected authentication stops retries; supply a fresh login session using a new client. `close()` cancels retries, heartbeat timers and browser wake listeners.
+
+Messages sent without an acknowledgement are rejected on disconnect and are **not replayed**: delivery is uncertain, so automatic retries could duplicate them. Callers should preserve drafts, display a reconnecting state, and refresh message history after recovery. No durable offline outbox is provided. An initial `connect()` wait times out after 30 seconds, but recovery continues until explicitly closed; retain the client and observe its connection state.

package/lib/index.d.ts

@@ -33,3 +33,5 @@ export * from "./hooks/useMentions";
 export * from "./components/MentionMenu";
 export * from "./runtime/activity";
 export * from "./runtime/call";
+export * from "./runtime/presence";
+export * from "./runtime/meeting";

package/lib/index.js

@@ -33,3 +33,5 @@ export * from "./hooks/useMentions";
 export * from "./components/MentionMenu";
 export * from "./runtime/activity";
 export * from "./runtime/call";
+export * from "./runtime/presence";
+export * from "./runtime/meeting";

package/lib/runtime/chatClient.d.ts

@@ -1,8 +1,10 @@
+import { type ChatPresence } from "./presence.js";
 import { ChatActivityPublisher, type ActivityTarget, type ChatActivity, type ChatActivityState, type ChatActivityUpdate } from "./activity.js";
 import type { ChatMention } from "../mentions/model";
 import { type BotLoginSession } from "./botAuth.js";
 import { type PmateBotKeyFile } from "./botKey.js";
 import { type ChatBody, type ChatRuntimeMessage, type RealtimeClient } from "./protocol.js";
+export type ChatConnectionState = "connecting" | "reconnecting" | "authenticating" | "connected" | "authentication_required" | "closed";
 export type ChatClientOptions = {
     appId: string;
     profileId?: string;
@@ -13,10 +15,22 @@ export type ChatClientOptions = {
     realtimeClient?: RealtimeClient;
     fetchImpl?: typeof fetch;
     onActivityError?: (error: unknown) => void;
+    presence?: {
+        baseUrl?: string;
+    };
     ackTimeoutMs?: number;
 };
 export declare class ChatClient {
     private readonly options;
+    private readonly instanceId;
+    private presence?;
+    private presenceProfiles;
+    private presenceHandlers;
+    private connection;
+    private readonly connectionHandlers;
+    private subscriptions;
+    private generation;
+    private connectPromise?;
     private client;
     private session;
     private profileIdValue;
@@ -27,7 +41,15 @@ export declare class ChatClient {
     private readonly messageHandlers;
     constructor(options: ChatClientOptions);
     connect(): Promise<this>;
+    private initialize;
     close(): void;
+    connectionState(): ChatConnectionState;
+    watchConnection(handler: (state: ChatConnectionState) => void): () => void;
+    private setConnection;
+    private rejectPending;
+    private authenticate;
+    watchPresenceProfiles(ids: string[]): void;
+    watchPresence(handler: (items: ChatPresence[]) => void): () => void;
     watchMessages(handler: (message: ChatRuntimeMessage) => void): () => boolean;
     watchActivities(handler: (activities: ChatActivity[]) => void): () => void;
     sendActivity(input: ActivityTarget & {
@@ -76,7 +98,7 @@ export declare class ChatClient {
     private sendAuth;
     private sendAndWaitForAck;
     private handleIncoming;
-    private waitUntilConnected;
+    private waitUntilReady;
     private accountId;
     private resolveProfileId;
     private profileId;

package/lib/runtime/chatClient.js

@@ -1,3 +1,4 @@
+import { ChatPresenceClient } from "./presence.js";
 import { ChatActivityStore, ChatActivityPublisher, createActivityMessage, parseChatActivity } from "./activity.js";
 import { loginPmateBot } from "./botAuth.js";
 import { parsePmateBotKeyJson } from "./botKey.js";
@@ -7,6 +8,15 @@ const DEFAULT_AUTH_API_BASE_URL = "https://auth-api-v2.pmate.chat";
 const DEFAULT_ACK_TIMEOUT_MS = 5_000;
 export class ChatClient {
     options;
+    instanceId = crypto.randomUUID();
+    presence;
+    presenceProfiles = [];
+    presenceHandlers = new Set();
+    connection = "closed";
+    connectionHandlers = new Set();
+    subscriptions = [];
+    generation = 0;
+    connectPromise;
     client = null;
     session = null;
     profileIdValue = null;
@@ -23,7 +33,20 @@ export class ChatClient {
         this.session = options.session ?? null;
         this.client = options.realtimeClient ?? null;
     }
-    async connect() {
+    connect() {
+        if (this.connectPromise)
+            return this.connectPromise;
+        if (this.connection === "connected")
+            return Promise.resolve(this);
+        const generation = this.generation;
+        this.setConnection("connecting");
+        const promise = this.initialize(generation);
+        this.connectPromise = promise;
+        void promise.finally(() => { if (this.connectPromise === promise)
+            this.connectPromise = undefined; }).catch(() => { });
+        return promise;
+    }
+    async initialize(generation) {
         if (!this.session) {
             if (!this.botKey) {
                 throw new Error("ChatClient requires either session or PMate bot key JSON");
@@ -35,35 +58,103 @@ export class ChatClient {
             });
         }
         const profileId = await this.resolveProfileId();
+        if (generation !== this.generation)
+            throw new Error("ChatClient closed");
+        if (this.options.presence && !this.presence) {
+            this.presence = new ChatPresenceClient({ appId: this.options.appId, profileId, instanceId: this.instanceId, token: () => this.session.token, baseUrl: this.options.presence.baseUrl, fetchImpl: this.options.fetchImpl });
+            this.presence.watchProfiles(this.presenceProfiles);
+            this.presence.watch(items => { for (const handler of this.presenceHandlers)
+                handler(items); });
+        }
         if (!this.client) {
             const hubUrl = normalizeWsUrl(this.options.hubUrl ?? DEFAULT_HUB_URL, profileId);
             this.client = new RuntimeWebsocketClient(hubUrl);
         }
-        this.client.on(ChatRealtimeEvents.Message, (message) => {
-            this.handleIncoming(message);
-        });
-        this.client.on(ChatRealtimeEvents.Connected, (connected) => { if (!connected) {
-            for (const publisher of this.publishers)
-                void publisher.stop();
-            this.activities.clear();
-        } });
-        await this.waitUntilConnected();
-        await this.sendAuth();
+        if (!this.subscriptions.length) {
+            this.subscriptions.push(this.client.on(ChatRealtimeEvents.Message, message => this.handleIncoming(message)), this.client.on(ChatRealtimeEvents.Connected, connected => {
+                if (connected)
+                    void this.authenticate();
+                else {
+                    this.generation++;
+                    this.setConnection("reconnecting");
+                    this.rejectPending(new Error("聊天连接已断开，消息尚未确认送达"));
+                    for (const publisher of this.publishers)
+                        void publisher.stop();
+                    this.activities.clear();
+                }
+            }));
+        }
+        if (this.client.isConnected())
+            void this.authenticate();
+        await this.waitUntilReady();
         return this;
     }
     close() {
+        this.generation++;
+        for (const off of this.subscriptions.splice(0))
+            off();
+        this.setConnection("closed");
         for (const publisher of this.publishers)
             void publisher.stop();
         this.publishers.clear();
         this.activities.clear();
         this.client?.close();
         this.client = null;
+        this.connectPromise = undefined;
+        this.rejectPending(new Error("ChatClient closed"));
+    }
+    connectionState() { return this.connection; }
+    watchConnection(handler) {
+        this.connectionHandlers.add(handler);
+        handler(this.connection);
+        return () => { this.connectionHandlers.delete(handler); };
+    }
+    setConnection(state) {
+        if (this.connection === state)
+            return;
+        this.connection = state;
+        if (state === "connected")
+            this.presence?.start();
+        else
+            this.presence?.stop();
+        for (const handler of this.connectionHandlers)
+            handler(state);
+    }
+    rejectPending(error) {
         for (const pending of this.pendingAcks.values()) {
-            pending.reject(new Error("ChatClient closed"));
+            pending.reject(error);
             clearTimeout(pending.timer);
         }
         this.pendingAcks.clear();
     }
+    async authenticate() {
+        if (this.connection === "authenticating" || this.connection === "connected")
+            return;
+        const generation = this.generation;
+        this.setConnection("authenticating");
+        try {
+            await this.sendAuth();
+            if (generation === this.generation)
+                this.setConnection("connected");
+        }
+        catch (error) {
+            if (generation !== this.generation)
+                return;
+            if (error instanceof ChatAckError) {
+                this.close();
+                this.setConnection("authentication_required");
+            }
+            else {
+                this.client?.close(false);
+            }
+        }
+    }
+    watchPresenceProfiles(ids) { this.presenceProfiles = ids; this.presence?.watchProfiles(ids); }
+    watchPresence(handler) {
+        this.presenceHandlers.add(handler);
+        handler(this.presence?.snapshot() ?? []);
+        return () => { this.presenceHandlers.delete(handler); };
+    }
     watchMessages(handler) {
         this.messageHandlers.add(handler);
         return () => this.messageHandlers.delete(handler);
@@ -160,11 +251,15 @@ export class ChatClient {
             token,
             as: "user",
             profileId,
+            clientInstanceId: this.instanceId,
         }, ChatMsgKind.DM);
         await this.sendAndWaitForAck(auth);
     }
     async sendAndWaitForAck(msg) {
         const client = this.requireClient();
+        if (msg.opcode !== ChatMsgOp.AUTH && this.connection !== "connected") {
+            throw new Error(this.connection === "authentication_required" ? "登录已失效，请重新登录" : "聊天连接正在恢复，请稍后重试");
+        }
         const ack = new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 this.pendingAcks.delete(msg.hash);
@@ -196,7 +291,7 @@ export class ChatClient {
                     pending.resolve(ack);
                 }
                 else {
-                    pending.reject(new Error(ack.message || ack.code || "Ack failed"));
+                    pending.reject(new ChatAckError(ack.message || ack.code || "Ack failed"));
                 }
             }
             return;
@@ -214,24 +309,26 @@ export class ChatClient {
             }
         }
     }
-    waitUntilConnected() {
-        const client = this.requireClient();
-        if (client.isConnected()) {
+    waitUntilReady() {
+        if (this.connection === "connected")
             return Promise.resolve();
-        }
         return new Promise((resolve, reject) => {
-            const offConnected = client.on(ChatRealtimeEvents.Connected, (connected) => {
-                if (connected) {
-                    offConnected();
-                    offError();
+            const timer = setTimeout(() => {
+                this.connectionHandlers.delete(check);
+                reject(new Error("聊天连接正在恢复，请稍后重试"));
+            }, 30_000);
+            const check = (state) => {
+                if (!["connected", "closed", "authentication_required"].includes(state))
+                    return;
+                clearTimeout(timer);
+                this.connectionHandlers.delete(check);
+                if (state === "connected")
                     resolve();
-                }
-            });
-            const offError = client.on(ChatRealtimeEvents.Error, (error) => {
-                offConnected();
-                offError();
-                reject(error instanceof Error ? error : new Error("WebSocket connection failed"));
-            });
+                else
+                    reject(new Error(state === "authentication_required" ? "登录已失效，请重新登录" : "ChatClient closed"));
+            };
+            this.connectionHandlers.add(check);
+            check(this.connection);
         });
     }
     accountId() {
@@ -292,6 +389,8 @@ export class ChatClient {
         return this.client;
     }
 }
+class ChatAckError extends Error {
+}
 export function createChatClient(options) {
     return new ChatClient(options);
 }

package/lib/runtime/index.d.ts

@@ -6,3 +6,5 @@ export * from "./readerClient.js";
 export * from "./thread.js";
 export * from "./activity.js";
 export * from "./call.js";
+export * from "./presence.js";
+export * from "./meeting";

package/lib/runtime/index.js

@@ -6,3 +6,5 @@ export * from "./readerClient.js";
 export * from "./thread.js";
 export * from "./activity.js";
 export * from "./call.js";
+export * from "./presence.js";
+export * from "./meeting";

package/lib/runtime/meeting.d.ts

@@ -0,0 +1,54 @@
+import type { CallClientOptions } from "./call";
+export type MeetingParticipant = {
+    id: string;
+    profileId: string;
+    muted: boolean;
+    connection: "connecting" | "connected" | "failed";
+    stream?: MediaStream;
+};
+export type MeetingSnapshot = {
+    phase: "idle" | "joining" | "joined" | "ended";
+    groupId?: string;
+    meetingId?: string;
+    selfId?: string;
+    participants: MeetingParticipant[];
+    muted: boolean;
+    sharingId?: string;
+    localScreen?: MediaStream;
+    error?: string;
+};
+/** Small-group mesh (six people maximum), media capture only after explicit join/share. */
+export declare class GroupMeetingClient {
+    private options;
+    private state;
+    private listeners;
+    private ws?;
+    private microphone?;
+    private screen?;
+    private links;
+    private generation;
+    private pendingCapture;
+    private timer?;
+    private heartbeat?;
+    private lastSeen;
+    private iceServers;
+    private queue;
+    constructor(options: CallClientOptions);
+    snapshot(): MeetingSnapshot;
+    subscribe(fn: (s: MeetingSnapshot) => void): () => void;
+    join(groupId: string): Promise<void>;
+    leave(): void;
+    dismiss(): void;
+    close(): void;
+    mute(): void;
+    shareScreen(): Promise<void>;
+    stopSharing(): Promise<void>;
+    private update;
+    private send;
+    private fail;
+    private release;
+    private participant;
+    private link;
+    private syncScreen;
+    private receive;
+}

package/lib/runtime/meeting.js

@@ -0,0 +1,262 @@
+/** Small-group mesh (six people maximum), media capture only after explicit join/share. */
+export class GroupMeetingClient {
+    options;
+    state = { phase: "idle", participants: [], muted: false };
+    listeners = new Set();
+    ws;
+    microphone;
+    screen;
+    links = new Map();
+    generation = 0;
+    pendingCapture = false;
+    timer;
+    heartbeat;
+    lastSeen = 0;
+    iceServers = [];
+    queue = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+    }
+    snapshot() { return this.state; }
+    subscribe(fn) { this.listeners.add(fn); fn(this.state); return () => { this.listeners.delete(fn); }; }
+    async join(groupId) {
+        if (!["idle", "ended"].includes(this.state.phase))
+            return;
+        this.release();
+        const gen = this.generation;
+        this.update({ phase: "joining", groupId, error: undefined });
+        this.timer = setTimeout(() => this.fail("CONNECTION_TIMEOUT"), 30000);
+        try {
+            const stream = await (this.options.mediaDevices ?? navigator.mediaDevices).getUserMedia({ audio: { echoCancellation: true, noiseSuppression: true }, video: false });
+            if (gen !== this.generation) {
+                stream.getTracks().forEach(t => t.stop());
+                return;
+            }
+            this.microphone = stream;
+            for (const t of stream.getAudioTracks())
+                t.onended = () => { if (gen === this.generation)
+                    this.fail("MICROPHONE_DENIED"); };
+            const ws = (this.options.createWebSocket ?? (url => new WebSocket(url)))(this.options.url ?? "wss://calls.pmate.chat/call");
+            this.ws = ws;
+            ws.onopen = () => { if (gen === this.generation)
+                this.send({ type: "auth", mode: "meeting", profileId: this.options.profileId, token: this.options.token }); };
+            ws.onmessage = e => { this.lastSeen = Date.now(); this.queue = this.queue.then(async () => { if (gen === this.generation)
+                await this.receive(JSON.parse(String(e.data)), gen); }).catch(() => { if (gen === this.generation)
+                this.fail("CONNECTION_FAILED"); }); };
+            ws.onerror = () => { };
+            ws.onclose = () => { if (gen === this.generation)
+                this.fail("DISCONNECTED"); };
+        }
+        catch {
+            if (gen === this.generation)
+                this.fail(this.microphone ? "CONNECTION_FAILED" : "MICROPHONE_DENIED");
+        }
+    }
+    leave() { this.send({ type: "room.leave", meetingId: this.state.meetingId }); this.release(); this.update({ phase: "ended" }); }
+    dismiss() { if (this.state.phase === "ended")
+        this.update({ phase: "idle", error: undefined }); }
+    close() { this.leave(); this.listeners.clear(); }
+    mute() { if (this.state.phase !== "joined")
+        return; const muted = !this.state.muted; this.microphone?.getAudioTracks().forEach(t => t.enabled = !muted); this.update({ muted }); this.send({ type: "room.mute", meetingId: this.state.meetingId, muted }); }
+    async shareScreen() {
+        if (this.state.phase !== "joined" || this.pendingCapture)
+            return;
+        if (this.screen)
+            return this.stopSharing();
+        if (this.state.sharingId && this.state.sharingId !== this.state.selfId) {
+            this.update({ error: "SCREEN_BUSY" });
+            return;
+        }
+        const gen = this.generation;
+        this.pendingCapture = true;
+        try {
+            const stream = await (this.options.mediaDevices ?? navigator.mediaDevices).getDisplayMedia({ video: { width: { ideal: 1280, max: 1920 }, height: { ideal: 720, max: 1080 }, frameRate: { ideal: 10, max: 15 } }, audio: false });
+            if (gen !== this.generation) {
+                stream.getTracks().forEach(t => t.stop());
+                return;
+            }
+            this.screen = stream;
+            const track = stream.getVideoTracks()[0];
+            if (!track)
+                throw new Error("No video");
+            track.contentHint = "detail";
+            track.onended = () => { if (gen === this.generation)
+                void this.stopSharing(); };
+            this.send({ type: "room.sharing", meetingId: this.state.meetingId, active: true });
+            this.update({ localScreen: stream, error: undefined });
+        }
+        catch (e) {
+            if (gen === this.generation) {
+                await this.stopSharing();
+                if (!(e instanceof DOMException && e.name === "NotAllowedError"))
+                    this.update({ error: "SCREEN_UNAVAILABLE" });
+            }
+        }
+        finally {
+            if (gen === this.generation)
+                this.pendingCapture = false;
+        }
+    }
+    async stopSharing() {
+        const gen = this.generation;
+        const stream = this.screen;
+        this.screen = undefined;
+        stream?.getTracks().forEach(t => { t.onended = null; t.stop(); });
+        await Promise.all([...this.links.values()].map(l => l.video.sender.replaceTrack(null).catch(() => { })));
+        if (gen !== this.generation)
+            return;
+        this.send({ type: "room.sharing", meetingId: this.state.meetingId, active: false });
+        this.update({ localScreen: undefined });
+    }
+    update(p) { this.state = { ...this.state, ...p }; for (const fn of this.listeners)
+        fn(this.state); }
+    send(m) { if (this.ws?.readyState === 1)
+        this.ws.send(JSON.stringify(m)); }
+    fail(error) { this.leave(); this.update({ error }); }
+    release() {
+        this.generation++;
+        clearTimeout(this.timer);
+        clearInterval(this.heartbeat);
+        this.pendingCapture = false;
+        const ws = this.ws;
+        this.ws = undefined;
+        ws?.close();
+        for (const link of this.links.values()) {
+            clearTimeout(link.timer);
+            link.pc.close();
+        }
+        this.links.clear();
+        for (const stream of [this.microphone, this.screen])
+            stream?.getTracks().forEach(t => { t.onended = null; t.stop(); });
+        this.microphone = undefined;
+        this.screen = undefined;
+        this.update({ participants: [], meetingId: undefined, selfId: undefined, sharingId: undefined, localScreen: undefined, muted: false });
+    }
+    participant(id, patch) { this.update({ participants: this.state.participants.map(p => p.id === id ? { ...p, ...patch } : p) }); }
+    link(id, gen) {
+        const previous = this.links.get(id);
+        if (previous)
+            return previous;
+        const pc = (this.options.createPeerConnection ?? (c => new RTCPeerConnection(c)))({ bundlePolicy: "max-bundle", iceServers: this.iceServers, iceTransportPolicy: this.options.iceTransportPolicy ?? "all" });
+        for (const track of this.microphone.getAudioTracks())
+            pc.addTrack(track, this.microphone);
+        const video = pc.addTransceiver("video", { direction: "sendrecv", sendEncodings: [{ maxBitrate: 800000, maxFramerate: 15 }] });
+        const link = { pc, video, remote: new MediaStream(), candidates: [] };
+        this.links.set(id, link);
+        const current = () => gen === this.generation && this.links.get(id) === link;
+        link.timer = setTimeout(() => { if (current())
+            this.participant(id, { connection: "failed" }); }, 30000);
+        pc.ontrack = e => { if (current()) {
+            link.remote.addTrack(e.track);
+            this.participant(id, { stream: link.remote });
+        } };
+        pc.onicecandidate = e => { if (current() && e.candidate)
+            this.send({ type: "room.ice", meetingId: this.state.meetingId, peerId: id, candidate: e.candidate.toJSON() }); };
+        pc.onconnectionstatechange = () => {
+            if (!current())
+                return;
+            if (pc.connectionState === "connected") {
+                clearTimeout(link.timer);
+                this.participant(id, { connection: "connected" });
+            }
+            else if (["failed", "disconnected", "closed"].includes(pc.connectionState))
+                this.participant(id, { connection: pc.connectionState === "disconnected" ? "connecting" : "failed" });
+        };
+        return link;
+    }
+    async syncScreen() {
+        const track = this.state.sharingId === this.state.selfId ? this.screen?.getVideoTracks()[0] ?? null : null;
+        await Promise.all([...this.links.values()].map(l => l.video.sender.replaceTrack(track)));
+    }
+    async receive(m, gen) {
+        if (m.type === "ready") {
+            this.send({ type: "room.join", groupId: this.state.groupId, requestId: String(gen) });
+            this.lastSeen = Date.now();
+            this.heartbeat = setInterval(() => { if (Date.now() - this.lastSeen > 60000)
+                this.fail("DISCONNECTED");
+            else
+                this.send({ type: "ping" }); }, 20000);
+            return;
+        }
+        if (m.type === "pong")
+            return;
+        if (m.type === "error") {
+            if (m.code === "SCREEN_BUSY") {
+                await this.stopSharing();
+                this.update({ error: "SCREEN_BUSY" });
+                return;
+            }
+            this.fail(m.code);
+            return;
+        }
+        if (m.type === "room.joined") {
+            if (m.requestId !== String(gen))
+                return;
+            clearTimeout(this.timer);
+            this.iceServers = m.iceServers;
+            this.update({ phase: "joined", meetingId: m.meetingId, selfId: m.selfId });
+            return;
+        }
+        if (m.meetingId !== this.state.meetingId || this.state.phase !== "joined")
+            return;
+        if (m.type === "room.state") {
+            const old = new Map(this.state.participants.map(p => [p.id, p]));
+            this.update({ sharingId: m.sharingId ?? undefined, participants: m.participants.map((p) => ({ ...old.get(p.id), ...p, connection: p.id === this.state.selfId ? "connected" : old.get(p.id)?.connection ?? "connecting" })) });
+            for (const [id, l] of this.links)
+                if (!this.state.participants.some(p => p.id === id)) {
+                    this.links.delete(id);
+                    clearTimeout(l.timer);
+                    l.pc.close();
+                }
+            for (const p of this.state.participants)
+                if (p.id !== this.state.selfId)
+                    this.link(p.id, gen);
+            await this.syncScreen();
+            return;
+        }
+        if (!this.state.participants.some(p => p.id === m.peerId) || m.peerId === this.state.selfId)
+            return;
+        const l = this.link(m.peerId, gen), pc = l.pc;
+        if (m.type === "room.offer") {
+            await pc.setLocalDescription(await pc.createOffer());
+            if (gen === this.generation)
+                this.send({ type: "room.sdp", meetingId: this.state.meetingId, peerId: m.peerId, description: pc.localDescription });
+        }
+        else if (m.type === "room.sdp") {
+            await pc.setRemoteDescription(m.description);
+            if (gen !== this.generation)
+                return;
+            for (const c of l.candidates.splice(0))
+                await pc.addIceCandidate(c);
+            if (m.description.type === "offer") {
+                // setRemoteDescription may create the answerer's receiving transceiver;
+                // attach sharing to that negotiated m-line, not an unassociated local one.
+                const negotiated = pc.getTransceivers().find(t => t.mid !== null && t.receiver.track.kind === "video");
+                if (negotiated) {
+                    if (l.video !== negotiated && l.video.mid === null)
+                        l.video.stop();
+                    l.video = negotiated;
+                    l.video.direction = "sendrecv";
+                    await l.video.sender.replaceTrack(this.state.sharingId === this.state.selfId ? this.screen?.getVideoTracks()[0] ?? null : null);
+                }
+                await pc.setLocalDescription(await pc.createAnswer());
+                if (gen === this.generation)
+                    this.send({ type: "room.sdp", meetingId: this.state.meetingId, peerId: m.peerId, description: pc.localDescription });
+            }
+            for (const sender of pc.getSenders()) {
+                const params = sender.getParameters();
+                if (params.encodings?.length) {
+                    for (const encoding of params.encodings)
+                        encoding.maxBitrate = sender === l.video.sender ? 800000 : 64000;
+                    await sender.setParameters(params);
+                }
+            }
+        }
+        else if (m.type === "room.ice") {
+            if (pc.remoteDescription)
+                await pc.addIceCandidate(m.candidate);
+            else if (l.candidates.length < 128)
+                l.candidates.push(m.candidate);
+        }
+    }
+}

package/lib/runtime/presence.d.ts

@@ -0,0 +1,44 @@
+export type PresenceStatus = "online" | "offline" | "unknown";
+export type ChatPresence = {
+    appId: string;
+    profileId: string;
+    status: PresenceStatus;
+    availability: "normal" | "degraded";
+};
+export type PresenceOptions = {
+    appId: string;
+    profileId: string;
+    instanceId?: string;
+    token: () => Promise<string> | string;
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+    onError?: (error: unknown) => void;
+};
+/** One instance is one authenticated client/runtime lease, never a whole profile. */
+export declare class ChatPresenceClient {
+    private options;
+    readonly instanceId: string;
+    private seq;
+    private active;
+    private generation;
+    private beatTimer?;
+    private queryTimer?;
+    private expiryTimer?;
+    private beating;
+    private querying;
+    private profiles;
+    private entries;
+    private handlers;
+    private availability;
+    constructor(options: PresenceOptions);
+    snapshot(): ChatPresence[];
+    watch(handler: (items: ChatPresence[]) => void): () => void;
+    watchProfiles(ids: string[]): void;
+    setAvailability(value: "normal" | "degraded"): void;
+    start(): void;
+    stop(): void;
+    private request;
+    private heartbeat;
+    private query;
+    private emit;
+}

package/lib/runtime/presence.js

@@ -0,0 +1,132 @@
+/** One instance is one authenticated client/runtime lease, never a whole profile. */
+export class ChatPresenceClient {
+    options;
+    instanceId;
+    seq = 0;
+    active = false;
+    generation = 0;
+    beatTimer;
+    queryTimer;
+    expiryTimer;
+    beating = false;
+    querying = false;
+    profiles = [];
+    entries = new Map();
+    handlers = new Set();
+    availability = "normal";
+    constructor(options) {
+        this.options = options;
+        this.instanceId = options.instanceId ?? crypto.randomUUID();
+    }
+    snapshot() {
+        return this.profiles.map(profileId => {
+            const entry = this.entries.get(profileId);
+            return entry && entry.expires > Date.now() ? { appId: entry.appId, profileId, status: entry.status, availability: entry.availability }
+                : { appId: this.options.appId, profileId, status: "unknown", availability: "normal" };
+        });
+    }
+    watch(handler) { this.handlers.add(handler); handler(this.snapshot()); return () => { this.handlers.delete(handler); }; }
+    watchProfiles(ids) {
+        const profiles = [...new Set(ids)].sort().slice(0, 50);
+        if (JSON.stringify(profiles) === JSON.stringify(this.profiles))
+            return;
+        this.profiles = profiles;
+        this.generation++;
+        this.entries.clear();
+        this.emit();
+        if (this.active)
+            void this.query();
+    }
+    setAvailability(value) { this.availability = value; }
+    start() {
+        if (this.active)
+            return;
+        this.active = true;
+        this.generation++;
+        void this.heartbeat();
+        void this.query();
+        this.beatTimer = setInterval(() => void this.heartbeat(), 20_000);
+        this.queryTimer = setInterval(() => void this.query(), 5_000);
+        this.expiryTimer = setInterval(() => {
+            if ([...this.entries.values()].some(e => e.expires <= Date.now())) {
+                for (const [id, e] of this.entries)
+                    if (e.expires <= Date.now())
+                        this.entries.delete(id);
+                this.emit();
+            }
+        }, 1000);
+    }
+    stop() {
+        const wasActive = this.active;
+        this.active = false;
+        this.generation++;
+        clearInterval(this.beatTimer);
+        clearInterval(this.queryTimer);
+        clearInterval(this.expiryTimer);
+        this.entries.clear();
+        this.emit();
+        // Sequence tombstones prevent an in-flight heartbeat from undoing release.
+        if (wasActive)
+            void this.request("release", { instanceId: this.instanceId, seq: ++this.seq }).catch(e => this.options.onError?.(e));
+    }
+    async request(action, params) {
+        const token = await this.options.token();
+        const response = await (this.options.fetchImpl ?? fetch)(`${(this.options.baseUrl ?? "https://hub.pmate.chat").replace(/\/$/, "")}/api/chat-presence/${action}`, {
+            method: "POST", headers: { Authorization: `Bearer ${token}`, "Content-Type": "application/json" },
+            body: JSON.stringify({ appId: this.options.appId, profileId: this.options.profileId, ...params }), signal: AbortSignal.timeout(12_000), keepalive: action === "release",
+        });
+        if (!response.ok)
+            throw new Error(`Presence request failed (${response.status})`);
+        const result = await response.json();
+        if (!result.success)
+            throw new Error("Presence unavailable");
+        return result.data;
+    }
+    async heartbeat() {
+        if (!this.active || this.beating)
+            return;
+        this.beating = true;
+        try {
+            await this.request("heartbeat", { instanceId: this.instanceId, seq: ++this.seq, availability: this.availability });
+        }
+        catch (e) {
+            this.options.onError?.(e);
+        }
+        finally {
+            this.beating = false;
+        }
+    }
+    async query() {
+        if (!this.active || !this.profiles.length || this.querying)
+            return;
+        this.querying = true;
+        const generation = this.generation, requested = this.profiles.slice(), started = Date.now();
+        try {
+            const result = await this.request("query", { profileIds: requested });
+            if (!this.active || generation !== this.generation)
+                return;
+            if (!Array.isArray(result?.items))
+                throw new Error("Invalid presence snapshot");
+            const entries = new Map();
+            for (const item of result.items) {
+                if (item.appId !== this.options.appId || !requested.includes(item.profileId) || !["online", "offline", "unknown"].includes(item.status) || !Number.isFinite(item.validForMs) || item.validForMs < 0)
+                    throw new Error("Invalid presence item");
+                entries.set(item.profileId, { ...item, availability: item.availability === "degraded" ? "degraded" : "normal", expires: started + Math.min(item.validForMs, 10_000) });
+            }
+            this.entries = entries;
+            this.emit();
+        }
+        catch (e) {
+            if (generation === this.generation) {
+                this.entries.clear();
+                this.emit();
+            }
+            this.options.onError?.(e);
+        }
+        finally {
+            this.querying = false;
+        }
+    }
+    emit() { const items = this.snapshot(); for (const h of this.handlers)
+        h(items); }
+}

package/lib/runtime/protocol.d.ts

@@ -72,13 +72,24 @@ export declare class RuntimeWebsocketClient implements RealtimeClient {
     private readonly wsUrl;
     private ws;
     private connected;
+    private closed;
+    private attempt;
+    private retryTimer?;
+    private connectTimer?;
+    private heartbeatTimer?;
+    private pongTimer?;
     private readonly listeners;
+    private readonly onWake;
     constructor(wsUrl: string);
     on<T>(topic: string, handler: (value: T) => void): () => boolean;
     isConnected(): boolean;
-    close(): void;
+    close(manual?: boolean): void;
     sendMsg(msg: ChatRuntimeMessage): Promise<void>;
     getConnectionType(): "websocket";
     private connect;
+    private ping;
+    private dropSocket;
+    private clearRetry;
+    private scheduleReconnect;
     private emit;
 }

package/lib/runtime/protocol.js

@@ -32,9 +32,31 @@ export class RuntimeWebsocketClient {
     wsUrl;
     ws = null;
     connected = false;
+    closed = false;
+    attempt = 0;
+    retryTimer;
+    connectTimer;
+    heartbeatTimer;
+    pongTimer;
     listeners = new Map();
+    onWake = () => {
+        if (this.closed || (typeof document !== "undefined" && document.hidden))
+            return;
+        if (this.connected)
+            this.ping();
+        else {
+            this.clearRetry();
+            if (!this.ws)
+                this.connect();
+        }
+    };
     constructor(wsUrl) {
         this.wsUrl = wsUrl;
+        if (typeof window !== "undefined") {
+            window.addEventListener("online", this.onWake);
+            window.addEventListener("pageshow", this.onWake);
+            document.addEventListener("visibilitychange", this.onWake);
+        }
         this.connect();
     }
     on(topic, handler) {
@@ -46,10 +68,17 @@ export class RuntimeWebsocketClient {
     isConnected() {
         return this.connected;
     }
-    close() {
-        this.ws?.close();
-        this.ws = null;
-        this.connected = false;
+    close(manual = true) {
+        this.closed = manual;
+        this.clearRetry();
+        this.dropSocket();
+        if (manual && typeof window !== "undefined") {
+            window.removeEventListener("online", this.onWake);
+            window.removeEventListener("pageshow", this.onWake);
+            document.removeEventListener("visibilitychange", this.onWake);
+        }
+        if (!manual)
+            this.scheduleReconnect();
     }
     async sendMsg(msg) {
         if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
@@ -61,20 +90,53 @@ export class RuntimeWebsocketClient {
         return "websocket";
     }
     connect() {
-        this.ws = new WebSocket(this.wsUrl);
-        this.ws.binaryType = "arraybuffer";
-        this.ws.onopen = () => {
+        if (this.closed || this.ws)
+            return;
+        let ws;
+        try {
+            ws = new WebSocket(this.wsUrl);
+        }
+        catch (error) {
+            this.emit(ChatRealtimeEvents.Error, error);
+            this.scheduleReconnect();
+            return;
+        }
+        this.ws = ws;
+        ws.binaryType = "arraybuffer";
+        this.connectTimer = setTimeout(() => this.close(false), 10_000);
+        ws.onopen = () => {
+            if (this.ws !== ws)
+                return;
+            clearTimeout(this.connectTimer);
             this.connected = true;
+            this.attempt = 0;
+            this.heartbeatTimer = setInterval(() => this.ping(), 20_000);
             this.emit(ChatRealtimeEvents.Connected, true);
         };
-        this.ws.onclose = () => {
-            this.connected = false;
-            this.emit(ChatRealtimeEvents.Connected, false);
-        };
-        this.ws.onerror = (event) => {
+        ws.onclose = () => { if (this.ws === ws)
+            this.close(false); };
+        ws.onerror = (event) => {
+            if (this.ws !== ws)
+                return;
             this.emit(ChatRealtimeEvents.Error, event);
+            this.close(false);
         };
-        this.ws.onmessage = (event) => {
+        ws.onmessage = (event) => {
+            if (this.ws !== ws)
+                return;
+            // Hub uses single-byte binary PING/PONG frames, separate from MessagePack.
+            const bytes = event.data instanceof ArrayBuffer ? new Uint8Array(event.data) : event.data;
+            if (bytes instanceof Uint8Array && bytes.length === 1) {
+                if (bytes[0] === 2) {
+                    clearTimeout(this.pongTimer);
+                    this.pongTimer = undefined;
+                    return;
+                }
+                if (bytes[0] === 1) {
+                    ws.send(new Uint8Array([2]));
+                    return;
+                }
+            }
             try {
                 this.emit(ChatRealtimeEvents.Message, decodeWireMessage(event.data));
             }
@@ -83,6 +145,41 @@ export class RuntimeWebsocketClient {
             }
         };
     }
+    ping() {
+        if (!this.connected || this.pongTimer || !this.ws)
+            return;
+        this.pongTimer = setTimeout(() => this.close(false), 10_000);
+        try {
+            this.ws.send(new Uint8Array([1]));
+        }
+        catch {
+            this.close(false);
+        }
+    }
+    dropSocket() {
+        clearTimeout(this.connectTimer);
+        clearInterval(this.heartbeatTimer);
+        clearTimeout(this.pongTimer);
+        this.pongTimer = undefined;
+        const ws = this.ws;
+        this.ws = null;
+        this.connected = false;
+        if (ws) {
+            ws.onopen = ws.onclose = ws.onerror = ws.onmessage = null;
+            ws.close();
+        }
+        this.emit(ChatRealtimeEvents.Connected, false);
+    }
+    clearRetry() { clearTimeout(this.retryTimer); this.retryTimer = undefined; }
+    scheduleReconnect() {
+        if (this.closed || this.retryTimer)
+            return;
+        const delay = Math.min(30_000, 500 * 2 ** Math.min(this.attempt++, 6));
+        this.retryTimer = setTimeout(() => {
+            this.retryTimer = undefined;
+            this.connect();
+        }, delay * (0.8 + Math.random() * 0.2));
+    }
     emit(topic, value) {
         for (const handler of this.listeners.get(topic) ?? []) {
             handler(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmate/chat-sdk",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "description": "Cross-platform PMate chat input components, voice input primitives, and ASR helpers",
   "type": "module",
   "main": "./lib/index.js",