@multiplatform.one/frappe 6.1.0 → 6.3.0

package/src/sync/subscriptionManager.ts

@@ -14,6 +14,22 @@ import type {
 } from "./types";
 import { VirtualPageManager } from "./virtualPageManager";
 
+/**
+ * Result of `SubscriptionManager.subscribe`.
+ */
+export interface SubscribeResult<Data extends FrappeDocData> {
+  subscriptionId: string;
+  rows: FrappeDoc<Data>[];
+  checkpoint?: string;
+  /**
+   * Present only when a restored (persisted) subscription was re-adopted:
+   * the returned `rows` came from the cache and this promise tracks the
+   * background network refresh. Never rejects — a failed refresh marks the
+   * subscription `stale` and resolves `{ ok: false }`.
+   */
+  refresh?: Promise<{ ok: boolean; error?: unknown }>;
+}
+
 export class SubscriptionManager {
   private subscriptions = new Map<string, Subscription>();
   private virtualPageManager: VirtualPageManager;
@@ -22,21 +38,35 @@ export class SubscriptionManager {
   private queryKeyToSubId = new Map<string, string>();
   /** Reference counts per subscriptionId for shared subscription lifecycle */
   private subRefCounts = new Map<string, number>();
-
-  constructor(
-    private readonly db: DbModule,
-    private readonly normalizedCache: NormalizedCache,
-    private readonly options: SyncOptions = {},
-  ) {
+  /**
+   * Subscriptions restored from a persisted snapshot (or detached on
+   * unsubscribe while persistence is on) that no live query has re-adopted
+   * yet. They serve cache-first renders on re-subscribe, are excluded from
+   * backfill fan-out, and are GC'd after `restoredSubscriptionTTL`.
+   */
+  private restoredByQueryKey = new Map<string, string>();
+  /** Restore/detach timestamps per restored subscriptionId (for TTL GC). */
+  private restoredAt = new Map<string, number>();
+  private readonly db: DbModule;
+  private readonly normalizedCache: NormalizedCache;
+  private readonly options: SyncOptions;
+
+  constructor(db: DbModule, normalizedCache: NormalizedCache, options: SyncOptions = {}) {
+    this.db = db;
+    this.normalizedCache = normalizedCache;
+    this.options = options;
     this.virtualPageManager = new VirtualPageManager(this.normalizedCache, this.db, {
       batchSize: this.options.batchSize,
     });
     this.backfillManager = new BackfillManager(this.db, this.normalizedCache, {
       pageSize: this.options.pageSize,
+      maxPages: this.options.backfillMaxPages,
     });
   }
 
-  async subscribe<Data extends FrappeDocData>(query: SubscriptionQuery) {
+  async subscribe<Data extends FrappeDocData>(
+    query: SubscriptionQuery,
+  ): Promise<SubscribeResult<Data>> {
     // Dedup: if an identical query is already active, reuse it
     const queryKey = JSON.stringify(query);
     const existingId = this.queryKeyToSubId.get(queryKey);
@@ -47,7 +77,68 @@ export class SubscriptionManager {
       return { subscriptionId: existingId, rows, checkpoint };
     }
 
+    // Cache-first: re-adopt a matching subscription restored from a persisted
+    // snapshot — serve its cached membership immediately and refresh from the
+    // network in the background.
+    const adopted = this.adoptRestoredSubscription<Data>(queryKey, query);
+    if (adopted) return adopted;
+
     const subscriptionId = cryptoRandomId();
+    const { rows, cursor, checkpoint } = await this.fetchInitialRows<Data>(query);
+    // Materialize the in-memory subscription record with initial membership
+    const subscription: Subscription = {
+      id: subscriptionId,
+      query,
+      checkpoint, // For CDC backfill
+      cursor, // For stable pagination
+      docIds: rows.map((row) => row.name),
+      tombstones: new Map<string, number>(),
+    };
+
+    // Track page boundaries for optimistic placement
+    if (rows.length > 0) {
+      subscription.boundaries = {
+        firstItem: rows[0] as unknown as FrappeDoc<Data>,
+        lastItem: rows[rows.length - 1] as unknown as FrappeDoc<Data>,
+        offset: query.limitStart || 0,
+        pageSize: query.limit || 20,
+      };
+    }
+
+    // Initialize metadata for tracking items outside current page
+    subscription.metadata = {
+      itemsBeforePage: 0,
+      itemsAfterPage: 0,
+    };
+
+    // Activate it
+    this.subscriptions.set(subscriptionId, subscription);
+    this.queryKeyToSubId.set(queryKey, subscriptionId);
+    this.subRefCounts.set(subscriptionId, 1);
+
+    // Register with VirtualPageManager for progressive pagination if requested
+    if (query.progressive) {
+      this.virtualPageManager.registerSubscription(
+        subscriptionId,
+        subscription,
+        subscription.docIds,
+        cursor,
+      );
+    }
+
+    // Provide the caller with the seeded rows and computed checkpoint
+    return { subscriptionId: subscriptionId, rows, checkpoint };
+  }
+
+  /**
+   * Performs the initial subscription fetch (single doc via getDoc, lists via
+   * getDocList), seeds the normalized cache, and computes the CDC checkpoint
+   * as the max `modified` across returned rows. Shared by fresh subscribes
+   * and adopted-subscription refreshes so both have identical semantics.
+   */
+  private async fetchInitialRows<Data extends FrappeDocData>(
+    query: SubscriptionQuery,
+  ): Promise<{ rows: FrappeDoc<Data>[]; cursor?: string; checkpoint?: string }> {
     // Only restrict fields when the caller explicitly specifies them.
     // When fields is undefined/empty, pass undefined so all fields are returned.
     const queryFields = query.fields?.length
@@ -101,55 +192,143 @@ export class SubscriptionManager {
       if (!row.modified) continue;
       if (!checkpoint || row.modified > checkpoint) checkpoint = row.modified;
     }
-    // Materialize the in-memory subscription record with initial membership
-    const subscription: Subscription = {
-      id: subscriptionId,
-      query,
-      checkpoint, // For CDC backfill
-      cursor, // For stable pagination
-      docIds: rows.map((row) => row.name),
-      tombstones: new Map<string, number>(),
-    };
+    return { rows, cursor, checkpoint };
+  }
 
-    // Track page boundaries for optimistic placement
-    if (rows.length > 0) {
-      subscription.boundaries = {
-        firstItem: rows[0] as unknown as FrappeDoc<Data>,
-        lastItem: rows[rows.length - 1] as unknown as FrappeDoc<Data>,
-        offset: query.limitStart || 0,
-        pageSize: query.limit || 20,
-      };
+  /**
+   * Re-adopts a subscription restored from a persisted snapshot when an
+   * identical query subscribes: the cached membership renders immediately and
+   * a background refresh re-seeds from the network. Progressive queries are
+   * excluded — their VirtualPageManager state is not persisted, so they take
+   * the fresh-subscribe path.
+   */
+  private adoptRestoredSubscription<Data extends FrappeDocData>(
+    queryKey: string,
+    query: SubscriptionQuery,
+  ): SubscribeResult<Data> | undefined {
+    if (query.progressive) return undefined;
+    const restoredId = this.restoredByQueryKey.get(queryKey);
+    if (!restoredId) return undefined;
+    const subscription = this.subscriptions.get(restoredId);
+    this.restoredByQueryKey.delete(queryKey);
+    this.restoredAt.delete(restoredId);
+    if (!subscription) return undefined;
+
+    // Activate under the live dedup/refcount lifecycle
+    this.queryKeyToSubId.set(queryKey, restoredId);
+    this.subRefCounts.set(restoredId, 1);
+
+    const refresh = this.refreshAdoptedSubscription<Data>(subscription);
+    const rows = this.getDocsForSubscription<Data>(restoredId);
+    return { subscriptionId: restoredId, rows, checkpoint: subscription.checkpoint, refresh };
+  }
+
+  /**
+   * Network refresh for an adopted subscription with fresh-subscribe
+   * semantics: an authoritative page fetch replaces membership and recomputes
+   * the checkpoint (identical to what a brand-new subscribe would produce).
+   * On failure (offline) the cached membership and the restored CDC
+   * checkpoint are kept and the subscription is marked stale — the next
+   * backfill trigger drains changes from that checkpoint. Never rejects.
+   */
+  private async refreshAdoptedSubscription<Data extends FrappeDocData>(
+    subscription: Subscription,
+  ): Promise<{ ok: boolean; error?: unknown }> {
+    try {
+      const { rows, cursor, checkpoint } = await this.fetchInitialRows<Data>(subscription.query);
+      subscription.checkpoint = checkpoint;
+      subscription.cursor = cursor;
+      subscription.docIds = rows.map((row) => row.name);
+      if (rows.length > 0) {
+        subscription.boundaries = {
+          firstItem: rows[0] as unknown as FrappeDoc<FrappeDocData>,
+          lastItem: rows[rows.length - 1] as unknown as FrappeDoc<FrappeDocData>,
+          offset: subscription.query.limitStart || 0,
+          pageSize: subscription.query.limit || 20,
+        };
+      }
+      subscription.metadata = { itemsBeforePage: 0, itemsAfterPage: 0 };
+      subscription.stale = false;
+      return { ok: true };
+    } catch (error) {
+      subscription.stale = true;
+      return { ok: false, error };
     }
+  }
 
-    // Initialize metadata for tracking items outside current page
-    subscription.metadata = {
-      itemsBeforePage: 0,
-      itemsAfterPage: 0,
+  /**
+   * Registers a subscription restored from a persisted snapshot. Restored
+   * subscriptions are dormant: they hold the persisted query, CDC checkpoint,
+   * and membership for cache-first re-adoption, but are skipped by backfill
+   * fan-out until adopted. Duplicate snapshot entries for the same query
+   * (accumulated by pre-GC versions) collapse last-wins.
+   */
+  restoreSubscription(
+    snapshotSub: Pick<Subscription, "id" | "query"> &
+      Partial<Pick<Subscription, "checkpoint" | "cursor" | "docIds">>,
+  ) {
+    if (!snapshotSub?.id || !snapshotSub.query?.doctype) return;
+    if (this.subscriptions.has(snapshotSub.id)) return;
+    const queryKey = JSON.stringify(snapshotSub.query);
+    // An active subscription already serves this query — the restored copy
+    // would never be adopted, so drop it.
+    const activeId = this.queryKeyToSubId.get(queryKey);
+    if (activeId && this.subscriptions.has(activeId)) return;
+    // Last-wins: later snapshot entries are from more recent sessions
+    const previousId = this.restoredByQueryKey.get(queryKey);
+    if (previousId) {
+      this.subscriptions.delete(previousId);
+      this.restoredAt.delete(previousId);
+    }
+    const subscription: Subscription = {
+      id: snapshotSub.id,
+      query: snapshotSub.query,
+      checkpoint: snapshotSub.checkpoint,
+      cursor: snapshotSub.cursor,
+      docIds: Array.isArray(snapshotSub.docIds) ? snapshotSub.docIds : [],
+      tombstones: new Map<string, number>(),
+      metadata: { itemsBeforePage: 0, itemsAfterPage: 0 },
     };
+    this.subscriptions.set(subscription.id, subscription);
+    this.restoredByQueryKey.set(queryKey, subscription.id);
+    this.restoredAt.set(subscription.id, Date.now());
+  }
 
-    // Activate it
-    this.subscriptions.set(subscriptionId, subscription);
-    this.queryKeyToSubId.set(queryKey, subscriptionId);
-    this.subRefCounts.set(subscriptionId, 1);
+  /** True when the subscription came from a snapshot and is not yet adopted. */
+  isRestoredSubscription(subscriptionId: string): boolean {
+    return this.restoredAt.has(subscriptionId);
+  }
 
-    // Register with VirtualPageManager for progressive pagination if requested
-    if (query.progressive) {
-      this.virtualPageManager.registerSubscription(
-        subscriptionId,
-        subscription,
-        subscription.docIds,
-        cursor,
-      );
+  /**
+   * Drops restored subscriptions that no query re-adopted within
+   * `restoredSubscriptionTTL` (default 30 minutes). Called before every
+   * persistence snapshot so expired entries also leave the snapshot.
+   */
+  gcRestoredSubscriptions(now = Date.now()) {
+    const ttl = this.options.restoredSubscriptionTTL ?? 30 * 60 * 1000;
+    for (const [subscriptionId, restoredAtMs] of this.restoredAt) {
+      if (now - restoredAtMs <= ttl) continue;
+      this.restoredAt.delete(subscriptionId);
+      this.subscriptions.delete(subscriptionId);
+      for (const [key, id] of this.restoredByQueryKey) {
+        if (id === subscriptionId) {
+          this.restoredByQueryKey.delete(key);
+          break;
+        }
+      }
     }
-
-    // Provide the caller with the seeded rows and computed checkpoint
-    return { subscriptionId: subscriptionId, rows, checkpoint };
   }
 
   /**
    * Removes a subscription by id. Cached docs remain until evicted by
    * realtime/backfill or explicit resets. This keeps other subs fast if they
    * share the same doctypes.
+   *
+   * With persistence enabled (`persistKey`), the released subscription is
+   * detached into the restored pool instead of deleted: its query,
+   * checkpoint, and membership stay in the snapshot so a remount (or a
+   * cold offline reload) can re-adopt it cache-first. Detached subscriptions
+   * are excluded from backfill and GC'd after `restoredSubscriptionTTL`.
    */
   unsubscribe(subscriptionId: string) {
     const refCount = (this.subRefCounts.get(subscriptionId) || 1) - 1;
@@ -159,12 +338,26 @@ export class SubscriptionManager {
     }
     // Last consumer released — clean up
     this.subRefCounts.delete(subscriptionId);
+    let queryKey: string | undefined;
     for (const [key, id] of this.queryKeyToSubId) {
       if (id === subscriptionId) {
+        queryKey = key;
         this.queryKeyToSubId.delete(key);
         break;
       }
     }
+    const subscription = this.subscriptions.get(subscriptionId);
+    if (
+      this.options.persistKey &&
+      subscription &&
+      queryKey &&
+      !subscription.query.progressive &&
+      !this.restoredByQueryKey.has(queryKey)
+    ) {
+      this.restoredByQueryKey.set(queryKey, subscriptionId);
+      this.restoredAt.set(subscriptionId, Date.now());
+      return;
+    }
     this.subscriptions.delete(subscriptionId);
   }
 
@@ -250,8 +443,13 @@ export class SubscriptionManager {
    */
   async backfill<Data extends FrappeDocData>(args: BackfillArgs) {
     if (args.scope === BackfillScope.All) {
-      for (const subscription of this.subscriptions.values())
+      for (const subscription of this.subscriptions.values()) {
+        // Restored-but-unadopted subscriptions have no consumers; catching
+        // them up would spend a CDC request per trigger for nothing (their
+        // adoption refresh re-seeds from the network anyway).
+        if (this.restoredAt.has(subscription.id)) continue;
         await this.backfillSub(subscription, args.pageSize);
+      }
       return;
     }
     if (args.scope === BackfillScope.Subscriptions) {
@@ -263,9 +461,11 @@ export class SubscriptionManager {
     }
     if (args.scope === BackfillScope.Doctypes) {
       const set = new Set(args.doctypes || []);
-      for (const subscription of this.subscriptions.values())
+      for (const subscription of this.subscriptions.values()) {
+        if (this.restoredAt.has(subscription.id)) continue;
         if (set.has(subscription.query.doctype))
           await this.backfillSub(subscription, args.pageSize);
+      }
       return;
     }
     if (args.scope === BackfillScope.Docs) {
@@ -280,7 +480,9 @@ export class SubscriptionManager {
    * Backfills one subscription using CDC checkpoint and updates membership.
    *
    * Algorithm
-   * - Query backfill using checkpoint for CDC (Change Data Capture)
+   * - Query backfill using checkpoint for CDC (Change Data Capture),
+   *   draining follow-up pages while the server reports has_more (bounded)
+   *   so reconnect catch-up is complete rather than one page deep
    * - Upsert each row to cache
    * - For each row: test client-side filters; add/remove membership accordingly
    * - Track tombstones for deleted documents
@@ -291,42 +493,55 @@ export class SubscriptionManager {
     subscription: Subscription,
     pageSize = this.options.pageSize ?? 200,
   ) {
-    // Request changes since the last known checkpoint using CDC backfill API
-    const response = await this.db.backfill<Data>({
-      doctype: subscription.query.doctype,
-      fields: subscription.query.fields,
-      filters: subscription.query.filters,
-      modifiedAfter: subscription.checkpoint, // CDC checkpoint
-      limit: pageSize,
-    });
+    const maxPages = this.options.backfillMaxPages ?? 20;
+    const rows: FrappeDoc<Data>[] = [];
+    const deleted: { doctype?: string; name: string }[] = [];
+    for (let page = 0; page < maxPages; page++) {
+      // Request changes since the last known checkpoint using CDC backfill API
+      const response = await this.db.backfill<Data>({
+        doctype: subscription.query.doctype,
+        fields: subscription.query.fields,
+        filters: subscription.query.filters,
+        modifiedAfter: subscription.checkpoint, // CDC checkpoint
+        limit: pageSize,
+      });
+      if (Array.isArray(response.deleted)) {
+        deleted.push(...(response.deleted as { doctype?: string; name: string }[]));
+      }
+      rows.push(...response.rows);
+      // Advance the checkpoint to the server-provided cursor for next cycle
+      if (response.checkpoint) subscription.checkpoint = response.checkpoint;
+      // Keep draining only while the server reports truncation AND handed us
+      // a cursor to resume from (guards against servers without has_more and
+      // against spinning on a fixed cursor).
+      const madeProgress = response.rows.length > 0 || (response.deleted?.length ?? 0) > 0;
+      if (!response.has_more || !response.checkpoint || !madeProgress) break;
+    }
     // Apply authoritative deletes first if backend returns tombstones.
     // The backfill endpoint returns {name: string} objects (no doctype),
     // so we fall back to the subscription's doctype when not provided.
-    if ((response as any).deleted && Array.isArray((response as any).deleted)) {
-      for (const deleted of (response as any).deleted as {
-        doctype?: string;
-        name: string;
-      }[]) {
-        if (!deleted?.name) continue;
-        const deletedDoctype = deleted.doctype || subscription.query.doctype;
-
-        // Track in tombstones map for this subscription with timestamp
-        if (deletedDoctype === subscription.query.doctype && subscription.tombstones) {
-          subscription.tombstones.set(deleted.name, Date.now());
-        }
-        // Evict from cache and any list memberships for this doctype
-        this.normalizedCache.remove({
-          doctype: deletedDoctype,
-          name: deleted.name,
-        });
-        if (deletedDoctype === subscription.query.doctype)
-          subscription.docIds = subscription.docIds.filter(
-            (currentName) => currentName !== deleted.name,
-          );
+    for (const deletedRef of deleted) {
+      if (!deletedRef?.name) continue;
+      const deletedDoctype = deletedRef.doctype || subscription.query.doctype;
+
+      // Track in tombstones map for this subscription with timestamp
+      if (deletedDoctype === subscription.query.doctype && subscription.tombstones) {
+        subscription.tombstones.set(deletedRef.name, Date.now());
       }
+      // Evict from cache and any list memberships for this doctype
+      this.normalizedCache.remove({
+        doctype: deletedDoctype,
+        name: deletedRef.name,
+      });
+      if (deletedDoctype === subscription.query.doctype)
+        subscription.docIds = subscription.docIds.filter(
+          (currentName) => currentName !== deletedRef.name,
+        );
     }
-    // Upsert each changed/inserted row, then reconcile membership using client filters
-    for (const row of response.rows) {
+    // Upsert each changed/inserted row, then reconcile membership using client filters.
+    // A doc deleted then recreated within the drained window is evicted above
+    // and re-added here, matching the server's delete-before-row ordering.
+    for (const row of rows) {
       if (!row.doctype) row.doctype = subscription.query.doctype;
       this.normalizedCache.upsert(row);
       const name = row.name;
@@ -336,11 +551,9 @@ export class SubscriptionManager {
       if (!match)
         subscription.docIds = subscription.docIds.filter((currentName) => currentName !== name);
     }
-    // Advance the checkpoint to the server-provided checkpoint for next cycle
-    if (response.checkpoint) subscription.checkpoint = response.checkpoint;
     // If no filters, the rows represent the full page; maintain membership directly
-    if (response.rows.length && !subscription.query.filters)
-      subscription.docIds = response.rows.map((row: any) => row.name);
+    if (rows.length && !subscription.query.filters)
+      subscription.docIds = rows.map((row) => row.name);
 
     // Update page boundaries after backfill
     if (subscription.docIds.length > 0) {
@@ -369,10 +582,13 @@ export class SubscriptionManager {
     // Cleanup expired tombstones to prevent memory leaks
     this.cleanupTombstones(subscription.id);
 
+    // A completed drain means the membership is authoritative again
+    subscription.stale = false;
+
     if (this.options.onBackfill)
       this.options.onBackfill({
         doctype: subscription.query.doctype,
-        fetched: response.rows.length,
+        fetched: rows.length,
         checkpoint: subscription.checkpoint,
       });
   }
@@ -405,6 +621,10 @@ export class SubscriptionManager {
   updateSubscriptionMembership<Data extends FrappeDocData>(doc: FrappeDoc<Data>): Subscription[] {
     const subscriptionsNeedingRehydration: Subscription[] = [];
     for (const subscription of this.subscriptions.values()) {
+      // Dormant restored subscriptions have no renderers and are re-seeded on
+      // adoption — skip them so realtime hints don't trigger rehydration
+      // fetches (or VPM updates) on their behalf.
+      if (this.restoredAt.has(subscription.id)) continue;
       if (subscription.query.doctype !== doc.doctype) continue;
       const match = matchesFilters(doc, subscription.query.filters);
       const isExisting = subscription.docIds.includes(doc.name);
@@ -529,6 +749,8 @@ export class SubscriptionManager {
     this.subscriptions.clear();
     this.queryKeyToSubId.clear();
     this.subRefCounts.clear();
+    this.restoredByQueryKey.clear();
+    this.restoredAt.clear();
   }
 
   /**

package/src/sync/syncModule.spec.ts

@@ -4,6 +4,7 @@ import { BackfillScope } from "./types";
 import type { SubscriptionQuery } from "./types";
 
 vi.mock("@multiplatform.one/platform", () => ({
+  isNative: false,
   onAppFocus: vi.fn(() => vi.fn()),
   onOnline: vi.fn(() => vi.fn()),
   onVisibilityChange: vi.fn(() => vi.fn()),
@@ -47,6 +48,8 @@ describe("SyncModule", () => {
       isHealthy: vi.fn(() => false),
       connect: vi.fn(),
       disconnect: vi.fn(),
+      subscribeList: vi.fn().mockResolvedValue(undefined),
+      unsubscribeList: vi.fn(),
     };
   });
 
@@ -177,6 +180,140 @@ describe("SyncModule", () => {
     });
   });
 
+  describe("realtime events bridge to store listeners", () => {
+    let eventHandlers: Record<string, (payload?: unknown) => Promise<void> | void>;
+
+    beforeEach(() => {
+      eventHandlers = {};
+      mockRealtime.on = vi.fn().mockImplementation((event: string, handler: any) => {
+        eventHandlers[event] = handler;
+      });
+    });
+
+    it("notifies store listeners after a remote doc_update reconciles", async () => {
+      sync = createSync();
+      await sync.subscribe({ doctype: "TestDoc", fields: ["title"] });
+
+      const listener = vi.fn();
+      sync.subscribeStore(listener);
+
+      mockDb.getDoc.mockResolvedValueOnce({
+        name: "doc1",
+        doctype: "TestDoc",
+        title: "Doc 1 edited",
+        modified: "2024-01-01T11:00:00",
+      });
+      await eventHandlers.doc_update?.({ doctype: "TestDoc", name: "doc1" });
+
+      expect(listener).toHaveBeenCalled();
+    });
+
+    it("notifies store listeners after a remote list_update reconciles", async () => {
+      sync = createSync();
+      await sync.subscribe({ doctype: "TestDoc", fields: ["title"] });
+
+      const listener = vi.fn();
+      sync.subscribeStore(listener);
+
+      await eventHandlers.list_update?.({ doctype: "TestDoc", name: "doc2" });
+
+      expect(listener).toHaveBeenCalled();
+    });
+
+    it("notifies store listeners after doc_deleted evicts the row", async () => {
+      sync = createSync();
+      const { subscriptionId } = await sync.subscribe({ doctype: "TestDoc", fields: ["title"] });
+      expect(sync.getDocsForSubscription(subscriptionId).map((d) => d.name)).toContain("doc1");
+
+      const listener = vi.fn();
+      sync.subscribeStore(listener);
+
+      await eventHandlers.doc_deleted?.({ doctype: "TestDoc", name: "doc1" });
+
+      expect(listener).toHaveBeenCalled();
+      expect(sync.getDocsForSubscription(subscriptionId).map((d) => d.name)).not.toContain("doc1");
+    });
+
+    it("flips getConnectionState and notifies listeners on connect/disconnect", async () => {
+      sync = createSync();
+      expect(sync.getConnectionState()).toEqual({ connected: false, everConnected: false });
+
+      const listener = vi.fn();
+      sync.subscribeStore(listener);
+
+      await eventHandlers.connected?.();
+      expect(sync.getConnectionState()).toEqual({ connected: true, everConnected: true });
+      expect(listener).toHaveBeenCalled();
+
+      listener.mockClear();
+      await eventHandlers.disconnect?.();
+      expect(sync.getConnectionState()).toEqual({ connected: false, everConnected: true });
+      expect(listener).toHaveBeenCalled();
+    });
+
+    it("forwards realtime events to subscribeRealtimeEvents listeners and unsubscribes", async () => {
+      sync = createSync();
+      const events: { type: string; payload?: unknown }[] = [];
+      const unsubscribe = sync.subscribeRealtimeEvents((event) =>
+        events.push(event as { type: string; payload?: unknown }),
+      );
+
+      await eventHandlers.list_update?.({ doctype: "TestDoc", name: "doc2" });
+      expect(events.some((e) => e.type === "list_update")).toBe(true);
+
+      unsubscribe();
+      events.length = 0;
+      await eventHandlers.list_update?.({ doctype: "TestDoc", name: "doc2" });
+      expect(events).toHaveLength(0);
+    });
+
+    it("chains a consumer-provided onRealtimeEvent option alongside listeners", async () => {
+      const onRealtimeEvent = vi.fn();
+      sync = createSync({ onRealtimeEvent });
+
+      await eventHandlers.doc_update?.({ doctype: "TestDoc", name: "doc1" });
+
+      expect(onRealtimeEvent).toHaveBeenCalledWith(expect.objectContaining({ type: "doc_update" }));
+    });
+
+    it("watchDoctype/unwatchDoctype join and leave the doctype room", () => {
+      sync = createSync();
+      sync.watchDoctype("TestDoc");
+      expect(mockRealtime.subscribeList).toHaveBeenCalledWith("TestDoc");
+
+      sync.unwatchDoctype("TestDoc");
+      expect(mockRealtime.unsubscribeList).toHaveBeenCalledWith("TestDoc");
+    });
+
+    it("notifies store listeners after debounced rehydration runs (remote create)", async () => {
+      sync = createSync();
+      await sync.subscribe({
+        doctype: "TestDoc",
+        fields: ["title"],
+        filters: { status: "Open" },
+      });
+
+      const listener = vi.fn();
+      sync.subscribeStore(listener);
+
+      // A brand-new doc matching the filters triggers RemoteCreate rehydration
+      mockDb.getDoc.mockResolvedValueOnce({
+        name: "doc3",
+        doctype: "TestDoc",
+        status: "Open",
+        title: "Doc 3",
+        modified: "2024-01-01T12:00:00",
+      });
+      await eventHandlers.doc_update?.({ doctype: "TestDoc", name: "doc3" });
+      listener.mockClear();
+
+      // RemoteCreate rehydration is debounced (~500ms) then refreshes the page
+      await vi.advanceTimersByTimeAsync(1000);
+
+      expect(listener).toHaveBeenCalled();
+    });
+  });
+
   describe("getPage and getNextBatch emit", () => {
     it("getPage notifies store listeners", async () => {
       sync = createSync();