@gonvex/react 0.5.2-staging.2 → 0.5.2-staging.20

package/dist/index.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import { GonvexClientError, control } from "@gonvex/client";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore as useReactSyncExternalStore } from "react";
+import { usePaintExternalStore as useSyncExternalStore } from "./paint-external-store.js";
+import { GonvexClientError, control, entityStatusFromIntents } from "@gonvex/client";
 export { GonvexClientError } from "@gonvex/client";
 export { createFirebaseAuthAdapter } from "@gonvex/client";
 const GonvexContext = createContext(null);
@@ -94,8 +95,13 @@ export function GonvexProviderWithAuth(props) {
 // code+PKCE exchange runs once. Without this, the first effect's finally
 // clears sessionStorage PKCE before the remount can finish verification.
 const authBootstrapPromises = new Map();
+// Creating a tenant provisions its database and runs every tenant migration,
+// which routinely takes longer than the default reducer timeout. Timing out
+// made onboarding report a failure for a tenant that was still being created.
+const TENANT_CREATE_TIMEOUT_MS = 120_000;
 export function GonvexAuthProvider(props) {
     const runtimeUrl = props.runtimeUrl.replace(/\/+$/, "");
+    const hasExplicitInitialTenant = props.initialTenantId !== undefined;
     const initialTenantId = props.initialTenantId?.trim() || undefined;
     const callbackPath = normalizeCallbackPath(props.callbackPath ?? "/");
     const storageKey = `gonvex-auth:${encodeURIComponent(runtimeUrl)}:${props.projectId}`;
@@ -103,23 +109,55 @@ export function GonvexAuthProvider(props) {
     const initialAuthRef = useRef(null);
     if (!initialAuthRef.current) {
         const persisted = readAuthSession(storageKey);
+        const warmSession = props.externalAuth
+            ? reusableExternalAuthSession(persisted, initialTenantId, props.externalAuth.provider, hasExplicitInitialTenant)
+            : null;
+        // A reload keeps developer mode only while this tab's stored grant
+        // belongs to the same account and project and has not expired.
+        const candidate = warmSession ?? persisted;
+        const storedDeveloper = candidate
+            ? readDeveloperGrant(storageKey, props.projectId, candidate.account.id)
+            : null;
+        clearDeveloperGrants(storageKey, storedDeveloper?.accountId);
         initialAuthRef.current = {
             session: persisted,
-            warmSession: props.externalAuth
-                ? reusableExternalAuthSession(persisted, initialTenantId, props.externalAuth.provider)
+            warmSession,
+            developer: storedDeveloper
+                ? {
+                    active: true,
+                    tenantId: storedDeveloper.tenantId,
+                    grantId: storedDeveloper.grantId,
+                    expiresAt: storedDeveloper.expiresAt,
+                    accountId: storedDeveloper.accountId,
+                    originalTenantId: storedDeveloper.originalTenantId,
+                    clientInstalled: false,
+                    restoring: true,
+                }
                 : null,
+            developerToken: storedDeveloper?.token ?? null,
         };
     }
     const initialAuth = initialAuthRef.current;
-    const [session, setSession] = useState(initialAuth.session);
+    // The session exposed to React must be the same scoped session installed on
+    // the client. On an explicit landlord origin, warmSession intentionally
+    // clears a persisted tenant selection. Keeping the unscoped persisted value
+    // here makes the tenant-directory effect see a different auth scope and skip
+    // its authoritative Control Query, leaving deleted tenants in the UI.
+    const initialSession = initialAuth.warmSession ?? initialAuth.session;
+    const [session, setSession] = useState(initialSession);
     const [isLoading, setIsLoading] = useState(!initialAuth.warmSession);
     const [sessionState, setSessionState] = useState(initialAuth.warmSession ? "reconnecting" : "loading");
     const [error, setError] = useState(null);
     const [refreshRetryAt, setRefreshRetryAt] = useState(0);
-    const [developerMode, setDeveloperMode] = useState({ active: false });
+    const [canonicalRefreshRequested, setCanonicalRefreshRequested] = useState(false);
+    const [developerMode, setDeveloperMode] = useState(() => initialAuth.developer ? publicDeveloperMode(initialAuth.developer) : { active: false });
     const sessionRef = useRef(session);
     const refreshRef = useRef(null);
-    const developerModeRef = useRef(null);
+    const developerModeRef = useRef(initialAuth.developer);
+    // The newest grant credential lives beside, never inside, the developer
+    // state so it cannot leak through the public auth value.
+    const developerTokenRef = useRef(initialAuth.developerToken);
+    const pendingDeveloperTokenRef = useRef(null);
     // A persisted session is only a candidate until bootstrap/external auth has
     // installed its complete project + tenant + account scope on the client.
     // Never let the token-refresh effect authenticate an account-only socket in
@@ -130,28 +168,51 @@ export function GonvexAuthProvider(props) {
     const installedWarmSessionRef = useRef(false);
     if (initialAuth.warmSession && !installedWarmSessionRef.current) {
         installedWarmSessionRef.current = true;
-        installClientSession(props.client, props.projectId, initialAuth.warmSession);
+        const developer = developerModeRef.current;
+        const developerToken = developerTokenRef.current;
+        if (developer && developerToken) {
+            installDeveloperClientAuth(props.client, props.projectId, developer, developerToken);
+            developer.clientInstalled = true;
+        }
+        else {
+            installClientSession(props.client, props.projectId, initialAuth.warmSession);
+        }
     }
     const installSession = useCallback((next, persist = true, installClientAuth = true) => {
         sessionRef.current = next;
+        const developer = developerModeRef.current;
+        if (developer && next?.account.id !== developer.accountId) {
+            // Signing out or switching accounts ends developer mode. The grant was
+            // issued to the previous account and must not survive into this one.
+            developerModeRef.current = null;
+            developerTokenRef.current = null;
+            setDeveloperMode({ active: false });
+            clearDeveloperGrants(storageKey);
+        }
+        const activeDeveloper = developerModeRef.current;
         if (next) {
             if (persist)
                 safeLocalStorageSet(storageKey, JSON.stringify(next));
-            if (!developerModeRef.current && installClientAuth) {
-                installClientSession(props.client, props.projectId, next);
+            if (!activeDeveloper) {
+                if (installClientAuth)
+                    installClientSession(props.client, props.projectId, next);
+                installedClientScopeRef.current = authSessionScope(props.projectId, next);
             }
-            if (!developerModeRef.current) {
+            else if (!activeDeveloper.clientInstalled && installClientAuth && developerTokenRef.current) {
+                // A grant restored after reload waits for its account session to be
+                // confirmed, then connects with the grant instead of that session.
+                installDeveloperClientAuth(props.client, props.projectId, activeDeveloper, developerTokenRef.current);
+                activeDeveloper.clientInstalled = true;
                 installedClientScopeRef.current = authSessionScope(props.projectId, next);
             }
         }
         else {
             if (persist)
                 safeLocalStorageRemove(storageKey);
-            if (!developerModeRef.current && installClientAuth) {
+            if (installClientAuth) {
                 props.client.setAuth({ project: props.projectId, tenant: undefined, token: undefined, identity: undefined });
             }
-            if (!developerModeRef.current)
-                installedClientScopeRef.current = null;
+            installedClientScopeRef.current = null;
         }
         setSession(next);
     }, [props.client, props.projectId, storageKey]);
@@ -183,7 +244,7 @@ export function GonvexAuthProvider(props) {
                 || message.targetOrigin !== window.location.origin)
                 return;
             const candidate = message.session ?? null;
-            const reusable = reusableExternalAuthSession(candidate, initialTenantId, props.externalAuth?.provider ?? candidate?.account.provider ?? "");
+            const reusable = reusableExternalAuthSession(candidate, initialTenantId, props.externalAuth?.provider ?? candidate?.account.provider ?? "", hasExplicitInitialTenant);
             if (!reusable)
                 return;
             installSession(reusable);
@@ -194,25 +255,46 @@ export function GonvexAuthProvider(props) {
         window.addEventListener("message", onMessage);
         window.parent.postMessage({ type: SESSION_HANDOFF_READY, nonce }, parentOrigin);
         return () => window.removeEventListener("message", onMessage);
-    }, [initialTenantId, installSession, props.crossOriginHandoff, props.externalAuth?.provider, props.projectId, runtimeUrl]);
+    }, [hasExplicitInitialTenant, initialTenantId, installSession, props.crossOriginHandoff, props.externalAuth?.provider, props.projectId, runtimeUrl]);
     const restoreAccountSession = useCallback(() => {
         const developer = developerModeRef.current;
         if (!developer)
             return;
         developerModeRef.current = null;
+        developerTokenRef.current = null;
+        clearDeveloperGrants(storageKey);
         setDeveloperMode({ active: false });
         const current = sessionRef.current;
         const activeTenantId = current?.tenants.some((tenant) => tenant.id === developer.originalTenantId)
             ? developer.originalTenantId
             : current?.activeTenantId;
         installSession(current ? { ...current, activeTenantId } : null);
-    }, [installSession]);
+    }, [installSession, storageKey]);
     useEffect(() => props.client.onAuthError((message) => {
-        if (!developerModeRef.current)
+        const developer = developerModeRef.current;
+        if (!developer)
             return;
         restoreAccountSession();
-        setError(message || "Developer mode ended because its authorization is no longer valid.");
+        // A grant restored after a reload may already be gone (exited in another
+        // tab, revoked, or expired server-side). Falling back to the account
+        // session is the expected outcome there, not an error to surface.
+        setError(developer.restoring ? null : message || "Developer mode ended because its authorization is no longer valid.");
     }), [props.client, restoreAccountSession]);
+    useEffect(() => props.client.onDeveloperCredential?.((token) => {
+        // The runtime consumed the previous credential and issued a single-use
+        // successor. Keep only the newest one so a reload can resume the grant.
+        const pending = pendingDeveloperTokenRef.current;
+        if (pending) {
+            pending.token = token;
+            return;
+        }
+        const developer = developerModeRef.current;
+        if (!developer?.clientInstalled)
+            return;
+        developer.restoring = false;
+        developerTokenRef.current = token;
+        writeDeveloperGrant(storageKey, props.projectId, developer, token);
+    }), [props.client, props.projectId, storageKey]);
     useEffect(() => {
         if (!developerMode.active || !developerMode.expiresAt)
             return;
@@ -273,8 +355,9 @@ export function GonvexAuthProvider(props) {
                 // Explicit signOut() clears both systems, and its localStorage removal
                 // propagates to every tab through the storage listener below.
                 const canonical = readAuthSession(storageKey) ?? sessionRef.current;
-                const reusableCanonical = reusableExternalAuthSession(canonical, initialTenantId, adapter.provider);
+                const reusableCanonical = reusableExternalAuthSession(canonical, initialTenantId, adapter.provider, hasExplicitInitialTenant);
                 if (reusableCanonical) {
+                    setCanonicalRefreshRequested(false);
                     if (!sameInstalledAuthSession(sessionRef.current, reusableCanonical)) {
                         installSession(reusableCanonical, false);
                     }
@@ -282,15 +365,18 @@ export function GonvexAuthProvider(props) {
                     setIsLoading(false);
                 }
                 else if (canonical) {
-                    // Keep a refreshable but expired session private until the external
-                    // provider supplies a current identity token. Its tenant Replica is
-                    // not safe to expose under an expired access token.
+                    // Firebase persistence is origin-scoped, while the canonical Gonvex
+                    // session is deliberately handed across tenant subdomains. Refresh
+                    // that canonical session directly instead of waiting forever for a
+                    // Firebase user that may never exist on this sibling origin.
                     sessionRef.current = canonical;
                     setSession(canonical);
                     setSessionState("loading");
                     setIsLoading(true);
+                    setCanonicalRefreshRequested(true);
                 }
                 else {
+                    setCanonicalRefreshRequested(false);
                     installSession(null, false);
                     setSessionState("signedOut");
                     setIsLoading(false);
@@ -298,12 +384,13 @@ export function GonvexAuthProvider(props) {
                 setError(null);
                 return;
             }
+            setCanonicalRefreshRequested(false);
             // A valid canonical Gonvex session remains usable while Firebase rotates
             // its identity token. Keep the application mounted and perform that
             // exchange in the background; unmounting the entire tree here destroys
             // open dialogs and other local UI state in every existing tab.
             const canonicalSession = readAuthSession(storageKey) ?? sessionRef.current;
-            const reusableCanonicalSession = reusableExternalAuthSession(canonicalSession, initialTenantId, adapter.provider);
+            const reusableCanonicalSession = reusableExternalAuthSession(canonicalSession, initialTenantId, adapter.provider, hasExplicitInitialTenant);
             if (reusableCanonicalSession) {
                 // A reload already has a valid canonical Gonvex session. Install its
                 // complete tenant scope before releasing application children; the
@@ -326,7 +413,8 @@ export function GonvexAuthProvider(props) {
                 // is waiting for the cross-tab exchange lock. Read the shared winner
                 // inside the lock instead of replaying this tab's stale in-memory
                 // refresh token.
-                const current = readAuthSession(storageKey) ?? sessionRef.current;
+                const storedCurrent = readAuthSession(storageKey) ?? sessionRef.current;
+                const current = scopeSessionForInitialTenant(storedCurrent, initialTenantId, hasExplicitInitialTenant) ?? storedCurrent;
                 attemptedRefreshToken = current?.refreshToken ?? "";
                 if (!current) {
                     props.client.setAuth({
@@ -334,7 +422,9 @@ export function GonvexAuthProvider(props) {
                         identity: { sub: identity.uid, iss: identity.issuer ?? adapter.provider },
                     });
                 }
-                const tenantId = initialTenantId ?? current?.activeTenantId;
+                const tenantId = hasExplicitInitialTenant
+                    ? initialTenantId
+                    : current?.activeTenantId;
                 const grant = await props.client.action(control.auth.exchangeExternalToken, {
                     provider: adapter.provider,
                     token,
@@ -345,7 +435,13 @@ export function GonvexAuthProvider(props) {
             }).then((next) => {
                 if (cancelled || currentGeneration !== generation)
                     return;
-                installSession(next);
+                // A user can select a different tenant while the provider exchange is
+                // still in flight. The returned access token is account-wide, but its
+                // activeTenantId reflects the scope captured when the exchange began.
+                // Preserve the latest locally accepted tenant selection so a stale
+                // background exchange cannot bounce a cross-origin handoff back to the
+                // previously active tenant.
+                installSession(preserveActiveTenant(next, sessionRef.current ?? undefined));
                 setSessionState("current");
                 setError(null);
             }).catch((cause) => {
@@ -384,7 +480,7 @@ export function GonvexAuthProvider(props) {
             generation += 1;
             unsubscribe();
         };
-    }, [initialTenantId, installSession, props.client, props.externalAuth, props.projectId, storageKey]);
+    }, [hasExplicitInitialTenant, initialTenantId, installSession, props.client, props.externalAuth, props.projectId, storageKey]);
     const refreshSession = useCallback(async (force = false) => {
         if (refreshRef.current)
             return refreshRef.current;
@@ -393,35 +489,36 @@ export function GonvexAuthProvider(props) {
             ? `${storageKey}:external-session`
             : `${storageKey}:refresh`;
         const request = withBrowserAuthLock(lockName, async () => {
-            const current = readAuthSession(storageKey) ?? sessionRef.current;
+            const storedCurrent = readAuthSession(storageKey) ?? sessionRef.current;
+            const current = scopeSessionForInitialTenant(storedCurrent, initialTenantId, hasExplicitInitialTenant) ?? storedCurrent;
             if (!current)
                 return null;
             if (!force && current.expiresAt > Date.now() + 60_000)
                 return current;
+            if (current.refreshExpiresAt <= Date.now())
+                return null;
             if (props.externalAuth) {
+                if (current.account.provider !== props.externalAuth.provider)
+                    return null;
                 attemptedRefreshToken = current.refreshToken;
                 const token = await props.externalAuth.getIdToken(force);
-                if (!token) {
-                    // External providers such as Firebase can briefly report no current
-                    // user while a new tab hydrates IndexedDB. That is not an explicit
-                    // sign-out and must not erase the still-valid canonical Gonvex
-                    // session shared by every tab. The provider callback will retry the
-                    // exchange once its identity is ready.
-                    setRefreshRetryAt(Date.now() + 1_000);
-                    return current;
-                }
-                const grant = await props.client.action(control.auth.exchangeExternalToken, {
-                    provider: props.externalAuth.provider,
-                    token,
-                    ...(current.activeTenantId ? { tenantId: current.activeTenantId } : {}),
-                    previousRefreshToken: current.refreshToken,
-                });
-                const next = sessionFromNativeGrant(grant, current);
+                const grant = token
+                    ? await props.client.action(control.auth.exchangeExternalToken, {
+                        provider: props.externalAuth.provider,
+                        token,
+                        ...(current.activeTenantId ? { tenantId: current.activeTenantId } : {}),
+                        previousRefreshToken: current.refreshToken,
+                    })
+                    : await props.client.action(control.auth.refreshSession, {
+                        refreshToken: current.refreshToken,
+                    });
+                const refreshed = sessionFromNativeGrant(grant, current);
+                const next = scopeSessionForInitialTenant(refreshed, initialTenantId, hasExplicitInitialTenant);
+                if (!next)
+                    return null;
                 safeLocalStorageSet(storageKey, JSON.stringify(next));
                 return next;
             }
-            if (current.refreshExpiresAt <= Date.now())
-                return null;
             attemptedRefreshToken = current.refreshToken;
             const grant = await props.client.action(control.auth.refreshSession, { refreshToken: current.refreshToken });
             const next = sessionFromNativeGrant(grant, current);
@@ -435,8 +532,13 @@ export function GonvexAuthProvider(props) {
             if (next) {
                 setRefreshRetryAt(0);
                 setError(null);
+                setSessionState("current");
+            }
+            else {
+                setSessionState("signedOut");
             }
             installSession(next);
+            setIsLoading(false);
             return next;
         }).catch((cause) => {
             const latest = readAuthSession(storageKey);
@@ -451,6 +553,8 @@ export function GonvexAuthProvider(props) {
             if (isFatalRefreshError(cause)) {
                 installSession(null);
                 setRefreshRetryAt(0);
+                setSessionState("signedOut");
+                setIsLoading(false);
                 setError(cause instanceof Error ? cause.message : "Your session expired. Please sign in again.");
                 return null;
             }
@@ -458,6 +562,8 @@ export function GonvexAuthProvider(props) {
             // destroy a valid refresh credential. Keep it and retry shortly.
             if (sessionRef.current)
                 setRefreshRetryAt(Date.now() + 5_000);
+            setSessionState("degraded");
+            setIsLoading(false);
             setError("Gonvex could not refresh your session. Retrying shortly…");
             return null;
         }).finally(() => {
@@ -465,7 +571,19 @@ export function GonvexAuthProvider(props) {
         });
         refreshRef.current = request;
         return request;
-    }, [installSession, props.client, props.externalAuth, storageKey]);
+    }, [hasExplicitInitialTenant, initialTenantId, installSession, props.client, props.externalAuth, storageKey]);
+    useEffect(() => {
+        if (!canonicalRefreshRequested)
+            return;
+        let cancelled = false;
+        void refreshSession().finally(() => {
+            if (!cancelled)
+                setCanonicalRefreshRequested(false);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, [canonicalRefreshRequested, refreshSession]);
     useEffect(() => {
         if (!session)
             return;
@@ -557,9 +675,14 @@ export function GonvexAuthProvider(props) {
         const revokeSession = current
             ? props.client.reducer(control.auth.logout, { refreshToken: current.refreshToken, all: options?.allDevices === true }).catch(() => undefined)
             : Promise.resolve();
+        const developer = developerModeRef.current;
+        const revokeDeveloper = developer
+            ? props.client.reducer(control.developer.exit, { grantId: developer.grantId }).catch(() => undefined)
+            : Promise.resolve();
+        // installSession(null) also ends developer mode and clears its stored grant.
         installSession(null);
         const signOutExternal = props.externalAuth?.signOut?.() ?? Promise.resolve();
-        await Promise.all([revokeSession, signOutExternal]);
+        await Promise.all([revokeSession, revokeDeveloper, signOutExternal]);
     }, [installSession, props.client, props.externalAuth]);
     const fetchAccessToken = useCallback(async (args) => {
         const current = sessionRef.current;
@@ -626,7 +749,7 @@ export function GonvexAuthProvider(props) {
         const tenant = await props.client.reducer(control.tenants.create, {
             name,
             ...(options?.domain ? { domain: options.domain } : {}),
-        });
+        }, { timeoutMs: TENANT_CREATE_TIMEOUT_MS });
         const current = sessionRef.current;
         installSession({ ...current, tenants: [...current.tenants.filter((item) => item.id !== tenant.id), tenant], activeTenantId: tenant.id });
         return tenant;
@@ -649,7 +772,20 @@ export function GonvexAuthProvider(props) {
         const frame = document.createElement("iframe");
         frame.hidden = true;
         frame.setAttribute("aria-hidden", "true");
-        frame.src = receiver.toString();
+        const receiverMethod = handoff.receiverMethod ?? "get";
+        let receiverForm = null;
+        if (receiverMethod === "get") {
+            frame.src = receiver.toString();
+        }
+        else {
+            const frameName = `gonvex-session-handoff-${nonce}`;
+            frame.name = frameName;
+            receiverForm = document.createElement("form");
+            receiverForm.hidden = true;
+            receiverForm.method = "post";
+            receiverForm.action = receiver.toString();
+            receiverForm.target = frameName;
+        }
         await new Promise((resolve, reject) => {
             const timeout = window.setTimeout(() => {
                 cleanup();
@@ -658,6 +794,7 @@ export function GonvexAuthProvider(props) {
             const cleanup = () => {
                 window.clearTimeout(timeout);
                 window.removeEventListener("message", onMessage);
+                receiverForm?.remove();
                 frame.remove();
             };
             const onMessage = (event) => {
@@ -683,6 +820,10 @@ export function GonvexAuthProvider(props) {
             };
             window.addEventListener("message", onMessage);
             document.body.append(frame);
+            if (receiverForm) {
+                document.body.append(receiverForm);
+                receiverForm.submit();
+            }
         });
     }, [props.crossOriginHandoff, props.projectId, runtimeUrl]);
     const inviteMember = useCallback(async (tenantId, email, options) => {
@@ -719,6 +860,10 @@ export function GonvexAuthProvider(props) {
         if (!grant.id || !grant.token || !Number.isFinite(Date.parse(expiresAt))) {
             throw new Error("Gonvex returned an invalid developer grant.");
         }
+        // The activation token is consumed by this authentication; the runtime
+        // answers with the reconnect credential that a reload must use instead.
+        const pending = { token: grant.token };
+        pendingDeveloperTokenRef.current = pending;
         try {
             await props.client.authenticate({
                 project: props.projectId,
@@ -738,10 +883,25 @@ export function GonvexAuthProvider(props) {
             });
             throw cause;
         }
-        const next = { active: true, tenantId, grantId: grant.id, expiresAt, originalTenantId: current.activeTenantId };
+        finally {
+            if (pendingDeveloperTokenRef.current === pending)
+                pendingDeveloperTokenRef.current = null;
+        }
+        const next = {
+            active: true,
+            tenantId,
+            grantId: grant.id,
+            expiresAt,
+            accountId: current.account.id,
+            originalTenantId: current.activeTenantId,
+            clientInstalled: true,
+            restoring: false,
+        };
         developerModeRef.current = next;
-        setDeveloperMode({ active: true, tenantId, grantId: grant.id, expiresAt });
-    }, [props.client, props.projectId]);
+        developerTokenRef.current = pending.token;
+        writeDeveloperGrant(storageKey, props.projectId, next, pending.token);
+        setDeveloperMode(publicDeveloperMode(next));
+    }, [props.client, props.projectId, storageKey]);
     const exitDeveloperMode = useCallback(async () => {
         const developer = developerModeRef.current;
         if (!developer?.grantId)
@@ -756,7 +916,9 @@ export function GonvexAuthProvider(props) {
     const activeTenant = session?.tenants.find((tenant) => tenant.id === visibleTenantId) ?? null;
     const authValue = useMemo(() => ({
         isLoading,
-        isAuthenticated: Boolean(session && session.refreshExpiresAt > Date.now()),
+        isAuthenticated: Boolean(session
+            && session.expiresAt > Date.now()
+            && session.refreshExpiresAt > Date.now()),
         sessionState,
         fetchAccessToken,
         account: session?.account ?? null,
@@ -778,7 +940,7 @@ export function GonvexAuthProvider(props) {
         enterDeveloperMode,
         exitDeveloperMode,
     }), [acceptInvitation, activeTenant, createTenant, developerMode, enterDeveloperMode, error, exitDeveloperMode, fetchAccessToken, handoffSessionTo, inviteMember, isLoading, refreshMemberships, revokeInvitation, session, sessionState, setActiveTenant, signIn, signInWithPassword, signInWithProvider, signOut]);
-    return (_jsx(ManagedAuthContext.Provider, { value: authValue, children: _jsx(GonvexAuthContext.Provider, { value: authValue, children: _jsx(GonvexProvider, { client: props.client, children: isLoading ? null : props.children }) }) }));
+    return (_jsx(ManagedAuthContext.Provider, { value: authValue, children: _jsx(GonvexAuthContext.Provider, { value: authValue, children: _jsx(GonvexProvider, { client: props.client, children: isLoading ? (props.loadingFallback ?? null) : props.children }) }) }));
 }
 export function useGonvexAuth() {
     const value = useContext(ManagedAuthContext);
@@ -901,10 +1063,17 @@ function sessionFromNativeGrant(value, previous) {
         throw new GonvexAuthRequestError("Gonvex returned an invalid native session.", 502);
     }
     const session = value;
-    const activeTenantId = previous && session.tenants.some((tenant) => tenant.id === previous.activeTenantId)
+    return preserveActiveTenant(session, previous);
+}
+function preserveActiveTenant(session, previous) {
+    const activeTenantId = previous
+        && previous.account.id === session.account.id
+        && session.tenants.some((tenant) => tenant.id === previous.activeTenantId)
         ? previous.activeTenantId
         : session.activeTenantId;
-    return { ...session, activeTenantId };
+    return activeTenantId === session.activeTenantId
+        ? session
+        : { ...session, activeTenantId };
 }
 async function requestGonvexAuthToken(runtimeUrl, body) {
     const controller = new AbortController();
@@ -929,7 +1098,16 @@ async function requestGonvexAuthToken(runtimeUrl, body) {
     }
 }
 function isFatalRefreshError(cause) {
-    return cause instanceof GonvexAuthRequestError && (cause.status === 400 || cause.status === 401 || cause.status === 403);
+    if (cause instanceof GonvexAuthRequestError) {
+        return cause.status === 400 || cause.status === 401 || cause.status === 403;
+    }
+    if (!(cause instanceof GonvexClientError))
+        return false;
+    if (cause.code === "auth")
+        return true;
+    if (cause.code !== "server")
+        return false;
+    return /invalid or expired refresh token|refresh token (?:reuse detected|was already rotated)|login was revoked/i.test(cause.message);
 }
 function isFatalExternalExchangeError(cause) {
     if (cause instanceof GonvexAuthRequestError) {
@@ -1017,6 +1195,87 @@ const WARM_SESSION_ACCESS_SAFETY_MS = 30_000;
 function authSessionScope(projectId, session) {
     return `${projectId}\u0000${session.activeTenantId ?? ""}\u0000${session.account.id}`;
 }
+const DEVELOPER_GRANT_RESTORE_MARGIN_MS = 5_000;
+function developerGrantStoragePrefix(storageKey) {
+    return `${storageKey}:developer:`;
+}
+function developerGrantStorageKey(storageKey, accountId) {
+    return `${developerGrantStoragePrefix(storageKey)}${encodeURIComponent(accountId)}`;
+}
+function publicDeveloperMode(developer) {
+    return { active: true, tenantId: developer.tenantId, grantId: developer.grantId, expiresAt: developer.expiresAt };
+}
+/**
+ * Developer grants live in sessionStorage: they survive a reload of the same
+ * tab but never reach other tabs or outlive the browser session.
+ */
+function readDeveloperGrant(storageKey, projectId, accountId) {
+    if (typeof window === "undefined")
+        return null;
+    const key = developerGrantStorageKey(storageKey, accountId);
+    let parsed = null;
+    try {
+        parsed = JSON.parse(sessionStorage.getItem(key) ?? "null");
+    }
+    catch {
+        parsed = null;
+    }
+    if (!parsed) {
+        safeSessionStorageRemove(key);
+        return null;
+    }
+    const expiresAt = typeof parsed.expiresAt === "string" ? Date.parse(parsed.expiresAt) : Number.NaN;
+    if (parsed.projectId !== projectId
+        || parsed.accountId !== accountId
+        || typeof parsed.tenantId !== "string" || !parsed.tenantId
+        || typeof parsed.grantId !== "string" || !parsed.grantId
+        || typeof parsed.token !== "string" || !(parsed.token.startsWith("gvx_imp_") || parsed.token.startsWith("gvx_dev_"))
+        || !Number.isFinite(expiresAt)
+        || expiresAt <= Date.now() + DEVELOPER_GRANT_RESTORE_MARGIN_MS) {
+        safeSessionStorageRemove(key);
+        return null;
+    }
+    return parsed;
+}
+function writeDeveloperGrant(storageKey, projectId, developer, token) {
+    const grant = {
+        projectId,
+        accountId: developer.accountId,
+        tenantId: developer.tenantId,
+        grantId: developer.grantId,
+        token,
+        expiresAt: developer.expiresAt,
+        ...(developer.originalTenantId ? { originalTenantId: developer.originalTenantId } : {}),
+    };
+    safeSessionStorageSet(developerGrantStorageKey(storageKey, developer.accountId), JSON.stringify(grant));
+}
+/** Removes every stored developer grant for this project, except `keepAccountId`'s. */
+function clearDeveloperGrants(storageKey, keepAccountId) {
+    if (typeof window === "undefined")
+        return;
+    const prefix = developerGrantStoragePrefix(storageKey);
+    const keep = keepAccountId ? developerGrantStorageKey(storageKey, keepAccountId) : undefined;
+    try {
+        const keys = [];
+        for (let index = 0; index < sessionStorage.length; index += 1) {
+            const key = sessionStorage.key(index);
+            if (key?.startsWith(prefix) && key !== keep)
+                keys.push(key);
+        }
+        for (const key of keys)
+            sessionStorage.removeItem(key);
+    }
+    catch { /* storage can be unavailable in hardened browsers */ }
+}
+function installDeveloperClientAuth(client, projectId, developer, token) {
+    client.setAuth({
+        project: projectId,
+        tenant: developer.tenantId,
+        token,
+        fetchToken: undefined,
+        identity: { sub: developer.accountId, iss: projectId },
+    });
+}
 function installClientSession(client, projectId, session) {
     client.setAuth({
         project: projectId,
@@ -1037,21 +1296,44 @@ function sameInstalledAuthSession(current, next) {
  * has a current access token. A refresh credential alone is not authorization
  * to expose cached tenant data.
  */
-function reusableExternalAuthSession(session, initialTenantId, provider, now = Date.now()) {
+function reusableExternalAuthSession(session, initialTenantId, provider, hasExplicitInitialTenant = initialTenantId !== undefined, now = Date.now()) {
     if (!session || session.account.provider !== provider)
         return null;
     if (!Number.isFinite(session.expiresAt) || session.expiresAt <= now + WARM_SESSION_ACCESS_SAFETY_MS) {
         return null;
     }
-    if (initialTenantId !== undefined
-        && !session.tenants.some((tenant) => (tenant.id === session.activeTenantId
+    const scoped = scopeSessionForInitialTenant(session, initialTenantId, hasExplicitInitialTenant);
+    if (!scoped)
+        return null;
+    if (hasExplicitInitialTenant
+        && initialTenantId !== undefined
+        && !scoped.tenants.some((tenant) => (tenant.id === scoped.activeTenantId
             && (tenant.id === initialTenantId || tenant.domain.toLowerCase() === initialTenantId.toLowerCase()))))
         return null;
-    if (session.activeTenantId !== undefined
-        && !session.tenants.some((tenant) => tenant.id === session.activeTenantId)) {
+    if (scoped.activeTenantId !== undefined
+        && !scoped.tenants.some((tenant) => tenant.id === scoped.activeTenantId)) {
         return null;
     }
-    return session;
+    return scoped;
+}
+/** Restrict a persisted session to the tenant context selected by the host. */
+function scopeSessionForInitialTenant(session, initialTenantId, hasExplicitInitialTenant) {
+    if (!session || !hasExplicitInitialTenant)
+        return session;
+    // The landlord is account-scoped. Reuse the valid token and tenant directory,
+    // but never carry a tenant Replica scope onto that origin.
+    if (initialTenantId === undefined) {
+        return session.activeTenantId === undefined
+            ? session
+            : { ...session, activeTenantId: undefined };
+    }
+    const tenant = session.tenants.find((candidate) => (candidate.id === initialTenantId
+        || candidate.domain.toLowerCase() === initialTenantId.toLowerCase()));
+    if (!tenant)
+        return null;
+    return session.activeTenantId === tenant.id
+        ? session
+        : { ...session, activeTenantId: tenant.id };
 }
 function readAuthSession(key) {
     if (typeof window === "undefined")
@@ -1124,7 +1406,7 @@ export function useQueryResult(ref, args = {}, options = {}) {
     const sessionScopeGeneration = useSessionScopeGeneration(client);
     const path = ref.path;
     const kind = ref.kind;
-    const optimisticKey = JSON.stringify(ref.optimistic ?? null);
+    const optimisticKey = useMemo(() => JSON.stringify(ref.optimistic ?? null), [ref.optimistic]);
     const argsKey = JSON.stringify(args);
     const keepPreviousData = options.keepPreviousData !== false;
     const timeoutMs = options.timeoutMs ?? DEFAULT_LIVE_QUERY_SLOW_MS;
@@ -1219,10 +1501,10 @@ export function useLiveQuery(ref, args = {}) {
     }
     const path = ref.path;
     const kind = ref.kind;
-    const optimisticKey = JSON.stringify(ref.optimistic ?? null);
+    const optimisticKey = useMemo(() => JSON.stringify(ref.optimistic ?? null), [ref.optimistic]);
     const argsKey = JSON.stringify(args);
-    const liveKey = JSON.stringify(ref.live ?? null);
-    const liveWatch = useMemo(() => args === "skip" ? undefined : client.watchLiveQuery(ref, args), 
+    const liveKey = useMemo(() => JSON.stringify(ref.live ?? null), [ref.live]);
+    const liveWatch = useMemo(() => args === "skip" ? undefined : client.watchLiveQuery(ref, args, { deferStart: true }), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [client, kind, path, optimisticKey, argsKey, liveKey]);
     const liveResult = useSyncExternalStore(useCallback((notify) => liveWatch?.onUpdate(notify) ?? (() => undefined), [liveWatch]), useCallback(() => liveWatch?.localLiveQueryResult(), [liveWatch]), () => undefined);
@@ -1235,21 +1517,58 @@ export function useControlQuery(ref, args = {}) {
     const watch = useMemo(() => args === "skip" ? undefined : client.watchControlQuery(ref, args), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [client, ref.kind, ref.path, argsKey]);
-    const snapshot = useSyncExternalStore(useCallback((notify) => watch?.onUpdate(notify) ?? (() => undefined), [watch]), useCallback(() => watch?.getSnapshot(), [watch]), () => undefined);
+    const snapshot = useSyncExternalStore(useCallback((notify) => watch?.onUpdate(notify) ?? (() => undefined), [watch]), useCallback(() => watch?.getSnapshot(), [watch]), () => undefined, 
+    // Batch cold control-query delivery, but publish later control changes
+    // before their Reducer promise settles and follow-up UI handlers run.
+    true);
     return snapshot?.result;
 }
 /** Read one normalized entity from the single Gonvex Local Replica. */
 export function useEntity(entity, id) {
     const client = useGonvexClient();
-    useSyncExternalStore(useCallback((notify) => client.localReplica.subscribe(notify), [client]), useCallback(() => client.localReplica.version(), [client]), () => 0);
-    return client.localReplica.entity(entity, id);
+    useEffect(() => client.retainReplicaEntities(entity, [id]), [client, entity, id]);
+    const version = useSyncExternalStore(useCallback((notify) => client.localReplica.subscribe(notify), [client]), useCallback(() => client.localReplica.entityVersion(entity, id), [client, entity, id]), () => 0);
+    return useMemo(() => client.localReplica.entity(entity, id), [client, entity, id, version]);
 }
 /** Resolve an ordered entity batch with one Local Replica subscription. */
 export function useReplicaEntities(entity, ids) {
     const client = useGonvexClient();
     const idsKey = JSON.stringify(ids);
-    const version = useSyncExternalStore(useCallback((notify) => client.localReplica.subscribe(notify), [client]), useCallback(() => client.localReplica.version(), [client]), () => 0);
-    return useMemo(() => client.replicaEntities(entity, ids), [client, entity, idsKey, version]);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    useEffect(() => client.retainReplicaEntities(entity, ids), [client, entity, idsKey]);
+    const cache = useMemo(() => new Map(), [client, entity]);
+    const getVersion = useMemo(() => {
+        let tableVersion;
+        let snapshot = "";
+        return () => {
+            const next = client.localReplica.entityVersion(entity);
+            // Metadata, presence and other tables publish through this subscription
+            // too. They cannot change this batch, so avoid scanning its IDs again.
+            if (next !== tableVersion) {
+                tableVersion = next;
+                snapshot = ids.map(id => client.localReplica.entityVersion(entity, id)).join(",");
+            }
+            return snapshot;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, entity, idsKey]);
+    const version = useSyncExternalStore(useCallback((notify) => client.localReplica.subscribe(notify), [client]), getVersion, () => "");
+    return useMemo(() => {
+        const retained = new Set(ids);
+        for (const id of cache.keys())
+            if (!retained.has(id))
+                cache.delete(id);
+        return ids.map(id => {
+            const rowVersion = client.localReplica.entityVersion(entity, id);
+            const prior = cache.get(id);
+            if (prior?.version === rowVersion)
+                return prior.row;
+            const row = client.localReplica.entity(entity, id);
+            cache.set(id, { version: rowVersion, row });
+            return row;
+        });
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, entity, idsKey, version, cache]);
 }
 /** Read a persisted Live Query window without opening another server subscription. */
 export function useRetainedLiveQuery(signatureOrReference, args = {}) {
@@ -1258,9 +1577,10 @@ export function useRetainedLiveQuery(signatureOrReference, args = {}) {
     const signature = typeof signatureOrReference === "string"
         ? signatureOrReference
         : client.replicaSignature(signatureOrReference, args);
-    const version = useSyncExternalStore(useCallback((notify) => client.localReplica.subscribe(notify), [client]), useCallback(() => client.localReplica.version(), [client]), () => 0);
-    return useMemo(() => client.retainedLiveQuery(signature), [client, signature, argsKey, version]);
+    useEffect(() => client.retainReplicaWindow(signature), [client, signature]);
+    return useSyncExternalStore(useCallback((notify) => client.localReplica.subscribe(notify), [client]), useCallback(() => client.localReplica.liveQuerySnapshot(signature), [client, signature, argsKey]), () => emptyLiveQuery);
 }
+const emptyLiveQuery = { rows: [], ids: [], source: 'cache', completeness: 'partial', freshness: 'verifying' };
 /** Structured Live Query state backed by normalized Local Replica entities. */
 export function useLiveQueryState(ref, args = {}) {
     const client = useGonvexClient();
@@ -1269,28 +1589,41 @@ export function useLiveQueryState(ref, args = {}) {
     useEffect(() => {
         if (args === "skip")
             return;
-        return client.subscribeLiveQuery(ref, args, () => undefined);
+        const release = client.retainReplicaWindow(signature);
+        const unsubscribe = client.subscribeLiveQuery(ref, args, () => undefined);
+        return () => { unsubscribe(); release(); };
         // eslint-disable-next-line react-hooks/exhaustive-deps
     }, [client, ref.kind, ref.path, argsKey]);
-    useSyncExternalStore(useCallback((notify) => client.localReplica.subscribe(notify), [client]), useCallback(() => client.localReplica.version(), [client]), () => 0);
-    if (args !== "skip" && client.localReplica.freshness() === "offline") {
-        const offline = client.offlineLiveQuery(ref, args);
-        return {
-            rows: offline.rows,
-            ids: offline.rows.map((row) => String(row.id ?? row._id ?? "")).filter(Boolean),
-            ...(offline.total === undefined ? {} : { total: offline.total }),
-            ...(offline.offset === undefined ? {} : { offset: offline.offset }),
-            ...(offline.limit === undefined ? {} : { limit: offline.limit }),
-            source: "cache",
-            completeness: offline.completeness,
-            freshness: "offline",
-            supported: offline.supported,
-            ...(offline.unsupportedOperator ? { unsupportedOperator: offline.unsupportedOperator } : {}),
+    const getSnapshot = useMemo(() => {
+        let offlineVersion = -1;
+        let offlineResult;
+        return () => {
+            if (args === 'skip')
+                return emptyLiveQuery;
+            if (client.localReplica.freshness() !== 'offline')
+                return client.localReplica.liveQuerySnapshot(signature);
+            const version = client.localReplica.version();
+            if (offlineVersion === version && offlineResult)
+                return offlineResult;
+            const offline = client.offlineLiveQuery(ref, args);
+            offlineResult = {
+                rows: offline.rows,
+                ids: offline.rows.map((row) => String(row.id ?? row._id ?? "")).filter(Boolean),
+                ...(offline.total === undefined ? {} : { total: offline.total }),
+                ...(offline.offset === undefined ? {} : { offset: offline.offset }),
+                ...(offline.limit === undefined ? {} : { limit: offline.limit }),
+                source: "cache",
+                completeness: offline.completeness,
+                freshness: "offline",
+                supported: offline.supported,
+                ...(offline.unsupportedOperator ? { unsupportedOperator: offline.unsupportedOperator } : {}),
+            };
+            offlineVersion = version;
+            return offlineResult;
         };
-    }
-    return signature
-        ? client.localReplica.liveQuery(signature)
-        : { rows: [], ids: [], source: "cache", completeness: "partial", freshness: client.localReplica.freshness() };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, ref.kind, ref.path, signature, argsKey]);
+    return useSyncExternalStore(useCallback(notify => signature ? client.localReplica.subscribe(notify) : () => undefined, [client, signature]), getSnapshot, () => emptyLiveQuery);
 }
 /** Execute a read-only Query once. Queries never subscribe or rerun. */
 export function useQuery(ref, args = {}) {
@@ -1325,9 +1658,9 @@ export function useReplicaCollection(ref, args = {}) {
     const client = useGonvexClient();
     const path = ref.path;
     const kind = ref.kind;
-    const optimisticKey = JSON.stringify(ref.optimistic ?? null);
+    const optimisticKey = useMemo(() => JSON.stringify(ref.optimistic ?? null), [ref.optimistic]);
     const argsKey = JSON.stringify(args);
-    const watch = useMemo(() => args === "skip" ? undefined : client.watchReplica(ref, args), 
+    const watch = useMemo(() => args === "skip" ? undefined : client.watchReplica(ref, args, { deferStart: true }), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [client, kind, path, optimisticKey, argsKey]);
     return useSyncExternalStore(useCallback((onStoreChange) => watch?.onUpdate(onStoreChange) ?? (() => undefined), [watch]), useCallback(() => watch?.localReplicaResult(), [watch]), () => undefined);
@@ -1337,22 +1670,75 @@ export function useReplicaCollectionState(ref, args = {}) {
     const client = useGonvexClient();
     const path = ref.path;
     const argsKey = JSON.stringify(args);
-    const watch = useMemo(() => args === "skip" ? undefined : client.watchReplica(ref, args), 
+    const watch = useMemo(() => args === "skip" ? undefined : client.watchReplica(ref, args, { deferStart: true }), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [client, ref.kind, path, argsKey]);
     return useSyncExternalStore(useCallback((onStoreChange) => watch?.onUpdate(onStoreChange) ?? (() => undefined), [watch]), useCallback(() => watch?.localReplicaState(), [watch]), () => undefined);
 }
+/** Subscribe to a bounded, dynamic set of slices of the same Replica Collection.
+ * Results borrow normalized SDK snapshots; there is no second entity cache.
+ * Deferred watches only start when React commits the subscription.
+ */
+export function useReplicaCollectionStates(ref, args) {
+    const client = useGonvexClient();
+    const argsKey = JSON.stringify(args);
+    const watches = useMemo(() => args.map(value => client.watchReplica(ref, value, { deferStart: true })), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [client, ref.kind, ref.path, argsKey]);
+    const getSnapshot = useMemo(() => {
+        let snapshot = [];
+        return () => {
+            const next = watches.map(watch => watch.localReplicaState());
+            if (next.length !== snapshot.length || next.some((state, index) => state !== snapshot[index]))
+                snapshot = next;
+            return snapshot;
+        };
+    }, [watches]);
+    return useSyncExternalStore(useCallback(notify => {
+        const releases = watches.map(watch => watch.onUpdate(notify));
+        return () => releases.forEach(release => release());
+    }, [watches]), getSnapshot, () => emptyCollectionStates);
+}
+const emptyCollectionStates = [];
+/** Select rows and authority metadata without rerendering for unused watermarks. */
+export function useReplicaCollectionStateSelector(ref, args, selector, isEqual = Object.is) {
+    const client = useGonvexClient();
+    const argsKey = JSON.stringify(args);
+    const watch = useMemo(() => args === "skip" ? undefined : client.watchReplica(ref, args, { deferStart: true }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [client, ref.kind, ref.path, argsKey]);
+    const committed = useRef(undefined);
+    const getSnapshot = useMemo(() => {
+        let initialized = false;
+        let previous;
+        let selected;
+        return () => {
+            const state = watch?.localReplicaState();
+            if (initialized && state === previous)
+                return selected;
+            const next = state === undefined ? undefined : selector(state);
+            const prior = initialized ? selected : committed.current && committed.current.watch === watch ? committed.current.value : undefined;
+            selected = prior !== undefined && next !== undefined && isEqual(prior, next) ? prior : next;
+            previous = state;
+            initialized = true;
+            return selected;
+        };
+    }, [watch, selector, isEqual]);
+    const selected = useSyncExternalStore(useCallback((notify) => watch?.onUpdate(notify) ?? (() => undefined), [watch]), getSnapshot, () => undefined);
+    useEffect(() => { committed.current = { watch, value: selected }; }, [watch, selected]);
+    return selected;
+}
 export function useReplicaSelector(ref, args, selector, isEqual = Object.is) {
     const client = useGonvexClient();
     const path = ref.path;
     const kind = ref.kind;
-    const optimisticKey = JSON.stringify(ref.optimistic ?? null);
+    const optimisticKey = useMemo(() => JSON.stringify(ref.optimistic ?? null), [ref.optimistic]);
     const argsKey = JSON.stringify(args);
     const selectorRef = useRef(selector);
     const equalityRef = useRef(isEqual);
     selectorRef.current = selector;
     equalityRef.current = isEqual;
-    const watch = useMemo(() => args === "skip" ? undefined : client.watchReplica(ref, args), 
+    const watch = useMemo(() => args === "skip" ? undefined : client.watchReplica(ref, args, { deferStart: true }), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [client, kind, path, optimisticKey, argsKey]);
     const selectedRef = useRef({
@@ -1404,6 +1790,7 @@ export function useReplicaSelector(ref, args, selector, isEqual = Object.is) {
 }
 export function useReducer(ref, options = {}) {
     const client = useGonvexClient();
+    useEffect(() => { void client.prepareReducer?.(ref)?.catch(() => undefined); }, [client, ref]);
     const refRef = useRef(ref);
     refRef.current = ref;
     const timeoutMs = options.timeoutMs;
@@ -1437,6 +1824,69 @@ export function useGonvexConnectionState() {
     }, [client]);
     return state;
 }
+const EMPTY_INTENTS = [];
+const NO_SUBSCRIPTION = () => () => undefined;
+/**
+ * Every durable reducer intent of the signed-in identity, oldest first:
+ * pending and inflight intents, intents parked as `failed` after exhausting
+ * their retry budget, and server-`rejected` intents awaiting dismissal.
+ * Use `client.retryIntent(id)` / `client.discardIntent(id)` to act on them.
+ */
+export function useOutboxIntents() {
+    const client = useGonvexClient();
+    const subscribe = useMemo(() => (typeof client.subscribeIntents === "function" ? client.subscribeIntents.bind(client) : NO_SUBSCRIPTION), [client]);
+    const getSnapshot = useCallback(() => (typeof client.intentsSnapshot === "function" ? client.intentsSnapshot() : EMPTY_INTENTS), [client]);
+    return useReactSyncExternalStore(subscribe, getSnapshot, () => EMPTY_INTENTS);
+}
+/**
+ * Delivery status of one row: `failed` or `rejected` when an intent that
+ * touched it needs attention, `syncing` while one is still queued, and
+ * undefined once everything touching it has been acknowledged.
+ */
+export function useEntityIntentStatus(entity, id) {
+    const intents = useOutboxIntents();
+    return useMemo(() => (id ? entityStatusFromIntents(intents, entity, id) : undefined), [intents, entity, id]);
+}
+/**
+ * Observe locally executing Reducers that fell back to a queued-only intent
+ * (no local result), for logging. The latest listener is always called; it
+ * does not need to be memoized.
+ */
+export function useLocalExecutionFallback(listener) {
+    const client = useGonvexClient();
+    const latest = useRef(listener);
+    useEffect(() => { latest.current = listener; });
+    useEffect(() => {
+        if (typeof client.onLocalExecutionFallback !== "function")
+            return undefined;
+        return client.onLocalExecutionFallback((event) => latest.current(event));
+    }, [client]);
+}
+/**
+ * Drive a "Clear cache" control: discards the persisted Local Replica and
+ * rehydrates it from the server, keeping queued intents unless asked.
+ */
+export function useResetLocalReplica() {
+    const client = useGonvexClient();
+    const [isResetting, setResetting] = useState(false);
+    const [error, setError] = useState();
+    const reset = useCallback(async (options) => {
+        setResetting(true);
+        setError(undefined);
+        try {
+            return await client.resetLocalReplica(options);
+        }
+        catch (cause) {
+            const failure = cause instanceof Error ? cause : new Error(String(cause));
+            setError(failure);
+            throw failure;
+        }
+        finally {
+            setResetting(false);
+        }
+    }, [client]);
+    return { reset, isResetting, error };
+}
 export function useGonvexClient() {
     const client = useContext(GonvexContext);
     if (!client)