@multiplatform.one/frappe 7.10.0 → 7.11.0

package/dist/jsx/syncOptionsKey.native.js

@@ -0,0 +1,82 @@
+"use strict";
+
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all) __defProp(target, name, {
+    get: all[name],
+    enumerable: true
+  });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from)) if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+      get: () => from[key],
+      enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+    });
+  }
+  return to;
+};
+var __toCommonJS = mod => __copyProps(__defProp({}, "__esModule", {
+  value: true
+}), mod);
+var syncOptionsKey_exports = {};
+__export(syncOptionsKey_exports, {
+  syncOptionsKey: () => syncOptionsKey
+});
+module.exports = __toCommonJS(syncOptionsKey_exports);
+function _type_of(obj) {
+  "@swc/helpers - typeof";
+
+  return obj && typeof Symbol !== "undefined" && obj.constructor === Symbol ? "symbol" : typeof obj;
+}
+var identities = /* @__PURE__ */new WeakMap();
+var nextIdentity = 0;
+function identity(value) {
+  var id = identities.get(value);
+  if (id === void 0) {
+    id = ++nextIdentity;
+    identities.set(value, id);
+  }
+  return ["reference", id];
+}
+function stableValue(value) {
+  var ancestors = arguments.length > 1 && arguments[1] !== void 0 ? arguments[1] : /* @__PURE__ */new Set();
+  if (typeof value === "function") return identity(value);
+  if (value === null || (typeof value === "undefined" ? "undefined" : _type_of(value)) !== "object") return [typeof value === "undefined" ? "undefined" : _type_of(value), String(value)];
+  var prototype = Object.getPrototypeOf(value);
+  if (ancestors.has(value) || !Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+    return identity(value);
+  }
+  var nested = new Set(ancestors).add(value);
+  if (Array.isArray(value)) return ["array", value.map(function (item) {
+    return stableValue(item, nested);
+  })];
+  return ["record", Object.entries(value).filter(function (param) {
+    var [, item] = param;
+    return item !== void 0;
+  }).sort(function (param, param1) {
+    var [left] = param,
+      [right] = param1;
+    return left.localeCompare(right);
+  }).map(function (param) {
+    var [key, item] = param;
+    return [key, stableValue(item, nested)];
+  })];
+}
+function syncOptionsKey() {
+  var options = arguments.length > 0 && arguments[0] !== void 0 ? arguments[0] : {};
+  var _options_catchUpStrategy;
+  var {
+    storage,
+    ...values
+  } = options;
+  return JSON.stringify([stableValue({
+    ...values,
+    catchUpStrategy: (_options_catchUpStrategy = options.catchUpStrategy) !== null && _options_catchUpStrategy !== void 0 ? _options_catchUpStrategy : "cdc",
+    cdcInterval: options.cdcInterval && options.cdcInterval > 0 ? options.cdcInterval : 0
+  }), storage ? identity(storage) : null]);
+}
+//# sourceMappingURL=syncOptionsKey.native.js.map

package/dist/jsx/syncOptionsKey.native.js.map

