@gonvex/react 0.1.31 → 0.3.0

package/dist/index.js

@@ -1,14 +1,12 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import { ConvexReactClient, GonvexClientError } from "@gonvex/client";
+import { GonvexClientError, control } from "@gonvex/client";
 export { GonvexClientError } from "@gonvex/client";
 const GonvexContext = createContext(null);
 const GonvexAuthContext = createContext({ isLoading: false, isAuthenticated: true });
-export const ConvexProvider = GonvexProvider;
 export function GonvexProvider(props) {
     return _jsx(GonvexContext.Provider, { value: props.client, children: props.children });
 }
-export { ConvexReactClient };
 class GonvexAuthRequestError extends Error {
     status;
     constructor(message, status) {
@@ -18,13 +16,22 @@ class GonvexAuthRequestError extends Error {
     }
 }
 const ManagedAuthContext = createContext(null);
-export function ConvexProviderWithAuth(props) {
+export function GonvexProviderWithAuth(props) {
     const auth = props.useAuth();
     const [tokenReady, setTokenReady] = useState(false);
+    const [clientAuthError, setClientAuthError] = useState(null);
+    const authError = auth.authError ?? clientAuthError;
+    useEffect(() => props.client.onAuthError((message) => {
+        setClientAuthError(new Error(message || "Authentication failed"));
+        setTokenReady(false);
+    }), [props.client]);
     useEffect(() => {
         setTokenReady(false);
-        if (auth.isLoading || !auth.isAuthenticated || !auth.fetchAccessToken)
+        if (auth.isLoading || !auth.isAuthenticated || !auth.fetchAccessToken) {
+            if (!auth.isLoading && !auth.isAuthenticated)
+                setClientAuthError(null);
             return;
+        }
         const fetchAccessToken = auth.fetchAccessToken;
         let cancelled = false;
         void fetchAccessToken({ forceRefreshToken: false }).then((token) => {
@@ -33,6 +40,7 @@ export function ConvexProviderWithAuth(props) {
                 // on reconnect and force-refreshes on auth.error itself, instead of
                 // replaying this token verbatim after it expires.
                 props.client.setAuth({ token: token ?? undefined, fetchToken: fetchAccessToken });
+                setClientAuthError(null);
                 setTokenReady(Boolean(token));
             }
         }, (error) => {
@@ -53,18 +61,14 @@ export function ConvexProviderWithAuth(props) {
     }, [auth.isLoading, auth.isAuthenticated, auth.fetchAccessToken, props.client]);
     const authValue = useMemo(() => ({
         ...auth,
-        isLoading: auth.isLoading || (auth.isAuthenticated && !tokenReady),
-        isAuthenticated: auth.isAuthenticated && tokenReady,
-    }), [auth, tokenReady]);
-    const shouldHoldChildren = auth.isLoading || (auth.isAuthenticated && !tokenReady);
+        authError,
+        isLoading: !authError && (auth.isLoading || (auth.isAuthenticated && !tokenReady)),
+        isAuthenticated: !authError && auth.isAuthenticated && tokenReady,
+    }), [auth, authError, tokenReady]);
+    const shouldHoldChildren = !authError && (auth.isLoading || (auth.isAuthenticated && !tokenReady));
     return (_jsx(GonvexAuthContext.Provider, { value: authValue, children: _jsx(GonvexProvider, { client: props.client, children: shouldHoldChildren ? null : props.children }) }));
 }
-/**
- * Native Gonvex authentication. The runtime performs the one centrally
- * configured Google OAuth flow, while each app uses PKCE and receives a
- * project-scoped Gonvex session. No Firebase or Google SDK is loaded in the
- * browser.
- */
+/** Native Gonvex authentication with password or a configured OAuth provider. */
 // Dedupe callback bootstrap across React StrictMode remounts so the OAuth
 // code+PKCE exchange runs once. Without this, the first effect's finally
 // clears sessionStorage PKCE before the remount can finish verification.
@@ -85,12 +89,15 @@ export function GonvexAuthProvider(props) {
         if (next) {
             if (persist)
                 safeLocalStorageSet(storageKey, JSON.stringify(next));
-            props.client.setAuth({ project: props.projectId, tenant: next.activeTenantId, token: next.accessToken });
+            props.client.setAuth({
+                project: props.projectId, tenant: next.activeTenantId, token: next.accessToken,
+                identity: { sub: next.account.id, iss: props.projectId },
+            });
         }
         else {
             if (persist)
                 safeLocalStorageRemove(storageKey);
-            props.client.setAuth({ project: props.projectId, tenant: undefined, token: undefined });
+            props.client.setAuth({ project: props.projectId, tenant: undefined, token: undefined, identity: undefined });
         }
         setSession(next);
     }, [props.client, props.projectId, storageKey]);
@@ -98,7 +105,7 @@ export function GonvexAuthProvider(props) {
         let cancelled = false;
         let bootstrap = authBootstrapPromises.get(storageKey);
         if (!bootstrap) {
-            bootstrap = bootstrapGonvexAuth({ callbackPath, pkceStorageKey, projectId: props.projectId, runtimeUrl, storageKey })
+            bootstrap = bootstrapGonvexAuth({ callbackPath, client: props.client, pkceStorageKey, projectId: props.projectId, runtimeUrl, storageKey })
                 .finally(() => {
                 // Keep the resolved promise briefly so a StrictMode remount attaches
                 // to the same result instead of re-running a spent OAuth code.
@@ -116,7 +123,7 @@ export function GonvexAuthProvider(props) {
         }).catch((cause) => {
             if (!cancelled) {
                 installSession(null);
-                setError(cause instanceof Error ? cause.message : "Google sign-in failed.");
+                setError(cause instanceof Error ? cause.message : "Sign-in failed.");
             }
         }).finally(() => {
             if (!cancelled)
@@ -135,12 +142,8 @@ export function GonvexAuthProvider(props) {
             if (!force && current.expiresAt > Date.now() + 60_000)
                 return current;
             attemptedRefreshToken = current.refreshToken;
-            const next = await requestGonvexAuthToken(runtimeUrl, {
-                grantType: "refresh_token",
-                project: props.projectId,
-                refreshToken: current.refreshToken,
-                tenant: current.activeTenantId,
-            });
+            const grant = await props.client.action(control.auth.refreshSession, { refreshToken: current.refreshToken });
+            const next = sessionFromNativeGrant(grant, current);
             // Persist the rotated token before releasing the cross-tab lock. The
             // next waiter must never read and reuse the just-consumed refresh token.
             safeLocalStorageSet(storageKey, JSON.stringify(next));
@@ -181,7 +184,7 @@ export function GonvexAuthProvider(props) {
         });
         refreshRef.current = request;
         return request;
-    }, [installSession, props.projectId, runtimeUrl, storageKey]);
+    }, [installSession, props.client, storageKey]);
     useEffect(() => {
         if (!session)
             return;
@@ -190,6 +193,25 @@ export function GonvexAuthProvider(props) {
         const timeout = window.setTimeout(() => { void refreshSession(); }, delay);
         return () => window.clearTimeout(timeout);
     }, [refreshRetryAt, refreshSession, session]);
+    // Keep the account tenant directory authoritative without a reducer+manual
+    // refetch pair. The live Control Plane Query resumes on reconnect.
+    useEffect(() => {
+        if (!sessionRef.current)
+            return;
+        const watch = props.client.watchControlQuery(control.tenants.mine, {});
+        return watch.onUpdate(() => {
+            const tenants = watch.getSnapshot().result;
+            const current = sessionRef.current;
+            if (!current || !tenants)
+                return;
+            const activeTenantId = tenants.some((tenant) => tenant.id === current.activeTenantId)
+                ? current.activeTenantId
+                : tenants[0]?.id;
+            if (JSON.stringify(current.tenants) === JSON.stringify(tenants) && current.activeTenantId === activeTenantId)
+                return;
+            installSession({ ...current, tenants, activeTenantId });
+        });
+    }, [installSession, props.client, session?.account.id]);
     useEffect(() => {
         const onStorage = (event) => {
             if (event.key !== storageKey)
@@ -199,7 +221,7 @@ export function GonvexAuthProvider(props) {
         window.addEventListener("storage", onStorage);
         return () => window.removeEventListener("storage", onStorage);
     }, [installSession, storageKey]);
-    const signIn = useCallback(async () => {
+    const signInWithProvider = useCallback(async (provider) => {
         setError(null);
         const verifier = randomBase64Url(64);
         const state = randomBase64Url(32);
@@ -207,8 +229,8 @@ export function GonvexAuthProvider(props) {
         const challenge = bytesToBase64Url(new Uint8Array(challengeBytes));
         const redirectUri = new URL(callbackPath, window.location.origin).toString();
         const returnTo = `${window.location.pathname}${window.location.search}${window.location.hash}`;
-        safeSessionStorageSet(pkceStorageKey, JSON.stringify({ state, verifier, redirectUri, returnTo, createdAt: Date.now() }));
-        const authorizeUrl = new URL(`${runtimeUrl}/auth/google/authorize`);
+        safeSessionStorageSet(pkceStorageKey, JSON.stringify({ state, verifier, redirectUri, returnTo, provider, createdAt: Date.now() }));
+        const authorizeUrl = new URL(`${runtimeUrl}/auth/${provider}/authorize`);
         authorizeUrl.searchParams.set("project", props.projectId);
         authorizeUrl.searchParams.set("redirect_uri", redirectUri);
         authorizeUrl.searchParams.set("state", state);
@@ -216,18 +238,21 @@ export function GonvexAuthProvider(props) {
         authorizeUrl.searchParams.set("code_challenge_method", "S256");
         window.location.assign(authorizeUrl.toString());
     }, [callbackPath, pkceStorageKey, props.projectId, runtimeUrl]);
+    const signIn = useCallback((provider = "google") => signInWithProvider(provider), [signInWithProvider]);
+    const signInWithPassword = useCallback(async (email, password) => {
+        setError(null);
+        const grant = await props.client.action(control.auth.passwordLogin, { email, password });
+        const next = sessionFromNativeGrant(grant, sessionRef.current ?? undefined);
+        installSession(next);
+    }, [installSession, props.client]);
     const signOut = useCallback(async (options) => {
         const current = sessionRef.current;
-        installSession(null);
         setError(null);
-        if (!current)
-            return;
-        await fetch(`${runtimeUrl}/auth/logout`, {
-            method: "POST",
-            headers: { authorization: `Bearer ${current.accessToken}`, "content-type": "application/json" },
-            body: JSON.stringify({ refreshToken: current.refreshToken, all: options?.allDevices === true }),
-        }).catch(() => undefined);
-    }, [installSession, runtimeUrl]);
+        if (current) {
+            await props.client.reducer(control.auth.logout, { refreshToken: current.refreshToken, all: options?.allDevices === true }).catch(() => undefined);
+        }
+        installSession(null);
+    }, [installSession, props.client]);
     const fetchAccessToken = useCallback(async (args) => {
         const current = sessionRef.current;
         if (!current)
@@ -248,82 +273,67 @@ export function GonvexAuthProvider(props) {
         if (!token)
             throw new Error("Sign in before loading tenant memberships.");
         const current = sessionRef.current;
-        const response = await fetch(`${runtimeUrl}/auth/me`, {
-            headers: { authorization: `Bearer ${token}`, ...(current.activeTenantId ? { "x-gonvex-tenant-id": current.activeTenantId } : {}) },
-        });
-        const payload = await response.json().catch(() => ({}));
-        if (!response.ok || !payload.user || !payload.tenants)
-            throw new Error(payload.error ?? "Could not load tenant memberships.");
-        installSession({ ...current, user: payload.user, tenants: payload.tenants, activeTenantId: payload.activeTenantId });
-        return payload.tenants;
-    }, [fetchAccessToken, installSession, runtimeUrl]);
+        const [account, tenants] = await Promise.all([
+            props.client.query(control.accounts.me, {}),
+            props.client.query(control.tenants.mine, {}),
+        ]);
+        const mappedAccount = { id: account.id, email: account.email, emailVerified: true, name: account.name, picture: account.avatarUrl, provider: current.account.provider };
+        const mappedTenants = tenants;
+        const activeTenantId = mappedTenants.some((tenant) => tenant.id === current.activeTenantId) ? current.activeTenantId : mappedTenants[0]?.id;
+        installSession({ ...current, account: mappedAccount, tenants: mappedTenants, activeTenantId });
+        return mappedTenants;
+    }, [fetchAccessToken, installSession, props.client]);
     const createTenant = useCallback(async (name) => {
         const token = await fetchAccessToken({ forceRefreshToken: false });
         if (!token)
             throw new Error("Sign in before creating a tenant.");
-        const response = await fetch(`${runtimeUrl}/auth/tenants`, {
-            method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
-            body: JSON.stringify({ name }),
-        });
-        const payload = await response.json().catch(() => ({}));
-        if (!response.ok || !payload.tenant)
-            throw new Error(payload.error ?? "Could not create the tenant.");
+        const tenant = await props.client.reducer(control.tenants.create, { name });
         const current = sessionRef.current;
-        installSession({ ...current, tenants: [...current.tenants.filter((tenant) => tenant.id !== payload.tenant.id), payload.tenant], activeTenantId: payload.tenant.id });
-        return payload.tenant;
-    }, [fetchAccessToken, installSession, runtimeUrl]);
+        installSession({ ...current, tenants: [...current.tenants.filter((item) => item.id !== tenant.id), tenant], activeTenantId: tenant.id });
+        return tenant;
+    }, [fetchAccessToken, installSession, props.client]);
     const inviteMember = useCallback(async (tenantId, email, options) => {
         const token = await fetchAccessToken({ forceRefreshToken: false });
         if (!token)
             throw new Error("Sign in before inviting a member.");
-        const response = await fetch(`${runtimeUrl}/auth/tenants/${encodeURIComponent(tenantId)}/members`, {
-            method: "POST", headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
-            body: JSON.stringify({ email, role: options?.role ?? "member", permissions: options?.permissions ?? {} }),
-        });
-        const payload = await response.json().catch(() => ({}));
-        if (!response.ok)
-            throw new Error(payload.error ?? "Could not invite the member.");
-    }, [fetchAccessToken, runtimeUrl]);
-    const removeMember = useCallback(async (tenantId, userId) => {
-        const token = await fetchAccessToken({ forceRefreshToken: false });
-        if (!token)
-            throw new Error("Sign in before removing a member.");
-        const response = await fetch(`${runtimeUrl}/auth/tenants/${encodeURIComponent(tenantId)}/members/${encodeURIComponent(userId)}`, {
-            method: "DELETE", headers: { authorization: `Bearer ${token}` },
-        });
-        const payload = await response.json().catch(() => ({}));
-        if (!response.ok)
-            throw new Error(payload.error ?? "Could not remove the member.");
-    }, [fetchAccessToken, runtimeUrl]);
+        if (tenantId !== sessionRef.current?.activeTenantId)
+            throw new Error("Switch to the tenant before inviting a member.");
+        return props.client.reducer(control.invitations.create, { email, role: options?.role ?? "member", permissions: (options?.permissions ?? {}), teamIds: options?.teamIds ?? [], allowedAuthProviders: options?.allowedAuthProviders ?? [], payload: options?.payload ?? {} });
+    }, [fetchAccessToken, props.client]);
+    const acceptInvitation = useCallback(async (token) => {
+        const accessToken = await fetchAccessToken({ forceRefreshToken: false });
+        if (!accessToken)
+            throw new Error("Sign in before accepting an invitation.");
+        return props.client.reducer(control.invitations.accept, { token });
+    }, [fetchAccessToken, props.client]);
     const revokeInvitation = useCallback(async (tenantId, email) => {
         const token = await fetchAccessToken({ forceRefreshToken: false });
         if (!token)
             throw new Error("Sign in before revoking an invitation.");
-        const response = await fetch(`${runtimeUrl}/auth/tenants/${encodeURIComponent(tenantId)}/invitations/${encodeURIComponent(email)}`, {
-            method: "DELETE", headers: { authorization: `Bearer ${token}` },
-        });
-        const payload = await response.json().catch(() => ({}));
-        if (!response.ok)
-            throw new Error(payload.error ?? "Could not revoke the invitation.");
-    }, [fetchAccessToken, runtimeUrl]);
+        if (tenantId !== sessionRef.current?.activeTenantId)
+            throw new Error("Switch to the tenant before revoking an invitation.");
+        await props.client.reducer(control.invitations.revoke, { id: "", email });
+    }, [fetchAccessToken, props.client]);
     const activeTenant = session?.tenants.find((tenant) => tenant.id === session.activeTenantId) ?? null;
     const authValue = useMemo(() => ({
         isLoading,
         isAuthenticated: Boolean(session && session.refreshExpiresAt > Date.now()),
         fetchAccessToken,
-        user: session?.user ?? null,
+        account: session?.account ?? null,
         tenants: session?.tenants ?? [],
         activeTenant,
         error,
         signIn,
+        signInWithProvider,
+        signInWithPassword,
         signOut,
         setActiveTenant,
         refreshMemberships,
         createTenant,
         inviteMember,
+        acceptInvitation,
         revokeInvitation,
-        removeMember,
-    }), [activeTenant, createTenant, error, fetchAccessToken, inviteMember, isLoading, refreshMemberships, removeMember, revokeInvitation, session, setActiveTenant, signIn, signOut]);
+    }), [acceptInvitation, activeTenant, createTenant, error, fetchAccessToken, inviteMember, isLoading, refreshMemberships, revokeInvitation, session, 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 }) }) }));
 }
 export function useGonvexAuth() {
@@ -332,6 +342,18 @@ export function useGonvexAuth() {
         throw new Error("GonvexAuthProvider is required");
     return value;
 }
+/** Subscribed profile for the active tenant, reconciled by GonvexAuthProvider. */
+export function useCurrentTenantProfile() {
+    return useGonvexAuth().activeTenant;
+}
+/** Live tenant-admin invitation list; reducer changes reconcile automatically. */
+export function useInvitationList() {
+    return useControlQuery(control.invitations.list, {});
+}
+/** Read the auth state installed by either auth provider. */
+export function useGonvexAuthState() {
+    return useContext(GonvexAuthContext);
+}
 export function GonvexGoogleAuthButton(props) {
     const { signOutLabel = "Sign out", children, disabled, onClick, ...buttonProps } = props;
     const auth = useGonvexAuth();
@@ -375,10 +397,9 @@ async function bootstrapGonvexAuth(options) {
                     return latest;
                 if (latest.refreshExpiresAt <= Date.now())
                     throw new GonvexAuthRequestError("Your session expired. Please sign in again.", 401);
-                const next = await requestGonvexAuthToken(options.runtimeUrl, {
-                    grantType: "refresh_token", project: options.projectId,
-                    refreshToken: latest.refreshToken, tenant: latest.activeTenantId,
-                });
+                options.client.setAuth({ project: options.projectId, token: latest.accessToken });
+                const grant = await options.client.action(control.auth.refreshSession, { refreshToken: latest.refreshToken });
+                const next = sessionFromNativeGrant(grant, latest);
                 safeLocalStorageSet(options.storageKey, JSON.stringify(next));
                 return next;
             });
@@ -390,26 +411,34 @@ async function bootstrapGonvexAuth(options) {
         }
     }
     const pkce = readPKCE(options.pkceStorageKey);
