@multiplatform.one/frappe 6.1.0 → 6.3.0

package/src/sync/persistence.ts

@@ -6,8 +6,9 @@
  */
 
 import { Debouncer } from "@tanstack/pacer";
-import { onVisibilityChange } from "@multiplatform.one/platform";
+import { isNative, onVisibilityChange } from "@multiplatform.one/platform";
 import type { FrappeDocData } from "../common/types";
+import { isGjs } from "../util";
 import type { MutationEngine } from "./mutationEngine";
 import type { MutationJournal } from "./mutationJournal";
 import type { NormalizedCache } from "./normalizedCache";
@@ -51,14 +52,29 @@ export class PersistenceManager {
   private activeResponseTimers = new Set<ReturnType<typeof setTimeout>>();
   /** Flag to prevent operations after destroy. */
   private isDestroyed = false;
+  /**
+   * Resolves once the persisted snapshot (if any) has been restored into
+   * memory. Resolved immediately when persistence is disabled. Never rejects.
+   */
+  private loadPromise: Promise<void> = Promise.resolve();
+  private readonly normalizedCache: NormalizedCache;
+  private readonly mutationJournal: MutationJournal;
+  private readonly subscriptionManager: SubscriptionManager;
+  private readonly mutationEngine: MutationEngine;
+  private readonly options: SyncOptions;
 
   constructor(
-    private readonly normalizedCache: NormalizedCache,
-    private readonly mutationJournal: MutationJournal,
-    private readonly subscriptionManager: SubscriptionManager,
-    private readonly mutationEngine: MutationEngine,
-    private readonly options: SyncOptions = {},
+    normalizedCache: NormalizedCache,
+    mutationJournal: MutationJournal,
+    subscriptionManager: SubscriptionManager,
+    mutationEngine: MutationEngine,
+    options: SyncOptions = {},
   ) {
+    this.normalizedCache = normalizedCache;
+    this.mutationJournal = mutationJournal;
+    this.subscriptionManager = subscriptionManager;
+    this.mutationEngine = mutationEngine;
+    this.options = options;
     // Initialize tab coordination config
     this.tabCoordinationConfig = {
       activeTabPriority: options.tabCoordination?.activeTabPriority ?? true,
@@ -66,6 +82,19 @@ export class PersistenceManager {
       handoffGracePeriod: options.tabCoordination?.handoffGracePeriod ?? 2000,
     };
 
+    // React Native has window but no document/BroadcastChannel; it does have
+    // full KV storage (MMKV via PlatformStorageKV), so enable snapshot
+    // persistence and skip only the DOM-dependent cross-tab machinery.
+    // GJS (GNOME) takes the same branch: single window, no BroadcastChannel
+    // or real DOM (any window/document globals are layout stubs) — storage
+    // arrives via an app-provided `SyncOptions.storage` adapter (e.g. a Gio
+    // file-backed KV) and persistence stays a clean no-op without one, since
+    // setupPersistence bails when persistKey is unset.
+    if (isNative || isGjs()) {
+      this.setupPersistence();
+      return;
+    }
+
     // Skip browser-only setup during SSR (document/window not available)
     if (typeof window === "undefined" || typeof document === "undefined") {
       return;
@@ -74,11 +103,29 @@ export class PersistenceManager {
     this.setupPersistence();
     this.setupBroadcastChannel();
 
-    if (this.tabCoordinationConfig.activeTabPriority) {
+    // Leadership election only coordinates persistence snapshots and
+    // cross-tab broadcast, and every one of those paths is persistKey-gated
+    // (setupPersistence/setupBroadcastChannel/scheduleSave all bail without
+    // one). Electing without a persistKey did nothing except leak: each
+    // SyncModule armed a forever leader-heartbeat setInterval (+ a
+    // visibilitychange listener + periodic localStorage writes) whose
+    // closure pinned the module's whole sync graph. Fixture-mode consumers
+    // (tests, stories) create a SyncModule per fixture set, so the leaked
+    // heartbeats accumulated and wedged vitest forks-worker teardown.
+    if (this.options.persistKey && this.tabCoordinationConfig.activeTabPriority) {
       this.setupTabCoordination();
     }
   }
 
+  /**
+   * Resolves when the initial snapshot restore has completed (immediately if
+   * persistence is off). `SyncModule.subscribe` awaits this so a fresh mount
+   * can re-adopt a restored subscription instead of racing the async load.
+   */
+  whenReady(): Promise<void> {
+    return this.loadPromise;
+  }
+
   /**
    * Sets up persistence storage based on environment and options.
    */
@@ -91,12 +138,20 @@ export class PersistenceManager {
     } else if (typeof indexedDB !== "undefined") {
       this.persistenceStorage = new IndexedDBKV();
     } else {
-      // PlatformStorageKV uses MMKV on native and localStorage on web
+      // PlatformStorageKV uses MMKV on native and localStorage on web. On
+      // GJS neither exists, so the store package degrades to an in-memory
+      // map — snapshots then die with the process. Say so instead of
+      // pretending persistKey persisted anything.
+      if (isGjs()) {
+        console.debug(
+          "[frappe-sync] persistKey set but no storage adapter on GJS — snapshots are in-memory only (pass SyncOptions.storage, e.g. a Gio file-backed KV, for real persistence)",
+        );
+      }
       this.persistenceStorage = new PlatformStorageKV();
     }
 
-    // Load persisted state if available
-    void this.load();
+    // Load persisted state if available; expose completion via whenReady()
+    this.loadPromise = this.load();
   }
 
   /**
@@ -270,12 +325,16 @@ export class PersistenceManager {
   private async save() {
     if (!this.options.persistKey || !this.persistenceStorage) return;
     try {
+      // Expire restored subscriptions nobody re-adopted so they leave the
+      // snapshot instead of accumulating across reloads.
+      this.subscriptionManager.gcRestoredSubscriptions();
       // Capture a minimal snapshot for fast resume after reload or tab switch
       const snapshot = {
         subs: [...this.subscriptionManager.getAllSubscriptions().values()].map((s) => ({
           id: s.id,
           query: s.query,
           checkpoint: s.checkpoint,
+          cursor: s.cursor,
           docIds: s.docIds,
         })),
         cache: this.normalizedCache.state,
@@ -299,16 +358,29 @@ export class PersistenceManager {
       if (!raw) return;
       const snap = JSON.parse(raw);
 
-      // Restore cache first so reads have data once subs are reinstated
-      if (snap?.cache) {
-        (this.normalizedCache as any).state = snap.cache;
+      // Restore cache first so reads have data once subs are reinstated.
+      // Merge per doc instead of replacing state wholesale: anything already
+      // in memory (e.g. an optimistic write that raced ahead of this load)
+      // is newer than the snapshot and wins. Per-doc upsert also keeps the
+      // cache's LRU bookkeeping and maxCacheSize bounds accurate.
+      if (snap?.cache && typeof snap.cache === "object") {
+        for (const bucket of Object.values(snap.cache as Record<string, unknown>)) {
+          const byId = (bucket as { byId?: Record<string, unknown> } | null)?.byId;
+          if (!byId || typeof byId !== "object") continue;
+          for (const doc of Object.values(byId) as FrappeDocData[]) {
+            if (!doc?.doctype || !doc?.name) continue;
+            if (this.normalizedCache.get(doc)) continue;
+            this.normalizedCache.upsert(doc, { replace: true });
+          }
+        }
       }
 
-      // Rehydrate subscriptions map including docIds and cursors
-      if (snap?.subs) {
-        const subscriptions = this.subscriptionManager.getAllSubscriptions();
-        for (const subscription of snap.subs as any[]) {
-          subscriptions.set(subscription.id, subscription);
+      // Rehydrate subscriptions as dormant "restored" entries: they hold the
+      // persisted query, checkpoint, and membership for cache-first
+      // re-adoption, and are GC'd if nothing re-adopts them.
+      if (snap?.subs && Array.isArray(snap.subs)) {
+        for (const subscription of snap.subs) {
+          this.subscriptionManager.restoreSubscription(subscription);
         }
       }
 

package/src/sync/persistenceGjs.spec.ts

@@ -0,0 +1,143 @@
+/**
+ * GJS (GNOME) persistence path: the GNOME bundles run with window/document
+ * LAYOUT STUBS (react-gnome polyfills), so the old DOM-presence branch would
+ * have started BroadcastChannel/tab-coordination machinery against fake
+ * globals. With `imports.gi` present the PersistenceManager must take the
+ * native-style branch: snapshot persistence through the provided storage
+ * adapter (a Gio file KV on GNOME), no BroadcastChannel, no tab
+ * coordination — and stay fully inert without persistKey.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { PersistenceManager } from "./persistence";
+
+vi.mock("@multiplatform.one/platform", () => ({
+  isNative: false,
+  onAppFocus: vi.fn(() => vi.fn()),
+  onOnline: vi.fn(() => vi.fn()),
+  onVisibilityChange: vi.fn(() => vi.fn()),
+}));
+
+describe("PersistenceManager on GJS (imports.gi global)", () => {
+  let persistenceManager: PersistenceManager | undefined;
+  let mockStorage: any;
+  let mockNormalizedCache: any;
+  let mockMutationJournal: any;
+  let mockSubscriptionManager: any;
+  let mockMutationEngine: any;
+  let broadcastChannelSpy: any;
+  let originalBroadcastChannel: any;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+
+    mockStorage = {
+      getItem: vi.fn().mockResolvedValue(null),
+      setItem: vi.fn().mockResolvedValue(undefined),
+      removeItem: vi.fn().mockResolvedValue(undefined),
+    };
+
+    mockNormalizedCache = {
+      state: {},
+      get: vi.fn().mockReturnValue(undefined),
+      upsert: vi.fn(),
+    };
+    mockMutationJournal = { listPending: vi.fn().mockReturnValue([]), add: vi.fn() };
+    mockSubscriptionManager = {
+      getAllSubscriptions: vi.fn().mockReturnValue(new Map()),
+      restoreSubscription: vi.fn(),
+      gcRestoredSubscriptions: vi.fn(),
+    };
+    mockMutationEngine = { getTemporaryIdToRealNameMap: vi.fn().mockReturnValue(new Map()) };
+
+    // The GJS runtime marker. Unlike the RN spec, document stays DEFINED
+    // (happy-dom) — mirroring the GNOME bundles where react-gnome installs
+    // window/document layout stubs.
+    (globalThis as any).imports = { gi: {} };
+
+    originalBroadcastChannel = (globalThis as any).BroadcastChannel;
+    broadcastChannelSpy = vi.fn();
+    Object.defineProperty(globalThis, "BroadcastChannel", {
+      value: broadcastChannelSpy,
+      configurable: true,
+      writable: true,
+    });
+  });
+
+  afterEach(() => {
+    persistenceManager?.destroy();
+    persistenceManager = undefined;
+    delete (globalThis as any).imports;
+    Object.defineProperty(globalThis, "BroadcastChannel", {
+      value: originalBroadcastChannel,
+      configurable: true,
+      writable: true,
+    });
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  function createManager(options: Record<string, unknown>) {
+    persistenceManager = new PersistenceManager(
+      mockNormalizedCache,
+      mockMutationJournal,
+      mockSubscriptionManager,
+      mockMutationEngine,
+      options,
+    );
+    return persistenceManager;
+  }
+
+  it("activates snapshot persistence through the provided storage adapter", async () => {
+    const manager = createManager({ persistKey: "gjs-key", storage: mockStorage });
+    await manager.whenReady();
+    expect(mockStorage.getItem).toHaveBeenCalledWith("gjs-key");
+
+    manager.scheduleSave();
+    await vi.advanceTimersByTimeAsync(60);
+    expect(mockStorage.setItem).toHaveBeenCalledWith("gjs-key", expect.any(String));
+  });
+
+  it("restores a persisted snapshot on startup", async () => {
+    const snapshotSub = {
+      id: "sub-gjs",
+      query: { doctype: "Workspace" },
+      checkpoint: "2026-01-01T10:00:00",
+      docIds: ["w1"],
+    };
+    mockStorage.getItem.mockResolvedValue(
+      JSON.stringify({
+        subs: [snapshotSub],
+        cache: {
+          Workspace: { byId: { w1: { doctype: "Workspace", name: "w1" } }, allIds: ["w1"] },
+        },
+        journal: [],
+        temp: [],
+      }),
+    );
+
+    const manager = createManager({ persistKey: "gjs-key", storage: mockStorage });
+    await manager.whenReady();
+
+    expect(mockSubscriptionManager.restoreSubscription).toHaveBeenCalledWith(snapshotSub);
+    expect(mockNormalizedCache.upsert).toHaveBeenCalledWith(
+      { doctype: "Workspace", name: "w1" },
+      { replace: true },
+    );
+  });
+
+  it("skips BroadcastChannel and tab coordination even though document exists", () => {
+    expect(typeof document).not.toBe("undefined");
+    createManager({ persistKey: "gjs-key", storage: mockStorage });
+    expect(broadcastChannelSpy).not.toHaveBeenCalled();
+  });
+
+  it("stays fully inert without persistKey", async () => {
+    const manager = createManager({});
+    await manager.whenReady();
+    manager.scheduleSave();
+    await vi.advanceTimersByTimeAsync(60);
+
+    expect(mockStorage.getItem).not.toHaveBeenCalled();
+    expect(mockStorage.setItem).not.toHaveBeenCalled();
+  });
+});

package/src/sync/persistenceNative.spec.ts

@@ -0,0 +1,139 @@
+/**
+ * React Native persistence path: RN has `window` but no `document` and no
+ * BroadcastChannel, yet full KV storage (MMKV via PlatformStorageKV). With
+ * `isNative` true the PersistenceManager must activate snapshot persistence
+ * and skip only the DOM-dependent cross-tab machinery — previously the
+ * `document` guard made persistence dead code on native.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { PersistenceManager } from "./persistence";
+
+vi.mock("@multiplatform.one/platform", () => ({
+  isNative: true,
+  onAppFocus: vi.fn(() => vi.fn()),
+  onOnline: vi.fn(() => vi.fn()),
+  onVisibilityChange: vi.fn(() => vi.fn()),
+}));
+
+describe("PersistenceManager on React Native (isNative)", () => {
+  let persistenceManager: PersistenceManager | undefined;
+  let mockStorage: any;
+  let mockNormalizedCache: any;
+  let mockMutationJournal: any;
+  let mockSubscriptionManager: any;
+  let mockMutationEngine: any;
+  let broadcastChannelSpy: any;
+  let originalDocument: any;
+  let originalBroadcastChannel: any;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+
+    mockStorage = {
+      getItem: vi.fn().mockResolvedValue(null),
+      setItem: vi.fn().mockResolvedValue(undefined),
+      removeItem: vi.fn().mockResolvedValue(undefined),
+    };
+
+    mockNormalizedCache = {
+      state: {},
+      get: vi.fn().mockReturnValue(undefined),
+      upsert: vi.fn(),
+    };
+    mockMutationJournal = { listPending: vi.fn().mockReturnValue([]), add: vi.fn() };
+    mockSubscriptionManager = {
+      getAllSubscriptions: vi.fn().mockReturnValue(new Map()),
+      restoreSubscription: vi.fn(),
+      gcRestoredSubscriptions: vi.fn(),
+    };
+    mockMutationEngine = { getTemporaryIdToRealNameMap: vi.fn().mockReturnValue(new Map()) };
+
+    // Simulate the RN runtime: no document, no BroadcastChannel
+    originalDocument = (globalThis as any).document;
+    originalBroadcastChannel = (globalThis as any).BroadcastChannel;
+    Object.defineProperty(globalThis, "document", { value: undefined, configurable: true });
+    broadcastChannelSpy = vi.fn();
+    Object.defineProperty(globalThis, "BroadcastChannel", {
+      value: broadcastChannelSpy,
+      configurable: true,
+      writable: true,
+    });
+  });
+
+  afterEach(() => {
+    persistenceManager?.destroy();
+    persistenceManager = undefined;
+    Object.defineProperty(globalThis, "document", { value: originalDocument, configurable: true });
+    Object.defineProperty(globalThis, "BroadcastChannel", {
+      value: originalBroadcastChannel,
+      configurable: true,
+      writable: true,
+    });
+    vi.useRealTimers();
+    vi.restoreAllMocks();
+  });
+
+  function createManager(options: Record<string, unknown>) {
+    persistenceManager = new PersistenceManager(
+      mockNormalizedCache,
+      mockMutationJournal,
+      mockSubscriptionManager,
+      mockMutationEngine,
+      options,
+    );
+    return persistenceManager;
+  }
+
+  it("activates snapshot persistence without a document", async () => {
+    const manager = createManager({ persistKey: "rn-key", storage: mockStorage });
+    await manager.whenReady();
+    expect(mockStorage.getItem).toHaveBeenCalledWith("rn-key");
+
+    manager.scheduleSave();
+    await vi.advanceTimersByTimeAsync(60);
+    expect(mockStorage.setItem).toHaveBeenCalledWith("rn-key", expect.any(String));
+  });
+
+  it("restores a persisted snapshot on startup", async () => {
+    const snapshotSub = {
+      id: "sub-rn",
+      query: { doctype: "ToDo" },
+      checkpoint: "2024-01-01T10:00:00",
+      docIds: ["t1"],
+    };
+    mockStorage.getItem.mockResolvedValue(
+      JSON.stringify({
+        subs: [snapshotSub],
+        cache: {
+          ToDo: { byId: { t1: { doctype: "ToDo", name: "t1" } }, allIds: ["t1"] },
+        },
+        journal: [],
+        temp: [],
+      }),
+    );
+
+    const manager = createManager({ persistKey: "rn-key", storage: mockStorage });
+    await manager.whenReady();
+
+    expect(mockSubscriptionManager.restoreSubscription).toHaveBeenCalledWith(snapshotSub);
+    expect(mockNormalizedCache.upsert).toHaveBeenCalledWith(
+      { doctype: "ToDo", name: "t1" },
+      { replace: true },
+    );
+  });
+
+  it("skips BroadcastChannel and tab coordination on native", () => {
+    createManager({ persistKey: "rn-key", storage: mockStorage });
+    expect(broadcastChannelSpy).not.toHaveBeenCalled();
+  });
+
+  it("stays fully inert without persistKey", async () => {
+    const manager = createManager({});
+    await manager.whenReady();
+    manager.scheduleSave();
+    await vi.advanceTimersByTimeAsync(60);
+
+    expect(mockStorage.getItem).not.toHaveBeenCalled();
+    expect(mockStorage.setItem).not.toHaveBeenCalled();
+  });
+});

package/src/sync/realtime.spec.ts

@@ -34,6 +34,8 @@ describe("RealtimeHandler", () => {
       }),
       isHealthy: vi.fn().mockReturnValue(true),
       disconnect: vi.fn(),
+      subscribeList: vi.fn().mockResolvedValue(undefined),
+      unsubscribeList: vi.fn(),
     } as any;
 
     mockNormalizedCache = {
@@ -71,6 +73,9 @@ describe("RealtimeHandler", () => {
         {},
       );
 
+      // Real Frappe v15 emits doc_update/list_update; designed names kept as forward-compat.
+      expect(mockRealtime.on).toHaveBeenCalledWith("doc_update", expect.any(Function));
+      expect(mockRealtime.on).toHaveBeenCalledWith("list_update", expect.any(Function));
       expect(mockRealtime.on).toHaveBeenCalledWith("doc_changed", expect.any(Function));
       expect(mockRealtime.on).toHaveBeenCalledWith("doc_deleted", expect.any(Function));
       expect(mockRealtime.on).toHaveBeenCalledWith("perm_epoch_bump", expect.any(Function));
@@ -366,7 +371,9 @@ describe("RealtimeHandler", () => {
 
         // Verify reconnection was cancelled
         vi.advanceTimersByTime(5000);
-        expect(mockRealtime.on).toHaveBeenCalledTimes(5); // Only initial setup calls
+        // Initial setup: doc_update, list_update, doc_changed, doc_deleted,
+        // perm_epoch_bump, connected, disconnect (real Frappe protocol + lifecycle).
+        expect(mockRealtime.on).toHaveBeenCalledTimes(7);
       });
     });
 
@@ -505,6 +512,16 @@ describe("RealtimeHandler", () => {
       // First establish connection
       eventHandlers.connected();
 
+      // calculateReconnectDelay clamps to reconnectBaseDelay, so any negative
+      // jitter draw (Math.random() < 0.5) collapses to exactly 1000ms — with
+      // three real draws all three collapsed ~12.5% of runs, flaking the
+      // variance assertion below. Use deterministic distinct draws instead.
+      vi.spyOn(Math, "random")
+        .mockReturnValueOnce(0.6)
+        .mockReturnValueOnce(0.8)
+        .mockReturnValueOnce(0.95)
+        .mockReturnValue(0.5);
+
       const delays: number[] = [];
 
       // Collect multiple reconnection delays