@multiplatform.one/frappe 7.7.6 → 7.10.0

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.ts

@@ -20,8 +20,12 @@ 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;
   /**
@@ -122,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 —

package/src/index.ts

@@ -64,7 +64,11 @@ export type {
   UseFrappeInfiniteListConfig,
   UseFrappeInfiniteListResult,
 } from "./frappeReact";
-export type { SyncRealtimeEvent } from "./sync";
+export type {
+  SyncRealtimeEvent,
+  SubscriptionRefreshOptions,
+  SubscriptionRefreshResult,
+} from "./sync";
 
 // TanStack Pacer utilities for Frappe
 export { useDebouncedSearch, useThrottledPagination, createRateLimitedBatch } from "./pacer";
@@ -201,7 +205,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,12 @@ 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). */
@@ -74,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

@@ -8,6 +8,8 @@ import { NormalizedCache } from "./normalizedCache";
 import { PersistenceManager } from "./persistence";
 import { RealtimeHandler } from "./realtime";
 import { RehydrationManager } from "./rehydration";
+import type { SubscriptionRefreshOptions, SubscriptionRefreshResult } from "./subscriptionManager";
+export type { SubscriptionRefreshOptions, SubscriptionRefreshResult } from "./subscriptionManager";
 import { SubscriptionManager } from "./subscriptionManager";
 import { BackfillScope, Status } from "./types";
 import type {
@@ -261,6 +263,16 @@ export class SyncModule {
     this.emit();
   }
 
+  /** Refresh active query snapshots in place. Failures retain the last committed data. */
+  async refreshSubscriptions(
+    options?: SubscriptionRefreshOptions,
+  ): Promise<SubscriptionRefreshResult[]> {
+    await this.persistenceManager.whenReady();
+    const results = await this.subscriptionManager.refreshSubscriptions(options);
+    this.emit();
+    return results;
+  }
+
   /**
    * Reconciles local state by fetching changes since stored cursors.
    */

package/src/sync/refreshSubscriptions.lifecycle.spec.ts

@@ -0,0 +1,268 @@
+import { describe, expect, it, vi } from "vitest";
+import { NormalizedCache } from "./normalizedCache";
+import { SubscriptionManager } from "./subscriptionManager";
+import type { SyncOptions } from "./types";
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (error: unknown) => void;
+  const promise = new Promise<T>((yes, no) => {
+    resolve = yes;
+    reject = no;
+  });
+  return { promise, resolve, reject };
+}
+const row = (name: string, title = name) => ({
+  name,
+  title,
+  doctype: "Item",
+  modified: "2026-09-09T01:00:00Z",
+});
+const query = { doctype: "Item" };
+async function setup(options: SyncOptions = {}) {
+  const db = { getDocList: vi.fn().mockResolvedValue([row("a")]) };
+  const cache = new NormalizedCache();
+  const manager = new SubscriptionManager(db as never, cache, options);
+  const { subscriptionId: id } = await manager.subscribe(query);
+  return { db, cache, manager, id };
+}
+function pending(db: Awaited<ReturnType<typeof setup>>["db"]) {
+  const response = deferred<ReturnType<typeof row>[]>();
+  const started = deferred<void>();
+  db.getDocList.mockImplementationOnce(() => {
+    started.resolve();
+    return response.promise;
+  });
+  return { ...response, started: started.promise };
+}
+
+describe("snapshot refresh lifecycle", () => {
+  it.each(["resolve", "reject"] as const)(
+    "invalidates pre-detach refresh that later %ss after re-adoption",
+    async (outcome) => {
+      const { manager, db, cache, id } = await setup({ persistKey: "lifecycle" });
+      const old = pending(db);
+      const oldResult = manager.refreshSubscriptions();
+      await old.started;
+      manager.unsubscribe(id);
+      const fresh = pending(db);
+      const adopted = await manager.subscribe(query);
+      expect(adopted.subscriptionId).toBe(id);
+      expect(adopted.rows).toEqual([row("a")]);
+      await fresh.started;
+      fresh.resolve([row("a", "new-adoption")]);
+      expect(await adopted.refresh).toMatchObject({ ok: true });
+      if (outcome === "resolve") old.resolve([row("a", "obsolete-before-detach"), row("obsolete")]);
+      else old.reject(new Error("old failure"));
+      expect((await oldResult)[0].ok).toBe(false);
+      expect(manager.getDocsForSubscription(id)).toEqual([row("a", "new-adoption")]);
+      expect(cache.get({ doctype: "Item", name: "obsolete" })).toBeUndefined();
+      expect(manager.getSubscription(id)?.stale).toBe(false);
+    },
+  );
+
+  it("does not let an old finally erase the new adoption operation", async () => {
+    const { manager, db, cache, id } = await setup({ persistKey: "lifecycle" });
+    const old = pending(db);
+    const oldResult = manager.refreshSubscriptions();
+    await old.started;
+    manager.unsubscribe(id);
+    const adoption = pending(db);
+    const adopted = await manager.subscribe(query);
+    await adoption.started;
+    old.resolve([row("obsolete")]);
+    expect((await oldResult)[0].ok).toBe(false);
+    const trailing = pending(db);
+    const explicit = manager.refreshSubscriptions();
+    expect(db.getDocList).toHaveBeenCalledTimes(3);
+    adoption.resolve([row("discarded-adoption")]);
+    await trailing.started;
+    expect(cache.get({ doctype: "Item", name: "discarded-adoption" })).toBeUndefined();
+    expect(manager.getDocsForSubscription(id)).toEqual([row("a")]);
+    trailing.resolve([row("final")]);
+    expect(await adopted.refresh).toEqual((await explicit)[0]);
+    expect(manager.getDocsForSubscription(id)).toEqual([row("final")]);
+    expect(db.getDocList).toHaveBeenCalledTimes(4);
+  });
+
+  it.each([false, true])(
+    "coalesces requests and retains the committed snapshot when trailing fails=%s",
+    async (fails) => {
+      const { manager, db, cache, id } = await setup();
+      const before = structuredClone(manager.getSubscription(id));
+      const first = pending(db);
+      const one = manager.refreshSubscriptions();
+      await first.started;
+      const last = pending(db);
+      const two = manager.refreshSubscriptions();
+      const three = manager.refreshSubscriptions();
+      first.resolve([row("a", "discarded"), row("obsolete")]);
+      await last.started;
+      expect(cache.get({ doctype: "Item", name: "obsolete" })).toBeUndefined();
+      expect(manager.getDocsForSubscription(id)).toEqual([row("a")]);
+      const error = new Error("trailing failed");
+      if (fails) last.reject(error);
+      else last.resolve([row("final")]);
+      const results = await Promise.all([one, two, three]);
+      expect(results).toEqual(
+        Array(3).fill([{ subscriptionId: id, ok: !fails, ...(fails ? { error } : {}) }]),
+      );
+      if (fails) for (const result of results) expect(result[0].error).toBe(error);
+      expect(db.getDocList).toHaveBeenCalledTimes(3);
+      if (fails) expect(manager.getSubscription(id)).toEqual({ ...before, stale: true });
+      else expect(manager.getDocsForSubscription(id)).toEqual([row("final")]);
+      await manager.refreshSubscriptions();
+      expect(db.getDocList).toHaveBeenCalledTimes(4);
+    },
+  );
+
+  it("trails a failed attempt only when another caller requested it", async () => {
+    const { manager, db, id } = await setup();
+    const first = pending(db);
+    const one = manager.refreshSubscriptions();
+    await first.started;
+    const last = pending(db);
+    const two = manager.refreshSubscriptions();
+    first.reject(new Error("superseded failure"));
+    await last.started;
+    last.resolve([row("final")]);
+    expect(await one).toEqual(await two);
+    expect(manager.getDocsForSubscription(id)).toEqual([row("final")]);
+    expect(db.getDocList).toHaveBeenCalledTimes(3);
+  });
+
+  it("joins an adoption already fetching and discards its superseded rows", async () => {
+    const { manager, db, cache, id } = await setup({ persistKey: "lifecycle" });
+    manager.unsubscribe(id);
+    const adoption = pending(db);
+    const adopted = await manager.subscribe(query);
+    await adoption.started;
+    const last = pending(db);
+    const explicit = manager.refreshSubscriptions();
+    adoption.resolve([row("obsolete")]);
+    await last.started;
+    expect(cache.get({ doctype: "Item", name: "obsolete" })).toBeUndefined();
+    last.resolve([row("final")]);
+    expect(await adopted.refresh).toEqual((await explicit)[0]);
+    expect(manager.getDocsForSubscription(id)).toEqual([row("final")]);
+  });
+
+  it("invalidates the last release without corrupting cached documents", async () => {
+    const { manager, db, cache, id } = await setup();
+    const read = pending(db);
+    const result = manager.refreshSubscriptions();
+    await read.started;
+    manager.unsubscribe(id);
+    read.resolve([row("a", "obsolete"), row("new")]);
+    expect((await result)[0].ok).toBe(false);
+    expect(manager.getSubscription(id)).toBeUndefined();
+    expect(cache.get({ doctype: "Item", name: "a" })).toEqual(row("a"));
+    expect(cache.get({ doctype: "Item", name: "new" })).toBeUndefined();
+  });
+
+  it("keeps shared refreshes active until the last consumer releases", async () => {
+    const { manager, db, id } = await setup();
+    expect((await manager.subscribe(query)).subscriptionId).toBe(id);
+    const first = pending(db);
+    const one = manager.refreshSubscriptions();
+    await first.started;
+    manager.unsubscribe(id);
+    first.resolve([row("updated")]);
+    expect(await one).toEqual([{ subscriptionId: id, ok: true }]);
+    const last = pending(db);
+    const two = manager.refreshSubscriptions();
+    await last.started;
+    manager.unsubscribe(id);
+    last.resolve([row("obsolete")]);
+    expect((await two)[0].ok).toBe(false);
+    expect(manager.getSubscription(id)).toBeUndefined();
+  });
+
+  it("invalidates clear and allows a subsequent activation", async () => {
+    const { manager, db, cache, id } = await setup();
+    const old = pending(db);
+    const result = manager.refreshSubscriptions();
+    await old.started;
+    manager.clear();
+    cache.clear();
+    const fresh = await manager.subscribe(query);
+    old.resolve([row("a", "obsolete"), row("obsolete")]);
+    expect((await result)[0].ok).toBe(false);
+    expect(manager.getSubscription(id)).toBeUndefined();
+    expect(manager.getDocsForSubscription(fresh.subscriptionId)).toEqual([row("a")]);
+    expect(cache.get({ doctype: "Item", name: "obsolete" })).toBeUndefined();
+  });
+
+  it("does not seed in the microtask between HTTP completion and acceptance", async () => {
+    const { manager, db, cache, id } = await setup();
+    const first = pending(db);
+    const one = manager.refreshSubscriptions();
+    await first.started;
+    const last = pending(db);
+    first.resolve([row("obsolete")]);
+    const two = Promise.resolve().then(() => manager.refreshSubscriptions());
+    await last.started;
+    expect(cache.get({ doctype: "Item", name: "obsolete" })).toBeUndefined();
+    expect(manager.getDocsForSubscription(id)).toEqual([row("a")]);
+    last.resolve([row("final")]);
+    expect(await one).toEqual(await two);
+  });
+
+  it("allows different subscriptions to finish independently", async () => {
+    const { manager, db, id } = await setup();
+    const second = await manager.subscribe({ doctype: "Other" });
+    const slow = pending(db);
+    const fast = pending(db);
+    const result = manager.refreshSubscriptions();
+    await Promise.all([slow.started, fast.started]);
+    fast.resolve([row("fast")]);
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(manager.getSubscription(second.subscriptionId)?.docIds).toEqual(["fast"]);
+    expect(manager.getSubscription(id)?.docIds).toEqual(["a"]);
+    slow.resolve([row("slow")]);
+    expect((await result).every((entry) => entry.ok)).toBe(true);
+  });
+});
+
+it("excludes dormant restored subscriptions and selects each shared id once", async () => {
+  const { manager, db, id } = await setup();
+  await manager.subscribe(query);
+  manager.restoreSubscription({ id: "dormant", query: { doctype: "Dormant" }, docIds: ["cached"] });
+  expect(await manager.refreshSubscriptions({ doctypes: ["Dormant"] })).toEqual([]);
+  expect(await manager.refreshSubscriptions({ doctypes: [] })).toEqual([]);
+  expect(db.getDocList).toHaveBeenCalledTimes(1);
+  expect(await manager.refreshSubscriptions()).toEqual([{ subscriptionId: id, ok: true }]);
+  expect(db.getDocList).toHaveBeenCalledTimes(2);
+  manager.unsubscribe(id);
+  manager.unsubscribe(id);
+  expect(manager.getSubscription(id)).toBeUndefined();
+});
+
+it("retains cached projections and documents outside the refreshed membership", async () => {
+  const { manager, db, cache, id } = await setup();
+  cache.upsert({ ...row("a"), detail: "other view" });
+  db.getDocList.mockResolvedValueOnce([row("b")]);
+  const other = await manager.subscribe({ doctype: "Item", filters: { enabled: 1 } });
+  db.getDocList
+    .mockResolvedValueOnce([{ name: "a", title: "projected" }])
+    .mockResolvedValueOnce([]);
+  await manager.refreshSubscriptions();
+  expect(manager.getDocsForSubscription(id)).toEqual([
+    { ...row("a", "projected"), detail: "other view" },
+  ]);
+  expect(manager.getDocsForSubscription(other.subscriptionId)).toEqual([]);
+  expect(cache.get({ doctype: "Item", name: "b" })).toEqual(row("b"));
+});
+
+it("shares the first read when callers arrive before it starts", async () => {
+  const { manager, db, id } = await setup();
+  const first = pending(db);
+  const one = manager.refreshSubscriptions();
+  const two = manager.refreshSubscriptions();
+  await first.started;
+  first.resolve([row("final")]);
+  expect(await one).toEqual(await two);
+  expect(manager.getDocsForSubscription(id)).toEqual([row("final")]);
+  expect(db.getDocList).toHaveBeenCalledTimes(2);
+});