-    // Prefer surfacing the runtime/Google error when PKCE is missing (e.g. after
-    // a StrictMode remount or a second tab), rather than always saying "verified".
+    const provider = pkce?.provider ?? "google";
+    const providerLabel = provider[0].toUpperCase() + provider.slice(1);
+    // Surface the runtime error even when another tab already consumed PKCE.
     if (callbackError) {
         const messages = {
-            access_denied: "Google sign-in was cancelled.",
-            invitation_required: "This app is invite-only. Ask an administrator to invite your verified Google email.",
+            access_denied: `${providerLabel} sign-in was cancelled.`,
+            invitation_required: `This app is invite-only. Ask an administrator to invite your verified ${providerLabel} email.`,
             verified_google_email_required: "Google must provide a verified email address for this app.",
+            verified_microsoft_email_required: "Microsoft must provide a verified email address for this app.",
             membership_setup_failed: "Your account was verified, but its workspace could not be prepared. Please try again.",
             google_exchange_failed: "Google rejected the sign-in code exchange. Check GONVEX_GOOGLE_CLIENT_ID/SECRET and the broker callback URI.",
+            microsoft_exchange_failed: "Microsoft rejected the sign-in code exchange. Check the project's Microsoft realm configuration.",
+            apple_exchange_failed: "Apple rejected the sign-in code exchange. Check the project's Apple realm configuration.",
             invalid_google_identity: "Google identity verification failed. Please try again.",
-            account_creation_failed: "Your Google account could not be linked. Please try again.",
+            invalid_microsoft_identity: "Microsoft identity verification failed. Please try again.",
+            invalid_apple_identity: "Apple identity verification failed. Please try again.",
+            microsoft_not_configured: "Microsoft sign-in is not configured for this project.",
+            apple_not_configured: "Apple sign-in is not configured for this project.",
+            account_creation_failed: `Your ${providerLabel} account could not be linked. Please try again.`,
             code_creation_failed: "Gonvex could not finish creating a sign-in code. Please try again.",
         };
         safeSessionStorageRemove(options.pkceStorageKey);
         clearAuthCallbackParams(url, pkce?.returnTo);
-        throw new Error(messages[callbackError] ?? `Google sign-in failed (${callbackError}). Please try again.`);
+        throw new Error(messages[callbackError] ?? `${providerLabel} sign-in failed (${callbackError}). Please try again.`);
     }
     if (!pkce || !returnedState || returnedState !== pkce.state || Date.now() - pkce.createdAt > 10 * 60 * 1000) {
         clearAuthCallbackParams(url, pkce?.returnTo);
-        throw new Error("The Google sign-in response could not be verified. Please try again.");
+        throw new Error(`The ${providerLabel} sign-in response could not be verified. Please try again.`);
     }
     // Consume PKCE only after validation so a concurrent remount still sees it.
     safeSessionStorageRemove(options.pkceStorageKey);
