@multiplatform.one/frappe 7.7.4 → 7.8.0

package/src/collection.ts

@@ -3,7 +3,7 @@ import { createCollection } from "@tanstack/db";
 import type { FrappeDocData } from "./common/types";
 import type { FixtureProvider } from "./fixtures";
 import type { SyncModule } from "./sync";
-import { Operation } from "./sync/types";
+import { defaultPageLength, Operation } from "./sync/types";
 import type { SubscriptionQuery } from "./sync/types";
 
 /**
@@ -24,7 +24,11 @@ export interface FrappeCollectionOptionsConfig<
   id?: string;
   /** Order-by configuration */
   orderBy?: SubscriptionQuery["orderBy"];
-  /** Limit for the subscription */
+  /**
+   * Rows to read. Omitting it reads {@link defaultPageLength} (20) rows in
+   * BOTH fixture mode and against a live bench. Pass `limit: 0` for every
+   * row, which also means the same on both.
+   */
   limit?: number;
   /**
    * Called when the initial subscription fetch fails (network down,
@@ -74,6 +78,13 @@ export function releaseFrappeCollectionSync(collection: object): boolean {
  * This follows TanStack DB's collection options creator pattern (Pattern B),
  * where mutation handlers are built-in and delegate to SyncModule.
  *
+ * ROW LIMIT. A collection created without `limit` reads
+ * {@link defaultPageLength} (20) rows, and reads the same 20 in fixture mode
+ * as it does against a live bench. Frappe clamps a request with no
+ * `limit_page_length` to 20 while a fixture provider returns every row, so
+ * the limit is now always sent rather than left off. Pass `limit: 0` for
+ * every row.
+ *
  * @typeParam TDoc - The Frappe document type
  * @param doctype - The Frappe doctype name (e.g. "ToDo", "Pokemon")
  * @param config - Configuration for the collection
@@ -249,6 +260,8 @@ export function frappeCollectionOptions<TDoc extends object & { name: string; do
  * Creates a TanStack DB Collection backed by a Frappe doctype via SyncModule.
  *
  * Convenience wrapper that calls `createCollection(frappeCollectionOptions(...))`.
+ * Without `limit` it reads {@link defaultPageLength} (20) rows in fixture mode
+ * and against a live bench alike; `limit: 0` reads every row.
  *
  * @typeParam TDoc - The Frappe document type
  * @param doctype - The Frappe doctype name
@@ -295,7 +308,10 @@ export interface FixtureCollectionOptionsConfig<
   id?: string;
   /** Order-by configuration */
   orderBy?: SubscriptionQuery["orderBy"];
-  /** Limit for the query */
+  /**
+   * Rows to read. Omitting it reads {@link defaultPageLength} (20) rows, the
+   * same as against a live bench. Pass `limit: 0` for every row.
+   */
   limit?: number;
   /** Offset for pagination */
   limitStart?: number;
@@ -304,6 +320,10 @@ export interface FixtureCollectionOptionsConfig<
 /**
  * Creates TanStack DB collection options wired to a FixtureProvider.
  * Used when config.fixtures is set (e.g. in tests or Storybook).
+ *
+ * ROW LIMIT. Without `limit` this reads {@link defaultPageLength} (20) rows,
+ * the same count a live bench returns for a request with no
+ * `limit_page_length`. Pass `limit: 0` for every row.
  */
 export function fixtureCollectionOptions<TDoc extends object & { name: string; doctype: string }>(
   doctype: string,
@@ -334,7 +354,10 @@ export function fixtureCollectionOptions<TDoc extends object & { name: string; d
           filters: filters as Partial<TDoc> | Array<[string, string, any]> | undefined,
           orderBy: orderByForFixture,
           limitStart,
-          limit,
+          // Same page length the bench applies to a request that carries no
+          // limit_page_length, so a no-limit collection reads the same rows
+          // here as it does in production.
+          limit: limit ?? defaultPageLength,
         });
 
         if (cancelled) return;
