@multiplatform.one/frappe 6.1.0 → 6.3.0

package/src/frappeReact.ts

@@ -1,3 +1,4 @@
+import { isWindowDefined } from "@multiplatform.one/platform";
 import type { Collection } from "@tanstack/db";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { createFrappeCollection, type FrappeCollectionOptionsConfig } from "./collection";
@@ -26,9 +27,17 @@ export interface UseFrappeCollectionConfig {
     useToken?: boolean;
     token?: string | (() => string | Promise<string>);
     type?: string;
+    /** Session id for Socket.IO cookie auth on Node / React Native */
+    sessionId?: string | (() => string | Promise<string>);
   };
   /** Sync options for the SyncModule */
   syncOptions?: import("./sync/types").SyncOptions;
+  /**
+   * Extra Socket.IO client options merged over the defaults — e.g.
+   * `{ transports: ["polling", "websocket"] }` behind dev proxies that can't
+   * forward WebSocket upgrades (websocket-first would never connect there).
+   */
+  socketOptions?: import("./realtime").RealtimeConfig["socketOptions"];
   /** Fixture provider for testing (used by frappe-ui in development) */
   fixtures?: import("./fixtures").FixtureProvider;
 }
@@ -58,8 +67,11 @@ export function __getActiveSyncModule(): SyncModule | undefined {
  * Fixture-mode SyncModules are keyed by the FixtureProvider instance so
  * different fixture sets never share cached state (important in tests).
  *
- * Returns `undefined` during SSR (Node.js) because the SyncModule relies
- * on browser-only APIs (localStorage, BroadcastChannel, window events).
+ * Returns `undefined` during SSR (Node.js) because a server render must not
+ * open sockets or share client caches. Every real client runtime constructs
+ * the module: web, React Native, and GJS/GNOME (isBrowser() covers all
+ * three; the engine's storage/BroadcastChannel/window usages are guarded
+ * per platform).
  */
 function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefined {
   if (!isBrowser()) return undefined;
@@ -77,11 +89,20 @@ function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefine
   const key = config.baseURL;
   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,
           token: config.auth.token,
           type: config.auth.type as AuthConfig["type"],
+          sessionId: config.auth.sessionId,
         }
       : undefined;
     const http = new HttpClient(config.baseURL, authConfig);
@@ -90,6 +111,7 @@ function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefine
       baseURL: config.baseURL,
       socketPort: config.socketPort,
       auth: authConfig,
+      socketOptions: config.socketOptions,
     };
     sync = new SyncModule(db, new RealtimeModule(realtimeConfig), config.syncOptions);
     syncModuleCache.set(key, sync);
@@ -97,12 +119,280 @@ function getSyncModule(config: UseFrappeCollectionConfig): SyncModule | undefine
   return sync;
 }
 
