pingerchips-js 2.1.1 → 3.0.0

package/index.js

@@ -1,4 +1,28 @@
 import { Socket } from "phoenix";
+import { decode, encode } from "@msgpack/msgpack";
+
+function messagePackEncode(message, callback) {
+  callback(
+    encode([
+      message.join_ref,
+      message.ref,
+      message.topic,
+      message.event,
+      message.payload,
+    ]),
+  );
+}
+
+function messagePackDecode(payload, callback) {
+  if (typeof payload === "string") {
+    throw new Error(
+      "MessagePack socket received an unexpected text payload; expected binary data",
+    );
+  }
+
+  const [join_ref, ref, topic, event, messagePayload] = decode(payload);
+  callback({ join_ref, ref, topic, event, payload: messagePayload });
+}
 
 export class Pingerchips {
   constructor(appKey, options = {}) {
@@ -9,72 +33,251 @@ export class Pingerchips {
     this.socketId = null;
     this.authInfo = options.authInfo || {};
     this._endpoint = this._resolveEndpoint();
+    this._socketIdPromise = null;
+    this._recoveryState = null;
 
     this.connect();
   }
 
   _resolveEndpoint() {
-    return (
-      this.options.endpoint ||
-      (this.options.debug === "false"
-        ? "wss://queue.pingerchips.com/socket"
-        : "ws://localhost:4000/socket")
-    );
+    if (this.options.endpoint) return this.options.endpoint;
+    const isProd = typeof process !== "undefined"
+      ? process.env.NODE_ENV === "production"
+      : !this.options.debug;
+    return isProd
+      ? "wss://queue.pingerchips.com/socket"
+      : "ws://localhost:4000/socket";
   }
 
   connect() {
     const params = { app_key: this.key, ...this.options.params };
+    const socketOptions = { params };
 
-    this.socket = new Socket(this._endpoint, { params });
-    this.socket.connect();
+    if (this.options.reconnectAfterMs) {
+      socketOptions.reconnectAfterMs = this.options.reconnectAfterMs;
+    }
+    if (this.options.rejoinAfterMs) {
+      socketOptions.rejoinAfterMs = this.options.rejoinAfterMs;
+    }
+    if (this.options.transport) {
+      socketOptions.transport = this.options.transport;
+    }
+    if (
+      this.options.serializer === "msgpack" ||
+      this.options.messageFormat === "msgpack"
+    ) {
+      Object.assign(socketOptions, {
+        vsn: "3.0.0",
+        binaryType: "arraybuffer",
+        encode: messagePackEncode,
+        decode: messagePackDecode,
+      });
+    }
 
-    this.socket.onOpen(() => {
-      // Socket ID comes from the server via socket params on open —
-      // read it directly from the socket transport if available,
-      // otherwise it is set when the first channel join receives socket_id.
-      const transportParams = this.socket.params();
+    if (this.socket) this.disconnect();
+    const socket = new Socket(this._endpoint, socketOptions);
+    this.socket = socket;
+
+    socket.onOpen(async () => {
+      if (this.socket !== socket) return;
+      const transportParams = socket.params();
       if (transportParams?.socket_id) {
         this.socketId = transportParams.socket_id;
       }
+      await this._resumeSubscriptions();
     });
 
-    this.socket.onClose(() => {
-      // Clear socket ID on disconnect — will be re-acquired on reconnect
+    socket.onClose(() => {
+      if (this.socket !== socket) return;
       this.socketId = null;
       this._resubscribeOnReconnect();
     });
+    socket.connect();
   }
 
-  // Re-join all previously subscribed channels after reconnect.
-  // Phoenix Socket handles reconnect automatically; we re-subscribe channels
-  // once the socket is open again.
   _resubscribeOnReconnect() {
-    const channelNames = Object.keys(this.channels);
-    if (channelNames.length === 0) return;
+    const entries = Object.entries(this.channels);
+    if (entries.length === 0) return;
+
+    // Capture last-known serials / log positions before clearing stale refs
+    const recoveryState = {};
+    for (const [name, wrapper] of entries) {
+      if (wrapper instanceof DurableObject) {
+        recoveryState[name] = {
+          durable: true,
+          type: wrapper.type,
+          key: wrapper.key,
+          afterLogId: wrapper.logId,
+          handlers: wrapper._handlers,
+        };
+      } else {
+        recoveryState[name] = {
+          options: wrapper._subscribeOptions,
+          serial: wrapper._lastSerial,
+        };
+      }
+    }
 
-    // Clear stale channel references — they are bound to the old socket connection
     this.channels = {};
+    for (const [, wrapper] of entries) wrapper.leave();
+    this._recoveryState = recoveryState;
+  }
 
-    const attemptResubscribe = () => {
-      if (this.socket.isConnected()) {
-        channelNames.forEach((name) => {
-          this.subscribe(name).catch(() => {
-            // Silently retry on next reconnect cycle
-          });
-        });
-      } else {
-        // Wait for next open event
-        this.socket.onOpen(() => {
-          channelNames.forEach((name) => {
-            this.subscribe(name).catch(() => {});
+  async _resumeSubscriptions() {
+    const recoveryState = this._recoveryState;
+    if (!recoveryState) return;
+    this._recoveryState = null;
+
+    const entries = Object.entries(recoveryState);
+    const needsAuth = entries.some(
+      ([name, s]) =>
+        s.durable ||
+        name.startsWith("private-") ||
+        name.startsWith("presence-"),
+    );
+    if (needsAuth) {
+      try {
+        await this.getSocketIdAsync();
+      } catch (err) {
+        console.error("[pingerchips] socket bootstrap failed:", err.message);
+        return;
+      }
+    }
+
+    for (const [name, s] of entries) {
+      if (s.durable) {
+        this.object(s.type, s.key, { afterLogId: s.afterLogId })
+          .then((obj) => {
+            // re-attach the handlers the previous view had
+            obj._handlers = s.handlers || {};
+          })
+          .catch((err) => {
+            console.error(
+              `[pingerchips] durable object resubscribe failed for ${s.type}/${s.key}:`,
+              err.message,
+            );
           });
-        });
+        continue;
       }
-    };
 
-    attemptResubscribe();
+      const opts =
+        s.serial != null ? { ...s.options, after_serial: s.serial } : s.options;
+      this.subscribe(name, opts).catch((err) => {
+        console.error(`[pingerchips] resubscribe failed for ${name}:`, err.message);
+      });
+    }
+  }
+
+  async getSocketIdAsync(timeoutMs = 10000) {
+    if (this.socketId) return this.socketId;
+    if (this._socketIdPromise) return this._socketIdPromise;
+
+    const pending = this._bootstrapSocketId(timeoutMs);
+    this._socketIdPromise = pending;
+    try {
+      return await pending;
+    } finally {
+      if (this._socketIdPromise === pending) this._socketIdPromise = null;
+    }
+  }
+
+  async _bootstrapSocketId(timeoutMs) {
+    const socket = this.socket;
+    if (!socket) throw new Error("Socket is not available");
+
+    if (!socket.isConnected()) {
+      await new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        let openRef;
+        let closeRef;
+        const finish = (callback) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          socket.off([openRef, closeRef]);
+          callback();
+        };
+        openRef = socket.onOpen(() => finish(() => {
+          if (this.socket === socket) resolve();
+          else reject(new Error("Socket changed during bootstrap"));
+        }));
+        closeRef = socket.onClose(() =>
+          finish(() => reject(new Error("Socket closed before opening"))),
+        );
+        timer = setTimeout(
+          () => finish(() => reject(new Error("Socket did not connect in time"))),
+          timeoutMs,
+        );
+      });
+    }
+
+    if (this.socket !== socket || !socket.isConnected()) {
+      throw new Error("Socket disconnected during bootstrap");
+    }
+
+    const channel = socket.channel(
+      `app:${this.key}:room:ephemeral-pingerchips-bootstrap`,
+      {},
+    );
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      let timer;
+      let closeRef;
+      const finish = (callback) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        socket.off([closeRef]);
+        channel.leave();
+        callback();
+      };
+      closeRef = socket.onClose(() =>
+        finish(() => reject(new Error("Socket closed during bootstrap"))),
+      );
+      timer = setTimeout(
+        () => finish(() => reject(new Error("Socket bootstrap timed out"))),
+        timeoutMs,
+      );
+
+      channel
+        .join(timeoutMs)
+        .receive("ok", (resp) => {
+          if (!resp?.socket_id) {
+            finish(() => reject(new Error("Socket bootstrap did not return a socket ID")));
+            return;
+          }
+          finish(() => {
+            if (this.socket !== socket) {
+              reject(new Error("Socket changed during bootstrap"));
+              return;
+            }
+            this.socketId = resp.socket_id;
+            resolve(this.socketId);
+          });
+        })
+        .receive("error", (resp) => {
+          finish(() => reject(new Error(`Socket bootstrap failed: ${JSON.stringify(resp)}`)));
+        })
+        .receive("timeout", () => {
+          finish(() => reject(new Error("Socket bootstrap timed out")));
+        });
+    });
   }
 
+  /**
+   * Subscribe to a channel.
+   *
+   * @param {string} channelName
+   * @param {object} [options]
+   * @param {object} [options.filter]        - ExSift filter applied server-side per-subscription.
+   *                                           Same query format as FilterNode:
+   *                                           { "data.type": { "$eq": "alert" }, "metadata.event": "order" }
+   * @param {"fossil"|"xdelta3"|boolean} [options.delta] - Enable delta compression. Server sends
+   *                                           "message:delta" diffs; client applies them automatically.
+   * @param {number} [options.after_serial]  - Resume from this serial (connection recovery).
+   * @param {string} [options.auth]          - Auth token for private/presence channels (overrides authEndpoint).
+   */
   async subscribe(channelName, options = {}) {
     if (this.channels[channelName]) {
       return this.channels[channelName];
@@ -87,7 +290,7 @@ export class Pingerchips {
     let joinParams = {};
 
     if (isPrivate || isPresence) {
-      if (!this.options.authEndpoint) {
+      if (!this.options.authEndpoint && !options.auth) {
         throw new Error(
           "authEndpoint must be configured for private/presence channels",
         );
@@ -99,9 +302,16 @@ export class Pingerchips {
         );
       }
 
-      joinParams = await this.authenticate(channelName);
+      joinParams = options.auth
+        ? { auth: options.auth }
+        : await this.authenticate(channelName);
     }
 
+    // Subscription-level options
+    if (options.filter != null)       joinParams.filter       = options.filter;
+    if (options.delta != null)        joinParams.delta        = options.delta;
+    if (options.after_serial != null) joinParams.after_serial = options.after_serial;
+
     const channel = this.socket.channel(topic, joinParams);
 
     return new Promise((resolve, reject) => {
@@ -112,7 +322,8 @@ export class Pingerchips {
             this.socketId = resp.socket_id;
           }
 
-          const wrapper = new ChannelWrapper(channel);
+          const wrapper = new ChannelWrapper(channel, channelName, options, this);
+          if (resp.serial != null) wrapper._lastSerial = resp.serial;
           this.channels[channelName] = wrapper;
           resolve(wrapper);
         })
@@ -157,6 +368,28 @@ export class Pingerchips {
     return this.socketId;
   }
 
+  disconnect() {
+    for (const wrapper of Object.values(this.channels)) wrapper.leave();
+    this.channels = {};
+    this._recoveryState = null;
+    this._socketIdPromise = null;
+    this.socketId = null;
+    const socket = this.socket;
+    this.socket = null;
+    socket?.disconnect();
+  }
+
+  /**
+   * Returns the last received serial for a subscribed channel.
+   * Use to checkpoint durable message position across page reloads.
+   *
+   * @param {string} channelName
+   * @returns {number|null}
+   */
+  getLastSerial(channelName) {
+    return this.channels[channelName]?._lastSerial ?? null;
+  }
+
   getHttpEndpoint() {
     return this._endpoint
       .replace("ws://", "http://")
@@ -164,26 +397,346 @@ export class Pingerchips {
       .replace("/socket", "");
   }
 
+  /**
+   * Register a push device token for a user.
+   * NOTE: This should be called from your backend, not from the browser.
+   * Use the server SDK (pingerchips-js-server) for push token management.
+   *
+   * @deprecated Use PingerchipsServer.registerPushToken() from pingerchips-js-server instead.
+   */
+  async registerPushToken() {
+    throw new Error(
+      "registerPushToken has been removed from the client SDK for security reasons. " +
+      "Use PingerchipsServer.registerPushToken() from pingerchips-js-server instead."
+    );
+  }
+
+  /**
+   * @deprecated Use PingerchipsServer.unregisterPushToken() from pingerchips-js-server instead.
+   */
+  async unregisterPushToken() {
+    throw new Error(
+      "unregisterPushToken has been removed from the client SDK for security reasons. " +
+      "Use PingerchipsServer.unregisterPushToken() from pingerchips-js-server instead."
+    );
+  }
+
   unsubscribe(channelName) {
     if (this.channels[channelName]) {
       this.channels[channelName].leave();
       delete this.channels[channelName];
     }
   }
+
+  /**
+   * Subscribe to a Durable Object. Read-only from the browser — writes go
+   * through your backend (pingerchips-js-server). Resolves once the initial
+   * `snapshot` has arrived, so `.state` / `.get()` are ready immediately.
+   *
+   * @param {string} type   - Object type (arbitrary string).
+   * @param {string} key    - Object key (arbitrary string).
+   * @param {object} [options]
+   * @param {number} [options.afterLogId] - Resume: replay entries after this
+   *                                        log_id before the snapshot.
+   * @param {string} [options.auth]       - Pre-minted capability token
+   *                                        (from server SDK authenticateObject),
+   *                                        bypassing the auth endpoint.
+   * @param {string} [options.authEndpoint] - Override the client's authEndpoint
+   *                                          for this call.
+   * @returns {Promise<DurableObject>}
+   */
+  async object(type, key, options = {}) {
+    if (!type || !key) {
+      throw new Error("object(type, key) requires a non-empty type and key");
+    }
+
+    const cacheKey = `durable:${type}:${key}`;
+    if (this.channels[cacheKey]) return this.channels[cacheKey];
+
+    const socketId = await this.getSocketIdAsync();
+
+    let auth = options.auth;
+    if (!auth) {
+      auth = await this.authenticateObject(type, key, socketId, options.authEndpoint);
+    }
+
+    const joinParams = { auth };
+    if (options.afterLogId != null) joinParams.after_log_id = options.afterLogId;
+
+    const topic = `durable:${this.key}:${type}:${key}`;
+    const channel = this.socket.channel(topic, joinParams);
+
+    return new Promise((resolve, reject) => {
+      const obj = new DurableObject(channel, type, key, this, cacheKey);
+
+      channel
+        .join()
+        .receive("ok", () => {
+          this.channels[cacheKey] = obj;
+          obj._whenReady().then(() => resolve(obj), reject);
+        })
+        .receive("error", (resp) => {
+          channel.leave();
+          reject(new Error(`Failed to join durable object: ${JSON.stringify(resp)}`));
+        })
+        .receive("timeout", () => {
+          channel.leave();
+          reject(new Error("Timed out joining durable object channel"));
+        });
+    });
+  }
+
+  /**
+   * Fetch a per-object capability token from your auth endpoint.
+   * POSTs { socket_id, object_type, object_key, auth_info } and expects
+   * { auth: "<capability token>" } back (see server SDK authenticateObject).
+   */
+  async authenticateObject(type, key, socketId, endpointOverride) {
+    const endpoint = endpointOverride || this.options.authEndpoint;
+    if (!endpoint) {
+      throw new Error(
+        "authEndpoint must be configured for Durable Object subscriptions " +
+          "(or pass an explicit `auth` token).",
+      );
+    }
+
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        ...this.options.authHeaders,
+      },
+      body: JSON.stringify({
+        socket_id: socketId || this.socketId,
+        object_type: type,
+        object_key: key,
+        auth_info: this.authInfo,
+      }),
+    });
+
+    if (!response.ok) {
+      const error = await response
+        .json()
+        .catch(() => ({ error: "Object authentication failed" }));
+      throw new Error(error.error || "Object authentication failed");
+    }
+
+    const data = await response.json();
+    if (!data || !data.auth) {
+      throw new Error("Auth endpoint did not return an `auth` token");
+    }
+    return data.auth;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Delta apply — fossil and xdelta3
+// Both algorithms are applied server-side on Rust NIFs; client receives
+// Base64-encoded patch bytes and applies them in JS.
+//
+// fossil-delta JS port: https://github.com/dchest/fossil-delta-js
+// xdelta3 WASM: not yet bundled — falls back to requesting a full message.
+// ---------------------------------------------------------------------------
+
+function applyFossilDelta(sourceBytes, deltaBytes) {
+  // Inline fossil-delta apply — same algorithm as the Rust fossil-delta crate.
+  // Source: adapted from dchest/fossil-delta-js (MIT)
+  let zDelta = deltaBytes;
+  let lenSrc = sourceBytes.length;
+  let lenDelta = zDelta.length;
+  let total = 0;
+  let i = 0;
+
+  function readInt() {
+    let v = 0;
+    while (i < lenDelta) {
+      let c = zDelta[i++];
+      if (c >= 0x80) {
+        v = (v << 7) | (c & 0x7f);
+      } else {
+        v = (v << 7) | c;
+        break;
+      }
+    }
+    return v;
+  }
+
+  let lenOut = readInt();
+  i++; // skip '\n'
+
+  let out = new Uint8Array(lenOut);
+  let outPos = 0;
+
+  while (i < lenDelta) {
+    let cnt = readInt();
+    let op = zDelta[i++];
+    if (op === 0x40) { // '@' copy from source
+      let ofst = readInt();
+      i++; // skip ','
+      out.set(sourceBytes.subarray(ofst, ofst + cnt), outPos);
+      outPos += cnt;
+    } else if (op === 0x3a) { // ':' literal
+      out.set(zDelta.subarray(i, i + cnt), outPos);
+      i += cnt;
+      outPos += cnt;
+      i++; // skip ','
+    } else if (op === 0x3b) { // ';' end
+      break;
+    }
+  }
+
+  return out.subarray(0, outPos);
 }
 
+function base64ToBytes(b64) {
+  const bin = atob(b64);
+  const bytes = new Uint8Array(bin.length);
+  for (let i = 0; i < bin.length; i++) bytes[i] = bin.charCodeAt(i);
+  return bytes;
+}
+
+// ---------------------------------------------------------------------------
+
 class ChannelWrapper {
-  constructor(channel) {
+  constructor(channel, channelName, subscribeOptions, client) {
     this.channel = channel;
+    this.channelName = channelName;
+    this._subscribeOptions = subscribeOptions;
+    this._client = client;
+    this._lastSerial = null;
+
+    // Per-channel delta state: { base: Uint8Array, seq: number } | null
+    this._deltaBase = null;
+
+    // Track serial from every message for reconnect recovery
+    this._trackSerial = (payload) => {
+      if (payload?.serial != null) this._lastSerial = payload.serial;
+    };
+
+    channel.on("message", (payload) => {
+      this._trackSerial(payload);
+    });
+
+    // Handle delta-compressed messages from server
+    channel.on("message:delta", (payload) => {
+      const full = this._applyDelta(payload);
+      if (full) {
+        this._trackSerial(full);
+        // Re-emit as "message" so callers don't need to handle both events
+        this._emitMessage(full);
+      } else {
+        // Apply failed — ask server to reset delta state for this channel
+        channel.push("pingerchips:delta_sync_error", { channel: channelName });
+      }
+    });
+
+    channel.on("pingerchips:delta_compression_enabled", (payload) => {
+      // Server confirmed delta negotiation — reset local base
+      this._deltaBase = null;
+    });
+
+    channel.on("pingerchips:recovery_failed", (payload) => {
+      // Server couldn't replay — reset serial and surface to app code
+      this._lastSerial = null;
+      for (const handler of this._recoveryFailedHandlers) {
+        handler({
+          reason: payload.reason,       // "position_expired" | "no_buffer"
+          channel: payload.channel,
+          afterSerial: payload.after_serial,
+        });
+      }
+    });
+
+    this._messageHandlers = [];
+    this._recoveryFailedHandlers = [];
+  }
+
+  /**
+   * Register a handler for when the server cannot replay missed messages.
+   * Payload: { reason: "position_expired"|"no_buffer", channel: string, afterSerial: number }
+   *
+   * Use this to decide whether to re-fetch state from your API.
+   *
+   * @param {function} callback
+   * @returns {this}
+   */
+  onRecoveryFailed(callback) {
+    this._recoveryFailedHandlers.push(callback);
+    return this;
+  }
+
+  _applyDelta(deltaPayload) {
+    if (!this._deltaBase) return null;
+
+    const { delta: b64, seq, algorithm } = deltaPayload;
+    if (!b64) return null;
+
+    try {
+      const deltaBytes = base64ToBytes(b64);
+
+      if (algorithm === "xdelta3") {
+        // xdelta3 WASM not bundled yet — signal sync error so server sends full
+        return null;
+      }
+
+      // Default: fossil
+      const sourceBytes = this._deltaBase.bytes;
+      const resultBytes = applyFossilDelta(sourceBytes, deltaBytes);
+      const text = new TextDecoder().decode(resultBytes);
+      const full = JSON.parse(text);
+
+      // Update base to the reconstructed full message
+      this._deltaBase = { bytes: resultBytes, seq };
+      return full;
+    } catch (err) {
+      console.warn("[pingerchips] delta apply failed:", err.message);
+      return null;
+    }
+  }
+
+  _emitMessage(payload) {
+    // Update delta base whenever we receive a full message
+    try {
+      const bytes = new TextEncoder().encode(JSON.stringify(payload));
+      this._deltaBase = { bytes, seq: payload.serial };
+    } catch (err) {
+      console.warn("[pingerchips] delta base update failed:", err.message);
+    }
+
+    for (const handler of this._messageHandlers) {
+      handler(payload);
+    }
   }
 
   bind(eventName, callback) {
-    this.channel.on(eventName, callback);
+    if (eventName === "message") {
+      // Route through delta-aware path
+      this._messageHandlers.push(callback);
+
+      // Also hook the raw channel.on once so _emitMessage fires
+      if (this._messageHandlers.length === 1) {
+        this.channel.on("message", (payload) => this._emitMessage(payload));
+      }
+    } else {
+      this.channel.on(eventName, callback);
+    }
     return this;
   }
 
-  unbind(eventName) {
-    this.channel.off(eventName);
+  unbind(eventName, callback) {
+    if (eventName === "message") {
+      if (callback) {
+        this._messageHandlers = this._messageHandlers.filter((h) => h !== callback);
+      } else {
+        this._messageHandlers = [];
+      }
+    } else {
+      if (callback) {
+        this.channel.off(eventName, callback);
+      } else {
+        this.channel.off(eventName);
+      }
+    }
     return this;
   }
 
@@ -198,3 +751,242 @@ class ChannelWrapper {
 }
 
 export default Pingerchips;
+
+export { ActiveRun, ChatSession, PingerchipsChat, View } from "./chat.js";
+
+// Chat API lives in chat.js — import { PingerchipsChat } from "./chat.js"
+
+// ---------------------------------------------------------------------------
+// DurableObject — read-only real-time view of a Durable Object
+// ---------------------------------------------------------------------------
+
+/**
+ * A live, read-only view of a Durable Object. Obtained from
+ * `pingerchips.object(type, key)`.
+ *
+ * The channel is read-only from the browser — all writes go through your
+ * backend via `pingerchips-js-server`.
+ *
+ * Server events:
+ *   snapshot  { state, log_id }                     — full state, on join / reconnect
+ *   change    { key, value, previous?, log_id }     — one slot set / incremented / deleted
+ *   batch     { changes: [{key, value, previous}], log_id } — setAll / transaction
+ *
+ * Local events you can listen for:
+ *   "snapshot", "change", "batch", "change:{slot}"
+ */
+export class DurableObject {
+  constructor(channel, type, key, client, cacheKey) {
+    this.channel = channel;
+    this.type = type;
+    this.key = key;
+    this._client = client;
+    this._cacheKey = cacheKey;
+
+    /** Last known state map. Updated on every snapshot / change / batch. */
+    this.state = {};
+    /** Last seen log position. Checkpoint this for resumable reconnects. */
+    this.logId = 0;
+
+    this._handlers = {};
+    this._ready = new Promise((resolve) => {
+      this._resolveReady = resolve;
+    });
+
+    channel.on("snapshot", (payload) => {
+      this.state = payload.state ?? {};
+      if (payload.log_id != null) this.logId = payload.log_id;
+      this._emit("snapshot", payload);
+      this._resolveReady?.();
+      this._resolveReady = null;
+    });
+
+    channel.on("change", (payload) => {
+      const { key, value } = payload;
+      if (value === null || value === undefined) {
+        const next = { ...this.state };
+        delete next[key];
+        this.state = next;
+      } else {
+        this.state = { ...this.state, [key]: value };
+      }
+      if (payload.log_id != null) this.logId = payload.log_id;
+      this._emit("change", payload);
+      this._emit(`change:${key}`, payload);
+    });
+
+    channel.on("batch", (payload) => {
+      const changes = payload.changes ?? [];
+      let next = { ...this.state };
+      for (const { key, value } of changes) {
+        if (value === null || value === undefined) delete next[key];
+        else next[key] = value;
+      }
+      this.state = next;
+      if (payload.log_id != null) this.logId = payload.log_id;
+      this._emit("batch", payload);
+      for (const change of changes) {
+        this._emit("change", { ...change, log_id: payload.log_id });
+        this._emit(`change:${change.key}`, { ...change, log_id: payload.log_id });
+      }
+    });
+  }
+
+  _whenReady() {
+    return this._ready;
+  }
+
+  /**
+   * Read a slot from the local cached state. Synchronous — no network call.
+   * @param {string} slot
+   * @returns {any}
+   */
+  get(slot) {
+    return this.state[slot];
+  }
+
+  /**
+   * Listen for an event. Built-in: "snapshot", "change", "batch",
+   * "change:{slot}". Returns an unsubscribe function.
+   * @param {string} event
+   * @param {function} callback
+   * @returns {() => void}
+   */
+  on(event, callback) {
+    if (!this._handlers[event]) this._handlers[event] = [];
+    this._handlers[event].push(callback);
+    return () => this.off(event, callback);
+  }
+
+  /**
+   * Remove a handler, or all handlers for an event.
+   * @param {string} event
+   * @param {function} [callback]
+   * @returns {this}
+   */
+  off(event, callback) {
+    if (!callback) {
+      delete this._handlers[event];
+    } else {
+      this._handlers[event] = (this._handlers[event] || []).filter(
+        (h) => h !== callback,
+      );
+    }
+    return this;
+  }
+
+  _emit(event, payload) {
+    for (const h of this._handlers[event] || []) h(payload);
+  }
+
+  /** Leave the channel and stop receiving events. */
+  unsubscribe() {
+    this.channel.leave();
+    if (this._client && this._cacheKey) {
+      delete this._client.channels[this._cacheKey];
+    }
+  }
+
+  /** Internal alias so `client.disconnect()` can tear this down uniformly. */
+  leave() {
+    this.channel.leave();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ChatThreadChannel — legacy read-only channel wrapper (deprecated)
+// ---------------------------------------------------------------------------
+
+/**
+ * ChatThreadChannel — real-time view of a durable thread.
+ *
+ * The channel is read-only from the client. All writes (send, edit, delete,
+ * react, etc.) must go through your backend using pingerchips-js-server.
+ *
+ * Events from server:
+ *   snapshot  { state: object, log_id: number }   — full state on join
+ *   change    { key: string, value: any, previous: any, log_id: number }
+ *   batch     { changes: [{key, value, previous}], log_id: number }
+ */
+class ChatThreadChannel {
+  constructor(channel, threadId) {
+    this.channel = channel;
+    this.threadId = threadId;
+
+    // Last known state and log_id — updated on every snapshot/change/batch
+    this.state = {};
+    this.logId = 0;
+
+    this._handlers = {}; // event → [callback]
+
+    channel.on("snapshot", (payload) => {
+      this.state = payload.state ?? {};
+      this.logId = payload.log_id ?? 0;
+      this._emit("snapshot", payload);
+    });
+
+    channel.on("change", (payload) => {
+      this.state = { ...this.state, [payload.key]: payload.value };
+      if (payload.log_id != null) this.logId = payload.log_id;
+      this._emit("change", payload);
+      this._emit(`change:${payload.key}`, payload);
+    });
+
+    channel.on("batch", (payload) => {
+      const changes = payload.changes ?? [];
+      for (const { key, value } of changes) {
+        this.state = { ...this.state, [key]: value };
+      }
+      if (payload.log_id != null) this.logId = payload.log_id;
+      this._emit("batch", payload);
+    });
+  }
+
+  /**
+   * Get a slot from local state (no network call).
+   * @param {string} slot
+   * @returns {any}
+   */
+  get(slot) {
+    return this.state[slot];
+  }
+
+  /**
+   * Register a handler for a channel event.
+   * Built-in events: "snapshot", "change", "batch", "change:{slot}"
+   *
+   * @param {string} event
+   * @param {function} callback
+   * @returns {this}
+   */
+  on(event, callback) {
+    if (!this._handlers[event]) this._handlers[event] = [];
+    this._handlers[event].push(callback);
+    return this;
+  }
+
+  /**
+   * Remove a handler (or all handlers for an event if no callback given).
+   * @param {string} event
+   * @param {function} [callback]
+   * @returns {this}
+   */
+  off(event, callback) {
+    if (!callback) {
+      delete this._handlers[event];
+    } else {
+      this._handlers[event] = (this._handlers[event] || []).filter((h) => h !== callback);
+    }
+    return this;
+  }
+
+  _emit(event, payload) {
+    for (const h of this._handlers[event] || []) {
+      h(payload);
+    }
+  }
+
+  leave() {
+    this.channel.leave();
+  }
+}