@multiplatform.one/frappe 7.10.0 → 7.15.0

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();
+});

package/src/sync/index.ts

@@ -17,6 +17,7 @@ import type {
   DebugMutationEntry,
   DebugSubscription,
   SyncOptions,
+  SyncCatchUpState,
   FrappeDebugState,
   Mutation,
   RealtimeEventType,
@@ -42,6 +43,12 @@ function getBrowserJournalStorage(): Storage | undefined {
   }
 }
 
+const idleCatchUpState: SyncCatchUpState = Object.freeze({
+  refreshing: false,
+  stale: false,
+  error: null,
+});
+
 /**
  * Synchronization engine that provides Zero-style UX on top of Frappe's REST API.
  *
@@ -113,6 +120,14 @@ export class SyncModule {
   private readonly db: DbModule;
   private readonly realtime?: RealtimeModule;
   private readonly options: SyncOptions;
+  private catchUpState = idleCatchUpState;
+  private catchUpEpoch = 0;
+  private disposed = false;
+  private catchUpRun?: {
+    trailing: boolean;
+    attempt: number;
+    promise: Promise<SyncCatchUpState>;
+  };
 
   constructor(db: DbModule, realtime?: RealtimeModule, options: SyncOptions = {}) {
     this.db = db;
@@ -159,7 +174,9 @@ export class SyncModule {
     const realtimeOptions: SyncOptions = {
       ...this.options,
       onResetCache: () => this.resetCache(),
-      onBackfillAll: () => this.backfill({ scope: BackfillScope.All }),
+      onBackfillAll: () => {
+        void this.catchUp();
+      },
       // Realtime reconciliation mutates cache/membership outside the public
       // mutate/backfill entry points — bridge those changes to store listeners.
       onStoreChange: () => this.emit(),
@@ -194,7 +211,9 @@ export class SyncModule {
    * Stores cleanup functions returned by each subscription.
    */
   private setupWindowEvents() {
-    this.cleanupFocus = onAppFocus(() => this.backfill({ scope: BackfillScope.All }));
+    this.cleanupFocus = onAppFocus(() => {
+      void this.catchUp();
+    });
     // Journal replay on foreground: React Native never fires `online`
     // (AppState is its only lifecycle signal), and on web this recovers
     // server-restart cases where connectivity never flipped. Guarded so it
@@ -202,14 +221,15 @@ export class SyncModule {
     this.cleanupFocusReplay = onAppFocus(() => {
       if (this.mutationJournal.listPending().length > 0) void this.replayPending();
     });
-    this.cleanupOnlineBackfill = onOnline(() => this.backfill({ scope: BackfillScope.All }));
+    this.cleanupOnlineBackfill = onOnline(() => {
+      void this.catchUp();
+    });
     this.cleanupOnlineReplay = onOnline(() => this.replayPending());
 
     if (this.options.cdcInterval && this.options.cdcInterval > 0) {
-      this.cdcIntervalHandle = setInterval(
-        () => this.backfill({ scope: BackfillScope.All }),
-        this.options.cdcInterval,
-      );
+      this.cdcIntervalHandle = setInterval(() => {
+        void this.catchUp();
+      }, this.options.cdcInterval);
     }
   }
 
@@ -223,6 +243,9 @@ export class SyncModule {
    * the subscription is marked stale until the next successful backfill.
    */
   async subscribe<Data extends FrappeDocData>(query: SubscriptionQuery) {
+    if (this.options.catchUpStrategy === "snapshot" && query.progressive) {
+      throw new Error("Snapshot catch-up does not support progressive subscriptions");
+    }
     // Wait for any persisted snapshot restore so a matching restored
     // subscription can be adopted instead of racing the async load.
     await this.persistenceManager.whenReady();
@@ -263,22 +286,92 @@ export class SyncModule {
     this.emit();
   }
 
+  /**
+   * The name the server assigned a document this module created under
+   * `temporaryName`, once the create is acknowledged. Undefined while it is
+   * pending, or when the server kept the name it was given.
+   */
+  createdName(temporaryName: string): string | undefined {
+    return this.rehydrationManager.resolveTempId(temporaryName);
+  }
+
   /** Refresh active query snapshots in place. Failures retain the last committed data. */
   async refreshSubscriptions(
     options?: SubscriptionRefreshOptions,
   ): Promise<SubscriptionRefreshResult[]> {
+    const epoch = this.catchUpEpoch;
     await this.persistenceManager.whenReady();
+    if (this.disposed || epoch !== this.catchUpEpoch) return [];
     const results = await this.subscriptionManager.refreshSubscriptions(options);
-    this.emit();
+    if (!this.disposed && epoch === this.catchUpEpoch) this.emit();
     return results;
   }
 
+  getCatchUpState(): SyncCatchUpState {
+    return this.catchUpState;
+  }
+
+  private publishCatchUp(state: SyncCatchUpState) {
+    this.catchUpState = Object.freeze(state);
+    for (const listener of this.storeListeners) listener();
+  }
+
+  /** Observes lifecycle/retry failures in state; explicit backfill still rejects. */
+  catchUp(): Promise<SyncCatchUpState> {
+    if (this.disposed) return Promise.resolve(this.catchUpState);
+    if (this.catchUpRun) {
+      if (this.catchUpRun.attempt === 0) this.catchUpRun.trailing = true;
+      return this.catchUpRun.promise;
+    }
+    const epoch = this.catchUpEpoch;
+    const run = { trailing: false, attempt: 0, promise: Promise.resolve(this.catchUpState) };
+    this.catchUpRun = run;
+    run.promise = Promise.resolve().then(async () => {
+      let error: unknown = null;
+      const active = () => !this.disposed && this.catchUpEpoch === epoch;
+      do {
+        if (!active()) return this.catchUpState;
+        run.trailing = false;
+        error = null;
+        try {
+          if (this.options.catchUpStrategy === "snapshot") {
+            const results = await this.refreshSubscriptions();
+            const failures = results.filter(
+              (result) =>
+                !result.ok &&
+                this.subscriptionManager.getSubscription(result.subscriptionId) &&
+                !this.subscriptionManager.isRestoredSubscription(result.subscriptionId),
+            );
+            if (failures.length)
+              error = new AggregateError(
+                failures.map((failure) => failure.error),
+                "Some subscriptions could not refresh. Showing previous data.",
+              );
+          } else {
+            await this.backfill({ scope: BackfillScope.All });
+          }
+        } catch (caught) {
+          error = caught;
+        }
+        // Bound a burst to one trailing read, including triggers during that read.
+      } while (active() && run.trailing && run.attempt++ === 0);
+      if (active()) {
+        this.catchUpRun = undefined;
+        this.publishCatchUp({ refreshing: false, stale: error !== null, error });
+      }
+      return this.catchUpState;
+    });
+    this.publishCatchUp({ ...this.catchUpState, refreshing: true });
+    return run.promise;
+  }
+
   /**
    * Reconciles local state by fetching changes since stored cursors.
    */
   async backfill(args: BackfillArgs) {
+    const epoch = this.catchUpEpoch;
     await this.subscriptionManager.backfill(args);
-    this.emit();
+    if (!this.disposed && epoch === this.catchUpEpoch) this.emit();
   }
 
   /**
@@ -450,6 +543,9 @@ export class SyncModule {
 
   /** Clears subscriptions, cache, journal, and temp id mappings. */
   resetCache() {
+    this.catchUpEpoch++;
+    this.catchUpRun = undefined;
+    this.catchUpState = idleCatchUpState;
     // Leave all realtime doctype rooms alongside dropping the subscriptions
     this.realtimeHandler.unwatchAll();
     // Drop all live subs, in-memory cache, journal, and temp mappings
@@ -463,6 +559,7 @@ export class SyncModule {
 
   /** Cleanup and dispose of resources */
   async dispose() {
+    this.disposed = true;
     // Clear all listeners
     this.storeListeners.clear();
     this.realtimeEventListeners.clear();

package/src/sync/rehydration.ts

@@ -370,6 +370,11 @@ export class RehydrationManager {
     this.temporaryIdMap.set(tempId, realName);
   }
 
+  /** The name the server gave a document created under a temp id. */
+  resolveTempId(tempId: string): string | undefined {
+    return this.temporaryIdMap.get(tempId);
+  }
+
   /**
    * Clears the rehydration queue.
    */

package/src/sync/syncModule.spec.ts

@@ -65,6 +65,26 @@ describe("SyncModule", () => {
     return new SyncModule(mockDb, mockRealtime, options);
   }
 
+  describe("createdName (MPO-333)", () => {
+    it("names the document the server created under a temporary name", async () => {
+      mockDb.createDoc.mockResolvedValue({
+        name: "a1b2c3",
+        doctype: "TestDoc",
+        modified: "2024-01-01T11:00:00",
+        title: "hash named",
+      });
+      sync = createSync();
+      expect(sync.createdName("new-1")).toBeUndefined();
+      await sync.mutate({
+        mutationId: "create-hash",
+        operation: Operation.Create,
+        doc: { name: "new-1", doctype: "TestDoc", title: "hash named" },
+      });
+      expect(sync.createdName("new-1")).toBe("a1b2c3");
+      expect(sync.createdName("new-2")).toBeUndefined();
+    });
+  });
+
   describe("automatic journal storage", () => {
     it("reads HTTP rows during SSR with Node's incomplete localStorage object", async () => {
       vi.stubGlobal("window", undefined);

package/src/sync/types.ts

@@ -197,7 +197,15 @@ export enum RealtimeEventType {
   PermEpochBump = "perm_epoch_bump",
 }
 
+export interface SyncCatchUpState {
+  readonly refreshing: boolean;
+  readonly stale: boolean;
+  readonly error: unknown | null;
+}
+
 export interface SyncOptions {
+  /** Lifecycle catch-up uses CDC by default; snapshot requires only resource reads. */
+  catchUpStrategy?: "cdc" | "snapshot";
   pageSize?: number;
   persistKey?: string;
   onConflict?: (info: { doctype: string; name?: string }) => void;
@@ -261,7 +269,7 @@ export interface SyncOptions {
   /** Rate limit for mutation replay - max mutations per second (default: 10) */
   replayRateLimit?: number;
   /**
-   * Optional interval (in milliseconds) for periodic CDC polling.
+   * Optional interval (in milliseconds) for the selected catch-up strategy.
    * Acts as a safety net for silent socket drops. Set to 0 or omit
    * to rely solely on event-driven backfill (focus, online, reconnect).
    * Recommended: 30000 (30 seconds) for production.

package/src/syncOptionsKey.spec.ts

@@ -0,0 +1,46 @@
+import { expect, it } from "vitest";
+import { syncOptionsKey } from "./syncOptionsKey";
+
+it("normalizes lifecycle defaults and plain options independent of key order", () => {
+  expect(syncOptionsKey()).toBe(syncOptionsKey({ catchUpStrategy: "cdc", cdcInterval: 0 }));
+  expect(syncOptionsKey({ cdcInterval: -1 })).toBe(syncOptionsKey());
+  expect(
+    syncOptionsKey({ versionFields: { Task: "modified", Item: "version" }, pageSize: 20 }),
+  ).toBe(
+    syncOptionsKey({
+      pageSize: 20,
+      versionFields: { Item: "version", Task: "modified" },
+      persistKey: undefined,
+    }),
+  );
+});
+
+it("separates strategy, interval, persistence and cursor capabilities", () => {
+  const keys = [
+    undefined,
+    { catchUpStrategy: "snapshot" as const },
+    { cdcInterval: 1000 },
+    { persistKey: "one" },
+    { useCursorPagination: true },
+  ].map(syncOptionsKey);
+  expect(new Set(keys).size).toBe(keys.length);
+});
+
+it("keeps callback and storage identities without dropping functions", () => {
+  const callback = () => 0;
+  const storage = {
+    getItem: async () => null,
+    setItem: async () => {},
+    removeItem: async () => {},
+  };
+  expect(syncOptionsKey({ onBackfill: callback, storage })).toBe(
+    syncOptionsKey({ storage, onBackfill: callback }),
+  );
+  expect(syncOptionsKey({ onBackfill: callback })).not.toBe(
+    syncOptionsKey({ onBackfill: () => {} }),
+  );
+  expect(syncOptionsKey({ storage })).not.toBe(syncOptionsKey({ storage: { ...storage } }));
+  expect(syncOptionsKey({ fieldMergeConfig: { Task: { value: callback } } })).not.toBe(
+    syncOptionsKey(),
+  );
+});

package/src/syncOptionsKey.ts

@@ -0,0 +1,45 @@
+import type { SyncOptions } from "./sync/types";
+
+const identities = new WeakMap<object, number>();
+let nextIdentity = 0;
+function identity(value: object) {
+  let id = identities.get(value);
+  if (id === undefined) {
+    id = ++nextIdentity;
+    identities.set(value, id);
+  }
+  return ["reference", id];
+}
+
+function stableValue(value: unknown, ancestors = new Set<object>()): unknown {
+  if (typeof value === "function") return identity(value);
+  if (value === null || typeof value !== "object") return [typeof value, String(value)];
+  const prototype = Object.getPrototypeOf(value);
+  if (
+    ancestors.has(value) ||
+    (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null)
+  ) {
+    return identity(value);
+  }
+  const nested = new Set(ancestors).add(value);
+  if (Array.isArray(value)) return ["array", value.map((item) => stableValue(item, nested))];
+  return [
+    "record",
+    Object.entries(value)
+      .filter(([, item]) => item !== undefined)
+      .sort(([left], [right]) => left.localeCompare(right))
+      .map(([key, item]) => [key, stableValue(item, nested)]),
+  ];
+}
+
+export function syncOptionsKey(options: SyncOptions = {}): string {
+  const { storage, ...values } = options;
+  return JSON.stringify([
+    stableValue({
+      ...values,
+      catchUpStrategy: options.catchUpStrategy ?? "cdc",
+      cdcInterval: options.cdcInterval && options.cdcInterval > 0 ? options.cdcInterval : 0,
+    }),
+    storage ? identity(storage) : null,
+  ]);
+}

package/src/useLiveQuery.hydration.spec.tsx

@@ -0,0 +1,129 @@
+import { act } from "react";
+import { hydrateRoot } from "react-dom/client";
+import { renderToString } from "react-dom/server";
+import { expect, it, vi } from "vitest";
+
+const platform = vi.hoisted(() => ({ server: true }));
+vi.mock("@multiplatform.one/platform", () => ({
+  get isServer() {
+    return platform.server;
+  },
+}));
+
+it.each([
+  { warm: false, enabled: true },
+  { warm: true, enabled: true },
+  { warm: true, enabled: false },
+])("hydrates real queries and preserves updates/cleanup (%j)", async ({ warm, enabled }) => {
+  platform.server = true;
+  vi.resetModules();
+  const serverDb = await import("@tanstack/db");
+  const serverCollection = serverDb.createCollection(
+    serverDb.localOnlyCollectionOptions({
+      getKey: (row: { id: string; label: string }) => row.id,
+      initialData: [{ id: "alpha", label: "Alpha" }],
+    }),
+  );
+  const { useLiveQuery: serverQuery } = await import("./useLiveQuery");
+  function ServerView() {
+    const result = serverQuery((q) => (enabled ? q.from({ item: serverCollection }) : undefined));
+    return (
+      <div data-testid="result">
+        {!result.isEnabled
+          ? "Disabled"
+          : result.data?.map((row) => row.label).join(",") || "Loading"}
+      </div>
+    );
+  }
+  const container = document.createElement("div");
+  container.innerHTML = renderToString(<ServerView />);
+  document.body.append(container);
+  const serverNode = container.firstChild;
+  platform.server = false;
+  vi.resetModules();
+  const clientDb = await import("@tanstack/db");
+  const collection = clientDb.createCollection(
+    clientDb.localOnlyCollectionOptions({
+      getKey: (row: { id: string; label: string }) => row.id,
+      initialData: [{ id: "alpha", label: "Alpha" }],
+    }),
+  );
+  if (warm) await collection.preload();
+  const { useLiveQuery: clientQuery } = await import("./useLiveQuery");
+  let observedQuery: { subscriberCount: number; status: string } | undefined;
+  function ClientView({ active = enabled, selected }: { active?: boolean; selected?: string }) {
+    const result = clientQuery(
+      (q) => {
+        if (!active) return undefined;
+        const query = q.from({ item: collection });
+        return selected ? query.where(({ item }) => clientDb.eq(item.id, selected)) : query;
+      },
+      [active, selected],
+    );
+    observedQuery = result.collection;
+    return (
+      <div data-testid="result">
+        {!result.isEnabled
+          ? "Disabled"
+          : result.data?.map((row) => row.label).join(",") || "Loading"}
+      </div>
+    );
+  }
+  const onRecoverableError = vi.fn();
+  let root: ReturnType<typeof hydrateRoot> | undefined;
+  try {
+    await act(async () => {
+      root = hydrateRoot(container, <ClientView />, { onRecoverableError });
+    });
+    expect(
+      onRecoverableError.mock.calls.map(([error]) => error.cause?.message || error.message),
+    ).toEqual([]);
+    expect(container.firstChild).toBe(serverNode);
+    await vi.waitFor(() => expect(container.textContent).toBe(enabled ? "Alpha" : "Disabled"));
+    if (!enabled) {
+      expect(collection.subscriberCount).toBe(0);
+      await act(async () => root!.render(<ClientView active />));
+    }
+    await act(async () => {
+      const transaction = collection.insert({ id: "beta", label: "Beta" });
+      await transaction.isPersisted.promise;
+    });
+    await vi.waitFor(() => expect(container.textContent).toBe("Alpha,Beta"));
+    await act(async () => root!.render(<ClientView active selected="beta" />));
+    await vi.waitFor(() => expect(container.textContent).toBe("Beta"));
+    const { createOptimisticAction } = await import("./optimistic");
+    let rejectWrite: (reason: Error) => void = () => {};
+    const write = new Promise<void>((_resolve, reject) => {
+      rejectWrite = reject;
+    });
+    const rename = createOptimisticAction({
+      onMutate: () =>
+        collection.update("beta", (row) => {
+          row.label = "Pending";
+        }),
+      mutationFn: () => write,
+    });
+    let transaction: ReturnType<typeof rename>;
+    await act(async () => {
+      transaction = rename(undefined);
+    });
+    await vi.waitFor(() => expect(container.textContent).toBe("Pending"));
+    await act(async () => {
+      const refused = expect(transaction!.isPersisted.promise).rejects.toThrow("Write refused");
+      rejectWrite(new Error("Write refused"));
+      await refused;
+    });
+    await vi.waitFor(() => expect(container.textContent).toBe("Beta"));
+    const lastQuery = observedQuery;
+    expect(lastQuery?.subscriberCount).toBeGreaterThan(0);
+    await act(async () => root!.unmount());
+    root = undefined;
+    await vi.waitFor(() => expect(lastQuery?.subscriberCount).toBe(0));
+    await vi.waitFor(() => expect(lastQuery?.status).toBe("cleaned-up"));
+  } finally {
+    await act(async () => root?.unmount());
+    container.remove();
+    await collection.cleanup();
+    await serverCollection.cleanup();
+  }
+});

package/src/useLiveQuery.spec.ts

@@ -1,6 +1,6 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
-import { isServer } from "@multiplatform.one/platform";
+import { useLiveQuery as upstreamUseLiveQuery } from "@tanstack/react-db";
 import { describe, expect, it } from "vitest";
 import { useLiveQuery } from "./useLiveQuery";
 
@@ -22,9 +22,8 @@ describe("useLiveQuery carries no import.meta (MPO-204)", () => {
     expect(source).not.toMatch(/import\.meta/);
   });
 
-  it("takes its SSR answer from the platform package, which is split by FILE and not by a bundler define", () => {
-    expect(source).toMatch(/import \{ isServer \} from "@multiplatform\.one\/platform";/);
-    expect(source).toMatch(/const IS_SSR: boolean = isServer;/);
+  it("preserves the upstream hook and its server snapshot lifecycle", () => {
+    expect(useLiveQuery).toBe(upstreamUseLiveQuery);
   });
 
   it("has no platform twin — a .web twin replaced the bake once already (MPO-192)", () => {
@@ -34,10 +33,3 @@ describe("useLiveQuery carries no import.meta (MPO-204)", () => {
     }
   });
 });
-
-describe("useLiveQuery answers client in a browser-like environment", () => {
-  it("resolves isServer false, so the hook delegates to @tanstack/react-db", () => {
-    expect(isServer).toBe(false);
-    expect(typeof useLiveQuery).toBe("function");
-  });
-});