+// ---------------------------------------------------------------------------
+// Shared collection cache
+// ---------------------------------------------------------------------------
+//
+// One Collection per (SyncModule, doctype, options) so N consumers of the
+// same subscription shape share one collection — one initial fetch, one
+// SyncModule subscription, one realtime room — instead of N (e.g. the desk
+// form page's FrappeForm + DeskFormSidebar both subscribing to the same doc).
+//
+// Entries are refcounted by mounted hook instances. When the last consumer
+// unmounts, the entry is cleaned up after a short grace period (covers
+// StrictMode remounts and quick route transitions). Because live queries
+// subscribe to the collection OUTSIDE the hook refcount (synchronously during
+// render, detaching asynchronously via TanStack DB's own GC), the grace GC
+// additionally defers — keeping the entry cached — while
+// `collection.subscriberCount > 0`, bounded by SHARED_COLLECTION_GC_FORCE_MS
+// so leaked queries from never-committed renders can't pin the subscription
+// forever. The outer WeakMap keys on the SyncModule instance, which
+// `getSyncModule` already dedupes per baseURL (live) / per FixtureProvider
+// (fixtures) — so fixture sets never share cached collections across tests,
+// and the cache dies with its provider.
+
+interface SharedCollectionEntry {
+  collection: Collection<any, string>;
+  refCount: number;
+  gcTimer: ReturnType<typeof setTimeout> | undefined;
+  /** While the hook refcount is 0 but live queries still subscribe to the
+   * collection, GC is deferred — until this wall-clock deadline, after which
+   * the entry is force-cleaned (leak guard for queries created by renders
+   * that never committed; see scheduleEntryGc). Reset on every retain. */
+  gcForceDeadline: number | undefined;
+  /** Per-consumer onSyncError handlers, fanned out from the one collection. */
+  errorHandlers: Set<(error: unknown) => void>;
+  /** Initial-sync failure. The entry HOLDS its error state while any consumer
+   * retains it: re-renders keep acquiring the same errored entry, so an
+   * error-in-state consumer cannot loop failing fetches (the retry storm that
+   * froze error/loading stories). The flag is replayed on retain so a
+   * consumer whose render raced the failure — or that mounts later while the
+   * error is held — still surfaces it. The entry is evicted when the LAST
+   * consumer releases it, so the next mount (an explicit Retry remount, per
+   * the consumer retry contract) is the one place a fresh sync attempt
+   * starts. */
+  hasSyncError: boolean;
+  lastSyncError: unknown;
+  cleaned: boolean;
+}
+
+const sharedCollectionCaches = new WeakMap<SyncModule, Map<string, SharedCollectionEntry>>();
+
+/** Grace before an unreferenced entry is cleaned up (also the leak guard for
+ * entries created by renders that never committed). */
+const SHARED_COLLECTION_GC_MS = 1_000;
+
+/** How long an unreferenced entry may stay alive because live queries still
+ * subscribe to its collection, before GC stops deferring and force-cleans.
+ * Covers every legitimate straggler — an unmounted `useLiveQuery`'s detach
+ * runs through TanStack DB's own GC + requestIdleCallback (~1–2s), and a
+ * suspended tree that commits re-retains long before this — while still
+ * reclaiming collections pinned by leaked queries (a live query created by a
+ * render that never committed never receives a subscriber, and TanStack DB
+ * only arms a live query's own GC when a subscriber detaches). */
+const SHARED_COLLECTION_GC_FORCE_MS = 30_000;
+
+/** True when TanStack DB has torn this collection down (`cleanup()` ran and
+ * sync has not been restarted). Attached live queries are permanently broken
+ * at that point — TanStack transitions them to an error state they never
+ * leave — so consumers must be handed a FRESH collection instance. */
+function collectionIsCleanedUp(collection: Collection<any, string>): boolean {
+  return (collection as { status?: string }).status === "cleaned-up";
+}
+
+/** Everything that changes what the underlying subscription fetches. */
+function collectionOptionsKey(
+  doctype: string,
+  options?: Omit<FrappeCollectionOptionsConfig<any>, "sync">,
+): string {
+  return [
+    doctype,
+    JSON.stringify(options?.fields),
+    JSON.stringify(options?.filters),
+    JSON.stringify(options?.orderBy),
+    String(options?.limit),
+    String(options?.id),
+  ].join("|");
+}
+
+function scheduleEntryGc(
+  cache: Map<string, SharedCollectionEntry>,
+  key: string,
+  entry: SharedCollectionEntry,
+): void {
+  if (entry.gcTimer) clearTimeout(entry.gcTimer);
+  entry.gcTimer = setTimeout(() => {
+    entry.gcTimer = undefined;
+    if (entry.refCount > 0 || entry.cleaned) return;
+    // The hook refcount doesn't cover live queries: `useLiveQuery` attaches
+    // to the collection synchronously during render (before the retain
+    // effect commits) and detaches asynchronously after unmount (TanStack
+    // DB's own GC + an idle callback). Calling cleanup() while any query is
+    // attached permanently errors it ("Source collection … was manually
+    // cleaned up while live query … depends on it") — and a query erroring
+    // while still loading never notifies React, wedging `isLoading` gates
+    // (the "Loading workspaces…" stick). Defer GC while subscribers remain;
+    // the entry stays cached so a remount reuses the SAME live collection.
+    const subscriberCount = (entry.collection as { subscriberCount?: number }).subscriberCount ?? 0;
+    if (subscriberCount > 0) {
+      entry.gcForceDeadline ??= Date.now() + SHARED_COLLECTION_GC_FORCE_MS;
+      if (Date.now() < entry.gcForceDeadline) {
+        scheduleEntryGc(cache, key, entry);
+        return;
+      }
+      // Past the deadline: a leaked query (created by a render that never
+      // committed — TanStack DB never GCs a live query that never had a
+      // subscriber) is pinning the sync subscription + realtime room.
+      // Force-clean; any consumer that appears later gets a fresh instance
+      // via the stale-entry paths in getOrCreateSharedCollection / the hook.
+    }
+    entry.cleaned = true;
+    entry.gcForceDeadline = undefined;
+    if (cache.get(key) === entry) cache.delete(key);
+    // Best-effort: Collection.cleanup() stops the sync (unsubscribes from the
+    // SyncModule, leaving the realtime room). A consumer that raced eviction
+    // still works — TanStack DB restarts a cleaned-up collection on next use.
+    Promise.resolve(entry.collection.cleanup?.()).catch(() => {});
+  }, SHARED_COLLECTION_GC_MS);
+}
+
+function getOrCreateSharedCollection<TDoc extends object & { name: string; doctype: string }>(
+  syncModule: SyncModule,
+  doctype: string,
+  options: Omit<FrappeCollectionOptionsConfig<TDoc>, "sync"> | undefined,
+  key: string,
+): { cache: Map<string, SharedCollectionEntry>; entry: SharedCollectionEntry } {
+  let existingCache = sharedCollectionCaches.get(syncModule);
+  if (!existingCache) {
+    existingCache = new Map();
+    sharedCollectionCaches.set(syncModule, existingCache);
+  }
+  const cache = existingCache;
+  let entry = cache.get(key);
+  // A cached entry whose collection was cleaned up out-of-band (manual
+  // cleanup() call, TanStack DB's own idle GC) is stale: queries attached at
+  // cleanup time are permanently errored, so hand out a fresh instance.
+  if (entry && !entry.cleaned && collectionIsCleanedUp(entry.collection)) {
+    entry.cleaned = true;
+    if (entry.gcTimer) {
+      clearTimeout(entry.gcTimer);
+      entry.gcTimer = undefined;
+    }
+  }
+  if (!entry || entry.cleaned) {
+    const created: SharedCollectionEntry = {
+      collection: undefined as unknown as Collection<any, string>,
+      refCount: 0,
+      gcTimer: undefined,
+      gcForceDeadline: undefined,
+      errorHandlers: new Set(),
+      hasSyncError: false,
+      lastSyncError: undefined,
+      cleaned: false,
+    };
+    created.collection = createFrappeCollection<TDoc>(doctype, {
+      ...options,
+      sync: syncModule,
+      onSyncError: (error) => {
+        created.hasSyncError = true;
+        created.lastSyncError = error;
+        // Do NOT evict here. The error handlers below typically setState in
+        // consumers → re-render → render-time acquire; evicting now would
+        // hand that very re-render a fresh entry with a fresh failing sync,
+        // looping fetch → error → re-render forever (the retry storm — it
+        // OOM'd vitest workers and froze storybook renderers). The errored
+        // entry stays cached and shared so mounted consumers reach a stable
+        // fixpoint; releaseSharedCollection evicts it when the last holder
+        // unmounts, giving the NEXT mount (an explicit Retry) one fresh
+        // attempt.
+        for (const handler of created.errorHandlers) handler(error);
+      },
+    });
+    cache.set(key, created);
+    // Provisional GC: if no consumer ever retains this entry (the creating
+    // render was discarded), it must not leak a live subscription.
+    scheduleEntryGc(cache, key, created);
+    entry = created;
+  }
+  return { cache, entry };
+}
+
+function retainSharedCollection(
+  entry: SharedCollectionEntry,
+  onSyncError: (error: unknown) => void,
+): void {
+  entry.refCount++;
+  if (entry.gcTimer) {
+    clearTimeout(entry.gcTimer);
+    entry.gcTimer = undefined;
+  }
+  entry.gcForceDeadline = undefined;
+  entry.errorHandlers.add(onSyncError);
+  if (entry.hasSyncError) onSyncError(entry.lastSyncError);
+}
+
+function releaseSharedCollection(
+  cache: Map<string, SharedCollectionEntry>,
+  key: string,
+  entry: SharedCollectionEntry,
+  onSyncError: (error: unknown) => void,
+): void {
+  entry.errorHandlers.delete(onSyncError);
+  entry.refCount = Math.max(0, entry.refCount - 1);
+  if (entry.refCount > 0 || entry.cleaned) return;
+  if (entry.hasSyncError) {
+    // Last holder of an errored entry released: evict + mark cleaned NOW (no
+    // grace) so the next mount starts a fresh sync attempt. This is what
+    // makes a consumer's Retry-by-remount contract work — the remounting
+    // body's effect finds this entry `cleaned`, bumps, and acquires a fresh
+    // one. A grace period here would hand the retry the same stale error
+    // back. The underlying collection is cleaned up once its live queries
+    // detach (an immediate cleanup() would hard-error queries created in the
+    // same commit — unmount ordering runs this release before useLiveQuery's
+    // own detach).
+    entry.cleaned = true;
+    if (entry.gcTimer) {
+      clearTimeout(entry.gcTimer);
+      entry.gcTimer = undefined;
+    }
+    entry.gcForceDeadline = undefined;
+    if (cache.get(key) === entry) cache.delete(key);
+    cleanupEntryCollectionWhenIdle(entry);
+    return;
+  }
+  scheduleEntryGc(cache, key, entry);
+}
+
 /**
- * React hook that creates and memoizes a TanStack DB Collection backed by a Frappe doctype.
+ * Cleans up an already-evicted entry's collection once no live queries are
+ * attached — polling on the GC cadence, bounded by the force window (leaked
+ * queries from never-committed renders would otherwise pin the sync
+ * subscription forever). The entry must already be marked `cleaned` and
+ * removed from the cache: nothing re-acquires it, so the only remaining
+ * subscribers are queries mid-detach.
+ */
+function cleanupEntryCollectionWhenIdle(entry: SharedCollectionEntry): void {
+  const deadline = Date.now() + SHARED_COLLECTION_GC_FORCE_MS;
+  const tick = () => {
+    entry.gcTimer = undefined;
+    const subscriberCount = (entry.collection as { subscriberCount?: number }).subscriberCount ?? 0;
+    if (subscriberCount > 0 && Date.now() < deadline) {
+      entry.gcTimer = setTimeout(tick, SHARED_COLLECTION_GC_MS);
+      return;
+    }
+    Promise.resolve(entry.collection.cleanup?.()).catch(() => {});
+  };
+  entry.gcTimer = setTimeout(tick, SHARED_COLLECTION_GC_MS);
+}
+
+/**
+ * React hook that returns a TanStack DB Collection backed by a Frappe doctype.
  *
- * The collection is created once and stable across re-renders. It can be used with
- * `useLiveQuery` for reactive queries and has `.insert()`, `.update()`, `.delete()`
- * methods for mutations.
+ * Collections are shared: every hook instance with the same connection,
+ * doctype, and options (fields/filters/orderBy/limit/id) receives the SAME
+ * collection instance backed by ONE SyncModule subscription and ONE realtime
+ * room. Instances are refcounted — the shared collection is cleaned up
+ * shortly after the last consumer unmounts. `onSyncError` callbacks are
+ * per-consumer: each mounted consumer's handler fires (replayed on retain
+ * for late mounts). A failed initial sync is HELD by the entry while any
+ * consumer retains it — error-state re-renders reuse the same errored
+ * collection instead of looping fresh failing syncs — and the entry is
+ * evicted when the last consumer releases it, so the next mount (an
+ * explicit Retry remount) starts exactly one fresh attempt.
+ *
+ * The collection is stable across re-renders. It can be used with
+ * `useLiveQuery` for reactive queries and has `.insert()`, `.update()`,
+ * `.delete()` methods for mutations.
  *
  * @typeParam TDoc - The Frappe document type
  * @param config - Connection configuration (baseURL, auth)
@@ -135,41 +425,156 @@ export function useFrappeCollection<TDoc extends object & { name: string; doctyp
   doctype: string,
   options?: Omit<FrappeCollectionOptionsConfig<TDoc>, "sync">,
 ): Collection<TDoc, string> | undefined {
-  const collectionRef = useRef<Collection<TDoc, string> | undefined>(undefined);
-  const configKeyRef = useRef<string>("");
-
-  // Compute a stable key for the config (include fixtures flag so fixture vs live collections differ)
-  const configKey = config
-    ? `${config.baseURL}:${config.fixtures ? "fixture" : "live"}:${doctype}:${JSON.stringify(options?.fields)}:${JSON.stringify(options?.filters)}`
-    : "";
-
-  // Re-create the collection when config changes, OR when the collection is
-  // still undefined on the client (can happen after SSR where SyncModule is
-  // unavailable – the configKey was stored during SSR but the collection was
-  // never actually created).
-  const needsCollection = config && (configKey !== configKeyRef.current || !collectionRef.current);
-  if (needsCollection) {
+  // 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);
+  errorHandlerRef.current = options?.onSyncError;
+  const stableErrorHandler = useCallback((error: unknown) => {
+    errorHandlerRef.current?.(error);
+  }, []);
+
+  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
+  // 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.
+  let cache: Map<string, SharedCollectionEntry> | undefined;
+  let key = "";
+  let entry: SharedCollectionEntry | undefined;
+  if (config && doctype) {
     const syncModule = getSyncModule(config);
-    // During SSR, getSyncModule returns undefined – leave the collection
-    // as undefined so the component renders a loading state.  The client
-    // hydration pass will create the real collection.
     if (syncModule) {
-      collectionRef.current = createFrappeCollection<TDoc>(doctype, {
-        ...options,
-        sync: syncModule,
-      });
-      configKeyRef.current = configKey;
+      key = collectionOptionsKey(doctype, options);
+      ({ cache, entry } = getOrCreateSharedCollection<TDoc>(syncModule, doctype, options, key));
     }
-    // NOTE: configKeyRef is NOT set when syncModule is undefined (SSR),
-    // so on client hydration the hook will retry and create the collection.
   }
 
-  if (!config) {
-    collectionRef.current = undefined;
-    configKeyRef.current = "";
-  }
+  useEffect(() => {
+    if (!entry || !cache) return;
+    if (entry.cleaned || collectionIsCleanedUp(entry.collection)) {
+      // Lost an eviction race between render and commit (needs a multi-second
+      // stall) — re-render to pick up a fresh entry from the cache.
+      setStaleEntryBump((n) => n + 1);
+      return;
+    }
+    const retained = entry;
+    const retainedCache = cache;
+    const retainedKey = key;
+    retainSharedCollection(retained, stableErrorHandler);
+    // Revive on out-of-band cleanup (a manual cleanup() call or TanStack DB's
+    // own idle GC after every query detached): live queries attached at
+    // cleanup time are permanently errored and never notify React on their
+    // own, so mark the entry stale and re-render — consumers pick up a fresh
+    // collection instance, which restarts their live queries.
+    const unsubscribeStatus = (
+      retained.collection as {
+        on?: (event: "status:change", cb: (event: { status?: string }) => void) => () => void;
+      }
+    ).on?.("status:change", (event) => {
+      if (event?.status !== "cleaned-up" || retained.cleaned) return;
+      retained.cleaned = true;
+      setStaleEntryBump((n) => n + 1);
+    });
+    return () => {
+      unsubscribeStatus?.();
+      releaseSharedCollection(retainedCache, retainedKey, retained, stableErrorHandler);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [entry, stableErrorHandler]);
+
+  return entry ? (entry.collection as Collection<TDoc, string>) : undefined;
+}
+
+// ---------------------------------------------------------------------------
+// Connection / realtime hooks
+// ---------------------------------------------------------------------------
+
+/** Snapshot returned by {@link useFrappeConnection}. */
+export interface FrappeConnectionState {
+  /** Socket connected right now. */
+  connected: boolean;
+  /** Socket has connected at least once this session. */
+  everConnected: boolean;
+}
+
+const DISCONNECTED_STATE: FrappeConnectionState = Object.freeze({
+  connected: false,
+  everConnected: false,
+});
+
+/**
+ * React hook exposing the realtime socket state for the given connection.
+ *
+ * `connected` flips on every socket connect/disconnect; `everConnected`
+ * distinguishes "reconnecting" (show an indicator) from "realtime was never
+ * up" (fixture mode / SSR / no socket — show nothing). Fixture-backed
+ * configs always report disconnected/never-connected.
+ */
+export function useFrappeConnection(
+  config: UseFrappeCollectionConfig | undefined,
+): FrappeConnectionState {
+  const [state, setState] = useState<FrappeConnectionState>(DISCONNECTED_STATE);
+
+  useEffect(() => {
+    if (!config || config.fixtures || !isBrowser()) return;
+    const syncModule = getSyncModule(config);
+    if (!syncModule) return;
+
+    const read = () => {
+      const next = syncModule.getConnectionState();
+      setState((prev) =>
+        prev.connected === next.connected && prev.everConnected === next.everConnected
+          ? prev
+          : next,
+      );
+    };
+    read();
+    return syncModule.subscribeStore(read);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [config?.baseURL, !!config?.fixtures]);
+
+  return state;
+}
+
+/**
+ * React hook that joins a doctype's realtime room and invokes `onEvent`
+ * for every realtime event targeting that doctype (doc_update, list_update,
+ * doc_deleted). Intended for consumers that manage their own fetching
+ * (e.g. server-side paginated tables) and want live invalidation hints.
+ *
+ * The handler is kept in a ref, so an inline function is fine.
+ */
+export function useFrappeDoctypeEvents(
+  config: UseFrappeCollectionConfig | undefined,
+  doctype: string,
+  onEvent: (event: { type: string; payload?: unknown }) => void,
+  enabled = true,
+): void {
+  const handlerRef = useRef(onEvent);
+  handlerRef.current = onEvent;
+
+  useEffect(() => {
+    if (!enabled || !config || config.fixtures || !doctype || !isBrowser()) return;
+    const syncModule = getSyncModule(config);
+    if (!syncModule) return;
 
-  return collectionRef.current;
+    syncModule.watchDoctype(doctype);
+    const unsubscribe = syncModule.subscribeRealtimeEvents((event) => {
+      const payload = event.payload as { doctype?: string } | undefined;
+      if (payload?.doctype && payload.doctype !== doctype) return;
+      handlerRef.current({ type: event.type as string, payload: event.payload });
+    });
+
+    return () => {
+      unsubscribe();
+      syncModule.unwatchDoctype(doctype);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, config?.baseURL, !!config?.fixtures, doctype]);
 }
 
 // ---------------------------------------------------------------------------
@@ -279,9 +684,12 @@ export function useInfiniteScroll(config: UseInfiniteScrollConfig): UseInfiniteS
     }
   }, [hasMore, isLoading, isLoadingMore, onLoadMore, debounceMs]);
 
-  // Set up IntersectionObserver
+  // Set up IntersectionObserver — web only. isBrowser() is TRUE on React
+  // Native (it gates the sync pipeline, which runs there), but
+  // IntersectionObserver is a DOM API: gate on window presence + the
+  // constructor itself so the hook is a safe no-op on native.
   useEffect(() => {
-    if (!isBrowser() || !enabled) return;
+    if (!isWindowDefined || typeof IntersectionObserver === "undefined" || !enabled) return;
 
     const node = sentinelNodeRef.current;
     if (!node) return;