@multiplatform.one/frappe 7.10.0 → 7.15.0

package/src/frappeReact.hydration.spec.tsx

@@ -0,0 +1,164 @@
+import { act, Suspense } from "react";
+import { createRoot, hydrateRoot, type Root } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { expect, it, vi } from "vitest";
+
+const runtime = vi.hoisted(() => ({ client: false }));
+const { mockSubscribe, mockUnsubscribe, mockGetDocsForSubscription, storeListeners, docStore } =
+  vi.hoisted(() => {
+    const listeners = new Set<() => void>();
+    const docs = new Map<string, Array<{ name: string; doctype: string; title: string }>>();
+    let subscriptionCounter = 0;
+    return {
+      storeListeners: listeners,
+      docStore: docs,
+      mockSubscribe: vi.fn(async (query: { doctype: string }) => {
+        const subscriptionId = `sub-${++subscriptionCounter}`;
+        docs.set(subscriptionId, [
+          { name: "ws-1", doctype: query.doctype, title: "Workspace One" },
+          { name: "ws-2", doctype: query.doctype, title: "Workspace Two" },
+        ]);
+        return { subscriptionId, rows: docs.get(subscriptionId), checkpoint: "t0" };
+      }),
+      mockUnsubscribe: vi.fn((subscriptionId: string) => {
+        docs.delete(subscriptionId);
+      }),
+      mockGetDocsForSubscription: vi.fn((subscriptionId: string) => {
+        return docs.get(subscriptionId) ?? [];
+      }),
+    };
+  });
+
+vi.mock("./sync", () => ({
+  SyncModule: class {
+    subscribe = mockSubscribe;
+    unsubscribe = mockUnsubscribe;
+    getDocsForSubscription = mockGetDocsForSubscription;
+    subscribeStore = (listener: () => void) => {
+      storeListeners.add(listener);
+      return () => storeListeners.delete(listener);
+    };
+    mutate = vi.fn();
+  },
+}));
+vi.mock("./realtime", () => ({ RealtimeModule: class {} }));
+vi.mock("./core/http", () => ({ HttpClient: class {} }));
+vi.mock("./db", () => ({ DbModule: class {} }));
+vi.mock("./util", () => ({ isBrowser: () => runtime.client }));
+vi.mock("./fixtureDb", () => ({ FixtureDbModule: class {} }));
+
+import { useFrappeCollection } from "./frappeReact";
+import { useLiveQuery } from "./useLiveQuery";
+
+type Doc = { name: string; doctype: string; title: string };
+
+it.each([false, true])(
+  "hydrates a cached collection after an earlier reader (delayed=%s)",
+  async (delayed) => {
+    const config = { baseURL: `https://neutral-${delayed}.invalid`, realtime: false };
+    const collections = new Set<NonNullable<ReturnType<typeof useFrappeCollection<Doc>>>>();
+    let release: () => void = () => {};
+    let wait = false;
+    const pending = new Promise<void>((resolve) => {
+      release = resolve;
+    });
+    function Reader({ late = false, enabled = true }: { late?: boolean; enabled?: boolean }) {
+      if (late && wait) throw pending;
+      const collection = useFrappeCollection<Doc>(enabled ? config : undefined, "Workspace");
+      if (collection) collections.add(collection);
+      const result = useLiveQuery(
+        (q) => (collection ? q.from({ item: collection }) : null),
+        [collection],
+      );
+      return (
+        <div data-result={late ? "late" : "early"}>
+          {!enabled
+            ? "Disabled"
+            : !collection || result.isLoading
+              ? "Loading"
+              : result.data?.map((row) => row.title).join(",")}
+        </div>
+      );
+    }
+    const view = (
+      <Suspense fallback={<span>Boundary pending</span>}>
+        <Reader late />
+      </Suspense>
+    );
+    runtime.client = false;
+    const host = document.createElement("div");
+    host.innerHTML = renderToString(view);
+    expect(host.textContent).toBe("Loading");
+    const serverNode = host.querySelector("[data-result]");
+    document.body.append(host);
+    const earlyHost = document.createElement("div");
+    document.body.append(earlyHost);
+    runtime.client = true;
+    const errors = vi.fn();
+    const consoleError = vi.spyOn(console, "error").mockImplementation(() => {});
+    let early: Root | undefined;
+    let late: Root | undefined;
+    try {
+      await act(async () => {
+        early = createRoot(earlyHost);
+        early.render(<Reader />);
+      });
+      await vi.waitFor(() => expect(earlyHost.textContent).toContain("Workspace One"));
+      const warm = [...collections][0];
+      expect(warm.status).toBe("ready");
+      wait = delayed;
+      await act(async () => {
+        late = hydrateRoot(host, view, { onRecoverableError: errors });
+      });
+      if (delayed) {
+        expect(host.querySelector("[data-result]")).toBe(serverNode);
+        expect(host.textContent).toBe("Loading");
+        await act(async () => {
+          wait = false;
+          release();
+        });
+      }
+      await vi.waitFor(() => expect(host.textContent).toContain("Workspace One"));
+      expect(errors.mock.calls.map(([e]) => String(e))).toEqual([]);
+      expect(
+        consoleError.mock.calls.filter((args) => /hydration|did not match/i.test(args.join(" "))),
+      ).toEqual([]);
+      expect(host.querySelector("[data-result]")).toBe(serverNode);
+      expect(collections.size).toBe(1);
+      await act(async () => {
+        for (const docs of docStore.values())
+          docs.push({ name: "ws-3", doctype: "Workspace", title: "Workspace Three" });
+        for (const listener of storeListeners) listener();
+      });
+      await vi.waitFor(() => expect(host.textContent).toContain("Workspace Three"));
+      await act(async () => late!.render(<Reader enabled={false} />));
+      expect(host.textContent).toBe("Disabled");
+      // A fresh boundary must use its own SSR snapshot after the shared cache
+      // and an earlier boundary have both committed updates.
+      await act(async () => late!.unmount());
+      runtime.client = false;
+      host.innerHTML = renderToString(view);
+      expect(host.textContent).toBe("Loading");
+      const freshServerNode = host.querySelector("[data-result]");
+      runtime.client = true;
+      await act(async () => {
+        late = hydrateRoot(host, view, { onRecoverableError: errors });
+      });
+      await vi.waitFor(() => expect(host.textContent).toContain("Workspace Three"));
+      expect(host.querySelector("[data-result]")).toBe(freshServerNode);
+      expect(errors).not.toHaveBeenCalled();
+    } finally {
+      await act(async () => {
+        early?.unmount();
+        late?.unmount();
+      });
+      host.remove();
+      earlyHost.remove();
+      consoleError.mockRestore();
+    }
+    await vi.waitFor(
+      () => expect([...collections].every((c) => c.subscriberCount === 0)).toBe(true),
+      { timeout: 10000 },
+    );
+  },
+);

