@multiplatform.one/frappe 6.1.0 → 6.4.0

package/dist/jsx/sync/realtime.mjs

@@ -1,5 +1,21 @@
 import { RealtimeEventType, RehydrationReason } from "./types.mjs";
 class RealtimeHandler {
+  reconnectAttempts = 0;
+  reconnectTimer;
+  hasConnected = false;
+  /** Live socket state: true between `connected` and `disconnect` events. */
+  connected = false;
+  connectionConfig;
+  /** Refcount of active subscriptions per doctype — drives doctype room membership. */
+  watchedDoctypes = /* @__PURE__ */new Map();
+  /** In-flight authoritative fetches, deduping concurrent doc_update/list_update pairs. */
+  inflightFetches = /* @__PURE__ */new Map();
+  db;
+  realtime;
+  normalizedCache;
+  subscriptionManager;
+  rehydrationManager;
+  options;
   constructor(db, realtime, normalizedCache, subscriptionManager, rehydrationManager, options = {}) {
     this.db = db;
     this.realtime = realtime;
@@ -16,21 +32,40 @@ class RealtimeHandler {
     this.setupRealtimeHandlers();
     this.setupConnectionManagement();
   }
-  db;
-  realtime;
-  normalizedCache;
-  subscriptionManager;
-  rehydrationManager;
-  options;
-  reconnectAttempts = 0;
-  reconnectTimer;
-  hasConnected = false;
-  connectionConfig;
   /**
    * Sets up realtime event handlers for document changes.
+   *
+   * Real Frappe (v15) wire protocol, verified live against a stock bench
+   * (see .test-evidence/storybook-rubric/p-results/frappe-realtime-live-e2e.md):
+   * - `doc_update`  `{doctype, name, modified}` — emitted to the per-doc room
+   *   `doc:{doctype}/{name}` on every save.
+   * - `list_update` `{doctype, name, user}` — emitted to the doctype room
+   *   `doctype:{doctype}` on every save of a non-single, non-child doctype.
+   * - Deletion emits the SAME two events (payload indistinguishable from an
+   *   update) — there is NO `doc_deleted` event. Deletions are detected here
+   *   opportunistically when the authoritative re-fetch 404s, but the durable
+   *   deletion signal remains the tombstone/CDC backfill (`Deleted Document`
+   *   doctype maintained by the `live` app's on_trash hook).
+   *
+   * Both real events funnel into the same fetch-and-reconcile path, deduped
+   * so a doc_update/list_update pair for the same doc costs one fetch.
    */
   setupRealtimeHandlers() {
     if (!this.realtime) return;
+    this.realtime?.on("doc_update", async payload => {
+      if (this.options.onRealtimeEvent) this.options.onRealtimeEvent({
+        type: RealtimeEventType.DocUpdate,
+        payload
+      });
+      return this.onDocChanged(payload);
+    });
+    this.realtime?.on("list_update", async payload => {
+      if (this.options.onRealtimeEvent) this.options.onRealtimeEvent({
+        type: RealtimeEventType.ListUpdate,
+        payload
+      });
+      return this.onDocChanged(payload);
+    });
     this.realtime?.on("doc_changed", async payload => {
       if (this.options.onRealtimeEvent) this.options.onRealtimeEvent({
         type: RealtimeEventType.DocChanged,
@@ -72,6 +107,7 @@ class RealtimeHandler {
    */
   onConnected() {
     this.hasConnected = true;
+    this.connected = true;
     this.reconnectAttempts = 0;
     if (this.reconnectTimer) {
       clearTimeout(this.reconnectTimer);
@@ -85,6 +121,7 @@ class RealtimeHandler {
     if (this.options.onBackfillAll) {
       this.options.onBackfillAll();
     }
+    this.options.onStoreChange?.();
     console.debug("[RealtimeHandler] Connected to realtime server");
   }
   /**
@@ -92,18 +129,24 @@ class RealtimeHandler {
    */
   onDisconnected() {
     console.debug("[RealtimeHandler] Disconnected from realtime server");
+    this.connected = false;
+    this.options.onStoreChange?.();
     if (this.hasConnected) {
       this.scheduleReconnection();
     }
   }
   /**
-   * Attempts to connect to the realtime server.
+   * No-op placeholder retained for the disconnect backoff schedule below.
+   * Transport reconnect is owned by Socket.IO inside RealtimeModule; this
+   * layer only tracks attempts for logging / future health hooks.
    */
   attemptConnection() {
     if (!this.realtime) return;
   }
   /**
-   * Schedules a reconnection attempt with exponential backoff and jitter.
+   * Schedules a reconnection *watchdog* tick with exponential backoff and jitter.
+   * Does not open sockets — RealtimeModule already reconnects. Kept so disconnect
+   * storms remain observable (and existing unit tests stay meaningful).
    */
   scheduleReconnection() {
     if (this.reconnectTimer) {
@@ -129,12 +172,61 @@ class RealtimeHandler {
     delay = Math.round(delay + jitter);
     return Math.max(this.connectionConfig.reconnectBaseDelay, Math.min(delay, this.connectionConfig.reconnectMaxDelay));
   }
+  /**
+   * Join the realtime doctype room for a doctype (refcounted). Called by the
+   * sync module whenever a subscription for the doctype is added. Room
+   * membership survives reconnects — RealtimeModule re-joins tracked rooms on
+   * every `connect`.
+   *
+   * Note: only doctype-level rooms are joined. `list_update` fires for every
+   * save of a regular doctype, which covers doc updates too; per-doc rooms
+   * would only add coverage for single/read-only doctypes.
+   */
+  watchDoctype(doctype) {
+    const count = (this.watchedDoctypes.get(doctype) ?? 0) + 1;
+    this.watchedDoctypes.set(doctype, count);
+    if (count === 1 && this.realtime) {
+      Promise.resolve(this.realtime.subscribeList(doctype)).catch(err => console.warn(`[RealtimeHandler] Failed to join doctype room ${doctype}:`, err));
+    }
+  }
+  /** Release one reference to a doctype room; leaves the room on the last one. */
+  unwatchDoctype(doctype) {
+    const count = (this.watchedDoctypes.get(doctype) ?? 0) - 1;
+    if (count > 0) {
+      this.watchedDoctypes.set(doctype, count);
+      return;
+    }
+    this.watchedDoctypes.delete(doctype);
+    this.realtime?.unsubscribeList(doctype);
+  }
+  /** Leave all doctype rooms (used by cache resets/disposal). */
+  unwatchAll() {
+    if (this.realtime) {
+      for (const doctype of this.watchedDoctypes.keys()) {
+        this.realtime.unsubscribeList(doctype);
+      }
+    }
+    this.watchedDoctypes.clear();
+  }
   /**
    * Realtime handler: authoritative document changed.
    * Fetches document via REST with current user context to respect permissions,
    * updates cache, and reconciles subscription membership.
+   *
+   * Concurrent events for the same document (frappe emits doc_update AND
+   * list_update per save) share a single in-flight fetch.
    */
-  async onDocChanged(payload) {
+  onDocChanged(payload) {
+    const key = `${payload?.doctype}\0${payload?.name}`;
+    const inflight = this.inflightFetches.get(key);
+    if (inflight) return inflight;
+    const fetchPromise = this.fetchAndReconcile(payload).finally(() => {
+      this.inflightFetches.delete(key);
+    });
+    this.inflightFetches.set(key, fetchPromise);
+    return fetchPromise;
+  }
+  async fetchAndReconcile(payload) {
     try {
       const document = await this.db.getDoc(payload.doctype, payload.name);
       this.normalizedCache.upsert(document);
@@ -142,7 +234,12 @@ class RealtimeHandler {
       for (const subscription of subscriptionsNeedingRehydration) {
         this.rehydrationManager?.scheduleRehydration(subscription, RehydrationReason.RemoteCreate);
       }
+      this.options.onStoreChange?.();
     } catch (err) {
+      if (err?.status === 404) {
+        await this.onDocDeleted(payload);
+        return;
+      }
       console.warn(`Failed to fetch document ${payload?.doctype}/${payload?.name} during realtime update:`, err);
     }
   }
@@ -159,6 +256,7 @@ class RealtimeHandler {
       for (const subscription of affectedSubscriptions) {
         this.rehydrationManager?.scheduleRehydration(subscription, RehydrationReason.Delete);
       }
+      this.options.onStoreChange?.();
     } catch (err) {
       console.warn(`Failed to process doc_deleted for ${payload?.doctype}/${payload?.name}:`, err);
     }
@@ -172,6 +270,18 @@ class RealtimeHandler {
   getIsConnected() {
     return this.hasConnected;
   }
+  /**
+   * Live connection snapshot for reconnect indicators.
+   * `connected` tracks the socket right now; `everConnected` distinguishes
+   * "reconnecting" (was up, dropped) from "never had realtime" (fixtures,
+   * SSR, no realtime module).
+   */
+  getConnectionState() {
+    return {
+      connected: this.connected,
+      everConnected: this.hasConnected
+    };
+  }
   /**
    * Disposes of resources and clears timers.
    */
@@ -180,6 +290,7 @@ class RealtimeHandler {
       clearTimeout(this.reconnectTimer);
       this.reconnectTimer = void 0;
     }
+    this.unwatchAll();
     if (this.realtime) {
       this.realtime?.disconnect();
     }

package/dist/jsx/sync/realtime.mjs.map

@@ -1 +1 @@
-{"version":3,"names":["RealtimeEventType","RehydrationReason","RealtimeHandler","constructor","db","realtime","normalizedCache","subscriptionManager","rehydrationManager","options","connectionConfig","reconnectBaseDelay","reconnectMaxDelay","reconnectJitter","exponentialBackoff","setupRealtimeHandlers","setupConnectionManagement","reconnectAttempts","reconnectTimer","hasConnected","on","payload","onRealtimeEvent","type","DocChanged","onDocChanged","DocDeleted","onDocDeleted","PermEpochBump","onResetCache","onConnected","onDisconnected","attemptConnection","clearTimeout","Connected","onBackfillAll","console","debug","scheduleReconnection","delay","calculateReconnectDelay","setTimeout","Math","min","jitterRange","jitter","random","round","max","document","getDoc","doctype","name","upsert","subscriptionsNeedingRehydration","updateSubscriptionMembership","subscription","scheduleRehydration","RemoteCreate","err","warn","remove","affectedSubscriptions","removeFromAllSubscriptions","Delete","isRealtimeHealthy","isHealthy","getIsConnected","dispose","disconnect"],"sources":["../../../src/sync/realtime.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
+{"version":3,"names":["RealtimeEventType","RehydrationReason","RealtimeHandler","reconnectAttempts","reconnectTimer","hasConnected","connected","connectionConfig","watchedDoctypes","Map","inflightFetches","db","realtime","normalizedCache","subscriptionManager","rehydrationManager","options","constructor","reconnectBaseDelay","reconnectMaxDelay","reconnectJitter","exponentialBackoff","setupRealtimeHandlers","setupConnectionManagement","on","payload","onRealtimeEvent","type","DocUpdate","onDocChanged","ListUpdate","DocChanged","DocDeleted","onDocDeleted","PermEpochBump","onResetCache","onConnected","onDisconnected","attemptConnection","clearTimeout","Connected","onBackfillAll","onStoreChange","console","debug","scheduleReconnection","delay","calculateReconnectDelay","setTimeout","Math","min","jitterRange","jitter","random","round","max","watchDoctype","doctype","count","get","set","Promise","resolve","subscribeList","catch","err","warn","unwatchDoctype","delete","unsubscribeList","unwatchAll","keys","clear","key","name","inflight","fetchPromise","fetchAndReconcile","finally","document","getDoc","upsert","subscriptionsNeedingRehydration","updateSubscriptionMembership","subscription","scheduleRehydration","RemoteCreate","status","remove","affectedSubscriptions","removeFromAllSubscriptions","Delete","isRealtimeHealthy","isHealthy","getIsConnected","getConnectionState","everConnected","dispose","disconnect"],"sources":["../../../src/sync/realtime.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}

package/dist/jsx/sync/realtime.native.js

@@ -68,24 +68,25 @@ var RealtimeHandler = /* @__PURE__ */function () {
     _class_call_check(this, RealtimeHandler2);
     var _ref, _ref1, _ref2, _ref3;
     var _options_connectionConfig, _options_connectionConfig1, _options_connectionConfig2, _options_connectionConfig3;
+    _define_property(this, "reconnectAttempts", 0);
+    _define_property(this, "reconnectTimer", void 0);
+    _define_property(this, "hasConnected", false);
+    _define_property(this, "connected", false);
+    _define_property(this, "connectionConfig", void 0);
+    _define_property(this, "watchedDoctypes", /* @__PURE__ */new Map());
+    _define_property(this, "inflightFetches", /* @__PURE__ */new Map());
     _define_property(this, "db", void 0);
     _define_property(this, "realtime", void 0);
     _define_property(this, "normalizedCache", void 0);
     _define_property(this, "subscriptionManager", void 0);
     _define_property(this, "rehydrationManager", void 0);
     _define_property(this, "options", void 0);
-    _define_property(this, "reconnectAttempts", void 0);
-    _define_property(this, "reconnectTimer", void 0);
-    _define_property(this, "hasConnected", void 0);
-    _define_property(this, "connectionConfig", void 0);
     this.db = db;
     this.realtime = realtime;
     this.normalizedCache = normalizedCache;
     this.subscriptionManager = subscriptionManager;
     this.rehydrationManager = rehydrationManager;
     this.options = options;
-    this.reconnectAttempts = 0;
-    this.hasConnected = false;
     this.connectionConfig = {
       reconnectBaseDelay: (_ref = (_options_connectionConfig = options.connectionConfig) === null || _options_connectionConfig === void 0 ? void 0 : _options_connectionConfig.reconnectBaseDelay) !== null && _ref !== void 0 ? _ref : 1e3,
       reconnectMaxDelay: (_ref1 = (_options_connectionConfig1 = options.connectionConfig) === null || _options_connectionConfig1 === void 0 ? void 0 : _options_connectionConfig1.reconnectMaxDelay) !== null && _ref1 !== void 0 ? _ref1 : 3e4,
@@ -100,26 +101,55 @@ var RealtimeHandler = /* @__PURE__ */function () {
     value: (
     /**
     * Sets up realtime event handlers for document changes.
+    *
+    * Real Frappe (v15) wire protocol, verified live against a stock bench
+    * (see .test-evidence/storybook-rubric/p-results/frappe-realtime-live-e2e.md):
+    * - `doc_update`  `{doctype, name, modified}` — emitted to the per-doc room
+    *   `doc:{doctype}/{name}` on every save.
+    * - `list_update` `{doctype, name, user}` — emitted to the doctype room
+    *   `doctype:{doctype}` on every save of a non-single, non-child doctype.
+    * - Deletion emits the SAME two events (payload indistinguishable from an
+    *   update) — there is NO `doc_deleted` event. Deletions are detected here
+    *   opportunistically when the authoritative re-fetch 404s, but the durable
+    *   deletion signal remains the tombstone/CDC backfill (`Deleted Document`
+    *   doctype maintained by the `live` app's on_trash hook).
+    *
+    * Both real events funnel into the same fetch-and-reconcile path, deduped
+    * so a doc_update/list_update pair for the same doc costs one fetch.
     */
     function setupRealtimeHandlers() {
       var _this = this;
-      var _this_realtime, _this_realtime1, _this_realtime2, _this_realtime3, _this_realtime4;
+      var _this_realtime, _this_realtime1, _this_realtime2, _this_realtime3, _this_realtime4, _this_realtime5, _this_realtime6;
       if (!this.realtime) return;
-      (_this_realtime = this.realtime) === null || _this_realtime === void 0 ? void 0 : _this_realtime.on("doc_changed", async function (payload) {
+      (_this_realtime = this.realtime) === null || _this_realtime === void 0 ? void 0 : _this_realtime.on("doc_update", async function (payload) {
+        if (_this.options.onRealtimeEvent) _this.options.onRealtimeEvent({
+          type: import_types.RealtimeEventType.DocUpdate,
+          payload
+        });
+        return _this.onDocChanged(payload);
+      });
+      (_this_realtime1 = this.realtime) === null || _this_realtime1 === void 0 ? void 0 : _this_realtime1.on("list_update", async function (payload) {
+        if (_this.options.onRealtimeEvent) _this.options.onRealtimeEvent({
+          type: import_types.RealtimeEventType.ListUpdate,
+          payload
+        });
+        return _this.onDocChanged(payload);
+      });
+      (_this_realtime2 = this.realtime) === null || _this_realtime2 === void 0 ? void 0 : _this_realtime2.on("doc_changed", async function (payload) {
         if (_this.options.onRealtimeEvent) _this.options.onRealtimeEvent({
           type: import_types.RealtimeEventType.DocChanged,
           payload
         });
         return _this.onDocChanged(payload);
       });
-      (_this_realtime1 = this.realtime) === null || _this_realtime1 === void 0 ? void 0 : _this_realtime1.on("doc_deleted", async function (payload) {
+      (_this_realtime3 = this.realtime) === null || _this_realtime3 === void 0 ? void 0 : _this_realtime3.on("doc_deleted", async function (payload) {
         if (_this.options.onRealtimeEvent) _this.options.onRealtimeEvent({
           type: import_types.RealtimeEventType.DocDeleted,
           payload
         });
         return _this.onDocDeleted(payload);
       });
-      (_this_realtime2 = this.realtime) === null || _this_realtime2 === void 0 ? void 0 : _this_realtime2.on("perm_epoch_bump", function () {
+      (_this_realtime4 = this.realtime) === null || _this_realtime4 === void 0 ? void 0 : _this_realtime4.on("perm_epoch_bump", function () {
         if (_this.options.onRealtimeEvent) _this.options.onRealtimeEvent({
           type: import_types.RealtimeEventType.PermEpochBump
         });
@@ -127,10 +157,10 @@ var RealtimeHandler = /* @__PURE__ */function () {
           _this.options.onResetCache();
         }
       });
-      (_this_realtime3 = this.realtime) === null || _this_realtime3 === void 0 ? void 0 : _this_realtime3.on("connected", function () {
+      (_this_realtime5 = this.realtime) === null || _this_realtime5 === void 0 ? void 0 : _this_realtime5.on("connected", function () {
         _this.onConnected();
       });
-      (_this_realtime4 = this.realtime) === null || _this_realtime4 === void 0 ? void 0 : _this_realtime4.on("disconnect", function () {
+      (_this_realtime6 = this.realtime) === null || _this_realtime6 === void 0 ? void 0 : _this_realtime6.on("disconnect", function () {
         _this.onDisconnected();
       });
     })
@@ -151,7 +181,9 @@ var RealtimeHandler = /* @__PURE__ */function () {
     * Handles successful connection.
     */
     function onConnected() {
+      var _this_options_onStoreChange, _this_options;
       this.hasConnected = true;
+      this.connected = true;
       this.reconnectAttempts = 0;
       if (this.reconnectTimer) {
         clearTimeout(this.reconnectTimer);
@@ -165,6 +197,7 @@ var RealtimeHandler = /* @__PURE__ */function () {
       if (this.options.onBackfillAll) {
         this.options.onBackfillAll();
       }
+      (_this_options_onStoreChange = (_this_options = this.options).onStoreChange) === null || _this_options_onStoreChange === void 0 ? void 0 : _this_options_onStoreChange.call(_this_options);
       console.debug("[RealtimeHandler] Connected to realtime server");
     })
   }, {
@@ -174,7 +207,10 @@ var RealtimeHandler = /* @__PURE__ */function () {
     * Handles disconnection with automatic reconnection.
     */
     function onDisconnected() {
+      var _this_options_onStoreChange, _this_options;
       console.debug("[RealtimeHandler] Disconnected from realtime server");
+      this.connected = false;
+      (_this_options_onStoreChange = (_this_options = this.options).onStoreChange) === null || _this_options_onStoreChange === void 0 ? void 0 : _this_options_onStoreChange.call(_this_options);
       if (this.hasConnected) {
         this.scheduleReconnection();
       }
@@ -183,18 +219,20 @@ var RealtimeHandler = /* @__PURE__ */function () {
     key: "attemptConnection",
     value: (
     /**
-    * Attempts to connect to the realtime server.
+    * No-op placeholder retained for the disconnect backoff schedule below.
+    * Transport reconnect is owned by Socket.IO inside RealtimeModule; this
+    * layer only tracks attempts for logging / future health hooks.
     */
     function attemptConnection() {
       if (!this.realtime) return;
     })
   }, {
     key: "scheduleReconnection",
-    value:
-    // RealtimeModule handles reconnection internally via its reconnection config.
-    // Handlers are already attached in the constructor via setupRealtimeHandlers().
+    value: (
     /**
-    * Schedules a reconnection attempt with exponential backoff and jitter.
+    * Schedules a reconnection *watchdog* tick with exponential backoff and jitter.
+    * Does not open sockets — RealtimeModule already reconnects. Kept so disconnect
+    * storms remain observable (and existing unit tests stay meaningful).
     */
     function scheduleReconnection() {
       var _this = this;
@@ -207,7 +245,7 @@ var RealtimeHandler = /* @__PURE__ */function () {
         _this.reconnectAttempts++;
         _this.attemptConnection();
       }, delay);
-    }
+    })
   }, {
     key: "calculateReconnectDelay",
     value: (
@@ -224,6 +262,72 @@ var RealtimeHandler = /* @__PURE__ */function () {
       delay = Math.round(delay + jitter);
       return Math.max(this.connectionConfig.reconnectBaseDelay, Math.min(delay, this.connectionConfig.reconnectMaxDelay));
     })
+  }, {
+    /**
+    * Join the realtime doctype room for a doctype (refcounted). Called by the
+    * sync module whenever a subscription for the doctype is added. Room
+    * membership survives reconnects — RealtimeModule re-joins tracked rooms on
+    * every `connect`.
+    *
+    * Note: only doctype-level rooms are joined. `list_update` fires for every
+    * save of a regular doctype, which covers doc updates too; per-doc rooms
+    * would only add coverage for single/read-only doctypes.
+    */
+    key: "watchDoctype",
+    value: function watchDoctype(doctype) {
+      var _this_watchedDoctypes_get;
+      var count = ((_this_watchedDoctypes_get = this.watchedDoctypes.get(doctype)) !== null && _this_watchedDoctypes_get !== void 0 ? _this_watchedDoctypes_get : 0) + 1;
+      this.watchedDoctypes.set(doctype, count);
+      if (count === 1 && this.realtime) {
+        Promise.resolve(this.realtime.subscribeList(doctype)).catch(function (err) {
+          return console.warn(`[RealtimeHandler] Failed to join doctype room ${doctype}:`, err);
+        });
+      }
+    }
+  }, {
+    /** Release one reference to a doctype room; leaves the room on the last one. */
+    key: "unwatchDoctype",
+    value: function unwatchDoctype(doctype) {
+      var _this_watchedDoctypes_get;
+      var _this_realtime;
+      var count = ((_this_watchedDoctypes_get = this.watchedDoctypes.get(doctype)) !== null && _this_watchedDoctypes_get !== void 0 ? _this_watchedDoctypes_get : 0) - 1;
+      if (count > 0) {
+        this.watchedDoctypes.set(doctype, count);
+        return;
+      }
+      this.watchedDoctypes.delete(doctype);
+      (_this_realtime = this.realtime) === null || _this_realtime === void 0 ? void 0 : _this_realtime.unsubscribeList(doctype);
+    }
+  }, {
+    /** Leave all doctype rooms (used by cache resets/disposal). */
+    key: "unwatchAll",
+    value: function unwatchAll() {
+      if (this.realtime) {
+        var _iteratorNormalCompletion = true,
+          _didIteratorError = false,
+          _iteratorError = void 0;
+        try {
+          for (var _iterator = this.watchedDoctypes.keys()[Symbol.iterator](), _step; !(_iteratorNormalCompletion = (_step = _iterator.next()).done); _iteratorNormalCompletion = true) {
+            var doctype = _step.value;
+            this.realtime.unsubscribeList(doctype);
+          }
+        } catch (err) {
+          _didIteratorError = true;
+          _iteratorError = err;
+        } finally {
+          try {
+            if (!_iteratorNormalCompletion && _iterator.return != null) {
+              _iterator.return();
+            }
+          } finally {
+            if (_didIteratorError) {
+              throw _iteratorError;
+            }
+          }
+        }
+      }
+      this.watchedDoctypes.clear();
+    }
   }, {
     key: "onDocChanged",
     value: (
@@ -231,9 +335,26 @@ var RealtimeHandler = /* @__PURE__ */function () {
     * Realtime handler: authoritative document changed.
     * Fetches document via REST with current user context to respect permissions,
     * updates cache, and reconciles subscription membership.
+    *
+    * Concurrent events for the same document (frappe emits doc_update AND
+    * list_update per save) share a single in-flight fetch.
     */
-    async function onDocChanged(payload) {
+    function onDocChanged(payload) {
+      var _this = this;
+      var key = `${payload === null || payload === void 0 ? void 0 : payload.doctype}\0${payload === null || payload === void 0 ? void 0 : payload.name}`;
+      var inflight = this.inflightFetches.get(key);
+      if (inflight) return inflight;
+      var fetchPromise = this.fetchAndReconcile(payload).finally(function () {
+        _this.inflightFetches.delete(key);
+      });
+      this.inflightFetches.set(key, fetchPromise);
+      return fetchPromise;
+    })
+  }, {
+    key: "fetchAndReconcile",
+    value: async function fetchAndReconcile(payload) {
       try {
+        var _this_options_onStoreChange, _this_options;
         var document = await this.db.getDoc(payload.doctype, payload.name);
         this.normalizedCache.upsert(document);
         var subscriptionsNeedingRehydration = this.subscriptionManager.updateSubscriptionMembership(document);
@@ -260,10 +381,15 @@ var RealtimeHandler = /* @__PURE__ */function () {
             }
           }
         }
+        (_this_options_onStoreChange = (_this_options = this.options).onStoreChange) === null || _this_options_onStoreChange === void 0 ? void 0 : _this_options_onStoreChange.call(_this_options);
       } catch (err) {
+        if ((err === null || err === void 0 ? void 0 : err.status) === 404) {
+          await this.onDocDeleted(payload);
+          return;
+        }
         console.warn(`Failed to fetch document ${payload === null || payload === void 0 ? void 0 : payload.doctype}/${payload === null || payload === void 0 ? void 0 : payload.name} during realtime update:`, err);
       }
-    })
+    }
   }, {
     key: "onDocDeleted",
     value: (
@@ -272,6 +398,7 @@ var RealtimeHandler = /* @__PURE__ */function () {
     */
     async function onDocDeleted(payload) {
       try {
+        var _this_options_onStoreChange, _this_options;
         this.normalizedCache.remove({
           doctype: payload.doctype,
           name: payload.name
@@ -300,6 +427,7 @@ var RealtimeHandler = /* @__PURE__ */function () {
             }
           }
         }
+        (_this_options_onStoreChange = (_this_options = this.options).onStoreChange) === null || _this_options_onStoreChange === void 0 ? void 0 : _this_options_onStoreChange.call(_this_options);
       } catch (err) {
         console.warn(`Failed to process doc_deleted for ${payload === null || payload === void 0 ? void 0 : payload.doctype}/${payload === null || payload === void 0 ? void 0 : payload.name}:`, err);
       }
@@ -319,6 +447,20 @@ var RealtimeHandler = /* @__PURE__ */function () {
     value: function getIsConnected() {
       return this.hasConnected;
     }
+  }, {
+    /**
+    * Live connection snapshot for reconnect indicators.
+    * `connected` tracks the socket right now; `everConnected` distinguishes
+    * "reconnecting" (was up, dropped) from "never had realtime" (fixtures,
+    * SSR, no realtime module).
+    */
+    key: "getConnectionState",
+    value: function getConnectionState() {
+      return {
+        connected: this.connected,
+        everConnected: this.hasConnected
+      };
+    }
   }, {
     /**
     * Disposes of resources and clears timers.
@@ -329,6 +471,7 @@ var RealtimeHandler = /* @__PURE__ */function () {
         clearTimeout(this.reconnectTimer);
         this.reconnectTimer = void 0;
       }
+      this.unwatchAll();
       if (this.realtime) {
         var _this_realtime;
         (_this_realtime = this.realtime) === null || _this_realtime === void 0 ? void 0 : _this_realtime.disconnect();