@foony/chat 0.1.0 → 0.3.0

package/lib-cjs/storage.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Optional message persistence. A {@link ChatStorage} keeps a per-room snapshot between page
+ * loads, so a returning client renders instantly from its own copy and the server replays only
+ * what was missed (via the channel's resume cursor) instead of serving history again.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.indexedDbChatStorage = indexedDbChatStorage;
+/** Object store holding one record per room inside the IndexedDB database. */
+const STORE = 'rooms';
+/**
+ * A {@link ChatStorage} backed by IndexedDB, or null where IndexedDB does not exist (Node,
+ * some webviews) so callers can pass the result straight to `new ChatClient(...)`.
+ *
+ * @example
+ * const chat = new ChatClient(realtime, { storage: indexedDbChatStorage() ?? undefined });
+ */
+function indexedDbChatStorage(dbName = 'foony-chat') {
+    if (typeof indexedDB === 'undefined') {
+        return null;
+    }
+    const database = openDatabase(dbName);
+    return {
+        async load(room) {
+            const db = await database;
+            return await requestOf(db.transaction(STORE, 'readonly').objectStore(STORE).get(room)) ?? null;
+        },
+        async save(room, state) {
+            const db = await database;
+            await requestOf(db.transaction(STORE, 'readwrite').objectStore(STORE).put(state, room));
+        },
+        async remove(room) {
+            const db = await database;
+            await requestOf(db.transaction(STORE, 'readwrite').objectStore(STORE).delete(room));
+        },
+    };
+}
+/** Open (or create) the database with its single room store. */
+function openDatabase(dbName) {
+    return new Promise((resolve, reject) => {
+        const request = indexedDB.open(dbName, 1);
+        request.onupgradeneeded = () => {
+            request.result.createObjectStore(STORE);
+        };
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error ?? new Error('indexedDB open failed'));
+    });
+}
+/** Promisify one IDBRequest. */
+function requestOf(request) {
+    return new Promise((resolve, reject) => {
+        request.onsuccess = () => resolve(request.result);
+        request.onerror = () => reject(request.error ?? new Error('indexedDB request failed'));
+    });
+}
+//# sourceMappingURL=storage.js.map