package/src/frappeReact.spec.ts

@@ -56,6 +56,7 @@ vi.mock("./fixtureDb", () => ({ FixtureDbModule: class {} }));
 
 import { isBrowser } from "./util";
 import { Order } from "./sync/types";
+import type { FixtureProvider } from "./fixtures";
 import type { UseFrappeCollectionConfig, UseFrappeInfiniteListConfig } from "./frappeReact";
 import {
   __getActiveSyncModule,
@@ -341,6 +342,61 @@ describe("useFrappeCollection", () => {
     expect(active).toBeDefined();
   });
 
+  it("__getActiveSyncModule returns the SyncModule when the only one was created in fixture mode", async () => {
+    vi.resetModules();
+    const fresh = await import("./frappeReact");
+    expect(fresh.__getActiveSyncModule()).toBeUndefined();
+    const fixtures = {} as FixtureProvider;
+    renderHook(() => fresh.useFrappeCollection({ fixtures }, "Task"));
+    const active = fresh.__getActiveSyncModule();
+    expect(active).toBeDefined();
+    expect(active).toBe(mockCreateFrappeCollection.mock.calls.at(-1)?.[1].sync);
+  });
+
+  it("__getActiveSyncModule prefers a fixture-mode SyncModule created after live ones", () => {
+    renderHook(() =>
+      useFrappeCollection({ baseURL: `https://before-fixture-${testNum}.example.com` }, "Task"),
+    );
+    const fixtures = {} as FixtureProvider;
+    renderHook(() => useFrappeCollection({ fixtures }, "Task"));
+    const fixtureSync = mockCreateFrappeCollection.mock.calls.at(-1)?.[1].sync;
+    expect(fixtureSync).toBeDefined();
+    expect(__getActiveSyncModule()).toBe(fixtureSync);
+  });
+
+  it("__getActiveSyncModule falls back to the live cache once the latest SyncModule is collected", async () => {
+    vi.resetModules();
+    const fresh = await import("./frappeReact");
+    const live = fresh.getFrappeSyncModule({ baseURL: `https://collected-${testNum}.example.com` });
+    vi.stubGlobal(
+      "WeakRef",
+      class {
+        deref() {
+          return undefined;
+        }
+      },
+    );
+    try {
+      expect(fresh.getFrappeSyncModule({ fixtures: {} as FixtureProvider })).toBeDefined();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+    expect(live).toBeDefined();
+    expect(fresh.__getActiveSyncModule()).toBe(live);
+  });
+
+  it("builds fixture-mode SyncModules on runtimes without WeakRef", async () => {
+    vi.resetModules();
+    const fresh = await import("./frappeReact");
+    vi.stubGlobal("WeakRef", undefined);
+    try {
+      expect(fresh.getFrappeSyncModule({ fixtures: {} as FixtureProvider })).toBeDefined();
+    } finally {
+      vi.unstubAllGlobals();
+    }
+    expect(fresh.__getActiveSyncModule()).toBeUndefined();
+  });
+
   it("passes socketOptions through to the RealtimeModule", () => {
     const socketOptions = { transports: ["polling", "websocket"] };
     const config: UseFrappeCollectionConfig = {

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,13 +73,29 @@ 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>
+>();
+// A WeakMap can't be enumerated, so this slot is how the accessor below sees
+// a fixture-mode module. WeakRef rather than an explicit clear: nothing
+// refcounts SyncModules, and a strong slot would pin a discarded fixture
+// set's module (and its FixtureProvider) and hand devtools a dead one.
+// Runtimes without WeakRef never fill the slot and keep the live-cache scan.
+let latestSyncModule: WeakRef<SyncModule> | undefined;
+
+function rememberLatestSyncModule(sync: SyncModule): void {
+  if (typeof WeakRef === "function") latestSyncModule = new WeakRef(sync);
+}
 
 /**
- * Returns the first active SyncModule, or undefined if none exist.
+ * Returns the most recently constructed SyncModule (live or fixture mode),
+ * falling back to the first live one, or undefined if none exist.
  * Intended for devtools integration — not part of the public API.
  */
 export function __getActiveSyncModule(): SyncModule | undefined {
+  const latest = latestSyncModule?.deref();
+  if (latest) return latest;
   for (const sync of syncModuleCache.values()) return sync;
   return undefined;
 }
@@ -115,13 +132,20 @@ 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);
+      rememberLatestSyncModule(sync);
     }
     return sync;
   }
@@ -143,17 +167,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,
@@ -182,6 +199,7 @@ function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefine
       config.syncOptions,
     );
     syncModuleCache.set(key, sync);
+    rememberLatestSyncModule(sync);
   }
   return sync;
 }