@@ -423,6 +452,16 @@ async function bootstrapGonvexAuth(options) {
     safeLocalStorageSet(options.storageKey, JSON.stringify(session));
     return session;
 }
+function sessionFromNativeGrant(value, previous) {
+    if (!value || typeof value !== "object" || Array.isArray(value) || !isGonvexAuthSession(value)) {
+        throw new GonvexAuthRequestError("Gonvex returned an invalid native session.", 502);
+    }
+    const session = value;
+    const activeTenantId = previous && session.tenants.some((tenant) => tenant.id === previous.activeTenantId)
+        ? previous.activeTenantId
+        : session.activeTenantId;
+    return { ...session, activeTenantId };
+}
 async function requestGonvexAuthToken(runtimeUrl, body) {
     const controller = new AbortController();
     const timeout = window.setTimeout(() => controller.abort(), 15_000);
@@ -450,7 +489,7 @@ function isFatalRefreshError(cause) {
 }
 function isGonvexAuthSession(value) {
     return Boolean(value.accessToken && value.expiresAt && value.refreshToken && value.refreshExpiresAt
-        && value.user?.id && Array.isArray(value.tenants));
+        && value.account?.id && Array.isArray(value.tenants));
 }
 async function withBrowserAuthLock(name, action) {
     const locks = typeof navigator === "undefined"
@@ -523,7 +562,7 @@ function readAuthSession(key) {
         return null;
     try {
         const parsed = JSON.parse(localStorage.getItem(key) ?? "null");
-        if (!parsed?.accessToken || !parsed.refreshToken || !parsed.user?.id || !Array.isArray(parsed.tenants) || parsed.refreshExpiresAt <= Date.now()) {
+        if (!parsed?.accessToken || !parsed.refreshToken || !parsed.account?.id || !Array.isArray(parsed.tenants) || parsed.refreshExpiresAt <= Date.now()) {
             safeLocalStorageRemove(key);
             return null;
         }
@@ -564,11 +603,7 @@ function bytesToBase64Url(bytes) {
     return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
 }
 const DEFAULT_LIVE_QUERY_SLOW_MS = 15_000;
-/**
- * Live query hook with an explicit status surface. Unlike `useQuery`, this
- * distinguishes loading / success / error / timeout / disconnected, keeps the
- * last good result while reconnecting, and exposes `retry()`.
- */
+/** One-shot Query hook with explicit loading/error/timeout status and retry. */
 export function useQueryResult(ref, args = {}, options = {}) {
     const client = useGonvexClient();
     const path = ref.path;
@@ -577,6 +612,7 @@ export function useQueryResult(ref, args = {}, options = {}) {
     const argsKey = JSON.stringify(args);
     const keepPreviousData = options.keepPreviousData !== false;
     const timeoutMs = options.timeoutMs ?? DEFAULT_LIVE_QUERY_SLOW_MS;
+    const [requestGeneration, setRequestGeneration] = useState(0);
     const [state, setState] = useState({
         data: undefined,
         status: args === "skip" ? "skip" : "loading",
@@ -608,147 +644,183 @@ export function useQueryResult(ref, args = {}, options = {}) {
             setState({ data: undefined, status: "skip", error: null, isStale: false });
             return;
         }
-        setState({ data: undefined, status: "loading", error: null, isStale: false });
+        setState((previous) => ({
+            data: keepPreviousData ? previous.data : undefined,
+            status: "loading",
+            error: null,
+            isStale: keepPreviousData && previous.data !== undefined,
+        }));
         startSlowTimer();
-        const unsubscribeScope = client.onSessionScopeChange(() => {
-            setState({ data: undefined, status: "loading", error: null, isStale: false });
-            startSlowTimer();
-        });
-        const unsubscribeQuery = client.subscribeQuery(ref, args, (message) => {
-            if (message.type === "query.result") {
-                clearSlowTimer();
-                setState({ data: message.result, status: "success", error: null, isStale: false });
-            }
-            if (message.type === "query.error") {
-                clearSlowTimer();
-                const error = new GonvexClientError(message.error, { code: "server", path, operation: "query" });
-                setState((previous) => ({
-                    data: keepPreviousData ? previous.data : undefined,
-                    status: "error",
-                    error,
-                    isStale: keepPreviousData && previous.data !== undefined,
-                }));
-            }
-        });
-        const applyConnection = (connection) => {
-            if (!connection.isWebSocketConnected) {
-                clearSlowTimer();
-                setState((previous) => {
-                    if (previous.status === "skip")
-                        return previous;
-                    return {
-                        data: keepPreviousData ? previous.data : undefined,
-                        status: "disconnected",
-                        error: previous.error,
-                        isStale: keepPreviousData && previous.data !== undefined,
-                    };
-                });
+        let active = true;
+        void client.query(ref, args).then((data) => {
+            if (!active)
                 return;
-            }
-            // The client resubscribes live queries itself on reconnect; report
-            // loading until the fresh result lands.
-            setState((previous) => {
-                if (previous.status !== "disconnected")
-                    return previous;
-                startSlowTimer();
-                return { ...previous, status: "loading" };
-            });
-        };
-        const unsubscribeConnection = typeof client.subscribeToConnectionState === "function"
-            ? (() => {
-                if (typeof client.connectionState === "function") {
-                    applyConnection(client.connectionState());
-                }
-                return client.subscribeToConnectionState(applyConnection);
-            })()
-            : undefined;
+            clearSlowTimer();
+            setState({ data, status: "success", error: null, isStale: false });
+        }, (failure) => {
+            if (!active)
+                return;
+            clearSlowTimer();
+            const error = failure instanceof Error
+                ? failure
+                : new GonvexClientError(String(failure), { code: "server", path, operation: "query" });
+            setState((previous) => ({
+                data: keepPreviousData ? previous.data : undefined,
+                status: "error",
+                error,
+                isStale: keepPreviousData && previous.data !== undefined,
+            }));
+        });
         return () => {
+            active = false;
             clearSlowTimer();
-            unsubscribeScope();
-            unsubscribeQuery();
-            unsubscribeConnection?.();
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [client, kind, path, optimisticKey, argsKey, keepPreviousData, startSlowTimer, clearSlowTimer]);
+    }, [client, kind, path, optimisticKey, argsKey, keepPreviousData, requestGeneration, startSlowTimer, clearSlowTimer]);
     const retry = useCallback(() => {
         if (args === "skip")
             return;
-        setState((previous) => ({
-            data: previous.data,
-            status: "loading",
-            error: null,
-            isStale: previous.data !== undefined,
-        }));
-        startSlowTimer();
-        if (typeof client.retryQuery === "function") {
-            client.retryQuery(ref, JSON.parse(argsKey));
-        }
+        setRequestGeneration((generation) => generation + 1);
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [client, kind, path, optimisticKey, argsKey, startSlowTimer]);
+    }, [argsKey]);
     return {
         data: state.data,
         status: state.status,
         error: state.error,
         isLoading: state.status === "loading",
-        isError: state.status === "error" || state.status === "timeout" || state.status === "disconnected",
+        isError: state.status === "error" || state.status === "timeout",
         isSuccess: state.status === "success",
         isStale: state.isStale,
         retry,
     };
 }
-export function useQuery(ref, args = {}) {
+export function useLiveQuery(ref, args = {}) {
     const client = useGonvexClient();
-    const [result, setResult] = useState();
-    const [error, setError] = useState(null);
+    if (ref.delivery !== "live" || !ref.live?.plan) {
+        throw new Error(`useLiveQuery requires a structured Live Query reference: ${ref.path}`);
+    }
     const path = ref.path;
     const kind = ref.kind;
     const optimisticKey = JSON.stringify(ref.optimistic ?? null);
     const argsKey = JSON.stringify(args);
+    const liveKey = JSON.stringify(ref.live ?? null);
+    const liveWatch = useMemo(() => args === "skip" ? undefined : client.watchLiveQuery(ref, args), 
+    // 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);
+    return liveResult;
+}
+/** Subscribe to a host-owned Control Plane Query on the existing Gonvex connection. */
+export function useControlQuery(ref, args = {}) {
+    const client = useGonvexClient();
+    const argsKey = JSON.stringify(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);
+    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);
+}
+/** 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]);
+}
+/** Read a persisted Live Query window without opening another server subscription. */
+export function useRetainedLiveQuery(signatureOrReference, args = {}) {
+    const client = useGonvexClient();
+    const argsKey = JSON.stringify(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]);
+}
+/** Structured Live Query state backed by normalized Local Replica entities. */
+export function useLiveQueryState(ref, args = {}) {
+    const client = useGonvexClient();
+    const argsKey = JSON.stringify(args);
+    const signature = args === "skip" ? "" : client.replicaSignature(ref, args);
     useEffect(() => {
+        if (args === "skip")
+            return;
+        return client.subscribeLiveQuery(ref, args, () => undefined);
+        // 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 } : {}),
+        };
+    }
+    return signature
+        ? client.localReplica.liveQuery(signature)
+        : { rows: [], ids: [], source: "cache", completeness: "partial", freshness: client.localReplica.freshness() };
+}
+/** Execute a read-only Query once. Queries never subscribe or rerun. */
+export function useQuery(ref, args = {}) {
+    const client = useGonvexClient();
+    const [result, setResult] = useState();
+    const [error, setError] = useState(null);
+    const argsKey = JSON.stringify(args);
+    useEffect(() => {
+        let active = true;
         if (args === "skip") {
             setResult(undefined);
             setError(null);
-            return;
+            return () => { active = false; };
         }
         setResult(undefined);
         setError(null);
-        const unsubscribeScope = client.onSessionScopeChange(() => {
-            setResult(undefined);
-            setError(null);
-        });
-        const unsubscribeQuery = client.subscribeQuery(ref, args, (message) => {
-            if (message.type === "query.result") {
-                setResult(message.result);
-                setError(null);
-            }
-            if (message.type === "query.error") {
-                setResult(undefined);
-                setError(new GonvexClientError(message.error, { code: "server", path, operation: "query" }));
-            }
-        });
-        return () => {
-            unsubscribeScope();
-            unsubscribeQuery();
-        };
-    }, [client, kind, path, optimisticKey, argsKey]);
-    // Convex-compatible: a failed query throws during render so error
-    // boundaries can catch it, instead of being indistinguishable from loading.
+        void client.query(ref, args).then((value) => { if (active)
+            setResult(value); }, (failure) => { if (active)
+            setError(failure instanceof Error ? failure : new Error(String(failure))); });
+        return () => { active = false; };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [client, ref.kind, ref.path, argsKey]);
     if (error)
         throw error;
     return result;
 }
-export function useSync(ref, args = {}) {
+export function useReplicaCollection(ref, args = {}) {
     const client = useGonvexClient();
     const path = ref.path;
     const kind = ref.kind;
     const optimisticKey = JSON.stringify(ref.optimistic ?? null);
     const argsKey = JSON.stringify(args);
-    const watch = useMemo(() => args === "skip" ? undefined : client.watchSync(ref, args), 
+    const watch = useMemo(() => args === "skip" ? undefined : client.watchReplica(ref, args), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [client, kind, path, optimisticKey, argsKey]);
-    return useSyncExternalStore(useCallback((onStoreChange) => watch?.onUpdate(onStoreChange) ?? (() => undefined), [watch]), useCallback(() => watch?.localSyncResult(), [watch]), () => undefined);
+    return useSyncExternalStore(useCallback((onStoreChange) => watch?.onUpdate(onStoreChange) ?? (() => undefined), [watch]), useCallback(() => watch?.localReplicaResult(), [watch]), () => undefined);
+}
+/** Replica rows plus authoritative completeness, truncation, and freshness metadata. */
+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), 
+    // 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);
 }
-export function useSyncSelector(ref, args, selector, isEqual = Object.is) {
+export function useReplicaSelector(ref, args, selector, isEqual = Object.is) {
     const client = useGonvexClient();
     const path = ref.path;
     const kind = ref.kind;
@@ -758,7 +830,7 @@ export function useSyncSelector(ref, args, selector, isEqual = Object.is) {
     const equalityRef = useRef(isEqual);
     selectorRef.current = selector;
     equalityRef.current = isEqual;
-    const watch = useMemo(() => args === "skip" ? undefined : client.watchSync(ref, args), 
+    const watch = useMemo(() => args === "skip" ? undefined : client.watchReplica(ref, args), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [client, kind, path, optimisticKey, argsKey]);
     const selectedRef = useRef({
@@ -769,7 +841,7 @@ export function useSyncSelector(ref, args, selector, isEqual = Object.is) {
         selectedRef.current = { initialized: false, value: undefined };
     }, [watch]);
     const getSnapshot = useCallback(() => {
-        const rows = watch?.localSyncResult();
+        const rows = watch?.localReplicaResult();
         const next = rows === undefined ? undefined : selectorRef.current(rows);
         if (!selectedRef.current.initialized
             || next === undefined
@@ -784,7 +856,7 @@ export function useSyncSelector(ref, args, selector, isEqual = Object.is) {
             return () => undefined;
         return watch.onUpdate(() => {
             const previous = selectedRef.current.value;
-            const rows = watch.localSyncResult();
+            const rows = watch.localReplicaResult();
             const next = rows === undefined ? undefined : selectorRef.current(rows);
             if (selectedRef.current.initialized
                 && previous !== undefined
@@ -797,31 +869,25 @@ export function useSyncSelector(ref, args, selector, isEqual = Object.is) {
     }, [watch]);
     return useSyncExternalStore(subscribe, getSnapshot, () => undefined);
 }
-export function useMutation(ref, options = {}) {
+export function useReducer(ref, options = {}) {
     const client = useGonvexClient();
-    return (args = {}) => client.mutation(ref, args, options);
+    return (args = {}) => client.reducer(ref, args, options);
 }
 export function useAction(ref, options = {}) {
     const client = useGonvexClient();
     return (args = {}) => client.action(ref, args, options);
 }
-export function useConvex() {
-    return useGonvexClient();
-}
-export function useConvexAuth() {
-    return useContext(GonvexAuthContext);
-}
 const FALLBACK_CONNECTION_STATE = {
     isWebSocketConnected: false,
     hasEverConnected: false,
     connectionCount: 0,
     connectionRetries: 0,
     hasInflightRequests: false,
-    inflightMutations: 0,
+    inflightReducers: 0,
     inflightActions: 0,
     inflightOneShotQueries: 0,
 };
-export function useConvexConnectionState() {
+export function useGonvexConnectionState() {
     const client = useGonvexClient();
     const [state, setState] = useState(() => (typeof client.connectionState === "function" ? client.connectionState() : FALLBACK_CONNECTION_STATE));
     useEffect(() => {
@@ -832,18 +898,7 @@ export function useConvexConnectionState() {
     }, [client]);
     return state;
 }
-export function usePaginatedQuery(ref, args = {}, options = {}) {
-    const pageArgs = args === "skip" ? "skip" : { ...(isRecord(args) ? args : { args }), paginationOpts: { numItems: options.initialNumItems ?? 25, cursor: null } };
-    const result = useQuery(ref, pageArgs);
-    const page = Array.isArray(result) ? { page: result, isDone: true, continueCursor: null } : result;
-    return {
-        results: (page?.page ?? []),
-        status: args === "skip" ? "Exhausted" : result === undefined ? "LoadingFirstPage" : page?.isDone ? "Exhausted" : "CanLoadMore",
-        isLoading: args !== "skip" && result === undefined,
-        loadMore: (_numItems) => undefined,
-    };
-}
-function useGonvexClient() {
+export function useGonvexClient() {
     const client = useContext(GonvexContext);
     if (!client)
         throw new Error("GonvexProvider is required");