package/lib-cjs/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../src/storage.ts"],"names":[],"mappings":";AAAA;;;;GAIG;;AAkCH,oDAqBC;AA/BD,8EAA8E;AAC9E,MAAM,KAAK,GAAG,OAAO,CAAC;AAEtB;;;;;;GAMG;AACH,SAAgB,oBAAoB,CAAC,MAAM,GAAG,YAAY;IACxD,IAAI,OAAO,SAAS,KAAK,WAAW,EAAE,CAAC;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,QAAQ,GAAG,YAAY,CAAC,MAAM,CAAC,CAAC;IACtC,OAAO;QACL,KAAK,CAAC,IAAI,CAAC,IAAY;YACrB,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC;YAC1B,OAAO,MAAM,SAAS,CACpB,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAC/D,IAAI,IAAI,CAAC;QACZ,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,IAAY,EAAE,KAAyB;YAChD,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC;YAC1B,MAAM,SAAS,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC;QAC1F,CAAC;QACD,KAAK,CAAC,MAAM,CAAC,IAAY;YACvB,MAAM,EAAE,GAAG,MAAM,QAAQ,CAAC;YAC1B,MAAM,SAAS,CAAC,EAAE,CAAC,WAAW,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QACtF,CAAC;KACF,CAAC;AACJ,CAAC;AAED,gEAAgE;AAChE,SAAS,YAAY,CAAC,MAAc;IAClC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,OAAO,GAAG,SAAS,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;QAC1C,OAAO,CAAC,eAAe,GAAG,GAAG,EAAE;YAC7B,OAAO,CAAC,MAAM,CAAC,iBAAiB,CAAC,KAAK,CAAC,CAAC;QAC1C,CAAC,CAAC;QACF,OAAO,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAClD,OAAO,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,uBAAuB,CAAC,CAAC,CAAC;IACtF,CAAC,CAAC,CAAC;AACL,CAAC;AAED,gCAAgC;AAChC,SAAS,SAAS,CAAI,OAAsB;IAC1C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,OAAO,CAAC,SAAS,GAAG,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QAClD,OAAO,CAAC,OAAO,GAAG,GAAG,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,IAAI,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC,CAAC;IACzF,CAAC,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foony/chat",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Chat API (rooms, messages, typing, reactions, presence, occupancy) built on @foony/realtime.",
   "license": "Apache-2.0",
   "repository": {
@@ -35,6 +35,7 @@
     }
   },
   "scripts": {
+    "prepublishOnly": "npm run build && npm test",
     "build": "tsc && tsc -p tsconfig.cjs.json && node ./scripts/write-cjs-package-json.mjs",
     "test": "vitest run",
     "test:watch": "vitest"
@@ -43,7 +44,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@foony/realtime": ">=0.3.0"
+    "@foony/realtime": ">=0.16.0"
   },
   "devDependencies": {
     "@foony/realtime": "file:../realtime-js",

package/src/chatClient.ts

@@ -6,14 +6,26 @@
 
 import type { Connection, Realtime } from '@foony/realtime';
 import { Rooms } from './rooms.js';
+import type { ChatStorage } from './storage.js';
+
+/** Client-wide options. */
+export type ChatClientOptions = {
+  /**
+   * Persist each room's recent messages between page loads (see
+   * {@link indexedDbChatStorage | `indexedDbChatStorage()`}). A returning client renders from
+   * its stored copy and the server replays only what it missed, instead of serving history
+   * again on every visit. Omit to keep everything in memory.
+   */
+  readonly storage?: ChatStorage;
+};
 
 /** Chat client built on top of a {@link Realtime} instance. */
 export class ChatClient {
   /** Room registry and factory. */
   readonly rooms: Rooms;
 
-  constructor(private readonly realtime: Realtime) {
-    this.rooms = new Rooms(realtime, () => this.clientId);
+  constructor(private readonly realtime: Realtime, options?: ChatClientOptions) {
+    this.rooms = new Rooms(realtime, () => this.clientId, options?.storage ?? null);
   }
 
   /** The underlying realtime connection (status, events). */

package/src/index.ts

@@ -7,7 +7,8 @@
  * package (planned as a separate `@foony/chat/react` subpath).
  */
 
-export { ChatClient } from './chatClient.js';
+export { ChatClient, type ChatClientOptions } from './chatClient.js';
+export { indexedDbChatStorage, type ChatStorage, type PersistedRoomState } from './storage.js';
 export { Rooms } from './rooms.js';
 export { Room, type RoomStatus, type DiscontinuityListener } from './room.js';
 export { Messages, type MessageListener } from './messages.js';

package/src/messages.ts

@@ -10,6 +10,7 @@
 import type { Channel, MessageFrame, UnsubscribeFn } from '@foony/realtime';
 import { MESSAGE_EVENT, PAYLOAD_VERSION, type MessagePayload } from './protocol.js';
 import { MessageReconciler } from './reconciler.js';
+import type { ChatStorage } from './storage.js';
 import type { ChatMessageEvent, Message, MessagePage, SendMessageParams, UpdateMessageParams } from './types.js';
 import { newMessageId } from './util.js';
 
@@ -17,12 +18,19 @@ import { newMessageId } from './util.js';
 export type MessageListener = (event: ChatMessageEvent) => void;
 
 /**
- * Retention requested for chat messages: the maximum the platform offers (1
- * year). The edge clamps this down to the app's plan ceiling, so a chat message
- * persists as long as the plan allows — versus typing/reactions, which are left
- * at the short ephemeral default. One year in milliseconds.
+ * How many stored frames a room keeps. Matches a deep scrollback page: anything older is
+ * re-fetchable through `history()` and not worth the disk.
  */
-const MESSAGE_TTL_MS = 365 * 24 * 60 * 60 * 1000;
+const PERSIST_MAX_FRAMES = 300;
+
+/** Delay between an applied frame and the storage write, so bursts save once. */
+const PERSIST_DEBOUNCE_MS = 300;
+
+/** Page size fetched when a stored resume cursor has aged out of retention. */
+const RECOVER_PAGE_LIMIT = 100;
+
+/** Default history page size, matching the server's default. */
+const DEFAULT_HISTORY_LIMIT = 100;
 
 /** The message feature of a {@link Room}. */
 export class Messages {
@@ -30,12 +38,108 @@ export class Messages {
   private readonly listeners = new Set<MessageListener>();
   private channelUnsubscribe: UnsubscribeFn | null = null;
 
+  /** Resolves once the stored snapshot (if any) has been replayed and the resume cursor seeded. */
+  private readonly ready: Promise<void>;
+  /** Frames worth persisting (those with a seq), oldest-first after each normalize. */
+  private frameLog: MessageFrame[] = [];
+  /** True when older messages remain on the server below the stored window. */
+  private storedHasMore = false;
+  /** The seeded resume serial, until the first attach reports whether it held. */
+  private seededSerial = 0;
+  private channelStateOff: UnsubscribeFn | null = null;
+  private persistTimer: ReturnType<typeof setTimeout> | null = null;
+  private pendingSubscribe = false;
+
   constructor(
     private readonly channel: Channel,
     private readonly roomName: string,
     private readonly getClientId: () => string | null,
+    private readonly storage: ChatStorage | null = null,
   ) {
     this.reconciler = new MessageReconciler(roomName);
+    this.ready = this.storage ? this.restore() : Promise.resolve();
+  }
+
+  /**
+   * Replay the stored snapshot into the reconciler and seed the channel's resume cursor, so the
+   * first attach replays only the gap. Runs before the first channel subscribe (see
+   * `ensureChannelSubscription`), because a seed after attach is a no-op.
+   */
+  private async restore(): Promise<void> {
+    let state = null;
+    try {
+      state = await this.storage!.load(this.roomName);
+    } catch {
+      return;
+    }
+    if (!state || state.frames.length === 0) {
+      return;
+    }
+    for (const frame of state.frames) {
+      if (frame.name === MESSAGE_EVENT) {
+        this.reconciler.apply(frame);
+      }
+      if (frame.seq !== undefined && frame.seq > 0) {
+        this.frameLog.push(frame);
+      }
+    }
+    this.storedHasMore = state.hasMore;
+    if (state.serial > 0) {
+      this.seededSerial = state.serial;
+      this.channel.resumeFrom(state.serial);
+      this.channelStateOff = this.channel.on((change) => this.onChannelState(change));
+    }
+  }
+
+  /**
+   * The seeded cursor is judged by the first attach: `resumed: false` means the serial aged out
+   * of retention, so the stored copy may be missing messages and is thrown away.
+   */
+  private onChannelState(change: { readonly current: string; readonly resumed: boolean }): void {
+    if (change.current !== 'attached' || this.seededSerial === 0) {
+      return;
+    }
+    this.seededSerial = 0;
+    this.channelStateOff?.();
+    this.channelStateOff = null;
+    if (!change.resumed) {
+      void this.recoverFromLostCursor();
+    }
+  }
+
+  /**
+   * The stored window could not be stitched to the live stream, so drop it and fetch a fresh
+   * page, emitting the result to subscribers like live traffic (their render already happened
+   * from the stale copy).
+   */
+  private async recoverFromLostCursor(): Promise<void> {
+    try {
+      await this.storage!.remove(this.roomName);
+    } catch {
+      // Best effort: a failed remove leaves a stale copy that the next failed resume retries.
+    }
+    this.frameLog = [];
+    this.storedHasMore = true;
+    try {
+      const { messages: frames, more } = await this.channel.history({ limit: RECOVER_PAGE_LIMIT });
+      this.storedHasMore = more;
+      for (const frame of frames) {
+        this.addToFrameLog(frame);
+        if (frame.name !== MESSAGE_EVENT) {
+          continue;
+        }
+        const event = this.reconciler.apply(frame);
+        if (event === null) {
+          continue;
+        }
+        for (const listener of [...this.listeners]) {
+          listener(event);
+        }
+      }
+      this.schedulePersist();
+    } catch {
+      // The room still works live; the next history() call backfills.
+    }
   }
 
   /** Send a new message. Returns the message optimistically; its `id` is stable. */
@@ -49,7 +153,7 @@ export class Messages {
       ...(params.metadata === undefined ? {} : { metadata: params.metadata }),
       ...(params.headers === undefined ? {} : { headers: params.headers }),
     };
-    await this.channel.publish(MESSAGE_EVENT, payload, { ttlMs: MESSAGE_TTL_MS });
+    await this.channel.publish(MESSAGE_EVENT, payload);
     const now = new Date();
     return {
       id,
@@ -75,13 +179,13 @@ export class Messages {
       ...(params.metadata === undefined ? {} : { metadata: params.metadata }),
       ...(params.headers === undefined ? {} : { headers: params.headers }),
     };
-    await this.channel.publish(MESSAGE_EVENT, payload, { ttlMs: MESSAGE_TTL_MS });
+    await this.channel.publish(MESSAGE_EVENT, payload);
   }
 
   /** Delete a message by id. */
   async delete(id: string): Promise<void> {
     const payload: MessagePayload = { v: PAYLOAD_VERSION, action: 'delete', id };
-    await this.channel.publish(MESSAGE_EVENT, payload, { ttlMs: MESSAGE_TTL_MS });
+    await this.channel.publish(MESSAGE_EVENT, payload);
   }
 
   /**
@@ -105,13 +209,23 @@ export class Messages {
    * reconciler as the live stream. Pass `cursor` (a previous page's
    * `nextCursor`) to page further back.
    */
-  async history(params?: { limit?: number; cursor?: string }): Promise<MessagePage> {
+  async history(params?: { limit?: number; cursor?: number }): Promise<MessagePage> {
+    if (this.storage) {
+      await this.ready;
+      if (params?.cursor === undefined) {
+        const stored = this.storedPage(params?.limit ?? DEFAULT_HISTORY_LIMIT);
+        if (stored) {
+          return stored;
+        }
+      }
+    }
     const { messages: frames, more } = await this.channel.history({
       ...(params?.limit === undefined ? {} : { limit: params.limit }),
-      ...(params?.cursor === undefined ? {} : { start: params.cursor }),
+      ...(params?.cursor === undefined ? {} : { before: params.cursor }),
     });
     const touched: string[] = [];
     for (const frame of frames) {
+      this.addToFrameLog(frame);
       if (frame.name !== MESSAGE_EVENT) {
         continue;
       }
@@ -121,30 +235,124 @@ export class Messages {
         touched.push(id);
       }
     }
+    this.schedulePersist();
     const messages = touched
       .map((id) => this.reconciler.get(id))
       .filter((message): message is Message => message !== undefined);
     return {
       messages,
       hasMore: more,
-      ...(frames.length > 0 && frames[0] ? { nextCursor: frames[0].messageId } : {}),
+      ...(frames.length > 0 && frames[0]?.seq !== undefined ? { nextCursor: frames[0].seq } : {}),
+    };
+  }
+
+  /**
+   * Build the newest page from the stored window, or null when the window is too small for the
+   * request (fewer frames than asked and older messages remain on the server).
+   */
+  private storedPage(limit: number): MessagePage | null {
+    this.normalizeFrameLog();
+    if (this.frameLog.length === 0 || (this.frameLog.length < limit && this.storedHasMore)) {
+      return null;
+    }
+    const window = this.frameLog.slice(-limit);
+    const touched: string[] = [];
+    for (const frame of window) {
+      const id = messageIdOf(frame);
+      if (id !== null && !touched.includes(id)) {
+        touched.push(id);
+      }
+    }
+    const messages = touched
+      .map((id) => this.reconciler.get(id))
+      .filter((message): message is Message => message !== undefined);
+    return {
+      messages,
+      hasMore: this.storedHasMore || this.frameLog.length > window.length,
+      ...(window[0]?.seq === undefined ? {} : { nextCursor: window[0].seq }),
     };
   }
 
   /** Lazily attach the single channel subscription that feeds the reconciler. */
   private ensureChannelSubscription(): void {
-    if (this.channelUnsubscribe) {
+    if (this.channelUnsubscribe || this.pendingSubscribe) {
+      return;
+    }
+    if (!this.storage) {
+      this.channelUnsubscribe = this.channel.subscribe(MESSAGE_EVENT, (frame) => this.onLiveFrame(frame));
       return;
     }
-    this.channelUnsubscribe = this.channel.subscribe(MESSAGE_EVENT, (frame) => {
-      const event = this.reconciler.apply(frame);
-      if (event === null) {
+    // With storage, the subscribe waits for the restore: the resume seed must be in place
+    // before the attach the subscription triggers, or the server backfills nothing.
+    this.pendingSubscribe = true;
+    void this.ready.then(() => {
+      this.pendingSubscribe = false;
+      if (this.channelUnsubscribe || this.listeners.size === 0) {
         return;
       }
+      this.channelUnsubscribe = this.channel.subscribe(MESSAGE_EVENT, (frame) => this.onLiveFrame(frame));
+    });
+  }
+
+  /** Apply one live frame, fan it out, and keep the stored window fresh. */
+  private onLiveFrame(frame: MessageFrame): void {
+    this.addToFrameLog(frame);
+    const event = this.reconciler.apply(frame);
+    if (event !== null) {
       for (const listener of [...this.listeners]) {
         listener(event);
       }
-    });
+    }
+    this.schedulePersist();
+  }
+
+  /** Track a sequenced frame for persistence. No-op without storage. */
+  private addToFrameLog(frame: MessageFrame): void {
+    if (!this.storage || frame.seq === undefined || frame.seq <= 0) {
+      return;
+    }
+    this.frameLog.push(frame);
+    if (this.frameLog.length > PERSIST_MAX_FRAMES * 2) {
+      this.normalizeFrameLog();
+    }
+  }
+
+  /** Sort, dedupe by seq, and trim the frame log to the newest window. */
+  private normalizeFrameLog(): void {
+    if (this.frameLog.length === 0) {
+      return;
+    }
+    const bySeq = new Map<number, MessageFrame>();
+    for (const frame of this.frameLog) {
+      bySeq.set(frame.seq!, frame);
+    }
+    const sorted = [...bySeq.values()].sort((left, right) => left.seq! - right.seq!);
+    if (sorted.length > PERSIST_MAX_FRAMES) {
+      this.frameLog = sorted.slice(-PERSIST_MAX_FRAMES);
+      this.storedHasMore = true;
+    } else {
+      this.frameLog = sorted;
+    }
+  }
+
+  /** Save the stored window shortly, coalescing bursts into one write. */
+  private schedulePersist(): void {
+    if (!this.storage || this.persistTimer !== null) {
+      return;
+    }
+    this.persistTimer = setTimeout(() => {
+      this.persistTimer = null;
+      this.normalizeFrameLog();
+      if (this.frameLog.length === 0) {
+        return;
+      }
+      const serial = this.frameLog[this.frameLog.length - 1]!.seq!;
+      void this.storage!
+        .save(this.roomName, { frames: [...this.frameLog], serial, hasMore: this.storedHasMore })
+        .catch(() => {
+          // Best effort: a lost save costs the next load a server history fetch, nothing more.
+        });
+    }, PERSIST_DEBOUNCE_MS);
   }
 }
 

package/src/room.ts

@@ -6,6 +6,7 @@
  */
 
 import type { Channel, ChannelStateChange, UnsubscribeFn } from '@foony/realtime';
+import type { ChatStorage } from './storage.js';
 import { Messages } from './messages.js';
 import { Occupancy } from './occupancy.js';
 import { Presence } from './presence.js';
@@ -41,8 +42,9 @@ export class Room {
     private readonly channel: Channel,
     getClientId: () => string | null,
     options?: RoomOptions,
+    storage: ChatStorage | null = null,
   ) {
-    this.messages = new Messages(channel, name, getClientId);
+    this.messages = new Messages(channel, name, getClientId, storage);
     this.presence = new Presence(channel);
     this.typing = new Typing(channel, getClientId, options?.typing?.heartbeatThrottleMs);
     this.reactions = new Reactions(channel, getClientId);

package/src/rooms.ts

@@ -7,6 +7,7 @@
 import type { Realtime } from '@foony/realtime';
 import { roomChannelName } from './protocol.js';
 import { Room } from './room.js';
+import type { ChatStorage } from './storage.js';
 import type { RoomOptions } from './types.js';
 
 /** Factory and cache for {@link Room} instances on a {@link ChatClient}. */
@@ -16,6 +17,7 @@ export class Rooms {
   constructor(
     private readonly realtime: Realtime,
     private readonly getClientId: () => string | null,
+    private readonly storage: ChatStorage | null = null,
   ) {}
 
   /** Get (or create) the room named `name`. Stable instance per name. */
@@ -23,7 +25,7 @@ export class Rooms {
     let existing = this.byName.get(name);
     if (!existing) {
       const channel = this.realtime.channels.get(roomChannelName(name), options?.cipher ? { cipher: options.cipher } : undefined);
-      existing = new Room(name, channel, this.getClientId, options);
+      existing = new Room(name, channel, this.getClientId, options, this.storage);
       this.byName.set(name, existing);
     }
     return existing;

package/src/storage.ts

@@ -0,0 +1,80 @@
+/**
+ * Optional message persistence. A {@link ChatStorage} keeps a per-room snapshot between page
+ * loads, so a returning client renders instantly from its own copy and the server replays only
+ * what was missed (via the channel's resume cursor) instead of serving history again.
+ */
+
+import type { MessageFrame } from '@foony/realtime';
+
+/** Snapshot of one room persisted between sessions. */
+export type PersistedRoomState = {
+  /** Raw message frames, oldest-first, replayed through the reconciler on load. */
+  readonly frames: readonly MessageFrame[];
+  /** Newest stored seq, seeded as the resume cursor so the server replays only the gap. */
+  readonly serial: number;
+  /** True when older messages remained on the server below the stored window when saved. */
+  readonly hasMore: boolean;
+};
+
+/** Where room snapshots live. Implementations must tolerate concurrent tabs (last write wins). */
+export type ChatStorage = {
+  /** The stored snapshot for `room`, or null when none exists. */
+  load(room: string): Promise<PersistedRoomState | null>;
+  /** Overwrite `room`'s snapshot. */
+  save(room: string, state: PersistedRoomState): Promise<void>;
+  /** Drop `room`'s snapshot (its resume cursor aged out, or the room was released). */
+  remove(room: string): Promise<void>;
+};
+
+/** Object store holding one record per room inside the IndexedDB database. */
+const STORE = 'rooms';
+
+/**
+ * A {@link ChatStorage} backed by IndexedDB, or null where IndexedDB does not exist (Node,
+ * some webviews) so callers can pass the result straight to `new ChatClient(...)`.
+ *
+ * @example
+ * const chat = new ChatClient(realtime, { storage: indexedDbChatStorage() ?? undefined });
+ */
+export function indexedDbChatStorage(dbName = 'foony-chat'): ChatStorage | null {
+  if (typeof indexedDB === 'undefined') {
+    return null;
+  }
+  const database = openDatabase(dbName);
+  return {
+    async load(room: string): Promise<PersistedRoomState | null> {
+      const db = await database;
+      return await requestOf<PersistedRoomState | undefined>(
+        db.transaction(STORE, 'readonly').objectStore(STORE).get(room),
+      ) ?? null;
+    },
+    async save(room: string, state: PersistedRoomState): Promise<void> {
+      const db = await database;
+      await requestOf(db.transaction(STORE, 'readwrite').objectStore(STORE).put(state, room));
+    },
+    async remove(room: string): Promise<void> {
+      const db = await database;
+      await requestOf(db.transaction(STORE, 'readwrite').objectStore(STORE).delete(room));
+    },
+  };
+}
+
+/** Open (or create) the database with its single room store. */
+function openDatabase(dbName: string): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(dbName, 1);
+    request.onupgradeneeded = () => {
+      request.result.createObjectStore(STORE);
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error('indexedDB open failed'));
+  });
+}
+
+/** Promisify one IDBRequest. */
+function requestOf<T>(request: IDBRequest<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error('indexedDB request failed'));
+  });
+}

package/src/types.ts

@@ -70,8 +70,8 @@ export type MessagePage = {
   readonly messages: readonly Message[];
   /** True when older messages remain beyond this page. */
   readonly hasMore: boolean;
-  /** Cursor (oldest message id in the page) to pass back for the next page. */
-  readonly nextCursor?: string;
+  /** Cursor (the page's oldest message serial) to pass back for the next page. */
+  readonly nextCursor?: number;
 };
 
 /** A single presence member in a room. */