@@ -462,6 +480,10 @@ function cleanupEntryCollectionWhenIdle(entry: SharedCollectionEntry): void {
   entry.gcTimer = setTimeout(tick, SHARED_COLLECTION_GC_MS);
 }
 
+const subscribeHydration = () => () => {};
+const clientCollectionAvailable = () => true;
+const serverCollectionAvailable = () => false;
+
 /**
  * React hook that returns a TanStack DB Collection backed by a Frappe doctype.
  *
@@ -485,7 +507,7 @@ function cleanupEntryCollectionWhenIdle(entry: SharedCollectionEntry): void {
  * @param config - Connection configuration (baseURL, auth)
  * @param doctype - The Frappe doctype name
  * @param options - Optional collection configuration (fields, filters, etc.)
- * @returns A stable TanStack DB Collection instance, or undefined if config is not provided
+ * @returns A stable collection, or undefined during SSR/hydration or without config
  *
  * @example
  * ```tsx
@@ -512,6 +534,13 @@ export function useFrappeCollection<TDoc extends object & { name: string; doctyp
   doctype: string,
   options?: Omit<FrappeCollectionOptionsConfig<TDoc>, "sync">,
 ): Collection<TDoc, string> | undefined {
+  // Each hydrating boundary must match SSR even if an earlier reader has
+  // already filled the shared cache. Client-only and native mounts read true.
+  const collectionAvailable = useSyncExternalStore(
+    subscribeHydration,
+    clientCollectionAvailable,
+    serverCollectionAvailable,
+  );
   // Consumers pass inline onSyncError closures; keep one stable wrapper per
   // hook instance so the entry's handler registry doesn't churn every render.
   const errorHandlerRef = useRef(options?.onSyncError);
@@ -523,16 +552,16 @@ export function useFrappeCollection<TDoc extends object & { name: string; doctyp
   const [, setStaleEntryBump] = useState(0);
 
   // Resolve the shared entry during render so the collection is available on
-  // the FIRST render (same contract as before the cache). An empty doctype is
+  // the first client-only/native render and after hydration. An empty doctype is
   // treated like an undefined config: consumers such as DynamicLink pass ""
   // before a doctype is chosen, and syncing doctype "" fires a bogus
   // `/api/v2/document/` 404. During SSR, getSyncModule returns undefined —
   // the component renders a loading state and the client hydration pass
-  // creates the real collection.
+  // exposes the real collection after this boundary hydrates.
   let cache: Map<string, SharedCollectionEntry> | undefined;
   let key = "";
   let entry: SharedCollectionEntry | undefined;
-  if (config && doctype) {
+  if (collectionAvailable && config && doctype) {
     const syncModule = getSyncModule(config);
     if (syncModule) {
       key = collectionOptionsKey(doctype, options);
@@ -580,6 +609,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 +659,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 +679,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 +700,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 +720,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 +760,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 +778,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 +1090,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 +1149,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

@@ -8,6 +8,13 @@
 // Core Frappe functionality
 export { FrappeApp } from "./frappeApp";
 export type { FrappeConfig } from "./frappeApp";
+export {
+  loadDoc,
+  loadDocList,
+  type FrappeLoaderRequest,
+  type LoadDocListOptions,
+  type LoadDocOptions,
+} from "./serverLoaders";
 export { AuthModule } from "./auth";
 export { CallModule } from "./call";
 export { DbModule } from "./db";
@@ -47,6 +54,7 @@ export type { OptimisticRpcContext, OptimisticRpcOptions } from "./optimistic";
 // React hooks for Frappe + TanStack DB
 export {
   useFrappeCollection,
+  useFrappeCatchUp,
   useFrappeConnection,
   useFrappeDoctypeEvents,
   useFrappePendingMutations,
@@ -57,6 +65,7 @@ export {
 } from "./frappeReact";
 export type {
   FrappeConnectionState,
+  UseFrappeCatchUpResult,
   UseFrappeCollectionConfig,
   UseFrappePendingMutationsResult,
   UseInfiniteScrollConfig,
@@ -172,11 +181,15 @@ export {
   useDocTypeSearch,
   parseDependsOn,
   parseFormLayout,
+  stockFieldTypes,
+  customFieldTypes,
+  frappeFieldTypes,
 } from "./doctype";
 export type {
   DocTypeMeta,
   DocTypeField,
   DocTypePermission,
+  DocTypeLink,
   FormSection,
   FormColumn,
   FrappeFieldType,
@@ -191,6 +204,7 @@ export type { FrappeDocValue, FrappeDocData, FrappeDoc, ChildTableRow } from "./
 // Sync types with advanced features
 export type {
   SyncOptions,
+  SyncCatchUpState,
   PageBoundaries,
   RehydrationStrategy,
   Mutation,

package/src/serverLoaders.ts

@@ -0,0 +1,77 @@
+import type { ListOptions } from "./core/types";
+import { FrappeApp } from "./frappeApp";
+
+/** The slice of a route loader's `Request` the server reads: its cookie header. */
+export interface FrappeLoaderRequest {
+  headers?: { get(name: string): string | null } | null;
+}
+
+interface LoaderTarget {
+  /** Bench address the server dials (not the browser's). */
+  baseURL: string;
+  doctype: string;
+  /**
+   * The incoming request. Its cookie rides along so the server reads with
+   * the visitor's session. Absent (a loader run in the browser), nothing is
+   * fetched: the live collection reads instead.
+   */
+  request?: FrappeLoaderRequest | null;
+}
+
+export type LoadDocListOptions = LoaderTarget &
+  Pick<ListOptions, "fields" | "filters" | "orderBy" | "limit">;
+
+export interface LoadDocOptions extends LoaderTarget {
+  name: string;
+}
+
+function serverApp(baseURL: string, request: FrappeLoaderRequest): FrappeApp {
+  const cookie = request.headers?.get("cookie") ?? undefined;
+  return new FrappeApp(baseURL, cookie ? { cookie } : {});
+}
+
+function isNotFound(error: unknown): boolean {
+  return (
+    typeof error === "object" && error !== null && (error as { status?: number }).status === 404
+  );
+}
+
+/**
+ * Rows for a server-rendered list, read with the query the page's live
+ * collection will use: hand both the same fields, filters, order and limit,
+ * or the collection's first sync replaces the rendered page with a
+ * different one (a 20-row default page shrank a 21-row list, MPO-322).
+ * A failed read renders an empty page rather than failing the route.
+ */
+export async function loadDocList<TDoc extends { name: string; doctype: string }>({
+  baseURL,
+  doctype,
+  request,
+  ...query
+}: LoadDocListOptions): Promise<TDoc[]> {
+  if (!request) return [];
+  try {
+    const rows = await serverApp(baseURL, request).db().getDocList<TDoc>(doctype, query);
+    return rows.map((row) => ({ ...row, doctype }) as TDoc);
+  } catch (error) {
+    console.error(`[loadDocList] ${doctype}:`, error);
+    return [];
+  }
+}
+
+/** One document, child tables included, for a server-rendered detail page; null when missing. */
+export async function loadDoc<TDoc extends { name: string; doctype: string }>({
+  baseURL,
+  doctype,
+  name,
+  request,
+}: LoadDocOptions): Promise<TDoc | null> {
+  if (!request || !name) return null;
+  try {
+    const doc = await serverApp(baseURL, request).db().getDoc<TDoc>(doctype, name);
+    return doc ? ({ ...doc, doctype } as TDoc) : null;
+  } catch (error) {
+    if (!isNotFound(error)) console.error(`[loadDoc] ${doctype}/${name}:`, error);
+    return null;
+  }
+}