@agent-native/core 0.144.1 → 0.144.3

package/dist/client/settings/useBuilderStatus.js

@@ -4,6 +4,7 @@ import { trackEvent } from "../analytics.js";
 import { agentNativePath } from "../api-path.js";
 import { getCallbackOrigin } from "../frame.js";
 import { openMcpAppHostLink } from "../mcp-app-host.js";
+import { usePollLoop } from "../use-poll-loop.js";
 /**
  * Fetches Builder connection status from the neutral connection-status route.
  * The legacy /_agent-native/builder/status route remains available for older
@@ -80,6 +81,10 @@ export function useBuilderStatus({ enabled = true, } = {}) {
 }
 const POLL_INTERVAL_MS = 2000;
 const POLL_TIMEOUT_MS = 5 * 60 * 1000;
+// Fallback timeout for callers of fetchStatus() with no external signal of
+// their own (the initial status fetch, the popup-open branches in `start`).
+// The connect-flow poll loop below gets its timeout from usePollLoop instead.
+const STATUS_FETCH_ABORT_MS = 10_000;
 const CALLBACK_SUCCESS_STATUS_RETRY_MS = 500;
 const CALLBACK_SUCCESS_STATUS_RETRIES = 10;
 const BUILDER_CONNECT_PARAM = "_an_connect";
@@ -388,7 +393,6 @@ export function useBuilderConnectFlow(opts = {}) {
     // still-good direct URL (desktop) or refresh a new one inside the popup
     // gesture path (browser/editor embeds).
     const statusConnectUrlAtRef = useRef(null);
-    const pollRef = useRef(null);
     const connectStartedAtRef = useRef(null);
     const mountedRef = useRef(true);
     const notifiedConnectedRef = useRef(false);
@@ -396,25 +400,42 @@ export function useBuilderConnectFlow(opts = {}) {
     // caller passes an inline arrow function.
     const onConnectedRef = useRef(onConnected);
     onConnectedRef.current = onConnected;
-    const stopPoll = useCallback(() => {
-        if (pollRef.current) {
-            clearInterval(pollRef.current);
-            pollRef.current = null;
-        }
-    }, []);
-    const fetchStatus = useCallback(async () => {
+    // Tracking identity for whichever click is currently connecting, read by
+    // the poll loop's timeout-failure event below.
+    const activeTrackingRef = useRef({
+        source: trackingSource,
+        flow: trackingFlow,
+    });
+    // Accepts an optional external `signal` so the connect-flow poll loop below
+    // can cancel this fetch via its own timeout instead of racing a second,
+    // separately-constructed AbortController. Callers with no signal of their
+    // own (the initial status fetch, the popup-open branches in `start`) keep
+    // the internal fallback timeout.
+    const fetchStatus = useCallback(async (signal) => {
         if (!enabled)
             return null;
         const origin = getCallbackOrigin() || window.location.origin;
+        const ownController = !signal && typeof AbortController !== "undefined"
+            ? new AbortController()
+            : null;
+        const timeoutId = ownController
+            ? setTimeout(() => ownController.abort(), STATUS_FETCH_ABORT_MS)
+            : null;
         try {
-            const r = await fetch(new URL(agentNativePath("/_agent-native/connection-status/builder"), origin).href);
+            const r = await fetch(new URL(agentNativePath("/_agent-native/connection-status/builder"), origin).href, { signal: signal ?? ownController?.signal });
             if (!r.ok)
                 return null;
             return (await r.json());
         }
         catch {
+            // coercion-ok: null means "status unknown this tick" and callers hold
+            // their previous state rather than rendering a disconnected Builder.
             return null;
         }
+        finally {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+        }
     }, [enabled]);
     // Initial fetch + focus/visibility refresh so if the user completed the
     // flow in another tab (or a downgraded same-tab nav) we notice it. Also
@@ -433,7 +454,6 @@ export function useBuilderConnectFlow(opts = {}) {
             setStatusResolved(false);
             setStatusConnectUrl(null);
             statusConnectUrlAtRef.current = null;
-            stopPoll();
             return;
         }
         mountedRef.current = true;
@@ -501,17 +521,19 @@ export function useBuilderConnectFlow(opts = {}) {
             window.removeEventListener("focus", refresh);
             document.removeEventListener("visibilitychange", onVisible);
             window.removeEventListener("agent-engine:configured-changed", refresh);
-            stopPoll();
         };
-    }, [enabled, fetchStatus, stopPoll]);
+    }, [enabled, fetchStatus]);
     const start = useCallback((startOptions) => {
         if (!enabled)
             return;
-        stopPoll();
         const started = Date.now();
         const clickTrackingSource = startOptions?.trackingSource ?? trackingSource;
         const clickTrackingFlow = startOptions?.trackingFlow ?? trackingFlow;
         connectStartedAtRef.current = started;
+        activeTrackingRef.current = {
+            source: clickTrackingSource,
+            flow: clickTrackingFlow,
+        };
         setConnecting(true);
         setError(null);
         // Open SYNCHRONOUSLY inside the caller's click handler — any await
@@ -580,7 +602,6 @@ export function useBuilderConnectFlow(opts = {}) {
                     const openedByHost = await openBuilderConnectViaMcpHost(trackedHostUrl);
                     if (!mountedRef.current || openedByHost)
                         return;
-                    stopPoll();
                     connectStartedAtRef.current = null;
                     setConnecting(false);
                     setError("Couldn't open Builder from this chat host. Open this app in a browser tab and try Connect Builder (free tier available) again.");
@@ -628,7 +649,6 @@ export function useBuilderConnectFlow(opts = {}) {
                         catch {
                             // Ignore close failures.
                         }
-                        stopPoll();
                         connectStartedAtRef.current = null;
                         setConnecting(false);
                         setError("Couldn't start Builder connect. Refresh this page and try again.");
@@ -639,7 +659,6 @@ export function useBuilderConnectFlow(opts = {}) {
                         flow: clickTrackingFlow,
                     });
                     if (!navigateBuilderConnectPopup(opened, trackedFreshUrl)) {
-                        stopPoll();
                         connectStartedAtRef.current = null;
                         setConnecting(false);
                         setError("Couldn't navigate the Builder popup. Allow popups and try again.");
@@ -647,66 +666,72 @@ export function useBuilderConnectFlow(opts = {}) {
                 })();
             }
         }
-        pollRef.current = setInterval(async () => {
-            const s = await fetchStatus();
-            if (!mountedRef.current) {
-                stopPoll();
-                return;
-            }
-            if (s?.configured) {
-                stopPoll();
-                setConfigured(true);
-                setEnvManaged(!!s.envManaged);
-                setBuilderEnabled(!!s.builderEnabled);
-                const nextConnectUrl = s.cliAuthUrl ?? s.connectUrl ?? null;
-                setStatusConnectUrl(nextConnectUrl);
-                statusConnectUrlAtRef.current = nextConnectUrl ? Date.now() : null;
-                const org = s.orgName ?? null;
-                setOrgName(org);
-                setConnecting(false);
-                connectStartedAtRef.current = null;
-                notifiedConnectedRef.current = true;
-                notifyAgentEngineConfiguredChanged("builder-connect");
-                try {
-                    await onConnectedRef.current?.({ orgName: org });
-                }
-                catch {
-                    // Consumer's callback failed; we've already flipped the UI state
-                    // to connected. Swallow so we don't re-arm the flow.
-                }
-            }
-            else if (isCurrentConnectError(s?.connectError, started)) {
-                // OAuth callback ran but writeBuilderCredentials threw — surface the
-                // real error instead of letting the user wait 5 minutes for timeout.
-                stopPoll();
-                connectStartedAtRef.current = null;
-                setConnecting(false);
-                setError(`Couldn't save Builder credentials: ${s.connectError.message}. Try again or contact support.`);
-            }
-            else if (Date.now() - started > POLL_TIMEOUT_MS) {
-                stopPoll();
-                connectStartedAtRef.current = null;
-                setConnecting(false);
-                trackEvent("builder connect failed", {
-                    feature: "builder",
-                    stage: "client",
-                    reason: "timeout",
-                    source: clickTrackingSource,
-                    flow: cleanTrackingParam(clickTrackingFlow) ??
-                        inferBuilderConnectTrackingFlow(clickTrackingSource),
-                });
-                setError("Didn't hear back from Builder in 5 minutes. Allow popups and try again.");
-            }
-        }, POLL_INTERVAL_MS);
     }, [
         enabled,
         fetchStatus,
         popupUrl,
         statusConnectUrl,
-        stopPoll,
         trackingFlow,
         trackingSource,
     ]);
+    // Connect-flow poll: while `connecting`, checks the server every 2s for the
+    // popup callback to have landed. `enabled` here folds in both the hook's
+    // own `enabled` option and the 5-minute overall cap (checked below and
+    // enforced by flipping `connecting` false, which then disables this loop).
+    usePollLoop(async (signal) => {
+        const started = connectStartedAtRef.current;
+        if (started == null)
+            return;
+        const s = await fetchStatus(signal);
+        if (!mountedRef.current)
+            return;
+        if (s?.configured) {
+            setConfigured(true);
+            setEnvManaged(!!s.envManaged);
+            setBuilderEnabled(!!s.builderEnabled);
+            const nextConnectUrl = s.cliAuthUrl ?? s.connectUrl ?? null;
+            setStatusConnectUrl(nextConnectUrl);
+            statusConnectUrlAtRef.current = nextConnectUrl ? Date.now() : null;
+            const org = s.orgName ?? null;
+            setOrgName(org);
+            setConnecting(false);
+            connectStartedAtRef.current = null;
+            notifiedConnectedRef.current = true;
+            notifyAgentEngineConfiguredChanged("builder-connect");
+            try {
+                await onConnectedRef.current?.({ orgName: org });
+            }
+            catch {
+                // coercion-ok: the connection itself succeeded and the UI state is
+                // already flipped; re-arming the flow on a consumer callback failure
+                // would reconnect an account that is connected.
+            }
+        }
+        else if (isCurrentConnectError(s?.connectError, started)) {
+            // OAuth callback ran but writeBuilderCredentials threw \u2014 surface the
+            // real error instead of letting the user wait 5 minutes for timeout.
+            connectStartedAtRef.current = null;
+            setConnecting(false);
+            setError(`Couldn't save Builder credentials: ${s.connectError.message}. Try again or contact support.`);
+        }
+        else if (Date.now() - started > POLL_TIMEOUT_MS) {
+            connectStartedAtRef.current = null;
+            setConnecting(false);
+            const { source, flow } = activeTrackingRef.current;
+            trackEvent("builder connect failed", {
+                feature: "builder",
+                stage: "client",
+                reason: "timeout",
+                source,
+                flow: cleanTrackingParam(flow) ?? inferBuilderConnectTrackingFlow(source),
+            });
+            setError("Didn't hear back from Builder in 5 minutes. Allow popups and try again.");
+        }
+    }, {
+        intervalMs: POLL_INTERVAL_MS,
+        leading: false,
+        enabled: enabled && connecting,
+    });
     // Popup-side fast path: the callback page broadcasts a message so we stop
     // polling immediately rather than waiting for the next 2s tick.
     //
@@ -714,11 +739,10 @@ export function useBuilderConnectFlow(opts = {}) {
     // AND on window.message (legacy path for environments without BC or for
     // popups that still have opener access). Both paths are safe to have open
     // simultaneously \u2014 the first one to fire wins and the error is deduplicated
-    // by the stopPoll() call which is idempotent.
+    // by the setConnecting(false) call, which is idempotent.
     useEffect(() => {
         let channel = null;
         const handleError = (message) => {
-            stopPoll();
             connectStartedAtRef.current = null;
             setConnecting(false);
             setError(`Couldn't save Builder credentials: ${message}.`);
@@ -754,14 +778,12 @@ export function useBuilderConnectFlow(opts = {}) {
                     setOrgName(s.orgName ?? null);
                 }
                 if (connectError) {
-                    stopPoll();
                     connectStartedAtRef.current = null;
                     setConnecting(false);
                     setError(`Couldn't save Builder credentials: ${connectError.message}. Try again or contact support.`);
                 }
                 return;
             }
-            stopPoll();
             setHasFetchedStatus(true);
             setConfigured(true);
             setEnvManaged(!!s.envManaged);
@@ -819,7 +841,7 @@ export function useBuilderConnectFlow(opts = {}) {
             channel?.close();
             window.removeEventListener("message", handler);
         };
-    }, [fetchStatus, stopPoll]);
+    }, [fetchStatus]);
     return {
         configured,
         statusResolved,

package/dist/client/track.js

@@ -1,3 +1,4 @@
+import { getOrCreateAnalyticsSessionId } from "./analytics-session.js";
 import { agentNativePath } from "./api-path.js";
 /**
  * Fire an analytics event from browser/app code. This is the client-side twin
@@ -35,6 +36,7 @@ export function track(name, properties) {
         // Non-serializable properties — drop rather than throw into the caller.
         return Promise.resolve();
     }
+    const browserSessionId = getOrCreateAnalyticsSessionId();
     return fetch(agentNativePath("/_agent-native/track"), {
         method: "POST",
         headers: {
@@ -43,6 +45,11 @@ export function track(name, properties) {
             // middleware trusts it as a first-party marker. Matches the convention
             // used by other client writes (application-state, guided-questions).
             "X-Agent-Native-CSRF": "1",
+            // Same session the action client and agent chat send, so a client event
+            // and the server events from the same visit share one session.
+            ...(browserSessionId
+                ? { "X-Agent-Native-Session-Id": browserSessionId }
+                : {}),
         },
         body,
         keepalive: true,

package/dist/client/transcription/BuilderTranscriptionCta.js

@@ -10,12 +10,14 @@ import { IconBolt, IconLoader2 } from "@tabler/icons-react";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { agentNativePath } from "../api-path.js";
 import { openBuilderConnectPopup } from "../settings/useBuilderStatus.js";
+import { usePollLoop } from "../use-poll-loop.js";
+const POLL_TIMEOUT_MS = 5 * 60 * 1000;
 export function BuilderTranscriptionCta() {
     const [configured, setConfigured] = useState(null);
     const [connectUrl, setConnectUrl] = useState(null);
     const [connecting, setConnecting] = useState(false);
     const [error, setError] = useState(null);
-    const pollRef = useRef(null);
+    const connectStartedAtRef = useRef(null);
     const mountedRef = useRef(true);
     useEffect(() => {
         mountedRef.current = true;
@@ -37,46 +39,40 @@ export function BuilderTranscriptionCta() {
         });
         return () => {
             mountedRef.current = false;
-            if (pollRef.current)
-                clearInterval(pollRef.current);
         };
     }, []);
     const handleConnect = useCallback(() => {
-        if (pollRef.current)
-            clearInterval(pollRef.current);
+        connectStartedAtRef.current = Date.now();
         setConnecting(true);
         setError(null);
         openBuilderConnectPopup({
             url: connectUrl ?? undefined,
             source: "builder_transcription_cta",
         });
-        const start = Date.now();
-        pollRef.current = setInterval(async () => {
-            try {
-                const r = await fetch(agentNativePath("/_agent-native/builder/status"));
-                if (!r.ok)
-                    return;
-                const s = (await r.json());
-                if (!mountedRef.current) {
-                    clearInterval(pollRef.current);
-                    return;
-                }
-                if (s.configured) {
-                    clearInterval(pollRef.current);
-                    setConfigured(true);
-                    setConnecting(false);
-                }
-                else if (Date.now() - start > 5 * 60 * 1000) {
-                    clearInterval(pollRef.current);
-                    setConnecting(false);
-                    setError("Didn't hear back from Builder. Allow popups and try again.");
-                }
-            }
-            catch {
-                // transient — keep polling
-            }
-        }, 2000);
     }, [connectUrl]);
+    usePollLoop(async (signal) => {
+        const started = connectStartedAtRef.current;
+        if (started == null)
+            return;
+        const r = await fetch(agentNativePath("/_agent-native/builder/status"), {
+            signal,
+        });
+        if (!r.ok || !mountedRef.current)
+            return;
+        const s = (await r.json());
+        if (!mountedRef.current)
+            return;
+        if (s.configured) {
+            connectStartedAtRef.current = null;
+            setConfigured(true);
+            setConnecting(false);
+        }
+        else if (Date.now() - started > POLL_TIMEOUT_MS) {
+            connectStartedAtRef.current = null;
+            setConnecting(false);
+            setError("Didn't hear back from Builder. Allow popups and try again.");
+        }
+    }, { intervalMs: 2000, leading: false, enabled: connecting });
     // Already connected or still loading — render nothing
     if (configured === null || configured)
         return null;

package/dist/client/use-action.js

@@ -22,6 +22,7 @@
  * compatibility.
  */
 import { useQuery, useMutation, useQueryClient } from "@tanstack/react-query";