@@ -0,0 +1 @@
+{"version":3,"names":["__defProp","Object","defineProperty","__getOwnPropDesc","getOwnPropertyDescriptor","__getOwnPropNames","getOwnPropertyNames","__hasOwnProp","prototype","hasOwnProperty","__export","target","all","name","get","enumerable","__copyProps","to","from","except","desc","key","call","__toCommonJS","mod","value","syncOptionsKey_exports","syncOptionsKey","module","exports","_type_of","obj","Symbol","constructor","identities","WeakMap","nextIdentity","identity","id","set"],"sources":["../../src/syncOptionsKey.ts"],"sourcesContent":[null],"mappings":"AAEA,YAAM;;AACN,IAAIA,SAAA,GAAAC,MAAe,CAAAC,cAAA;AACnB,IAAAC,gBAAkB,GAAAF,MAAe,CAAAG,wBAAA;AAC/B,IAAAC,iBAAS,GAAWJ,MAAI,CAAKK,mBAAA;AAC7B,IAAAC,YAAW,GAAAN,MAAW,CAAAO,SAAA,CAAAC,cAAA;AACpB,IAAAC,QAAO,GAAAA,CAAAC,MAAA,EAAAC,GAAA;EACP,SAAAC,IAAW,IAAID,GAAA,EACjBZ,SAAA,CAAAW,MAAA,EAAAE,IAAA;IAAAC,GAAA,EAAAF,GAAA,CAAAC,IAAA;IAAAE,UAAA;EAAA;AACA;AACF,IAAAC,WAAA,GAAAA,CAAAC,EAAA,EAAAC,IAAA,EAAAC,MAAA,EAAAC,IAAA;EAEA,IAAAF,IAAS,WAAYA,IAAA,KAAgB,YAAY,OAAAA,IAAA,eAA4B;IAC3E,KAAI,IAAOG,GAAA,IAAAhB,iBAAsB,CAAAa,IAAO,GACpC,KAAAX,YAAU,CAAQe,IAAA,CAAAL,EAAO,EAAAI,GAAA,KAAUA,GAAA,KAAAF,MAAU,EAC3CnB,SAAA,CAAAiB,EAAY,EAAAI,GAAA,EAAO;MAAAP,GAAA,EAAAA,CAAA,KAAAI,IAAe,CAAAG,GAAK;MAAAN,UAAA,IAAAK,IAAA,GAAAjB,gBAAA,CAAAe,IAAA,EAAAG,GAAA,MAAAD,IAAA,CAAAL;IAAA;EAC7C;EAIE,OAAAE,EAAO;AAAc;AAEvB,IAAAM,YAAM,GAASC,GAAI,IAAIR,WAAW,CAAIhB,SAAK;EAAAyB,KAAA;AAAA,IAAAD,GAAA;AAC3C,IAAAE,sBAAuB,GAAG;AAC1BhB,QAAA,CAAOgB,sBAAA;EAAAC,cACL,EAAAA,CAAA,KAAAA;AAAA;AAIwDC,MAC1D,CAAAC,OAAA,GAAAN,YAAA,CAAAG,sBAAA;AACF,SAAAI,SAAAC,GAAA;EAEO,uBAAwB;;EAC7B,OAAMA,GAAE,WAAYC,MAAO,KAAI,eAAAD,GAAA,CAAAE,WAAA,KAAAD,MAAA,qBAAAD,GAAA;AAC/B;AAAsB,IACpBG,UAAA,GAAY,mBAAAC,OAAA;AAAA,IAAAC,YACP;AAAA,SACHC,SAAAZ,KAAiB;EAA2B,IAC5Ca,EAAA,GAAAJ,UAAa,CAAApB,GAAA,CAAAW,KAAQ;EAA+D,IACrFa,EAAA;IACDA,EAAA,KAAAF,YAAmB;IACpBF,UAAA,CAAAK,GAAA,CAAAd,KAAA,EAAAa,EAAA;EACH","ignoreList":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@multiplatform.one/frappe",
-  "version": "7.10.0",
+  "version": "7.11.0",
   "description": "frappe client for multiplatform.one ecosystem",
   "keywords": [
     "auth",
@@ -60,15 +60,18 @@
     "access": "public"
   },
   "dependencies": {
+    "@multiplatform.one/store": "7.11.0",
     "@tanstack/db": "0.6.5",
     "@tanstack/pacer": "0.21.0",
     "@tanstack/react-db": "0.1.83",
     "@tanstack/react-pacer": "0.22.0",
     "broadcast-channel": "^7.3.0",
-    "socket.io-client": "^4.8.3",
-    "@multiplatform.one/store": "7.10.0"
+    "socket.io-client": "^4.8.3"
   },
   "devDependencies": {
+    "@multiplatform.one/config": "7.11.0",
+    "@multiplatform.one/platform": "7.11.0",
+    "@multiplatform.one/test-utils": "7.11.0",
     "@tamagui/build": "2.7.6",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.2",
@@ -78,14 +81,11 @@
     "react": "19.2.5",
     "tamagui": "2.7.6",
     "typescript": "~5.9.3",
-    "vitest": "^4.1.5",
-    "@multiplatform.one/config": "7.10.0",
-    "@multiplatform.one/platform": "7.10.0",
-    "@multiplatform.one/test-utils": "7.10.0"
+    "vitest": "^4.1.5"
   },
   "peerDependencies": {
-    "react": "^19.1.0",
-    "@multiplatform.one/platform": "^7.10.0"
+    "@multiplatform.one/platform": "^7.11.0",
+    "react": "^19.1.0"
   },
   "engines": {
     "node": ">=6.0.0"

package/src/frappeReact.catchUp.spec.tsx

@@ -0,0 +1,105 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, expect, it, vi } from "vitest";
+import { getFrappeSyncModule, useFrappeCatchUp, useFrappePendingMutations } from "./frappeReact";
+import { Operation, Status } from "./sync/types";
+import { InMemoryFixtureProvider } from "./fixtures";
+import type { SyncModule } from "./sync";
+import type { UseFrappeCollectionConfig } from "./frappeReact";
+
+const modules = new Set<SyncModule>();
+function moduleFor(config: UseFrappeCollectionConfig) {
+  const sync = getFrappeSyncModule(config)!;
+  expect(sync).toBeDefined();
+  modules.add(sync);
+  return sync;
+}
+afterEach(async () => {
+  for (const sync of modules) await sync.dispose();
+  modules.clear();
+  vi.unstubAllGlobals();
+});
+
+it.each([false, true])(
+  "separates effective options in the shared cache, fixtures=%s",
+  (fixture) => {
+    const config = fixture
+      ? { fixtures: new InMemoryFixtureProvider({}) }
+      : { baseURL: "https://cache-options.test", realtime: false };
+    const defaultSync = moduleFor(config);
+    expect(moduleFor({ ...config, syncOptions: { catchUpStrategy: "cdc", cdcInterval: 0 } })).toBe(
+      defaultSync,
+    );
+    const snapshot = moduleFor({ ...config, syncOptions: { catchUpStrategy: "snapshot" } });
+    expect(snapshot).not.toBe(defaultSync);
+    expect(moduleFor({ ...config, syncOptions: { catchUpStrategy: "snapshot" } })).toBe(snapshot);
+    expect(moduleFor({ ...config, syncOptions: { cdcInterval: 1000 } })).not.toBe(defaultSync);
+  },
+);
+
+it("follows the selected module, retains failure state during retry and does not retry on render", async () => {
+  const transport = vi.fn(async () => Response.json({ data: [{ name: "a", doctype: "Task" }] }));
+  vi.stubGlobal("fetch", transport);
+  const cdc = { baseURL: "https://hook-options.test", realtime: false };
+  const snapshot = { ...cdc, syncOptions: { catchUpStrategy: "snapshot" as const } };
+  const first = moduleFor(cdc);
+  const second = moduleFor(snapshot);
+  await first.subscribe({ doctype: "Task" });
+  await second.subscribe({ doctype: "Task" });
+  const view = renderHook(({ config }) => useFrappeCatchUp(config), {
+    initialProps: { config: cdc as UseFrappeCollectionConfig | undefined },
+  });
+  transport.mockImplementation(async () =>
+    Response.json({ message: "unavailable" }, { status: 404 }),
+  );
+  await act(async () => {
+    await view.result.current.retry();
+  });
+  expect(view.result.current).toMatchObject({
+    refreshing: false,
+    stale: true,
+    error: { status: 404 },
+  });
+  const calls = transport.mock.calls.length;
+  view.rerender({ config: { ...cdc } });
+  expect(transport).toHaveBeenCalledTimes(calls);
+  view.rerender({ config: snapshot });
+  await waitFor(() => expect(view.result.current.stale).toBe(false));
+  transport.mockImplementation(async () => Response.json({ data: [] }));
+  await act(async () => {
+    await view.result.current.retry();
+  });
+  expect(view.result.current.error).toBeNull();
+  expect(second.__debug().subscriptions[0].docCount).toBe(0);
+  expect(first.__debug().subscriptions[0].docCount).toBe(1);
+  view.rerender({ config: undefined });
+  expect(await view.result.current.retry()).toEqual({
+    refreshing: false,
+    stale: false,
+    error: null,
+  });
+  view.unmount();
+});
+
+it("drops the previous module's mutation notice when changed options select an empty ledger", () => {
+  const config = { fixtures: new InMemoryFixtureProvider({}) };
+  const next = { ...config, syncOptions: { catchUpStrategy: "snapshot" as const } };
+  vi.spyOn(moduleFor(config), "getMutationEntries").mockReturnValue([
+    {
+      id: "old",
+      operation: Operation.Update,
+      doctype: "Task",
+      status: Status.Failed,
+      createdAt: 1,
+      retryCount: 0,
+      error: "old module failure",
+    },
+  ]);
+  moduleFor(next);
+  const view = renderHook(({ connection }) => useFrappePendingMutations(connection), {
+    initialProps: { connection: config as UseFrappeCollectionConfig },
+  });
+  expect(view.result.current.failed.map((entry) => entry.id)).toEqual(["old"]);
+  view.rerender({ connection: next });
+  expect(view.result.current.entries).toEqual([]);
+  view.unmount();
+});

package/src/frappeReact.ts

@@ -1,6 +1,6 @@
 import { isWindowDefined } from "@multiplatform.one/platform";
 import type { Collection } from "@tanstack/db";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import {
   createFrappeCollection,
   releaseFrappeCollectionSync,
@@ -13,7 +13,8 @@ import { FixtureDbModule } from "./fixtureDb";
 import { RealtimeModule } from "./realtime";
 import { SyncModule } from "./sync";
 import { Status } from "./sync/types";
-import type { DebugMutationEntry } from "./sync/types";
+import type { DebugMutationEntry, SyncCatchUpState } from "./sync/types";
+import { syncOptionsKey } from "./syncOptionsKey";
 import { isBrowser } from "./util";
 
 /**
@@ -72,7 +73,10 @@ export interface UseFrappeCollectionConfig {
 const syncModuleCache = new Map<string, SyncModule>();
 // Fixture-mode SyncModules keyed by the FixtureProvider instance so each unique
 // fixture set gets its own SyncModule (prevents cross-test cache pollution).
-const fixtureSyncModuleCache = new WeakMap<import("./fixtures").FixtureProvider, SyncModule>();
+const fixtureSyncModuleCache = new WeakMap<
+  import("./fixtures").FixtureProvider,
+  Map<string, SyncModule>
+>();
 
 /**
  * Returns the first active SyncModule, or undefined if none exist.
@@ -115,13 +119,19 @@ export function getFrappeSyncModule(
  */
 function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefined {
   if (!isBrowser()) return undefined;
+  const optionsKey = syncOptionsKey(config.syncOptions);
 
   if (config.fixtures) {
-    let sync = fixtureSyncModuleCache.get(config.fixtures);
+    let cache = fixtureSyncModuleCache.get(config.fixtures);
+    if (!cache) {
+      cache = new Map();
+      fixtureSyncModuleCache.set(config.fixtures, cache);
+    }
+    let sync = cache.get(optionsKey);
     if (!sync) {
       const db = new FixtureDbModule(config.fixtures) as unknown as DbModule;
       sync = new SyncModule(db, undefined, config.syncOptions);
-      fixtureSyncModuleCache.set(config.fixtures, sync);
+      cache.set(optionsKey, sync);
     }
     return sync;
   }
@@ -143,17 +153,10 @@ function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefine
     config.socketPort ?? "",
     config.socketBaseURL ?? "",
     config.siteName ?? "",
+    optionsKey,
   ].join("|");
   let sync = syncModuleCache.get(key);
   if (!sync) {
-    // The FIRST config for a baseURL wins for every later consumer (the
-    // module is shared) — surface what it was constructed with so a
-    // missing persistKey/cdcInterval is traceable to the winning mount.
-    console.debug(
-      `[frappe-sync] SyncModule created for ${key} ` +
-        `(persistKey=${config.syncOptions?.persistKey ?? "none"}, ` +
-        `cdcInterval=${config.syncOptions?.cdcInterval ?? "off"})`,
-    );
     const authConfig: AuthConfig | undefined = config.auth
       ? {
           useToken: config.auth.useToken,
@@ -580,6 +583,31 @@ export function useFrappeCollection<TDoc extends object & { name: string; doctyp
 // Connection / realtime hooks
 // ---------------------------------------------------------------------------
 
+export interface UseFrappeCatchUpResult extends SyncCatchUpState {
+  retry: () => Promise<SyncCatchUpState>;
+}
+
+const idleCatchUpState: SyncCatchUpState = Object.freeze({
+  refreshing: false,
+  stale: false,
+  error: null,
+});
+
+/** Connection-level refresh qualification. Retry resolves with state, including failures. */
+export function useFrappeCatchUp(
+  config: UseFrappeCollectionConfig | undefined,
+): UseFrappeCatchUpResult {
+  const sync = getFrappeSyncModule(config);
+  const subscribe = useCallback(
+    (listener: () => void) => sync?.subscribeStore(listener) ?? (() => {}),
+    [sync],
+  );
+  const snapshot = useCallback(() => sync?.getCatchUpState() ?? idleCatchUpState, [sync]);
+  const state = useSyncExternalStore(subscribe, snapshot, () => idleCatchUpState);
+  const retry = useCallback(() => sync?.catchUp() ?? Promise.resolve(idleCatchUpState), [sync]);
+  return useMemo(() => ({ ...state, retry }), [state, retry]);
+}
+
 /** Snapshot returned by {@link useFrappeConnection}. */
 export interface FrappeConnectionState {
   /** Socket connected right now. */
@@ -605,14 +633,14 @@ export function useFrappeConnection(
   config: UseFrappeCollectionConfig | undefined,
 ): FrappeConnectionState {
   const [state, setState] = useState<FrappeConnectionState>(DISCONNECTED_STATE);
+  const syncModule =
+    config && !config.fixtures && config.realtime !== false ? getSyncModule(config) : undefined;
 
   useEffect(() => {
-    if (!config || config.fixtures || config.realtime === false || !isBrowser()) {
+    if (!syncModule) {
       setState(DISCONNECTED_STATE);
       return;
     }
-    const syncModule = getSyncModule(config);
-    if (!syncModule) return;
 
     const read = () => {
       const next = syncModule.getConnectionState();
@@ -625,7 +653,7 @@ export function useFrappeConnection(
     read();
     return syncModule.subscribeStore(read);
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [config?.baseURL, config?.realtime, !!config?.fixtures]);
+  }, [syncModule]);
 
   return config?.realtime === false ? DISCONNECTED_STATE : state;
 }
@@ -646,18 +674,12 @@ export function useFrappeDoctypeEvents(
 ): void {
   const handlerRef = useRef(onEvent);
   handlerRef.current = onEvent;
+  const syncModule =
+    enabled && config && !config.fixtures && config.realtime !== false && doctype
+      ? getSyncModule(config)
+      : undefined;
 
   useEffect(() => {
-    if (
-      !enabled ||
-      !config ||
-      config.fixtures ||
-      config.realtime === false ||
-      !doctype ||
-      !isBrowser()
-    )
-      return;
-    const syncModule = getSyncModule(config);
     if (!syncModule) return;
 
     syncModule.watchDoctype(doctype);
@@ -672,7 +694,7 @@ export function useFrappeDoctypeEvents(
       syncModule.unwatchDoctype(doctype);
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [enabled, config?.baseURL, config?.realtime, !!config?.fixtures, doctype]);
+  }, [syncModule, doctype]);
 }
 
 // ---------------------------------------------------------------------------
@@ -712,17 +734,16 @@ export function useFrappePendingMutations(
 ): UseFrappePendingMutationsResult {
   const [entries, setEntries] = useState<DebugMutationEntry[]>(EMPTY_LEDGER);
   const syncModuleRef = useRef<SyncModule | undefined>(undefined);
+  const syncModule = getFrappeSyncModule(config);
 
   useEffect(() => {
-    if (!config || !isBrowser()) {
+    if (!syncModule) {
       setEntries(EMPTY_LEDGER);
       return;
     }
-    const syncModule = getSyncModule(config);
-    if (!syncModule) return;
     syncModuleRef.current = syncModule;
 
-    let lastSignature = "";
+    let lastSignature: string | undefined;
     const read = () => {
       const next = syncModule.getMutationEntries(doctype);
       const signature = next.map((e) => `${e.id}:${e.status}:${e.retryCount}`).join("|");
@@ -731,9 +752,13 @@ export function useFrappePendingMutations(
       setEntries(next.length === 0 ? EMPTY_LEDGER : next);
     };
     read();
-    return syncModule.subscribeStore(read);
+    const unsubscribe = syncModule.subscribeStore(read);
+    return () => {
+      unsubscribe();
+      syncModuleRef.current = undefined;
+    };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [config?.baseURL, config?.realtime, !!config?.fixtures, doctype]);
+  }, [syncModule, doctype]);
 
   const retry = useCallback(async () => {
     await syncModuleRef.current?.replayPending();
@@ -1039,12 +1064,10 @@ export function useFrappeInfiniteList<TDoc extends object & { name: string; doct
 
   // Stable serialised key for filters so we can depend on it in useEffect
   const filtersKey = JSON.stringify(filters);
+  const syncModule = getFrappeSyncModule(config);
 
   // Subscribe via SyncModule with progressive: true
   useEffect(() => {
-    if (!config || !isBrowser()) return;
-
-    const syncModule = getSyncModule(config);
     if (!syncModule) return;
     syncModuleRef.current = syncModule;
 
@@ -1100,9 +1123,10 @@ export function useFrappeInfiniteList<TDoc extends object & { name: string; doct
         syncModule.unsubscribe(subscriptionIdRef.current);
         subscriptionIdRef.current = undefined;
       }
+      syncModuleRef.current = undefined;
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [config?.baseURL, config?.realtime, config?.auth?.token, doctype, filtersKey, pageSize]);
+  }, [syncModule, config?.auth?.token, doctype, filtersKey, pageSize]);
 
   const loadMore = useCallback(async () => {
     const syncModule = syncModuleRef.current;

package/src/index.ts

@@ -47,6 +47,7 @@ export type { OptimisticRpcContext, OptimisticRpcOptions } from "./optimistic";
 // React hooks for Frappe + TanStack DB
 export {
   useFrappeCollection,
+  useFrappeCatchUp,
   useFrappeConnection,
   useFrappeDoctypeEvents,
   useFrappePendingMutations,
@@ -57,6 +58,7 @@ export {
 } from "./frappeReact";
 export type {
   FrappeConnectionState,
+  UseFrappeCatchUpResult,
   UseFrappeCollectionConfig,
   UseFrappePendingMutationsResult,
   UseInfiniteScrollConfig,
@@ -191,6 +193,7 @@ export type { FrappeDocValue, FrappeDocData, FrappeDoc, ChildTableRow } from "./
 // Sync types with advanced features
 export type {
   SyncOptions,
+  SyncCatchUpState,
   PageBoundaries,
   RehydrationStrategy,
   Mutation,

package/src/sync/catchUp.spec.ts

@@ -0,0 +1,142 @@
+import { afterEach, expect, it, vi } from "vitest";
+import { HttpClient } from "../core/http";
+import { DbModule } from "../db";
+import { SyncModule } from "./index";
+import { BackfillScope, type SyncOptions } from "./types";
+
+const modules: SyncModule[] = [];
+const row = (name: string) => ({ name, doctype: "Task", modified: "2026-09-09T00:00:00Z" });
+function setup(options: SyncOptions = {}) {
+  const transport = vi.fn(async (_url: string) => Response.json({ data: [row("a")] }));
+  vi.stubGlobal("fetch", transport);
+  const sync = new SyncModule(
+    new DbModule(new HttpClient("https://catch-up.test", undefined, { maxRetries: 0 }), {
+      appName: "live.live",
+    }),
+    undefined,
+    options,
+  );
+  modules.push(sync);
+  return { sync, transport };
+}
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  const promise = new Promise<T>((done) => {
+    resolve = done;
+  });
+  return { promise, resolve };
+}
+afterEach(async () => {
+  for (const sync of modules.splice(0)) await sync.dispose();
+  vi.unstubAllGlobals();
+  vi.useRealTimers();
+});
+
+it("refreshes resource snapshots through focus, online and the optional interval", async () => {
+  vi.useFakeTimers();
+  const { sync, transport } = setup({ catchUpStrategy: "snapshot", cdcInterval: 1000 });
+  const { subscriptionId } = await sync.subscribe({ doctype: "Task" });
+  expect(sync.getCatchUpState()).toEqual({ refreshing: false, stale: false, error: null });
+  for (const trigger of ["focus", "online", "interval"]) {
+    transport.mockResolvedValue(Response.json({ data: [row(trigger)] }));
+    if (trigger === "interval") await vi.advanceTimersByTimeAsync(1000);
+    else window.dispatchEvent(new Event(trigger));
+    await vi.waitFor(() =>
+      expect(sync.getDocsForSubscription(subscriptionId)[0]?.name).toBe(trigger),
+    );
+    await vi.waitFor(() => expect(sync.getCatchUpState().refreshing).toBe(false));
+  }
+  expect(
+    transport.mock.calls.every(([url]) => new URL(url).pathname === "/api/resource/Task"),
+  ).toBe(true);
+  expect(transport).toHaveBeenCalledTimes(4);
+});
+
+it("retains rows and stale/error qualification through a deferred retry", async () => {
+  const { sync, transport } = setup({ catchUpStrategy: "snapshot" });
+  const { subscriptionId } = await sync.subscribe({ doctype: "Task" });
+  transport.mockResolvedValue(Response.json({ message: "unavailable" }, { status: 503 }));
+  const failed = await sync.catchUp();
+  expect(failed).toMatchObject({ refreshing: false, stale: true });
+  expect(failed.error).toBeInstanceOf(AggregateError);
+  expect(sync.getDocsForSubscription(subscriptionId)).toEqual([row("a")]);
+  const read = deferred<Response>();
+  transport.mockImplementation(() => read.promise);
+  const retry = sync.catchUp();
+  expect(sync.getCatchUpState()).toMatchObject({
+    refreshing: true,
+    stale: true,
+    error: failed.error,
+  });
+  read.resolve(Response.json({ data: [] }));
+  expect(await retry).toEqual({ refreshing: false, stale: false, error: null });
+  expect(sync.getDocsForSubscription(subscriptionId)).toEqual([]);
+});
+
+it("keeps CDC as default, observes its error and preserves explicit backfill rejection", async () => {
+  const { sync, transport } = setup();
+  const { subscriptionId } = await sync.subscribe({ doctype: "Task" });
+  transport.mockImplementation(async () => Response.json({ message: "no CDC" }, { status: 404 }));
+  const result = await sync.catchUp();
+  expect(result).toMatchObject({ stale: true, error: { status: 404 } });
+  expect(new URL(transport.mock.calls[1][0]).pathname).toBe("/api/method/live.live.api.backfill");
+  await expect(sync.backfill({ scope: BackfillScope.All })).rejects.toMatchObject({ status: 404 });
+  transport.mockImplementation(async () =>
+    Response.json({
+      message: {
+        rows: [row("b")],
+        deleted: [{ name: "a" }],
+        checkpoint: "next",
+        has_more: false,
+      },
+    }),
+  );
+  expect(await sync.catchUp()).toEqual({ refreshing: false, stale: false, error: null });
+  expect(sync.getDocsForSubscription(subscriptionId).map((doc) => doc.name)).toEqual(["b"]);
+  expect(sync.getSubscription(subscriptionId)?.checkpoint).toBe("next");
+});
+
+it("rejects progressive snapshot subscriptions before any fetch", async () => {
+  const { sync, transport } = setup({ catchUpStrategy: "snapshot" });
+  await expect(sync.subscribe({ doctype: "Task", progressive: true })).rejects.toThrow(
+    /progressive/,
+  );
+  expect(transport).not.toHaveBeenCalled();
+});
+
+it("coalesces overlap into at most one trailing request and settles despite more events", async () => {
+  const { sync, transport } = setup({ catchUpStrategy: "snapshot" });
+  await sync.subscribe({ doctype: "Task" });
+  const first = deferred<Response>();
+  const last = deferred<Response>();
+  transport.mockImplementationOnce(() => first.promise).mockImplementationOnce(() => last.promise);
+  const one = sync.catchUp();
+  await vi.waitFor(() => expect(transport).toHaveBeenCalledTimes(2));
+  expect(sync.catchUp()).toBe(one);
+  expect(sync.catchUp()).toBe(one);
+  first.resolve(Response.json({ data: [row("first")] }));
+  await vi.waitFor(() => expect(transport).toHaveBeenCalledTimes(3));
+  for (let i = 0; i < 20; i++) expect(sync.catchUp()).toBe(one);
+  last.resolve(Response.json({ data: [row("last")] }));
+  expect(await one).toEqual({ refreshing: false, stale: false, error: null });
+  expect(transport).toHaveBeenCalledTimes(3);
+});
+
+it.each(["reset", "dispose"])("does not publish a late failed catch-up after %s", async (end) => {
+  const { sync, transport } = setup({ catchUpStrategy: "snapshot" });
+  await sync.subscribe({ doctype: "Task" });
+  const read = deferred<Response>();
+  transport.mockImplementation(() => read.promise);
+  const pending = sync.catchUp();
+  await vi.waitFor(() => expect(transport).toHaveBeenCalledTimes(2));
+  if (end === "reset") sync.resetCache();
+  else await sync.dispose();
+  const afterReset = sync.getCatchUpState();
+  const listener = vi.fn();
+  const unsubscribe = sync.subscribeStore(listener);
+  read.resolve(Response.json({ message: "obsolete" }, { status: 503 }));
+  await pending;
+  expect(sync.getCatchUpState()).toBe(afterReset);
+  expect(listener).not.toHaveBeenCalled();
+  unsubscribe();
+});