@@ -393,6 +416,8 @@ export function fixtureCollectionOptions<TDoc extends object & { name: string; d
 /**
  * Creates a TanStack DB Collection backed by a FixtureProvider.
  * Used when config.fixtures is set (e.g. in tests or Storybook).
+ * Without `limit` it reads {@link defaultPageLength} (20) rows, matching a
+ * live bench; `limit: 0` reads every row.
  */
 export function createFixtureCollection<TDoc extends object & { name: string; doctype: string }>(
   doctype: string,

package/src/collectionLimitParity.spec.ts

@@ -0,0 +1,135 @@
+/**
+ * A collection created with no `limit` must return the same rows in fixture
+ * mode as it does against a live bench (MPO-238). Frappe clamps a request
+ * that carries no `limit_page_length` to 20 rows while a fixture provider
+ * slices only when asked, so development read every row, production read 20,
+ * and neither one errored to say so.
+ */
+import { describe, expect, it, vi } from "vitest";
+import { fixtureCollectionOptions } from "./collection";
+import type { DbModule } from "./db";
+import { FixtureDbModule } from "./fixtureDb";
+import { InMemoryFixtureProvider } from "./fixtures";
+import { NormalizedCache } from "./sync/normalizedCache";
+import { SubscriptionManager } from "./sync/subscriptionManager";
+import { defaultPageLength } from "./sync/types";
+import type { SubscriptionQuery } from "./sync/types";
+
+const rowCount = 50;
+
+interface Todo {
+  name: string;
+  doctype: string;
+  description: string;
+  modified: string;
+}
+
+function todos(): Todo[] {
+  return Array.from({ length: rowCount }, (_, index) => ({
+    name: `TODO-${String(index + 1).padStart(4, "0")}`,
+    doctype: "ToDo",
+    description: `row ${index + 1}`,
+    modified: `2026-01-01T00:${String(index).padStart(2, "0")}:00`,
+  }));
+}
+
+/**
+ * Stands in for a live bench: /api/resource pages a request with no
+ * `limit_page_length` at 20 rows and reads `limit_page_length=0` as every
+ * row. Nothing else about the response differs from fixture mode, so any
+ * divergence these specs catch is the page length alone.
+ */
+function benchDb(): DbModule {
+  const rows = todos();
+  return {
+    getDoc: async (_doctype: string, name: string) => rows.find((row) => row.name === name) ?? null,
+    getDocList: async (_doctype: string, options: { limit?: number; limitStart?: number } = {}) => {
+      const start = options.limitStart ?? 0;
+      const pageLength = options.limit ?? 20;
+      return rows.slice(start, pageLength === 0 ? undefined : start + pageLength);
+    },
+  } as unknown as DbModule;
+}
+
+function fixtureDb(): DbModule {
+  return new FixtureDbModule(new InMemoryFixtureProvider({ ToDo: todos() })) as unknown as DbModule;
+}
+
+async function subscribedNames(db: DbModule, query: SubscriptionQuery): Promise<string[]> {
+  const manager = new SubscriptionManager(db, new NormalizedCache());
+  const result = await manager.subscribe(query);
+  return result.rows.map((row) => String(row.name));
+}
+
+async function fixtureCollectionNames(limit?: number): Promise<string[]> {
+  const options = fixtureCollectionOptions<Todo>("ToDo", {
+    fixtures: new InMemoryFixtureProvider({ ToDo: todos() }),
+    ...(limit === undefined ? {} : { limit }),
+  });
+  const written: string[] = [];
+  const cleanup = options.sync!.sync({
+    begin: vi.fn(),
+    write: (message: any) => {
+      written.push(message.value.name);
+    },
+    commit: vi.fn(),
+    markReady: vi.fn(),
+    truncate: vi.fn(),
+    collection: {} as any,
+  } as any);
+  await new Promise((resolve) => setTimeout(resolve, 10));
+  if (typeof cleanup === "function") cleanup();
+  return written;
+}
+
+describe("collection row limit parity", () => {
+  it("reads the default page length with no limit, on both paths", async () => {
+    const query: SubscriptionQuery = { doctype: "ToDo" };
+
+    const live = await subscribedNames(benchDb(), query);
+    const fixture = await subscribedNames(fixtureDb(), query);
+
+    expect(fixture).toEqual(live);
+    expect(fixture).toHaveLength(defaultPageLength);
+    expect(fixture.at(-1)).toBe("TODO-0020");
+  });
+
+  it("reads every row with limit 0, on both paths", async () => {
+    const query: SubscriptionQuery = { doctype: "ToDo", limit: 0 };
+
+    const live = await subscribedNames(benchDb(), query);
+    const fixture = await subscribedNames(fixtureDb(), query);
+
+    expect(fixture).toEqual(live);
+    expect(fixture).toHaveLength(rowCount);
+  });
+
+  it("reads an explicit limit past the bench default, on both paths", async () => {
+    const query: SubscriptionQuery = { doctype: "ToDo", limit: 35 };
+
+    const live = await subscribedNames(benchDb(), query);
+    const fixture = await subscribedNames(fixtureDb(), query);
+
+    expect(fixture).toEqual(live);
+    expect(fixture).toHaveLength(35);
+  });
+
+  it("offsets by limitStart with no limit, on both paths", async () => {
+    const query: SubscriptionQuery = { doctype: "ToDo", limitStart: 20 };
+
+    const live = await subscribedNames(benchDb(), query);
+    const fixture = await subscribedNames(fixtureDb(), query);
+
+    expect(fixture).toEqual(live);
+    expect(fixture[0]).toBe("TODO-0021");
+    expect(fixture).toHaveLength(defaultPageLength);
+  });
+
+  it("gives the direct fixture collection the same default page length", async () => {
+    expect(await fixtureCollectionNames()).toHaveLength(defaultPageLength);
+  });
+
+  it("gives the direct fixture collection every row with limit 0", async () => {
+    expect(await fixtureCollectionNames(0)).toHaveLength(rowCount);
+  });
+});

package/src/devtools/FrappeDevtoolsPanel.spec.tsx

@@ -131,7 +131,9 @@ describe("FrappeDevtoolsPanel reads __debug()", () => {
     );
     expect(stub.module.__debug).toHaveBeenCalled();
     expect(container.textContent).toContain("ToDo");
+    expect(container.textContent).toContain("8 docs");
     expect(container.textContent).toContain("Note");
+    expect(container.textContent).toContain("3 docs");
   });
 
   it("an empty snapshot still paints the shell, not a blank div", () => {
@@ -262,8 +264,8 @@ describe("FrappeDevtoolsPanel theme prop", () => {
     );
     const darkBg = (dark.container.firstElementChild as HTMLElement).style.backgroundColor;
     expect(lightBg).not.toBe(darkBg);
-    expect(lightBg).toBeTruthy();
-    expect(darkBg).toBeTruthy();
+    expect(lightBg).toBe(themes.light.bg);
+    expect(darkBg).toBe(themes.dark.bg);
     // The panel owns its own palette (devtools/theme.ts); it never reads the app knobs.
     expect(Object.keys(themes)).toEqual(["light", "dark"]);
   });

package/src/doctype.ts

@@ -372,7 +372,8 @@ export function parseFormLayout(fields: DocTypeField[]): FormSection[] {
 // Internal helpers
 // ---------------------------------------------------------------------------
 
-function createHttpClient(config: FrappeConnectionConfig): HttpClient {
+function createHttpClient(config: FrappeConnectionConfig): HttpClient | undefined {
+  if (!config.baseURL) return undefined;
   const authConfig: AuthConfig | undefined = config.auth
     ? {
         useToken: config.auth.useToken,
@@ -474,6 +475,27 @@ function parseRawDocTypeMeta(raw: RawDocTypeResponse): DocTypeMeta {
   };
 }
 
+/**
+ * Cache identity for a connection. A fixtures-only connection has no
+ * baseURL, so it is keyed by its FixtureProvider instance instead — two
+ * corpora must not share one cached DocType (the cross-test pollution the
+ * SyncModule cache already avoids the same way).
+ */
+const fixtureConnectionIds = new WeakMap<object, string>();
+let nextFixtureConnectionId = 0;
+
+function connectionKey(config: FrappeConnectionConfig): string {
+  if (config.baseURL) return config.baseURL;
+  const fixtures = config.fixtures;
+  if (!fixtures) return "";
+  let id = fixtureConnectionIds.get(fixtures);
+  if (!id) {
+    id = `fixtures#${++nextFixtureConnectionId}`;
+    fixtureConnectionIds.set(fixtures, id);
+  }
+  return id;
+}
+
 /**
  * Setup pattern for a stable HttpClient ref, following the same pattern
  * used in `useDebouncedSearch` for DbModule.
@@ -538,7 +560,7 @@ export function useDocTypeMeta(
   error: Error | null;
   refetch: () => void;
 } {
-  const cacheKey = config ? `${config.baseURL}:${doctype}` : "";
+  const cacheKey = config ? `${connectionKey(config)}:${doctype}` : "";
 
   const [meta, setMeta] = useState<DocTypeMeta | undefined>(() =>
     cacheKey ? metaCache.get(cacheKey) : undefined,
@@ -571,12 +593,14 @@ export function useDocTypeMeta(
       return;
     }
 
-    const key = `${config.baseURL}:${doctype}`;
+    const key = `${connectionKey(config)}:${doctype}`;
     // Already have cached data (synchronized during render)
     if (metaCache.has(key)) return;
 
     const http = httpRef.current;
-    if (!http) return;
+    // No client AND no corpus: nothing can answer, so park rather than
+    // dial `undefined` (a fixtures-only host has no baseURL by design).
+    if (!http && !config.fixtures) return;
 
     let cancelled = false;
     setIsLoading(true);
@@ -596,6 +620,14 @@ export function useDocTypeMeta(
         let raw = fromFixtures?.fields ? fromFixtures : undefined;
 
         if (!raw) {
+          if (!http) {
+            // Fixtures-only host: there is no server behind the corpus, so a
+            // missing DocType entry is the honest end of the road.
+            throw new Error(
+              `DocType "${doctype}" is not in the fixture corpus and no baseURL is configured`,
+            );
+          }
+
           // `getdoctype` is the whitelisted RPC the Desk itself loads form
           // metadata with, and every logged-in user may call it. Reading
           // `/api/resource/DocType/<name>` instead asks for the DocType
@@ -612,20 +644,20 @@ export function useDocTypeMeta(
           // docs[0] is the requested doctype; docs[1..] are its child tables.
           const docs = response.payload?.docs;
           raw = docs?.find((doc) => doc?.name === doctype) ?? docs?.[0];
-        }
 
-        if (!raw) {
-          // Sites that expose the REST API without the desk leave the RPC
-          // above unregistered, so it answers with no `docs`. The document
-          // route still serves meta there, and such a site's API clients are
-          // typically System Managers, who may read it.
-          const rest = await http.get<{ data?: RawDocTypeResponse }>(
-            `/api/resource/DocType/${encodeURIComponent(doctype)}`,
-          );
+          if (!raw) {
+            // Sites that expose the REST API without the desk leave the RPC
+            // above unregistered, so it answers with no `docs`. The document
+            // route still serves meta there, and such a site's API clients are
+            // typically System Managers, who may read it.
+            const rest = await http.get<{ data?: RawDocTypeResponse }>(
+              `/api/resource/DocType/${encodeURIComponent(doctype)}`,
+            );
 
-          if (cancelled) return;
+            if (cancelled) return;
 
-          raw = rest.payload?.data;
+            raw = rest.payload?.data;
+          }
         }
 
         if (!raw) {

package/src/frappeReact.spec.ts

@@ -1073,3 +1073,18 @@ describe("useInfiniteScroll", () => {
     expect(ioInstances[0].disconnect).toHaveBeenCalled();
   });
 });
+
+describe("explicit HTTP-only realtime mode", () => {
+  it("isolates the disabled engine while default and true share realtime", async () => {
+    const { getFrappeSyncModule } = await import("./frappeReact");
+    mockRealtimeCtor.mockClear();
+    const baseURL = "https://realtime-mode-cache.test";
+    const http = getFrappeSyncModule({ baseURL, realtime: false });
+    expect(mockRealtimeCtor).not.toHaveBeenCalled();
+    const enabled = getFrappeSyncModule({ baseURL });
+    expect(mockRealtimeCtor).toHaveBeenCalledTimes(1);
+    expect(getFrappeSyncModule({ baseURL, realtime: true })).toBe(enabled);
+    expect(getFrappeSyncModule({ baseURL, realtime: false })).toBe(http);
+    expect(http).not.toBe(enabled);
+  });
+});

package/src/frappeReact.ts

@@ -20,8 +20,14 @@ import { isBrowser } from "./util";
  * Configuration for creating a Frappe collection with connection details.
  */
 export interface UseFrappeCollectionConfig {
-  /** The base URL of the Frappe server */
-  baseURL: string;
+  /**
+   * The base URL of the Frappe server. Required unless `fixtures` is set —
+   * a fixture corpus is the whole data source and nothing is ever dialled,
+   * so a fixtures-only host legitimately has no server to name.
+   */
+  baseURL?: string;
+  /** False keeps HTTP sync without constructing a realtime transport. Defaults to true. */
+  realtime?: boolean;
   /**
    * Override the port used for the Socket.IO realtime connection.
    * In dev, set to `FRAPPE_SOCKETIO_PORT` (e.g. 9000).  Omit in production
@@ -120,6 +126,11 @@ function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefine
     return sync;
   }
 
+  // No fixtures and no baseURL: there is nothing to dial. Same contract as
+  // SSR above — consumers render their loading/empty state instead of
+  // constructing an HttpClient against `undefined`.
+  if (!config.baseURL) return undefined;
+
   // Key on the full socket target, not just baseURL: socketPort /
   // socketBaseURL / siteName all change where (or how) the realtime socket
   // dials, so configs that differ in them must not share a SyncModule —
@@ -128,6 +139,7 @@ function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefine
   // (identical fields → identical key).
   const key = [
     config.baseURL,
+    config.realtime === false ? "http" : "realtime",
     config.socketPort ?? "",
     config.socketBaseURL ?? "",
     config.siteName ?? "",
@@ -164,7 +176,11 @@ function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefine
       auth: authConfig,
       socketOptions: config.socketOptions,
     };
-    sync = new SyncModule(db, new RealtimeModule(realtimeConfig), config.syncOptions);
+    sync = new SyncModule(
+      db,
+      config.realtime === false ? undefined : new RealtimeModule(realtimeConfig),
+      config.syncOptions,
+    );
     syncModuleCache.set(key, sync);
   }
   return sync;
@@ -591,7 +607,10 @@ export function useFrappeConnection(
   const [state, setState] = useState<FrappeConnectionState>(DISCONNECTED_STATE);
 
   useEffect(() => {
-    if (!config || config.fixtures || !isBrowser()) return;
+    if (!config || config.fixtures || config.realtime === false || !isBrowser()) {
+      setState(DISCONNECTED_STATE);
+      return;
+    }
     const syncModule = getSyncModule(config);
     if (!syncModule) return;
 
@@ -606,9 +625,9 @@ export function useFrappeConnection(
     read();
     return syncModule.subscribeStore(read);
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [config?.baseURL, !!config?.fixtures]);
+  }, [config?.baseURL, config?.realtime, !!config?.fixtures]);
 
-  return state;
+  return config?.realtime === false ? DISCONNECTED_STATE : state;
 }
 
 /**
@@ -629,7 +648,15 @@ export function useFrappeDoctypeEvents(
   handlerRef.current = onEvent;
 
   useEffect(() => {
-    if (!enabled || !config || config.fixtures || !doctype || !isBrowser()) return;
+    if (
+      !enabled ||
+      !config ||
+      config.fixtures ||
+      config.realtime === false ||
+      !doctype ||
+      !isBrowser()
+    )
+      return;
     const syncModule = getSyncModule(config);
     if (!syncModule) return;
 
@@ -645,7 +672,7 @@ export function useFrappeDoctypeEvents(
       syncModule.unwatchDoctype(doctype);
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [enabled, config?.baseURL, !!config?.fixtures, doctype]);
+  }, [enabled, config?.baseURL, config?.realtime, !!config?.fixtures, doctype]);
 }
 
 // ---------------------------------------------------------------------------
@@ -706,7 +733,7 @@ export function useFrappePendingMutations(
     read();
     return syncModule.subscribeStore(read);
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [config?.baseURL, !!config?.fixtures, doctype]);
+  }, [config?.baseURL, config?.realtime, !!config?.fixtures, doctype]);
 
   const retry = useCallback(async () => {
     await syncModuleRef.current?.replayPending();
@@ -1075,7 +1102,7 @@ export function useFrappeInfiniteList<TDoc extends object & { name: string; doct
       }
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [config?.baseURL, config?.auth?.token, doctype, filtersKey, pageSize]);
+  }, [config?.baseURL, config?.realtime, config?.auth?.token, doctype, filtersKey, pageSize]);
 
   const loadMore = useCallback(async () => {
     const syncModule = syncModuleRef.current;

package/src/index.ts

@@ -201,7 +201,7 @@ export type {
   DebugMutationEntry,
   PageIsland,
 } from "./sync/types";
-export { Order, Operation } from "./sync/types";
+export { defaultPageLength, Order, Operation } from "./sync/types";
 export { MergeStrategy, FieldMergeStrategy } from "./sync/merge";
 export type { FieldMergeStrategyOrFunction, MergeConfig, MergeResult } from "./sync/merge";
 

package/src/pacer.ts

@@ -53,8 +53,14 @@ export interface DebouncedSearchResult<TDoc extends FrappeDocData> {
  * Connection configuration for hooks that need a Frappe backend.
  */
 export interface FrappeConnectionConfig {
-  /** The base URL of the Frappe server */
-  baseURL: string;
+  /**
+   * The base URL of the Frappe server. Required unless `fixtures` is set:
+   * a fixtures-only host has no server, and the hooks here read the corpus
+   * (or park) instead of dialling one.
+   */
+  baseURL?: string;
+  /** False disables realtime when this connection is used by collection hooks. */
+  realtime?: boolean;
   /** Override port for Socket.IO realtime connection (e.g. 9000 in dev). */
   socketPort?: number;
   /** Authentication configuration */
@@ -72,7 +78,8 @@ export interface FrappeConnectionConfig {
   fixtures?: FixtureProvider;
 }
 
-function createDbModule(config: FrappeConnectionConfig): DbModule {
+function createDbModule(config: FrappeConnectionConfig): DbModule | undefined {
+  if (!config.baseURL) return undefined;
   const authConfig: AuthConfig | undefined = config.auth
     ? {
         useToken: config.auth.useToken,

package/src/sync/index.ts

@@ -27,6 +27,19 @@ export interface SyncRealtimeEvent {
   payload?: unknown;
 }
 
+function getBrowserJournalStorage(): Storage | undefined {
+  if (typeof window === "undefined" || typeof document === "undefined") return undefined;
+  try {
+    const storage = window.localStorage;
+    return typeof storage?.getItem === "function" && typeof storage.setItem === "function"
+      ? storage
+      : undefined;
+  } catch {
+    // Browsers can deny access; Node's Web Storage is not browser-scoped.
+    return undefined;
+  }
+}
+
 /**
  * Synchronization engine that provides Zero-style UX on top of Frappe's REST API.
  *
@@ -110,7 +123,7 @@ export class SyncModule {
     this.mutationJournal = new MutationJournal({
       ttl: this.options.mutationTTL,
       enableAutoCleanup: true,
-      storage: typeof localStorage !== "undefined" ? localStorage : undefined,
+      storage: getBrowserJournalStorage(),
     });
     this.subscriptionManager = new SubscriptionManager(this.db, this.normalizedCache, this.options);
 

package/src/sync/subscriptionManager.spec.ts

@@ -1,7 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 import type { FrappeDoc, FrappeDocData } from "../common/types";
 import { SubscriptionManager } from "./subscriptionManager";
-import { BackfillScope } from "./types";
+import { BackfillScope, defaultPageLength } from "./types";
 import { Order } from "./types";
 import type { SubscriptionQuery, SyncOptions } from "./types";
 
@@ -156,7 +156,10 @@ describe("SubscriptionManager", () => {
       });
     });
 
-    it("omits limit from the initial fetch when the query has none", async () => {
+    it("sends the default page length when the query has no limit", async () => {
+      // MPO-238: leaving limit_page_length off let the bench clamp to 20
+      // while fixture mode returned every row, so a no-limit collection read
+      // one count in development and another in production.
       const query: SubscriptionQuery = {
         doctype: "TestDoc",
         fields: ["title"],
@@ -168,6 +171,42 @@ describe("SubscriptionManager", () => {
         fields: ["title", "modified", "name"],
         filters: undefined,
         orderBy: undefined,
+        limit: defaultPageLength,
+      });
+    });
+
+    it("passes limit 0 through as Frappe's every-row page length", async () => {
+      const query: SubscriptionQuery = {
+        doctype: "TestDoc",
+        fields: ["title"],
+        limit: 0,
+      };
+
+      await subscriptionManager.subscribe(query);
+
+      expect(mockDb.getDocList).toHaveBeenCalledWith("TestDoc", {
+        fields: ["title", "modified", "name"],
+        filters: undefined,
+        orderBy: undefined,
+        limit: 0,
+      });
+    });
+
+    it("applies limitStart without an explicit limit", async () => {
+      const query: SubscriptionQuery = {
+        doctype: "TestDoc",
+        fields: ["title"],
+        limitStart: 20,
+      };
+
+      await subscriptionManager.subscribe(query);
+
+      expect(mockDb.getDocList).toHaveBeenCalledWith("TestDoc", {
+        fields: ["title", "modified", "name"],
+        filters: undefined,
+        orderBy: undefined,
+        limit: defaultPageLength,
+        limitStart: 20,
       });
     });
 

package/src/sync/subscriptionManager.ts

@@ -4,7 +4,7 @@ import type { DbModule } from "../db";
 import { BackfillManager } from "./backfill";
 import { extractSingleName, matchesFilters } from "./filters";
 import type { NormalizedCache } from "./normalizedCache";
-import { BackfillScope, Order } from "./types";
+import { BackfillScope, defaultPageLength, Order } from "./types";
 import type {
   BackfillArgs,
   OrderByField,
@@ -168,16 +168,13 @@ export class SubscriptionManager {
         filters: query.filters,
         orderBy: query.orderBy,
       };
-      // Honor an explicit subscription limit on the INITIAL fetch. Without
-      // this the request carries no limit_page_length and the bench clamps
-      // to its default page length (20) — collections created with
-      // `limit: N` silently truncated to 20 rows (surfaced by the pokemon
-      // moves accordion once rosters grew past 20 junction rows). No
-      // explicit limit keeps the previous no-param behavior.
-      if (query.limit != null) {
-        listOptions.limit = query.limit;
-        if (query.limitStart != null) listOptions.limitStart = query.limitStart;
-      }
+      // Always send a page length on the INITIAL fetch. A request with no
+      // limit_page_length is clamped to 20 rows by the bench while a fixture
+      // provider returns every row, so an absent limit made development and
+      // production disagree with nothing on screen to say so. `limit: 0`
+      // (every row) passes through untouched.
+      listOptions.limit = query.limit ?? defaultPageLength;
+      if (query.limitStart != null) listOptions.limitStart = query.limitStart;
       if (this.options.useCursorPagination) listOptions.cursor = undefined;
       const response = await this.db.getDocList<Data>(query.doctype, listOptions);