+import { getOrCreateAnalyticsSessionId } from "./analytics-session.js";
 import { trackEvent } from "./analytics.js";
 import { agentNativePath } from "./api-path.js";
 import { getBrowserTabId } from "./browser-tab-id.js";
@@ -192,8 +193,16 @@ async function performActionFetch(name, method, params, options) {
     if (buildId)
         headers["X-Agent-Native-Build-Id"] = buildId;
     const tz = resolveUserTimezone();
-    if (tz)
+    if (tz) {
         headers["x-user-timezone"] = tz;
+    }
+    // Same browser session the agent chat sends on an agent run, so an action
+    // called from the UI and an action the agent calls during that visit land on
+    // one `$session_id` in traces and session replay.
+    const browserSessionId = getOrCreateAnalyticsSessionId();
+    if (browserSessionId) {
+        headers["X-Agent-Native-Session-Id"] = browserSessionId;
+    }
     const init = {
         method,
         headers,

package/dist/client/use-agent-engine-configured.js

@@ -95,6 +95,17 @@ export function useAgentEngineConfigured(enabled = true, options) {
         let requestSeq = 0;
         let retryTimer;
         let retryAttempt = 0;
+        const scheduleRetry = (delay) => {
+            retryTimer = setTimeout(() => {
+                if (document.hidden) {
+                    // Tab is backgrounded — keep the same backoff instead of hitting
+                    // the network; the visibilitychange listener below recovers fast.
+                    scheduleRetry(delay);
+                    return;
+                }
+                void check();
+            }, delay);
+        };
         const check = async (options) => {
             const seq = ++requestSeq;
             if (retryTimer !== undefined) {
@@ -114,9 +125,7 @@ export function useAgentEngineConfigured(enabled = true, options) {
             // back short of a reload.
             const delay = Math.min(RETRY_BASE_MS * 2 ** retryAttempt, RETRY_MAX_MS);
             retryAttempt += 1;
-            retryTimer = setTimeout(() => {
-                void check();
-            }, delay);
+            scheduleRetry(delay);
         };
         const onConfiguredChanged = () => {
             void check();
@@ -130,15 +139,24 @@ export function useAgentEngineConfigured(enabled = true, options) {
             }
             void check({ missingFallback: true });
         };
+        const onVisibilityChange = () => {
+            if (!document.hidden && retryTimer !== undefined) {
+                clearTimeout(retryTimer);
+                retryTimer = undefined;
+                void check();
+            }
+        };
         void check();
         window.addEventListener("agent-engine:configured-changed", onConfiguredChanged);
         // A stale failed stream can arrive after a reconnect succeeds. Re-check the
         // current status before pinning the composer in setup.
         window.addEventListener("agent-chat:missing-api-key", onMissing);
+        document.addEventListener("visibilitychange", onVisibilityChange);
         return () => {
             cancelled = true;
             if (retryTimer !== undefined)
                 clearTimeout(retryTimer);
+            document.removeEventListener("visibilitychange", onVisibilityChange);
             window.removeEventListener("agent-engine:configured-changed", onConfiguredChanged);
             window.removeEventListener("agent-chat:missing-api-key", onMissing);
         };

package/dist/client/use-pausing-interval.d.ts

@@ -6,5 +6,11 @@
  * Pass `pollMs=0` to disable. Pass `pauseWhenHidden=false` to keep the
  * interval running even when the tab is hidden — the bell's browser-
  * notification popup loop uses that to still reach backgrounded tabs.
+ *
+ * @deprecated Use `usePollLoop` instead — it has the same visibility
+ * semantics plus a built-in per-attempt timeout and settle-then-reschedule
+ * (rather than `setInterval`) scheduling, so a hung `callback` can't wedge
+ * the loop. No remaining callers in this codebase; new polling code should
+ * use `usePollLoop` directly.
  */
 export declare function usePausingInterval(callback: () => void | Promise<void>, pollMs: number, pauseWhenHidden?: boolean): void;

package/dist/client/use-pausing-interval.js

@@ -7,6 +7,12 @@ import { useEffect } from "react";
  * Pass `pollMs=0` to disable. Pass `pauseWhenHidden=false` to keep the
  * interval running even when the tab is hidden — the bell's browser-
  * notification popup loop uses that to still reach backgrounded tabs.
+ *
+ * @deprecated Use `usePollLoop` instead — it has the same visibility
+ * semantics plus a built-in per-attempt timeout and settle-then-reschedule
+ * (rather than `setInterval`) scheduling, so a hung `callback` can't wedge
+ * the loop. No remaining callers in this codebase; new polling code should
+ * use `usePollLoop` directly.
  */
 export function usePausingInterval(callback, pollMs, pauseWhenHidden = true) {
     useEffect(() => {

package/dist/client/use-poll-loop.d.ts

@@ -0,0 +1,39 @@
+export interface UsePollLoopOptions {
+    /** Delay in ms between attempts while the tab is visible. */
+    intervalMs: number;
+    /** Per-attempt timeout. Default: `Math.max(timeoutFloorMs, intervalMs * 4)`. */
+    timeoutMs?: number;
+    /** Floor used by the default `timeoutMs`. Default: 10_000. */
+    timeoutFloorMs?: number;
+    /** Called when an attempt throws or times out. Default: swallow. */
+    onError?: (err: unknown) => void;
+    /** Run the first attempt immediately on mount. Default: true. */
+    leading?: boolean;
+    /** Set to false to tear the loop down without unmounting the caller. Default: true. */
+    enabled?: boolean;
+    /**
+     * true: fully stop while the tab is hidden, resuming immediately when it
+     * becomes visible again. false (default): keep polling at a relaxed
+     * cadence (`Math.max(intervalMs, hiddenIntervalFloorMs)`) — use this for
+     * loops that must still reach a backgrounded tab (e.g. browser
+     * notifications).
+     */
+    pauseWhenHidden?: boolean;
+    /** Floor for the relaxed hidden-tab cadence when `pauseWhenHidden` is false. Default: 10_000. */
+    hiddenIntervalFloorMs?: number;
+}
+export interface UsePollLoopHandle {
+    /** Cancel the pending wait and run an attempt now. */
+    pollNow: () => void;
+}
+/**
+ * Poll a network endpoint on a recurring cadence without hand-rolling a
+ * visibility check, an in-flight guard, or a request timeout — see
+ * `createPollEngine` for the underlying guarantees. `attempt` receives an
+ * `AbortSignal`; pass it to `fetch` for real cancellation on timeout.
+ *
+ * Supersedes `usePausingInterval`, which pauses/resumes on visibility but has
+ * no request timeout and schedules via `setInterval` rather than a
+ * settle-then-reschedule loop.
+ */
+export declare function usePollLoop(attempt: (signal: AbortSignal) => Promise<void>, options: UsePollLoopOptions): UsePollLoopHandle;

package/dist/client/use-poll-loop.js

@@ -0,0 +1,73 @@
+import { useEffect, useRef } from "react";
+import { createPollEngine } from "../shared/poll-engine.js";
+const HIDDEN_INTERVAL_FLOOR_MS = 10_000;
+function isDocumentHidden() {
+    return (typeof document !== "undefined" && document.visibilityState === "hidden");
+}
+/**
+ * Poll a network endpoint on a recurring cadence without hand-rolling a
+ * visibility check, an in-flight guard, or a request timeout — see
+ * `createPollEngine` for the underlying guarantees. `attempt` receives an
+ * `AbortSignal`; pass it to `fetch` for real cancellation on timeout.
+ *
+ * Supersedes `usePausingInterval`, which pauses/resumes on visibility but has
+ * no request timeout and schedules via `setInterval` rather than a
+ * settle-then-reschedule loop.
+ */
+export function usePollLoop(attempt, options) {
+    const attemptRef = useRef(attempt);
+    attemptRef.current = attempt;
+    const pollNowRef = useRef(() => { });
+    const { intervalMs, timeoutMs, timeoutFloorMs, onError, leading, enabled = true, pauseWhenHidden = false, hiddenIntervalFloorMs = HIDDEN_INTERVAL_FLOOR_MS, } = options;
+    useEffect(() => {
+        if (!enabled)
+            return;
+        const engine = createPollEngine((signal) => attemptRef.current(signal), {
+            intervalMs: pauseWhenHidden
+                ? intervalMs
+                : () => isDocumentHidden()
+                    ? Math.max(intervalMs, hiddenIntervalFloorMs)
+                    : intervalMs,
+            timeoutMs,
+            timeoutFloorMs,
+            onError,
+            leading,
+        });
+        pollNowRef.current = () => engine.pollNow();
+        // Mounting in an already-hidden tab (background restore, prerender) must
+        // not fire the leading attempt when pauseWhenHidden promises a full pause
+        // while hidden — the visibility handler below starts the loop instead.
+        if (!pauseWhenHidden || !isDocumentHidden())
+            engine.start();
+        const onVisibilityChange = () => {
+            if (isDocumentHidden()) {
+                if (pauseWhenHidden)
+                    engine.stop();
+                else
+                    engine.reschedule();
+            }
+            else if (pauseWhenHidden) {
+                engine.start();
+            }
+            else {
+                engine.pollNow();
+            }
+        };
+        document.addEventListener("visibilitychange", onVisibilityChange);
+        return () => {
+            engine.stop();
+            pollNowRef.current = () => { };
+            document.removeEventListener("visibilitychange", onVisibilityChange);
+        };
+    }, [
+        intervalMs,
+        timeoutMs,
+        timeoutFloorMs,
+        onError,
+        leading,
+        enabled,
+        pauseWhenHidden,
+        hiddenIntervalFloorMs,
+    ]); // eslint-disable-line react-hooks/exhaustive-deps
+    return { pollNow: () => pollNowRef.current() };
+}