kitcn 0.0.1 → 0.12.1

package/dist/react/index.js

@@ -0,0 +1,2526 @@
+'use client';
+import { C as defaultIsUnauthorized, S as CRPCClientError, _ as useConvexAuthBridge, a as ConvexProviderWithAuth, b as useMaybeAuth, c as MaybeUnauthenticated, d as isSessionSyncGraceActive, f as useAuth, g as useAuthValue, h as useAuthStore, i as ConvexAuthBridge, l as Unauthenticated, m as useAuthState, n as AuthProvider, o as FetchAccessTokenContext, p as useAuthGuard, r as Authenticated, s as MaybeAuthenticated, t as AUTH_SESSION_SYNC_GRACE_MS, u as decodeJwtExp, v as useFetchAccessToken, w as isCRPCClientError, x as useSafeConvexAuth, y as useIsAuth } from "../auth-store-Cljlmdmi.js";
+import { ConvexProvider, ConvexReactClient, ConvexReactClient as ConvexReactClient$1, useAction, useConvex, useMutation } from "convex/react";
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from "react";
+import { jsx } from "react/jsx-runtime";
+import { getFunctionName } from "convex/server";
+import { notifyManager, skipToken, useQueries, useQueryClient } from "@tanstack/react-query";
+import { ConvexHttpClient } from "convex/browser";
+import { hashKey } from "@tanstack/query-core";
+import { convexToJson } from "convex/values";
+
+//#region src/shared/meta-utils.ts
+const metaCache = /* @__PURE__ */ new WeakMap();
+const nonMetaLeafKeys = new Set(["functionRef", "ref"]);
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isFunctionType(value) {
+	return value === "query" || value === "mutation" || value === "action";
+}
+function isMetaScalar(value) {
+	return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function extractLeafMeta(value) {
+	const type = value.type;
+	if (!isFunctionType(type)) return;
+	const result = { type };
+	for (const [key, entry] of Object.entries(value)) {
+		if (key === "type" || nonMetaLeafKeys.has(key) || key.startsWith("_")) continue;
+		if (entry === void 0) continue;
+		if (isMetaScalar(entry)) result[key] = entry;
+	}
+	return result;
+}
+function getHttpRoutes(api) {
+	const routes = api._http;
+	if (!isRecord(routes)) return;
+	const normalized = {};
+	for (const [routeKey, routeValue] of Object.entries(routes)) {
+		if (!isRecord(routeValue)) continue;
+		const routePath = routeValue.path;
+		const routeMethod = routeValue.method;
+		if (typeof routePath === "string" && typeof routeMethod === "string") normalized[routeKey] = {
+			path: routePath,
+			method: routeMethod
+		};
+	}
+	return normalized;
+}
+/**
+* Build a metadata index from merged API leaves.
+* Supports both generated `api` objects and plain metadata fixtures.
+*/
+function buildMetaIndex(api) {
+	const cached = metaCache.get(api);
+	if (cached) return cached;
+	const meta = {};
+	const httpRoutes = getHttpRoutes(api);
+	if (httpRoutes) meta._http = httpRoutes;
+	const walk = (node, path) => {
+		for (const [key, value] of Object.entries(node)) {
+			if (key.startsWith("_")) continue;
+			if (!isRecord(value)) continue;
+			const leafMeta = extractLeafMeta(value);
+			if (leafMeta) {
+				if (path.length === 0) continue;
+				const namespace = path.join("/");
+				meta[namespace] ??= {};
+				meta[namespace][key] = leafMeta;
+				continue;
+			}
+			walk(value, [...path, key]);
+		}
+	};
+	walk(api, []);
+	metaCache.set(api, meta);
+	return meta;
+}
+/**
+* Get a function reference from the API object by traversing the path.
+*/
+function getFuncRef(api, path) {
+	let current = api;
+	for (const key of path) if (current && typeof current === "object") {
+		const next = current[key];
+		if (next === void 0) throw new Error(`Invalid path: ${path.join(".")}`);
+		current = next;
+	} else throw new Error(`Invalid path: ${path.join(".")}`);
+	if (current && typeof current === "object") {
+		const maybeFunctionRef = current.functionRef;
+		if (maybeFunctionRef && typeof maybeFunctionRef === "object") return maybeFunctionRef;
+	}
+	if (!current || typeof current !== "object") throw new Error(`Invalid function reference at path: ${path.join(".")}`);
+	return current;
+}
+/**
+* Get function type from meta using path.
+* Supports nested paths like ['items', 'queries', 'list'] → namespace='items/queries', fn='list'
+*
+* @param path - Path segments like ['todos', 'create'] or ['items', 'queries', 'list']
+* @param meta - The meta object from codegen
+* @returns Function type or 'query' as default
+*/
+function getFunctionType(path, source) {
+	if (path.length < 2) return "query";
+	const meta = buildMetaIndex(source);
+	const fnName = path.at(-1);
+	const fnType = meta[path.slice(0, -1).join("/")]?.[fnName]?.type;
+	if (fnType === "query" || fnType === "mutation" || fnType === "action") return fnType;
+	return "query";
+}
+/**
+* Get function metadata from meta using path.
+* Supports nested paths like ['items', 'queries', 'list'] → namespace='items/queries', fn='list'
+*
+* @param path - Path segments like ['todos', 'create'] or ['items', 'queries', 'list']
+* @param meta - The meta object from codegen
+* @returns Function metadata or undefined
+*/
+function getFunctionMeta(path, source) {
+	if (path.length < 2) return;
+	const meta = buildMetaIndex(source);
+	const fnName = path.at(-1);
+	return meta[path.slice(0, -1).join("/")]?.[fnName];
+}
+
+//#endregion
+//#region src/crpc/http-types.ts
+/** HTTP client error */
+var HttpClientError = class extends Error {
+	name = "HttpClientError";
+	code;
+	status;
+	procedureName;
+	constructor(opts) {
+		super(opts.message ?? `${opts.code}: ${opts.procedureName}`);
+		this.code = opts.code;
+		this.status = opts.status;
+		this.procedureName = opts.procedureName;
+	}
+};
+
+//#endregion
+//#region src/crpc/http-client.ts
+/**
+* HTTP Client Helpers
+*
+* Framework-agnostic utilities for executing HTTP requests
+* against Convex HTTP endpoints.
+*/
+/** Reserved keys that are not part of JSON body */
+const RESERVED_KEYS = new Set([
+	"params",
+	"searchParams",
+	"form",
+	"fetch",
+	"init",
+	"headers"
+]);
+/**
+* Replace URL path parameters with actual values.
+* e.g., '/users/:id' with { id: '123' } -> '/users/123'
+*/
+function replaceUrlParam(url, params) {
+	return url.replace(/:(\w+)/g, (_, key) => {
+		const value = params[key];
+		return value !== void 0 ? encodeURIComponent(value) : `:${key}`;
+	});
+}
+/**
+* Build URLSearchParams from query object.
+* Handles array values as multiple params with same key (like Hono).
+*/
+function buildSearchParams(query) {
+	const params = new URLSearchParams();
+	for (const [key, value] of Object.entries(query)) if (Array.isArray(value)) for (const v of value) params.append(key, v);
+	else if (value !== void 0 && value !== null) params.append(key, value);
+	return params;
+}
+/**
+* Hono-style HTTP request executor.
+* Processes args in the same way as Hono's ClientRequestImpl.fetch().
+*/
+async function executeHttpRequest(opts) {
+	const { method, path } = opts.route;
+	const args = opts.args ?? {};
+	let rBody;
+	let cType;
+	if (args.form) {
+		const form = new FormData();
+		for (const [k, v] of Object.entries(args.form)) if (Array.isArray(v)) for (const v2 of v) form.append(k, v2);
+		else form.append(k, v);
+		rBody = form;
+	} else {
+		const jsonBody = {};
+		for (const [key, value] of Object.entries(args)) if (!RESERVED_KEYS.has(key) && value !== void 0) jsonBody[key] = value;
+		if (Object.keys(jsonBody).length > 0) {
+			rBody = JSON.stringify(opts.transformer.input.serialize(jsonBody));
+			cType = "application/json";
+		}
+	}
+	const argsClientOpts = {};
+	if (args.fetch) argsClientOpts.fetch = args.fetch;
+	if (args.init) argsClientOpts.init = args.init;
+	if (args.headers) argsClientOpts.headers = args.headers;
+	const mergedClientOpts = {
+		...opts.clientOpts,
+		...argsClientOpts
+	};
+	const resolvedBaseHeaders = typeof opts.baseHeaders === "function" ? await opts.baseHeaders() : opts.baseHeaders;
+	const headerValues = { ...typeof mergedClientOpts.headers === "function" ? await mergedClientOpts.headers() : mergedClientOpts.headers };
+	if (cType) headerValues["Content-Type"] = cType;
+	const finalHeaders = {};
+	if (resolvedBaseHeaders) {
+		for (const [key, value] of Object.entries(resolvedBaseHeaders)) if (value !== void 0) finalHeaders[key] = value;
+	}
+	Object.assign(finalHeaders, headerValues);
+	let url = opts.convexSiteUrl + path;
+	if (args.params) url = opts.convexSiteUrl + replaceUrlParam(path, args.params);
+	if (args.searchParams) {
+		const queryString = buildSearchParams(args.searchParams).toString();
+		if (queryString) url = `${url}?${queryString}`;
+	}
+	const methodUpperCase = method.toUpperCase();
+	const setBody = !(methodUpperCase === "GET" || methodUpperCase === "HEAD");
+	const response = await (mergedClientOpts.fetch ?? opts.baseFetch ?? globalThis.fetch)(url, {
+		body: setBody ? rBody : void 0,
+		method: methodUpperCase,
+		headers: finalHeaders,
+		...mergedClientOpts.init
+	});
+	if (!response.ok) {
+		const errorData = await response.json().catch(() => ({ error: {
+			code: "UNKNOWN",
+			message: response.statusText
+		} }));
+		const errorCode = errorData?.error?.code || "UNKNOWN";
+		const errorMessage = errorData?.error?.message || response.statusText;
+		throw new HttpClientError({
+			code: errorCode,
+			status: response.status,
+			procedureName: opts.procedureName,
+			message: errorMessage
+		});
+	}
+	if (response.headers.get("content-length") === "0" || response.status === 204) return;
+	if ((response.headers.get("content-type") || "").includes("application/json")) return opts.transformer.output.deserialize(await response.json());
+	return response.text();
+}
+
+//#endregion
+//#region src/crpc/transformer.ts
+const isPlainObject = (value) => {
+	if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+	const prototype = Object.getPrototypeOf(value);
+	return prototype === Object.prototype || prototype === null;
+};
+const CODEC_MARKER_KEY = "__crpc";
+const CODEC_MARKER_VALUE = 1;
+const CODEC_TAG_KEY = "t";
+const CODEC_VALUE_KEY = "v";
+const hasOnlyCodecPayloadKeys = (value) => {
+	let keyCount = 0;
+	for (const key in value) {
+		if (!Object.hasOwn(value, key)) continue;
+		keyCount += 1;
+		if (key !== CODEC_MARKER_KEY && key !== CODEC_TAG_KEY && key !== CODEC_VALUE_KEY) return false;
+		if (keyCount > 3) return false;
+	}
+	return keyCount === 3;
+};
+/**
+* Date wire tag (Convex-style reserved key).
+*/
+const DATE_CODEC_TAG = "$date";
+/**
+* Built-in Date codec.
+*/
+const dateWireCodec = {
+	tag: DATE_CODEC_TAG,
+	isType: (value) => value instanceof Date,
+	encode: (value) => value.getTime(),
+	decode: (value) => {
+		if (typeof value !== "number") return value;
+		return new Date(value);
+	}
+};
+/**
+* Build a recursive tagged transformer from codecs.
+*/
+const createTaggedTransformer = (codecs) => {
+	const codecByTag = /* @__PURE__ */ new Map();
+	for (const codec of codecs) {
+		if (!codec.tag.startsWith("$")) throw new Error(`Invalid wire codec tag '${codec.tag}'. Tags must start with '$'.`);
+		if (codecByTag.has(codec.tag)) throw new Error(`Duplicate wire codec tag '${codec.tag}'.`);
+		codecByTag.set(codec.tag, codec);
+	}
+	const serialize = (value) => {
+		for (const codec of codecs) if (codec.isType(value)) return {
+			[CODEC_MARKER_KEY]: CODEC_MARKER_VALUE,
+			[CODEC_TAG_KEY]: codec.tag,
+			[CODEC_VALUE_KEY]: serialize(codec.encode(value))
+		};
+		if (Array.isArray(value)) {
+			let result;
+			for (let index = 0; index < value.length; index += 1) {
+				const item = value[index];
+				const serialized = serialize(item);
+				if (serialized !== item) {
+					if (!result) result = value.slice();
+					result[index] = serialized;
+				}
+			}
+			return result ?? value;
+		}
+		if (isPlainObject(value)) {
+			let result;
+			for (const key in value) {
+				if (!Object.hasOwn(value, key)) continue;
+				const nested = value[key];
+				const serialized = serialize(nested);
+				if (serialized !== nested) {
+					if (!result) result = { ...value };
+					result[key] = serialized;
+				}
+			}
+			return result ?? value;
+		}
+		return value;
+	};
+	const deserialize = (value) => {
+		if (Array.isArray(value)) {
+			let result;
+			for (let index = 0; index < value.length; index += 1) {
+				const item = value[index];
+				const deserialized = deserialize(item);
+				if (deserialized !== item) {
+					if (!result) result = value.slice();
+					result[index] = deserialized;
+				}
+			}
+			return result ?? value;
+		}
+		if (isPlainObject(value)) {
+			const marker = value[CODEC_MARKER_KEY];
+			const tag = value[CODEC_TAG_KEY];
+			if (marker === CODEC_MARKER_VALUE && typeof tag === "string" && CODEC_VALUE_KEY in value && hasOnlyCodecPayloadKeys(value)) {
+				const codec = codecByTag.get(tag);
+				if (codec) return codec.decode(deserialize(value[CODEC_VALUE_KEY]));
+			}
+			let result;
+			for (const key in value) {
+				if (!Object.hasOwn(value, key)) continue;
+				const nested = value[key];
+				const deserialized = deserialize(nested);
+				if (deserialized !== nested) {
+					if (!result) result = { ...value };
+					result[key] = deserialized;
+				}
+			}
+			return result ?? value;
+		}
+		return value;
+	};
+	return {
+		serialize,
+		deserialize
+	};
+};
+/**
+* Default cRPC transformer (Date-enabled).
+*/
+const defaultCRPCTransformer = createTaggedTransformer([dateWireCodec]);
+const DEFAULT_COMBINED_TRANSFORMER = {
+	input: defaultCRPCTransformer,
+	output: defaultCRPCTransformer
+};
+/**
+* Normalize transformer config to split input/output shape.
+*/
+const normalizeCustomTransformer = (transformer) => {
+	if (!transformer) return;
+	if ("input" in transformer && "output" in transformer) return transformer;
+	return {
+		input: transformer,
+		output: transformer
+	};
+};
+/**
+* Compose user transformer with default Date transformer.
+*
+* Date transformer is always active:
+* - serialize: user -> default(Date)
+* - deserialize: default(Date) -> user
+*/
+const composeWithDefault = (transformer) => {
+	if (!transformer) return defaultCRPCTransformer;
+	return {
+		serialize: (value) => defaultCRPCTransformer.serialize(transformer.serialize(value)),
+		deserialize: (value) => transformer.deserialize(defaultCRPCTransformer.deserialize(value))
+	};
+};
+const transformerCache = /* @__PURE__ */ new WeakMap();
+/**
+* Normalize transformer config to split input/output shape.
+* User transformers are additive and always composed with default Date handling.
+*/
+const getTransformer = (transformer) => {
+	if (!transformer) return DEFAULT_COMBINED_TRANSFORMER;
+	const cacheKey = transformer;
+	const cached = transformerCache.get(cacheKey);
+	if (cached) return cached;
+	const custom = normalizeCustomTransformer(transformer);
+	const resolved = {
+		input: composeWithDefault(custom?.input),
+		output: composeWithDefault(custom?.output)
+	};
+	transformerCache.set(cacheKey, resolved);
+	return resolved;
+};
+
+//#endregion
+//#region src/react/http-proxy.ts
+/**
+* Create a recursive proxy for HTTP routes with TanStack Query integration.
+*
+* Terminal methods:
+* - GET endpoints: `queryOptions`, `queryKey`
+* - POST/PUT/PATCH/DELETE: `mutationOptions`, `mutationKey`
+*/
+function createRecursiveHttpProxy(opts, path = []) {
+	return new Proxy(() => {}, { get(_, prop) {
+		if (typeof prop === "symbol") return;
+		if (prop === "then") return;
+		const routeKey = path.join(".");
+		const route = opts.routes[routeKey];
+		if (prop === "query") {
+			if (!route) throw new Error(`Unknown HTTP procedure: ${routeKey}`);
+			return async (args) => {
+				try {
+					return await executeHttpRequest({
+						convexSiteUrl: opts.convexSiteUrl,
+						route,
+						procedureName: routeKey,
+						args,
+						baseHeaders: opts.headers,
+						baseFetch: opts.fetch,
+						transformer: opts.transformer
+					});
+				} catch (error) {
+					if (opts.onError && error instanceof HttpClientError) opts.onError(error);
+					throw error;
+				}
+			};
+		}
+		if (prop === "mutate") {
+			if (!route) throw new Error(`Unknown HTTP procedure: ${routeKey}`);
+			return async (args) => {
+				try {
+					return await executeHttpRequest({
+						convexSiteUrl: opts.convexSiteUrl,
+						route,
+						procedureName: routeKey,
+						args,
+						baseHeaders: opts.headers,
+						baseFetch: opts.fetch,
+						transformer: opts.transformer
+					});
+				} catch (error) {
+					if (opts.onError && error instanceof HttpClientError) opts.onError(error);
+					throw error;
+				}
+			};
+		}
+		if (prop === "queryOptions") {
+			if (!route) throw new Error(`Unknown HTTP procedure: ${routeKey}`);
+			if (route.method !== "GET") throw new Error(`queryOptions is only available for GET endpoints, got ${route.method} for ${routeKey}`);
+			return (args, queryOpts) => ({
+				...queryOpts,
+				queryKey: [
+					"httpQuery",
+					routeKey,
+					args
+				],
+				queryFn: async () => {
+					try {
+						return await executeHttpRequest({
+							convexSiteUrl: opts.convexSiteUrl,
+							route,
+							procedureName: routeKey,
+							args,
+							baseHeaders: opts.headers,
+							baseFetch: opts.fetch,
+							transformer: opts.transformer
+						});
+					} catch (error) {
+						if (opts.onError && error instanceof HttpClientError) opts.onError(error);
+						throw error;
+					}
+				}
+			});
+		}
+		if (prop === "queryKey") return (args) => {
+			return args !== void 0 && !(typeof args === "object" && args !== null && Object.keys(args).length === 0) ? [
+				"httpQuery",
+				routeKey,
+				args
+			] : ["httpQuery", routeKey];
+		};
+		if (prop === "queryFilter") return (args, filters) => {
+			const hasArgs = args !== void 0 && !(typeof args === "object" && args !== null && Object.keys(args).length === 0);
+			return {
+				...filters,
+				queryKey: hasArgs ? [
+					"httpQuery",
+					routeKey,
+					args
+				] : ["httpQuery", routeKey]
+			};
+		};
+		if (prop === "mutationOptions") {
+			if (!route) throw new Error(`Unknown HTTP procedure: ${routeKey}`);
+			return (mutationOpts) => ({
+				...mutationOpts,
+				mutationKey: ["httpMutation", routeKey],
+				mutationFn: async (args) => {
+					try {
+						return await executeHttpRequest({
+							convexSiteUrl: opts.convexSiteUrl,
+							route,
+							procedureName: routeKey,
+							args,
+							baseHeaders: opts.headers,
+							baseFetch: opts.fetch,
+							transformer: opts.transformer
+						});
+					} catch (error) {
+						if (opts.onError && error instanceof HttpClientError) opts.onError(error);
+						throw error;
+					}
+				}
+			});
+		}
+		if (prop === "mutationKey") return () => ["httpMutation", routeKey];
+		return createRecursiveHttpProxy(opts, [...path, prop]);
+	} });
+}
+/**
+* Create an HTTP proxy with TanStack Query integration.
+*
+* Returns a proxy that provides:
+* - `queryOptions` for GET endpoints (no subscription)
+* - `mutationOptions` for POST/PUT/PATCH/DELETE endpoints
+*
+* @example
+* ```ts
+* const httpProxy = createHttpProxy<AppRouter>({
+*   convexSiteUrl: process.env.NEXT_PUBLIC_CONVEX_SITE_URL!,
+*   routes: httpRoutes,
+* });
+*
+* // GET endpoint
+* const opts = httpProxy.todos.get.queryOptions({ id: '123' });
+* const { data } = useQuery(opts);
+*
+* // POST endpoint
+* const mutation = useMutation(httpProxy.todos.create.mutationOptions());
+* await mutation.mutateAsync({ title: 'New todo' });
+* ```
+*/
+function createHttpProxy(opts) {
+	const transformer = getTransformer(opts.transformer);
+	return createRecursiveHttpProxy({
+		convexSiteUrl: opts.convexSiteUrl,
+		routes: opts.routes,
+		headers: opts.headers,
+		fetch: opts.fetch,
+		onError: opts.onError,
+		transformer
+	});
+}
+
+//#endregion
+//#region src/crpc/query-options.ts
+/**
+* Query options factory for Convex query function subscriptions.
+* Requires `convexQueryClient.queryFn()` set as the default `queryFn` globally.
+*/
+function convexQuery(funcRef, args, meta, opts) {
+	const finalArgs = args ?? {};
+	const isSkip = finalArgs === "skip";
+	const funcName = getFunctionName(funcRef);
+	const [namespace, fnName] = funcName.split(":");
+	const authType = meta?.[namespace]?.[fnName]?.auth;
+	const skipUnauth = opts?.skipUnauth;
+	return {
+		queryKey: [
+			"convexQuery",
+			funcName,
+			isSkip ? "skip" : finalArgs
+		],
+		staleTime: Number.POSITIVE_INFINITY,
+		refetchInterval: false,
+		refetchOnMount: false,
+		refetchOnReconnect: false,
+		refetchOnWindowFocus: false,
+		...isSkip ? { enabled: false } : {},
+		meta: {
+			authType,
+			skipUnauth,
+			subscribe: true
+		}
+	};
+}
+/**
+* Query options factory for Convex action functions.
+* Actions are NOT reactive - they follow normal TanStack Query semantics.
+*
+* @example
+* ```ts
+* useQuery(convexAction(api.ai.generate, { prompt }))
+* ```
+*
+* @example With additional options (use spread):
+* ```ts
+* useQuery({
+*   ...convexAction(api.files.process, { fileId }),
+*   staleTime: 60_000
+* });
+* ```
+*/
+function convexAction(funcRef, args, meta, opts) {
+	const finalArgs = args ?? {};
+	const isSkip = finalArgs === "skip";
+	const funcName = getFunctionName(funcRef);
+	const [namespace, fnName] = funcName.split(":");
+	const authType = meta?.[namespace]?.[fnName]?.auth;
+	const skipUnauth = opts?.skipUnauth;
+	return {
+		queryKey: [
+			"convexAction",
+			funcName,
+			isSkip ? {} : finalArgs
+		],
+		staleTime: Number.POSITIVE_INFINITY,
+		refetchInterval: false,
+		refetchOnMount: false,
+		refetchOnReconnect: false,
+		refetchOnWindowFocus: false,
+		...isSkip ? { enabled: false } : {},
+		meta: {
+			authType,
+			skipUnauth,
+			subscribe: false
+		}
+	};
+}
+/**
+* Infinite query options factory for paginated Convex queries.
+* Server-safe (non-hook) - can be used in RSC.
+*
+* Uses flat { cursor, limit } input like tRPC.
+*/
+function convexInfiniteQueryOptions(funcRef, args, opts = {}, meta) {
+	const { limit, skipUnauth, enabled, ...queryOptions } = opts;
+	const finalArgs = args === "skip" ? {} : args;
+	const isSkip = args === "skip";
+	const funcName = getFunctionName(funcRef);
+	const [namespace, fnName] = funcName.split(":");
+	const authType = (meta?.[namespace]?.[fnName])?.auth;
+	const firstPageArgs = {
+		...finalArgs,
+		cursor: null,
+		limit
+	};
+	const finalEnabled = enabled === false || isSkip ? false : void 0;
+	return {
+		queryKey: [
+			"convexQuery",
+			funcName,
+			firstPageArgs
+		],
+		staleTime: Number.POSITIVE_INFINITY,
+		refetchInterval: false,
+		refetchOnMount: false,
+		refetchOnReconnect: false,
+		refetchOnWindowFocus: false,
+		...queryOptions,
+		...finalEnabled === false ? { enabled: false } : {},
+		meta: {
+			authType,
+			skipUnauth,
+			subscribe: true,
+			queryName: funcName,
+			args: finalArgs,
+			limit
+		}
+	};
+}
+
+//#endregion
+//#region src/crpc/types.ts
+/** Symbol key for attaching FunctionReference to options (non-serializable) */
+const FUNC_REF_SYMBOL = Symbol.for("convex.funcRef");
+
+//#endregion
+//#region src/internal/auth.ts
+/** Get auth type from meta for a function */
+function getAuthType(meta, funcName) {
+	const [namespace, fnName] = funcName.split(":");
+	return meta?.[namespace]?.[fnName]?.auth;
+}
+/** Hook to compute auth-based skip logic for queries */
+function useAuthSkip(funcRef, opts) {
+	const { isAuthenticated, isLoading: isAuthLoading } = useSafeConvexAuth();
+	const authType = getAuthType(useMeta(), getFunctionName(funcRef));
+	const authLoadingApplies = authType === "optional" || authType === "required";
+	return {
+		authType,
+		isAuthLoading,
+		isAuthenticated,
+		shouldSkip: opts?.enabled === false || authLoadingApplies && isAuthLoading || authType === "required" && !isAuthenticated && !isAuthLoading || !isAuthenticated && !isAuthLoading && !!opts?.skipUnauth
+	};
+}
+
+//#endregion
+//#region src/react/use-query-options.ts
+/** biome-ignore-all lint/suspicious/noExplicitAny: Convex type compatibility */
+/**
+* Query options factories for Convex functions.
+* Forked from @convex-dev/react-query to support auth-aware error handling.
+*/
+/**
+* Hook that returns query options for use with useQuery.
+* Handles skipUnauth by setting enabled: false when unauthorized.
+*
+* @example
+* ```tsx
+* const { data } = useQuery(useConvexQueryOptions(api.user.get, { id }));
+* ```
+*
+* @example With skipToken for conditional queries
+* ```tsx
+* const { data } = useQuery(useConvexQueryOptions(api.user.get, userId ? { id: userId } : skipToken));
+* ```
+*
+* @example With skipUnauth
+* ```tsx
+* const { data } = useQuery(useConvexQueryOptions(api.user.get, { id }, { skipUnauth: true }));
+* ```
+*
+* @example With TanStack Query options
+* ```tsx
+* const { data } = useQuery(useConvexQueryOptions(api.user.get, { id }, { enabled: !!id, placeholderData: [] }));
+* ```
+*/
+function useConvexQueryOptions(funcRef, args, options) {
+	const isSkipped = args === skipToken;
+	const enabled = typeof options?.enabled === "function" ? void 0 : options?.enabled;
+	const { authType, shouldSkip } = useAuthSkip(funcRef, {
+		enabled: isSkipped ? false : enabled,
+		skipUnauth: options?.skipUnauth
+	});
+	const baseOptions = convexQuery(funcRef, isSkipped ? {} : args);
+	const { skipUnauth: _, subscribe, ...queryOptions } = options ?? {};
+	return {
+		...baseOptions,
+		...queryOptions,
+		enabled: isSkipped ? false : !shouldSkip,
+		meta: {
+			...baseOptions.meta,
+			authType,
+			subscribe: subscribe !== false
+		}
+	};
+}
+/**
+* Hook that returns infinite query options for use with useInfiniteQuery.
+* Handles auth type detection from meta and skipUnauth.
+*
+* @example
+* ```tsx
+* const { data } = useInfiniteQuery(
+*   useConvexInfiniteQueryOptions(api.posts.list, { userId }, { limit: 20 })
+* );
+* ```
+*
+* @example With skipToken for conditional queries
+* ```tsx
+* const { data } = useInfiniteQuery(
+*   useConvexInfiniteQueryOptions(api.posts.list, userId ? { userId } : skipToken, { limit: 20 })
+* );
+* ```
+*
+* @example With skipUnauth
+* ```tsx
+* const { data } = useInfiniteQuery(
+*   useConvexInfiniteQueryOptions(api.posts.list, { userId }, { limit: 20, skipUnauth: true })
+* );
+* ```
+*/
+function useConvexInfiniteQueryOptions(funcRef, args, opts) {
+	const meta = useMeta();
+	const isSkipped = args === skipToken;
+	const enabledOpt = typeof opts.enabled === "function" ? void 0 : opts.enabled;
+	const { authType, shouldSkip } = useAuthSkip(funcRef, {
+		enabled: isSkipped ? false : enabledOpt,
+		skipUnauth: opts.skipUnauth
+	});
+	const enabled = isSkipped || shouldSkip ? false : enabledOpt;
+	const baseOptions = convexInfiniteQueryOptions(funcRef, isSkipped ? {} : args, {
+		...opts,
+		enabled
+	}, meta);
+	return {
+		...baseOptions,
+		meta: {
+			...baseOptions.meta,
+			authType
+		}
+	};
+}
+/**
+* Hook that returns query options for using an action as a one-shot query.
+* Actions don't support WebSocket subscriptions - they're one-time calls.
+*
+* @example
+* ```tsx
+* const { data } = useQuery(useConvexActionQueryOptions(api.ai.analyze, { id }));
+* ```
+*
+* @example With skipToken for conditional queries
+* ```tsx
+* const { data } = useQuery(useConvexActionQueryOptions(api.ai.analyze, id ? { id } : skipToken));
+* ```
+*
+* @example With skipUnauth
+* ```tsx
+* const { data } = useQuery(useConvexActionQueryOptions(api.ai.analyze, { id }, { skipUnauth: true }));
+* ```
+*/
+function useConvexActionQueryOptions(action, args, options) {
+	const isSkipped = args === skipToken;
+	const enabled = typeof options?.enabled === "function" ? void 0 : options?.enabled;
+	const { shouldSkip } = useAuthSkip(action, {
+		enabled: isSkipped ? false : enabled,
+		skipUnauth: options?.skipUnauth
+	});
+	const baseOptions = convexAction(action, isSkipped ? {} : args);
+	const { skipUnauth: _, ...queryOptions } = options ?? {};
+	return {
+		...baseOptions,
+		...queryOptions,
+		enabled: isSkipped ? false : !shouldSkip
+	};
+}
+/**
+* Hook that returns mutation options for use with useMutation.
+* Wraps the Convex mutation with auth guard logic.
+*
+* @example
+* ```tsx
+* const { mutate } = useMutation(useConvexMutationOptions(api.user.update));
+* ```
+*
+* @example With TanStack Query options
+* ```tsx
+* const { mutate } = useMutation(useConvexMutationOptions(api.user.update, {
+*   onSuccess: () => toast.success('Updated!'),
+* }));
+* ```
+*/
+function useConvexMutationOptions(mutation, options, transformer) {
+	const guard = useAuthGuard();
+	const getMeta = useFnMeta();
+	const name = getFunctionName(mutation);
+	const [namespace, fnName] = name.split(":");
+	const authType = getMeta(namespace, fnName)?.auth;
+	const convexMutation = useMutation(mutation);
+	const resolvedTransformer = getTransformer(transformer);
+	return {
+		...options,
+		mutationFn: async (args) => {
+			if (authType === "required" && guard()) throw new CRPCClientError({
+				code: "UNAUTHORIZED",
+				functionName: name
+			});
+			return convexMutation(resolvedTransformer.input.serialize(args));
+		}
+	};
+}
+/**
+* Hook that returns action options for use with useMutation.
+* Wraps the Convex action with auth guard logic.
+*
+* @example
+* ```tsx
+* const { mutate } = useMutation(useConvexActionOptions(api.ai.generate));
+* ```
+*
+* @example With TanStack Query options
+* ```tsx
+* const { mutate } = useMutation(useConvexActionOptions(api.ai.generate, {
+*   onSuccess: (data) => console.info(data),
+* }));
+* ```
+*/
+function useConvexActionOptions(action, options, transformer) {
+	const guard = useAuthGuard();
+	const getMeta = useFnMeta();
+	const name = getFunctionName(action);
+	const [namespace, fnName] = name.split(":");
+	const authType = getMeta(namespace, fnName)?.auth;
+	const convexAction = useAction(action);
+	const resolvedTransformer = getTransformer(transformer);
+	return {
+		...options,
+		mutationFn: async (args) => {
+			if (authType === "required" && guard()) throw new CRPCClientError({
+				code: "UNAUTHORIZED",
+				functionName: name
+			});
+			return convexAction(resolvedTransformer.input.serialize(args));
+		}
+	};
+}
+/**
+* Hook that returns upload mutation options for use with useMutation.
+* Generates a presigned URL, then uploads the file directly to storage.
+*
+* @example
+* ```tsx
+* const { mutate } = useMutation(useUploadMutationOptions(api.storage.generateUrl));
+* mutate({ file, ...otherArgs });
+* ```
+*
+* @example With TanStack Query options
+* ```tsx
+* const { mutate } = useMutation(useUploadMutationOptions(api.storage.generateUrl, {
+*   onSuccess: (result) => console.info('Uploaded:', result.key),
+* }));
+* ```
+*/
+function useUploadMutationOptions(generateUrlMutation, options) {
+	const generateUrl = useMutation(generateUrlMutation);
+	return {
+		...options,
+		mutationFn: async ({ file, ...args }) => {
+			const result = await generateUrl(args);
+			const { url } = result;
+			const response = await fetch(url, {
+				body: file,
+				headers: { "Content-Type": file.type },
+				method: "PUT"
+			});
+			if (!response.ok) throw new Error(`Upload failed: ${response.statusText}`);
+			return result;
+		}
+	};
+}
+
+//#endregion
+//#region src/react/proxy.ts
+/**
+* CRPC Recursive Proxy
+*
+* Creates a tRPC-like proxy that wraps Convex API functions with
+* TanStack Query options builders.
+*
+* @example
+* ```ts
+* const crpc = createCRPCOptionsProxy(api);
+* const opts = crpc.user.get.queryOptions({ id: '123' });
+* const { data } = useQuery(opts);
+* ```
+*/
+/** Get query key prefix based on function type */
+function getQueryKeyPrefix(path, meta) {
+	if (getFunctionType(path, meta) === "action") return "convexAction";
+	return "convexQuery";
+}
+/**
+* Create a recursive proxy that accumulates path segments.
+*/
+function createRecursiveProxy(api, path, meta, transformer) {
+	return new Proxy(() => {}, { get(_target, prop) {
+		if (typeof prop === "symbol") return;
+		if (prop === "then") return;
+		if (prop === "queryOptions") return (args = {}, opts) => {
+			const funcRef = getFuncRef(api, path);
+			if (getFunctionType(path, meta) === "action") return useConvexActionQueryOptions(funcRef, args, opts);
+			return useConvexQueryOptions(funcRef, args, opts);
+		};
+		if (prop === "staticQueryOptions") return (args = {}, opts) => {
+			const funcRef = getFuncRef(api, path);
+			const fnType = getFunctionType(path, meta);
+			const finalArgs = args === skipToken ? "skip" : args;
+			if (fnType === "action") return convexAction(funcRef, finalArgs, meta, opts);
+			return convexQuery(funcRef, finalArgs, meta, opts);
+		};
+		if (prop === "queryKey") return (args = {}) => {
+			const funcName = getFunctionName(getFuncRef(api, path));
+			return [
+				getQueryKeyPrefix(path, meta),
+				funcName,
+				args
+			];
+		};
+		if (prop === "queryFilter") return (args, filters) => {
+			const funcName = getFunctionName(getFuncRef(api, path));
+			const prefix = getQueryKeyPrefix(path, meta);
+			return {
+				...filters,
+				queryKey: [
+					prefix,
+					funcName,
+					args
+				]
+			};
+		};
+		if (prop === "infiniteQueryOptions") return (args = {}, opts = {}) => {
+			const funcRef = getFuncRef(api, path);
+			const options = useConvexInfiniteQueryOptions(funcRef, args, opts);
+			Object.defineProperty(options, FUNC_REF_SYMBOL, {
+				value: funcRef,
+				enumerable: false,
+				configurable: false
+			});
+			return options;
+		};
+		if (prop === "infiniteQueryKey") return (args) => {
+			return [
+				"convexQuery",
+				getFunctionName(getFuncRef(api, path)),
+				args ?? {}
+			];
+		};
+		if (prop === "meta" && path.length >= 2) return getFunctionMeta(path, meta);
+		if (prop === "mutationKey") return () => {
+			return ["convexMutation", getFunctionName(getFuncRef(api, path))];
+		};
+		if (prop === "mutationOptions") return (opts) => {
+			const funcRef = getFuncRef(api, path);
+			if (getFunctionType(path, meta) === "action") return useConvexActionOptions(funcRef, opts, transformer);
+			return useConvexMutationOptions(funcRef, opts, transformer);
+		};
+		return createRecursiveProxy(api, [...path, prop], meta, transformer);
+	} });
+}
+/**
+* Create a CRPC proxy for a Convex API object.
+*
+* The proxy provides a tRPC-like interface for accessing Convex functions
+* with TanStack Query options builders.
+*
+* @param api - The Convex API object (from `@convex/api`)
+* @param meta - Generated function metadata for runtime type detection
+* @returns A typed proxy with queryOptions/mutationOptions methods
+*
+* @example
+* ```tsx
+* import { api } from '@convex/api';
+*
+* // Usually you should use createCRPCContext({ api }) instead.
+* // createCRPCOptionsProxy is a low-level helper.
+* const crpc = createCRPCOptionsProxy(api, {} as any);
+*
+* function MyComponent() {
+*   const { data } = useQuery(crpc.user.get.queryOptions({ id }));
+*   const { mutate } = useMutation(crpc.user.update.mutationOptions());
+* }
+* ```
+*/
+function createCRPCOptionsProxy(api, meta, transformer) {
+	return createRecursiveProxy(api, [], meta, transformer);
+}
+
+//#endregion
+//#region src/react/vanilla-client.ts
+/**
+* Create a recursive proxy for vanilla (direct) calls.
+*/
+function createRecursiveVanillaProxy(api, path, meta, convexClient, transformer) {
+	return new Proxy(() => {}, { get(_target, prop) {
+		if (typeof prop === "symbol") return;
+		if (prop === "then") return;
+		if (prop === "query") return async (args = {}) => {
+			const funcRef = getFuncRef(api, path);
+			const fnType = getFunctionType(path, meta);
+			const wireArgs = transformer.input.serialize(args);
+			if (fnType === "action") return transformer.output.deserialize(await convexClient.action(funcRef, wireArgs));
+			return transformer.output.deserialize(await convexClient.query(funcRef, wireArgs));
+		};
+		if (prop === "watchQuery") return (args = {}, opts) => {
+			const funcRef = getFuncRef(api, path);
+			return convexClient.watchQuery(funcRef, transformer.input.serialize(args), opts);
+		};
+		if (prop === "mutate") return async (args = {}) => {
+			const funcRef = getFuncRef(api, path);
+			const fnType = getFunctionType(path, meta);
+			const wireArgs = transformer.input.serialize(args);
+			if (fnType === "action") return transformer.output.deserialize(await convexClient.action(funcRef, wireArgs));
+			return transformer.output.deserialize(await convexClient.mutation(funcRef, wireArgs));
+		};
+		return createRecursiveVanillaProxy(api, [...path, prop], meta, convexClient, transformer);
+	} });
+}
+/**
+* Create a vanilla CRPC proxy for direct procedural calls.
+*
+* The proxy provides a tRPC-like interface for imperative Convex function calls.
+*
+* @param api - The Convex API object (from `@convex/api`)
+* @param meta - Generated function metadata for runtime type detection
+* @param convexClient - The ConvexReactClient instance
+* @returns A typed proxy with query/mutate methods
+*
+* @example
+* ```tsx
+* const client = createVanillaCRPCProxy(api, meta, convexClient);
+*
+* // Direct calls (no React Query)
+* const user = await client.user.get.query({ id });
+* await client.user.update.mutate({ id, name: 'test' });
+* ```
+*/
+function createVanillaCRPCProxy(api, meta, convexClient, transformer) {
+	return createRecursiveVanillaProxy(api, [], meta, convexClient, getTransformer(transformer));
+}
+
+//#endregion
+//#region src/react/context.tsx
+const ConvexQueryClientContext = createContext(null);
+/** Access ConvexQueryClient (e.g., for logout cleanup) */
+const useConvexQueryClient = () => useContext(ConvexQueryClientContext);
+const MetaContext = createContext(void 0);
+/**
+* Hook to access the meta object from context.
+* Returns undefined if meta was not provided to createCRPCContext.
+*/
+function useMeta() {
+	return useContext(MetaContext);
+}
+/**
+* Hook to get auth type for a function from meta.
+*/
+function useFnMeta() {
+	const meta = useMeta();
+	return (namespace, fnName) => meta?.[namespace]?.[fnName];
+}
+/**
+* Create CRPC context, provider, and hooks for a Convex API.
+*
+* @param options - Configuration object containing api and optional HTTP settings
+* @returns Object with CRPCProvider, useCRPC, and useCRPCClient
+*
+* @example
+* ```tsx
+* // lib/crpc.ts
+* import { api } from '@convex/api';
+* import { createCRPCContext } from 'kitcn/react';
+*
+* // Works for both regular Convex functions and generated HTTP router types
+* export const { useCRPC } = createCRPCContext({
+*   api,
+*   convexSiteUrl: process.env.NEXT_PUBLIC_CONVEX_SITE_URL!,
+* });
+*
+* // components/user-profile.tsx
+* function UserProfile({ id }) {
+*   const crpc = useCRPC();
+*   const { data } = useQuery(crpc.user.get.queryOptions({ id }));
+*
+*   // HTTP endpoints (if configured)
+*   const { data: httpData } = useQuery(crpc.http.todos.get.queryOptions({ id }));
+* }
+* ```
+*/
+function createCRPCContext(options) {
+	const { api, ...httpOptions } = options;
+	const meta = buildMetaIndex(api);
+	const CRPCProxyContext = createContext(null);
+	const VanillaClientContext = createContext(null);
+	const HttpProxyContext = createContext(void 0);
+	/** Inner provider */
+	function CRPCProviderInner({ children, convexClient, convexQueryClient }) {
+		const authStore = useAuthStore();
+		const fetchAccessToken = useFetchAccessToken();
+		const httpProxy = useMemo(() => {
+			if (!httpOptions.convexSiteUrl || !meta._http) return;
+			return createHttpProxy({
+				convexSiteUrl: httpOptions.convexSiteUrl,
+				routes: meta._http,
+				headers: async () => {
+					const token = authStore.get("token");
+					const expiresAt = authStore.get("expiresAt");
+					const timeRemaining = expiresAt ? expiresAt - Date.now() : 0;
+					if (token && expiresAt && timeRemaining >= 6e4) return {
+						...typeof httpOptions.headers === "function" ? await httpOptions.headers() : httpOptions.headers,
+						Authorization: `Bearer ${token}`
+					};
+					if (fetchAccessToken) {
+						const newToken = await fetchAccessToken({ forceRefreshToken: !!expiresAt });
+						if (newToken) return {
+							...typeof httpOptions.headers === "function" ? await httpOptions.headers() : httpOptions.headers,
+							Authorization: `Bearer ${newToken}`
+						};
+					}
+					return { ...typeof httpOptions.headers === "function" ? await httpOptions.headers() : httpOptions.headers };
+				},
+				fetch: httpOptions.fetch,
+				onError: httpOptions.onError,
+				transformer: options.transformer
+			});
+		}, [authStore, fetchAccessToken]);
+		const proxy = useMemo(() => createCRPCOptionsProxy(api, meta, options.transformer), []);
+		const vanillaClient = useMemo(() => createVanillaCRPCProxy(api, meta, convexClient, options.transformer), [convexClient]);
+		return /* @__PURE__ */ jsx(ConvexQueryClientContext.Provider, {
+			value: convexQueryClient,
+			children: /* @__PURE__ */ jsx(MetaContext.Provider, {
+				value: meta,
+				children: /* @__PURE__ */ jsx(VanillaClientContext.Provider, {
+					value: vanillaClient,
+					children: /* @__PURE__ */ jsx(HttpProxyContext.Provider, {
+						value: httpProxy,
+						children: /* @__PURE__ */ jsx(CRPCProxyContext.Provider, {
+							value: proxy,
+							children
+						})
+					})
+				})
+			})
+		});
+	}
+	/**
+	* Provider component that wraps the app with CRPC context.
+	* For auth, wrap with ConvexAuthProvider (or AuthProvider) above this.
+	*/
+	function CRPCProvider({ children, convexClient, convexQueryClient }) {
+		return /* @__PURE__ */ jsx(CRPCProviderInner, {
+			convexClient,
+			convexQueryClient,
+			children
+		});
+	}
+	/**
+	* Hook to access the CRPC proxy for building query/mutation options.
+	*
+	* @returns The typed CRPC proxy (with http namespace if configured)
+	* @throws If used outside of CRPCProvider
+	*
+	* @example
+	* ```tsx
+	* const crpc = useCRPC();
+	* const { data } = useQuery(crpc.user.get.queryOptions({ id }));
+	*
+	* // HTTP endpoints (if configured)
+	* const { data: httpData } = useQuery(crpc.http.todos.get.queryOptions({ id }));
+	* ```
+	*/
+	function useCRPC() {
+		const ctx = useContext(CRPCProxyContext);
+		const httpProxy = useContext(HttpProxyContext);
+		if (!ctx) throw new Error("useCRPC must be used within CRPCProvider");
+		if (httpProxy) return new Proxy(ctx, { get(target, prop) {
+			if (prop === "http") return httpProxy;
+			return Reflect.get(target, prop);
+		} });
+		return ctx;
+	}
+	/**
+	* Hook to access the vanilla CRPC client for direct procedural calls.
+	*
+	* @returns The typed VanillaCRPCClient for direct .query()/.mutate() calls
+	* @throws If used outside of CRPCProvider
+	*
+	* @example
+	* ```tsx
+	* const client = useCRPCClient();
+	*
+	* // Direct calls (no React Query)
+	* const user = await client.user.get.query({ id });
+	* await client.user.update.mutate({ id, name: 'test' });
+	*
+	* // HTTP endpoints (if configured)
+	* const todos = await client.http.todos.list.queryOptions({});
+	* ```
+	*/
+	function useCRPCClient() {
+		const ctx = useContext(VanillaClientContext);
+		const httpProxy = useContext(HttpProxyContext);
+		if (!ctx) throw new Error("useCRPCClient must be used within CRPCProvider");
+		if (httpProxy) return new Proxy(ctx, { get(target, prop) {
+			if (prop === "http") return httpProxy;
+			return Reflect.get(target, prop);
+		} });
+		return ctx;
+	}
+	return {
+		CRPCProvider,
+		useCRPC,
+		useCRPCClient
+	};
+}
+
+//#endregion
+//#region src/crpc/auth-error.ts
+/**
+* Auth Mutation Error
+*
+* Framework-agnostic error class for Better Auth mutations.
+*/
+/**
+* Error thrown when a Better Auth mutation fails.
+* Contains the original error details from Better Auth.
+*/
+var AuthMutationError = class extends Error {
+	/** Error code from Better Auth (e.g., 'INVALID_PASSWORD', 'EMAIL_ALREADY_REGISTERED') */
+	code;
+	/** HTTP status code */
+	status;
+	/** HTTP status text */
+	statusText;
+	constructor(authError) {
+		super(authError.message || authError.statusText);
+		this.name = "AuthMutationError";
+		this.code = authError.code;
+		this.status = authError.status;
+		this.statusText = authError.statusText;
+	}
+};
+/**
+* Type guard to check if an error is an AuthMutationError.
+*/
+function isAuthMutationError(error) {
+	return error instanceof AuthMutationError;
+}
+
+//#endregion
+//#region src/react/auth-mutations.ts
+/** Poll until JWT token exists (auth complete) (max 5s) */
+const waitForAuth = async (store, timeout = 5e3) => {
+	const start = Date.now();
+	while (Date.now() - start < timeout) {
+		if (store.get("token")) return true;
+		await new Promise((r) => setTimeout(r, 50));
+	}
+	return false;
+};
+const authStateTimeoutError = () => new AuthMutationError({
+	code: "AUTH_STATE_TIMEOUT",
+	message: "Authentication did not complete. Try again.",
+	status: 401,
+	statusText: "UNAUTHORIZED"
+});
+const ensureAuth = async (store) => {
+	if (await waitForAuth(store)) return;
+	throw authStateTimeoutError();
+};
+const readReturnedToken = (value) => {
+	if (!value || typeof value !== "object") return null;
+	const record = value;
+	if (typeof record.token === "string" && record.token.length > 0) return record.token;
+	return readReturnedToken(record.data) ?? readReturnedToken(record.session);
+};
+const seedReturnedToken = (store, value) => {
+	const token = readReturnedToken(value);
+	if (!token) return;
+	store.set("token", token);
+	store.set("expiresAt", decodeJwtExp(token));
+	store.set("sessionSyncGraceUntil", Date.now() + AUTH_SESSION_SYNC_GRACE_MS);
+};
+const syncSessionAtom = (authClient, sessionData) => {
+	const sessionAtom = authClient.$store?.atoms?.session;
+	if (typeof sessionAtom?.get !== "function" || typeof sessionAtom.set !== "function") return;
+	const current = sessionAtom.get();
+	sessionAtom.set({
+		data: sessionData,
+		error: null,
+		isPending: false,
+		isRefetching: false,
+		refetch: current?.refetch ?? (async () => {})
+	});
+};
+const hydrateReturnedSession = async (authClient, value) => {
+	const token = readReturnedToken(value);
+	if (!token || typeof authClient.getSession !== "function") return;
+	const session = await authClient.getSession({ fetchOptions: {
+		credentials: "omit",
+		headers: { Authorization: `Bearer ${token}` }
+	} });
+	if (session?.data) syncSessionAtom(authClient, session.data);
+};
+const withDisabledSessionSignal = (args) => {
+	const record = args && typeof args === "object" ? args : {};
+	return {
+		...record,
+		fetchOptions: {
+			...record.fetchOptions,
+			disableSignal: true
+		}
+	};
+};
+/**
+* Create mutation option hooks from a better-auth client.
+*
+* @example
+* ```tsx
+* // lib/auth-client.ts
+* import { createAuthMutations } from 'kitcn/react';
+*
+* export const authClient = createAuthClient({...});
+*
+* export const {
+*   useSignOutMutationOptions,
+*   useSignInSocialMutationOptions,
+*   useSignInMutationOptions,
+*   useSignUpMutationOptions,
+* } = createAuthMutations(authClient);
+*
+* // components/header.tsx
+* const signOutMutation = useMutation(useSignOutMutationOptions({
+*   onSuccess: () => router.push('/login'),
+* }));
+* ```
+*/
+function createAuthMutations(authClient) {
+	const useSignOutMutationOptions = ((options) => {
+		const convexQueryClient = useConvexQueryClient();
+		const authStoreApi = useAuthStore();
+		return {
+			...options,
+			mutationFn: async (args) => {
+				authStoreApi.set("isAuthenticated", false);
+				convexQueryClient?.unsubscribeAuthQueries();
+				const res = await authClient.signOut(args);
+				if (res?.error) throw new AuthMutationError(res.error);
+				authStoreApi.set("token", null);
+				authStoreApi.set("expiresAt", null);
+				authStoreApi.set("sessionSyncGraceUntil", null);
+				return res;
+			}
+		};
+	});
+	const useSignInSocialMutationOptions = ((options) => {
+		const authStoreApi = useAuthStore();
+		return {
+			...options,
+			mutationFn: async (args) => {
+				const res = await authClient.signIn.social(withDisabledSessionSignal(args));
+				if (res?.error) throw new AuthMutationError(res.error);
+				seedReturnedToken(authStoreApi, res);
+				await hydrateReturnedSession(authClient, res);
+				await ensureAuth(authStoreApi);
+				return res;
+			}
+		};
+	});
+	const useSignInMutationOptions = ((options) => {
+		const authStoreApi = useAuthStore();
+		return {
+			...options,
+			mutationFn: async (args) => {
+				const res = await authClient.signIn.email(withDisabledSessionSignal(args));
+				if (res?.error) throw new AuthMutationError(res.error);
+				seedReturnedToken(authStoreApi, res);
+				await hydrateReturnedSession(authClient, res);
+				await ensureAuth(authStoreApi);
+				return res;
+			}
+		};
+	});
+	const useSignUpMutationOptions = ((options) => {
+		const authStoreApi = useAuthStore();
+		return {
+			...options,
+			mutationFn: async (args) => {
+				const res = await authClient.signUp.email(withDisabledSessionSignal(args));
+				if (res?.error) throw new AuthMutationError(res.error);
+				seedReturnedToken(authStoreApi, res);
+				await hydrateReturnedSession(authClient, res);
+				await ensureAuth(authStoreApi);
+				return res;
+			}
+		};
+	});
+	return {
+		useSignOutMutationOptions,
+		useSignInSocialMutationOptions,
+		useSignInMutationOptions,
+		useSignUpMutationOptions
+	};
+}
+
+//#endregion
+//#region src/internal/query-key.ts
+/**
+* Shared query key utilities for Convex + TanStack Query.
+* This file has NO React dependencies so it can be imported in both
+* server (RSC) and client contexts.
+*/
+/**
+* Check if query key is for a Convex query function.
+* Format: ['convexQuery', 'namespace:functionName', { args }]
+*/
+function isConvexQuery(queryKey) {
+	return queryKey.length >= 2 && queryKey[0] === "convexQuery";
+}
+/**
+* Check if query key is for a Convex action function.
+* Format: ['convexAction', 'namespace:functionName', { args }]
+*/
+function isConvexAction$1(queryKey) {
+	return queryKey.length >= 2 && queryKey[0] === "convexAction";
+}
+/**
+* Create stable hash for Convex query keys.
+* Uses Convex's JSON serialization for consistent argument hashing.
+*/
+function hashConvexQuery(queryKey) {
+	const [, funcName, args] = queryKey;
+	return `convexQuery|${funcName}|${JSON.stringify(convexToJson(args))}`;
+}
+/**
+* Create stable hash for Convex action keys.
+* Uses Convex's JSON serialization for consistent argument hashing.
+*/
+function hashConvexAction(queryKey) {
+	const [, funcName, args] = queryKey;
+	return `convexAction|${funcName}|${JSON.stringify(convexToJson(args))}`;
+}
+
+//#endregion
+//#region src/internal/hash.ts
+/**
+* Create a hash function for TanStack Query that handles Convex keys.
+*/
+function createHashFn(fallback = hashKey) {
+	return (queryKey) => {
+		if (isConvexQuery(queryKey)) return hashConvexQuery(queryKey);
+		if (isConvexAction$1(queryKey)) return hashConvexAction(queryKey);
+		return fallback(queryKey);
+	};
+}
+
+//#endregion
+//#region src/react/client.ts
+/**
+* ConvexQueryClient - Real-time subscription bridge for TanStack Query + Convex
+*
+* ## Why This Exists
+*
+* TanStack Query is request-based (fetch once, cache, refetch on stale).
+* Convex is subscription-based (WebSocket push updates in real-time).
+*
+* This client bridges the two by:
+* 1. Listening to TanStack Query cache events (query added/removed)
+* 2. Creating Convex WebSocket subscriptions for each active query
+* 3. Pushing Convex updates into TanStack Query cache
+*
+* ## Architecture
+*
+* ```
+* useConvexQuery (hook)
+*       │
+*       ▼
+* TanStack Query Cache ◄──── ConvexQueryClient listens to cache events
+*       │                           │
+*       │                           ▼
+*       │                    Convex WebSocket subscriptions
+*       │                           │
+*       │                           ▼
+*       └──────────────────── Real-time updates pushed to cache
+* ```
+*
+* ## Subscription Lifecycle
+*
+* WebSocket subscriptions are decoupled from cache retention:
+* - Subscribe when query has observers (component mounted)
+* - Unsubscribe immediately when last observer removed (component unmounted)
+* - Cache data persists for gcTime (default 5 min) for instant back-navigation
+* - On remount: show cached data instantly, re-subscribe for fresh updates
+*
+* ## Query Key Format
+*
+* Convex queries use this key format:
+* ```ts
+* ['convexQuery', 'functionName', { args }]
+* ['convexAction', 'functionName', { args }]
+* ['convexQuery', 'functionName', 'skip'] // skipped queries
+* ```
+*
+* ## SSR Support
+*
+* On server: Uses ConvexHttpClient for one-shot queries (no WebSocket).
+* On client: Uses ConvexReactClient with WebSocket subscriptions.
+*
+* @module
+*/
+const isServer = typeof window === "undefined";
+/**
+* Check if query is marked as skipped (used when auth required but not authenticated).
+* Skipped queries have 'skip' as the third element instead of args.
+*/
+function isConvexSkipped(queryKey) {
+	return queryKey.length >= 2 && ["convexQuery", "convexAction"].includes(queryKey[0]) && queryKey[2] === "skip";
+}
+/**
+* Check if query key is for a Convex action function.
+* Format: ['convexAction', 'namespace:functionName', { args }]
+*/
+function isConvexAction(queryKey) {
+	return queryKey.length >= 2 && queryKey[0] === "convexAction";
+}
+/**
+* Bridges TanStack Query with Convex real-time subscriptions.
+*
+* ## Setup
+*
+* ```ts
+* const convexQueryClient = new ConvexQueryClient(CONVEX_URL);
+*
+* const queryClient = new QueryClient({
+*   defaultOptions: {
+*     queries: {
+*       queryFn: convexQueryClient.queryFn(),
+*       queryKeyHashFn: convexQueryClient.hashFn(),
+*     },
+*   },
+* });
+*
+* convexQueryClient.connect(queryClient);
+* ```
+*
+* ## How It Works
+*
+* 1. **Query Added**: When TanStack adds a Convex query to cache,
+*    ConvexQueryClient creates a WebSocket subscription via `watchQuery`.
+*
+* 2. **Real-time Updates**: When Convex pushes an update, the subscription
+*    callback updates the TanStack cache via `setQueryData`.
+*
+* 3. **Query Removed**: When TanStack removes a query (no observers),
+*    ConvexQueryClient unsubscribes from the WebSocket.
+*
+* ## Auth Integration
+*
+* Auth is handled via TanStack Query `meta`:
+* - `convexQuery` includes `meta.authType` from generated Convex metadata
+* - `queryFn` checks `meta.authType` via `getAuthState()` and throws `CRPCClientError` if unauthorized
+* - `subscribeInner` respects `meta.subscribe === false` to skip WebSocket
+*/
+var ConvexQueryClient = class {
+	/** Convex client for WebSocket subscriptions (client) and one-shot queries */
+	convexClient;
+	/**
+	* Active WebSocket subscriptions, keyed by TanStack query hash.
+	* Each subscription has:
+	* - watch: Convex Watch object for the query
+	* - unsubscribe: Cleanup function to remove the subscription
+	* - queryKey: Original query key for cache updates
+	*/
+	subscriptions;
+	/** Cleanup function for QueryCache subscription */
+	unsubscribe;
+	/**
+	* Pending unsubscribes with timeout IDs.
+	* Used to debounce unsubscribe/subscribe cycles from React StrictMode.
+	*/
+	pendingUnsubscribes = /* @__PURE__ */ new Map();
+	/** HTTP client for SSR queries (no WebSocket on server) */
+	serverHttpClient;
+	/** TanStack QueryClient reference */
+	_queryClient;
+	/** SSR query mode: 'consistent' guarantees same timestamp, 'inconsistent' is faster */
+	ssrQueryMode;
+	/** Auth store for checking auth state */
+	authStore;
+	/** Delay before unsubscribing when query has no observers */
+	unsubscribeDelay;
+	/** Payload transformer used across request/response boundaries. */
+	transformer;
+	/** Runtime-safe accessor for pending unsubscribe map (defensive for HMR edge cases) */
+	getPendingUnsubscribesMap() {
+		const self = this;
+		if (!self.pendingUnsubscribes) self.pendingUnsubscribes = /* @__PURE__ */ new Map();
+		return self.pendingUnsubscribes;
+	}
+	/** Cancel a pending delayed unsubscribe for a query hash. */
+	cancelPendingUnsubscribe(queryHash) {
+		const pendingUnsubscribes = this.getPendingUnsubscribesMap();
+		const timeoutId = pendingUnsubscribes.get(queryHash);
+		if (!timeoutId) return;
+		clearTimeout(timeoutId);
+		pendingUnsubscribes.delete(queryHash);
+	}
+	/** Unsubscribe a live Convex watch (if present) and remove it from the subscription map. */
+	unsubscribeQueryByHash(queryHash) {
+		const sub = this.subscriptions[queryHash];
+		if (!sub) return;
+		sub.unsubscribe();
+		delete this.subscriptions[queryHash];
+	}
+	/** Update auth store (for HMR where jotai store may reset) */
+	updateAuthStore(authStore) {
+		this.authStore = authStore;
+	}
+	/** Get current auth state from store */
+	getAuthState() {
+		if (!this.authStore) return;
+		return {
+			isLoading: this.authStore.get("isLoading"),
+			isAuthenticated: this.authStore.get("isAuthenticated"),
+			onUnauthorized: this.authStore.get("onQueryUnauthorized"),
+			isUnauthorized: this.authStore.get("isUnauthorized")
+		};
+	}
+	/**
+	* Check if subscription should be skipped due to auth state.
+	* Needed for useSuspenseQuery which ignores enabled: false.
+	* Regular useQuery already handles this via enabled: false in hooks.
+	*/
+	shouldSkipSubscription(authType) {
+		if (!authType || !this.authStore) return false;
+		const authState = this.getAuthState();
+		if (authState?.isLoading) return true;
+		if (authType === "required" && !authState?.isAuthenticated) return true;
+		return false;
+	}
+	/** Get QueryClient, throwing if not connected */
+	get queryClient() {
+		if (!this._queryClient) throw new Error("ConvexQueryClient not connected to TanStack QueryClient.");
+		return this._queryClient;
+	}
+	/**
+	* Create a ConvexQueryClient.
+	*
+	* @param client - Convex URL string or existing ConvexReactClient
+	* @param options - Configuration options
+	*/
+	constructor(client, options = {}) {
+		if (typeof client === "string") this.convexClient = new ConvexReactClient$1(client, options);
+		else this.convexClient = client;
+		this.ssrQueryMode = options.dangerouslyUseInconsistentQueriesDuringSSR ? "inconsistent" : "consistent";
+		this.subscriptions = {};
+		this.authStore = options.authStore;
+		this.unsubscribeDelay = options.unsubscribeDelay ?? 3e3;
+		this.transformer = getTransformer(options.transformer);
+		if (options.queryClient) {
+			this._queryClient = options.queryClient;
+			this.unsubscribe = this.subscribeInner(options.queryClient.getQueryCache());
+		}
+		if (isServer) this.serverHttpClient = new ConvexHttpClient(this.convexClient.url, { fetch: options.serverFetch });
+	}
+	/**
+	* Connect to TanStack QueryClient.
+	* Starts listening to cache events for subscription management.
+	*/
+	connect(queryClient) {
+		if (this._queryClient === queryClient && this.unsubscribe) return;
+		if (this.unsubscribe) this.unsubscribe();
+		this._queryClient = queryClient;
+		this.unsubscribe = this.subscribeInner(queryClient.getQueryCache());
+	}
+	/**
+	* Clean up all subscriptions.
+	* Call this when the client is no longer needed.
+	*/
+	destroy() {
+		this.unsubscribe?.();
+		for (const timeoutId of this.getPendingUnsubscribesMap().values()) clearTimeout(timeoutId);
+		this.getPendingUnsubscribesMap().clear();
+		for (const sub of Object.values(this.subscriptions)) sub.unsubscribe();
+		this.subscriptions = {};
+	}
+	/**
+	* Unsubscribe from all auth-required queries.
+	* Call before logout to prevent UNAUTHORIZED errors during session invalidation.
+	*/
+	unsubscribeAuthQueries() {
+		for (const queryHash of Object.keys(this.subscriptions)) if ((this.queryClient.getQueryCache().get(queryHash)?.meta)?.authType === "required") {
+			this.cancelPendingUnsubscribe(queryHash);
+			this.unsubscribeQueryByHash(queryHash);
+		}
+	}
+	/**
+	* Batch update all subscriptions.
+	* Called internally when Convex client reconnects.
+	*/
+	onUpdate = () => {
+		notifyManager.batch(() => {
+			for (const key of Object.keys(this.subscriptions)) this.onUpdateQueryKeyHash(key);
+		});
+	};
+	/**
+	* Handle Convex subscription update for a specific query.
+	* Reads latest value from Watch and updates TanStack cache.
+	*
+	* @param queryHash - TanStack query hash identifying the query
+	*/
+	onUpdateQueryKeyHash(queryHash) {
+		const subscription = this.subscriptions[queryHash];
+		if (!subscription) throw new Error(`Internal ConvexQueryClient error: onUpdateQueryKeyHash called for ${queryHash}`);
+		const query = this.queryClient.getQueryCache().get(queryHash);
+		if (!query) return;
+		const { queryKey, watch } = subscription;
+		let result;
+		try {
+			result = {
+				ok: true,
+				value: watch.localQueryResult()
+			};
+		} catch (error) {
+			result = {
+				ok: false,
+				error
+			};
+		}
+		if (result.ok) {
+			const existingData = this.queryClient.getQueryData(queryKey);
+			if (result.value !== null && result.value !== void 0 || !(existingData !== null && existingData !== void 0)) this.queryClient.setQueryData(queryKey, this.transformer.output.deserialize(result.value));
+		} else {
+			const { error } = result;
+			const authState = this.getAuthState();
+			const meta = query.meta;
+			const isUnauthorized = authState?.isUnauthorized(error) ?? false;
+			if (isUnauthorized && meta?.skipUnauth) {
+				this.queryClient.setQueryData(queryKey, this.transformer.output.deserialize(null));
+				return;
+			}
+			query.setState({
+				error,
+				errorUpdateCount: query.state.errorUpdateCount + 1,
+				errorUpdatedAt: Date.now(),
+				fetchFailureCount: query.state.fetchFailureCount + 1,
+				fetchFailureReason: error,
+				fetchStatus: "idle",
+				status: "error"
+			}, { meta: "set by ConvexQueryClient" });
+			if (isUnauthorized && authState?.isAuthenticated) {
+				const [, funcName] = queryKey;
+				authState.onUnauthorized({ queryName: funcName });
+			}
+		}
+	}
+	/**
+	* Subscribe to TanStack QueryCache events.
+	* Creates/removes Convex WebSocket subscriptions as queries are added/removed.
+	*
+	* @param queryCache - TanStack QueryCache to subscribe to
+	* @returns Cleanup function to unsubscribe
+	*/
+	subscribeInner(queryCache) {
+		if (isServer) return () => {};
+		return queryCache.subscribe((event) => {
+			if (!isConvexQuery(event.query.queryKey)) return;
+			if (isConvexSkipped(event.query.queryKey)) return;
+			switch (event.type) {
+				case "removed":
+					this.cancelPendingUnsubscribe(event.query.queryHash);
+					this.unsubscribeQueryByHash(event.query.queryHash);
+					break;
+				case "added": {
+					const meta = event.query.meta;
+					if (meta?.subscribe === false) break;
+					const [, funcName, args] = event.query.queryKey;
+					if (event.query.getObserversCount() === 0) break;
+					if (this.shouldSkipSubscription(meta?.authType)) break;
+					const watch = this.convexClient.watchQuery(funcName, this.transformer.input.serialize(args));
+					const unsubscribe = watch.onUpdate(() => {
+						this.onUpdateQueryKeyHash(event.query.queryHash);
+					});
+					this.subscriptions[event.query.queryHash] = {
+						queryKey: event.query.queryKey,
+						watch,
+						unsubscribe
+					};
+					break;
+				}
+				case "observerAdded": {
+					this.cancelPendingUnsubscribe(event.query.queryHash);
+					if (this.subscriptions[event.query.queryHash]) break;
+					if (event.query.options.enabled === false) break;
+					const meta = event.query.meta;
+					if (meta?.subscribe === false) break;
+					const [, funcName, args] = event.query.queryKey;
+					if (this.shouldSkipSubscription(meta?.authType)) break;
+					const watch = this.convexClient.watchQuery(funcName, this.transformer.input.serialize(args));
+					const unsubscribe = watch.onUpdate(() => {
+						this.onUpdateQueryKeyHash(event.query.queryHash);
+					});
+					this.subscriptions[event.query.queryHash] = {
+						queryKey: event.query.queryKey,
+						watch,
+						unsubscribe
+					};
+					break;
+				}
+				case "observerRemoved":
+					if (event.query.getObserversCount() === 0 && this.subscriptions[event.query.queryHash]) {
+						const queryHash = event.query.queryHash;
+						const timeoutId = setTimeout(() => {
+							this.getPendingUnsubscribesMap().delete(queryHash);
+							if (event.query.getObserversCount() === 0) this.unsubscribeQueryByHash(queryHash);
+						}, this.unsubscribeDelay);
+						this.getPendingUnsubscribesMap().set(queryHash, timeoutId);
+					}
+					break;
+				case "observerResultsUpdated": break;
+				case "updated":
+					if (event.action.type === "setState" && event.action.setStateOptions?.meta === "set by ConvexQueryClient") break;
+					break;
+				case "observerOptionsUpdated": {
+					const isDisabled = event.query.options.enabled === false;
+					const isSubscribed = !!this.subscriptions[event.query.queryHash];
+					if (isDisabled && isSubscribed) {
+						this.cancelPendingUnsubscribe(event.query.queryHash);
+						this.unsubscribeQueryByHash(event.query.queryHash);
+						break;
+					}
+					if (isSubscribed || isDisabled) break;
+					const meta = event.query.meta;
+					if (meta?.subscribe === false) break;
+					const [, funcName, args] = event.query.queryKey;
+					if (this.shouldSkipSubscription(meta?.authType)) break;
+					const watch = this.convexClient.watchQuery(funcName, this.transformer.input.serialize(args));
+					const unsubscribe = watch.onUpdate(() => {
+						this.onUpdateQueryKeyHash(event.query.queryHash);
+					});
+					this.subscriptions[event.query.queryHash] = {
+						queryKey: event.query.queryKey,
+						watch,
+						unsubscribe
+					};
+					break;
+				}
+			}
+		});
+	}
+	/**
+	* Create default queryFn for TanStack QueryClient.
+	*
+	* Handles:
+	* - Convex queries and actions
+	* - Auth checking (throws CRPCClientError if unauthorized)
+	* - SSR via HTTP client
+	* - Client via WebSocket client
+	*
+	* ## Usage
+	*
+	* ```ts
+	* const queryClient = new QueryClient({
+	*   defaultOptions: {
+	*     queries: {
+	*       queryFn: convexQueryClient.queryFn(),
+	*     },
+	*   },
+	* });
+	* ```
+	*
+	* @param otherFetch - Fallback queryFn for non-Convex queries
+	* @returns QueryFunction compatible with TanStack Query
+	*/
+	queryFn(otherFetch = throwBecauseNotConvexQuery) {
+		return async (context) => {
+			const { queryKey, meta: rawMeta } = context;
+			const meta = rawMeta;
+			if (isConvexSkipped(queryKey)) throw new Error("Skipped query should not actually run, should { enabled: false }");
+			if (isConvexQuery(queryKey)) {
+				const [, funcName, args] = queryKey;
+				const wireArgs = this.transformer.input.serialize(args);
+				const skipUnauth = meta?.skipUnauth ?? false;
+				if (meta?.authType === "required" && !isServer && this.authStore) {
+					const authState = this.getAuthState();
+					if (authState && !authState.isLoading && !authState.isAuthenticated) {
+						if (skipUnauth) return null;
+						authState.onUnauthorized({ queryName: funcName });
+						throw new CRPCClientError({
+							code: "UNAUTHORIZED",
+							functionName: funcName
+						});
+					}
+				}
+				try {
+					if (isServer) {
+						if (this.ssrQueryMode === "consistent") return this.transformer.output.deserialize(await this.serverHttpClient.consistentQuery(funcName, wireArgs));
+						return this.transformer.output.deserialize(await this.serverHttpClient.query(funcName, wireArgs));
+					}
+					return this.transformer.output.deserialize(await this.convexClient.query(funcName, wireArgs));
+				} catch (error) {
+					if (skipUnauth && defaultIsUnauthorized(error)) return null;
+					throw error;
+				}
+			}
+			if (isConvexAction(queryKey)) {
+				const [, funcName, args] = queryKey;
+				const wireArgs = this.transformer.input.serialize(args);
+				const skipUnauth = meta?.skipUnauth ?? false;
+				if (meta?.authType === "required" && !isServer && this.authStore) {
+					const authState = this.getAuthState();
+					if (authState && !authState.isLoading && !authState.isAuthenticated) {
+						if (skipUnauth) return null;
+						authState.onUnauthorized({ queryName: funcName });
+						throw new CRPCClientError({
+							code: "UNAUTHORIZED",
+							functionName: funcName
+						});
+					}
+				}
+				try {
+					if (isServer) return this.transformer.output.deserialize(await this.serverHttpClient.action(funcName, wireArgs));
+					return this.transformer.output.deserialize(await this.convexClient.action(funcName, wireArgs));
+				} catch (error) {
+					if (skipUnauth && defaultIsUnauthorized(error)) return null;
+					throw error;
+				}
+			}
+			return otherFetch(context);
+		};
+	}
+	/**
+	* Create hash function for TanStack QueryClient.
+	*
+	* Uses Convex-specific hashing for Convex queries to ensure
+	* consistent cache keys across serialization.
+	*
+	* ## Usage
+	*
+	* ```ts
+	* const queryClient = new QueryClient({
+	*   defaultOptions: {
+	*     queries: {
+	*       queryKeyHashFn: convexQueryClient.hashFn(),
+	*     },
+	*   },
+	* });
+	* ```
+	*
+	* @param otherHashKey - Fallback hash function for non-Convex queries
+	* @returns Hash function compatible with TanStack Query
+	*/
+	hashFn(fallback) {
+		return createHashFn(fallback);
+	}
+};
+/** Default fallback queryFn that throws for non-Convex queries */
+function throwBecauseNotConvexQuery(context) {
+	throw new Error(`Query key is not for a Convex Query: ${context.queryKey}`);
+}
+
+//#endregion
+//#region src/react/singleton.ts
+const globalStore = globalThis;
+/** Get/create QueryClient singleton (fresh on SSR, singleton on client) */
+const getQueryClientSingleton = (factory, symbolKey = "convex.queryClient") => {
+	const key = Symbol.for(symbolKey);
+	if (typeof window === "undefined") return factory();
+	if (!globalStore[key]) globalStore[key] = factory();
+	return globalStore[key];
+};
+/** Get/create ConvexQueryClient singleton (fresh on SSR, singleton on client) */
+const getConvexQueryClientSingleton = ({ authStore, convex, queryClient, symbolKey = "convex.convexQueryClient", unsubscribeDelay, transformer }) => {
+	const key = Symbol.for(symbolKey);
+	const isServer = typeof window === "undefined";
+	let client;
+	if (isServer) client = new ConvexQueryClient(convex, {
+		authStore,
+		unsubscribeDelay,
+		transformer
+	});
+	else {
+		if (globalStore[key]) globalStore[key].updateAuthStore(authStore);
+		else globalStore[key] = new ConvexQueryClient(convex, {
+			authStore,
+			unsubscribeDelay,
+			transformer
+		});
+		client = globalStore[key];
+		client.connect(queryClient);
+	}
+	const currentOpts = queryClient.getDefaultOptions();
+	queryClient.setDefaultOptions({
+		...currentOpts,
+		queries: {
+			...currentOpts.queries,
+			queryFn: client.queryFn(),
+			queryKeyHashFn: client.hashFn()
+		}
+	});
+	return client;
+};
+
+//#endregion
+//#region src/react/use-infinite-query.ts
+/** biome-ignore-all lint/suspicious/noExplicitAny: Convex query/mutation type compatibility */
+const PAGINATION_KEY_PREFIX = "__pagination__";
+const paginationIdStore = /* @__PURE__ */ new Map();
+let paginationIdCounter = 0;
+const getOrCreatePaginationId = (storeKey) => {
+	const existing = paginationIdStore.get(storeKey);
+	if (existing !== void 0) return existing;
+	const newId = ++paginationIdCounter;
+	paginationIdStore.set(storeKey, newId);
+	return newId;
+};
+/** Build a unique key for recovery attempt detection */
+const buildRecoveryKey = (pageKeys, page0Cursor, page0UpdatedAt) => JSON.stringify({
+	pageKeys,
+	page0Cursor,
+	page0UpdatedAt
+});
+/**
+* Hook for auto-recovering from stale cursors after WebSocket reconnection.
+*
+* When Convex WebSocket reconnects, page 0 (cursor: null) resubscribes and
+* gets fresh data. However, pages 1+ may have stale cursors that fail.
+*
+* This hook detects this pattern and creates a recovery page that fetches
+* enough items to cover the lost pages, preserving the user's scroll position.
+*/
+const useStaleCursorRecovery = ({ argsObject, combined, limit, setState, state }) => {
+	useEffect(() => {
+		if (!combined.isFetchNextPageError) return;
+		const page0Result = combined._rawResults[0];
+		const page0Data = page0Result?.data;
+		const page0UpdatedAt = page0Result?.dataUpdatedAt ?? 0;
+		const hasPage0Data = page0Data !== void 0 && !page0Result?.isError;
+		const hasSubsequentErrors = combined._rawResults.slice(1).some((q) => q?.isError && !q?.isFetching);
+		if (!hasPage0Data || !hasSubsequentErrors || !page0Data?.continueCursor) return;
+		const recoveryKey = buildRecoveryKey(state.pageKeys, page0Data.continueCursor, page0UpdatedAt);
+		if (state.autoRecoveryAttempted === recoveryKey) return;
+		const erroredPageKeys = state.pageKeys.filter((_, i) => i > 0 && combined._rawResults[i]?.isError);
+		const itemsToRecover = erroredPageKeys.reduce((sum, key) => {
+			return sum + (state.queries[key]?.args?.limit ?? limit ?? 20);
+		}, 0);
+		console.warn("[Pagination] Auto-recovering from stale cursors", {
+			erroredPages: erroredPageKeys.length,
+			itemsToRecover
+		});
+		setState((prev) => ({
+			...prev,
+			id: prev.id,
+			nextPageKey: 2,
+			pageKeys: [prev.pageKeys[0], 1],
+			queries: {
+				[prev.pageKeys[0]]: prev.queries[prev.pageKeys[0]],
+				1: { args: {
+					...argsObject,
+					cursor: page0Data.continueCursor,
+					limit: Math.min(itemsToRecover + (limit ?? 20), 500),
+					__paginationId: prev.id
+				} }
+			},
+			version: prev.version + 1,
+			autoRecoveryAttempted: recoveryKey
+		}));
+	}, [
+		combined.isFetchNextPageError,
+		combined._rawResults,
+		state.pageKeys,
+		state.queries,
+		state.autoRecoveryAttempted,
+		argsObject,
+		limit,
+		setState
+	]);
+	useEffect(() => {
+		if ((combined.status === "CanLoadMore" || combined.status === "Exhausted") && state.autoRecoveryAttempted) setState((prev) => ({
+			...prev,
+			autoRecoveryAttempted: void 0
+		}));
+	}, [
+		combined.status,
+		state.autoRecoveryAttempted,
+		setState
+	]);
+};
+/**
+* Internal infinite query hook using TanStack Query + convexQuery.
+* Each page gets:
+* - Convex WebSocket subscription (real-time reactivity)
+* - TanStack Query retry on timeout errors
+*
+* Use `useInfiniteQuery` for the public API with auth handling.
+*/
+const useInfiniteQueryInternal = (query, args, options) => {
+	const { limit, enabled, placeholderData, ...queryOptions } = options;
+	const { isLoading: isAuthLoading } = useSafeConvexAuth();
+	const meta = useMeta();
+	const queryClient = useQueryClient();
+	const prefetchedFirstPage = useMemo(() => {
+		const serverQueryKey = [
+			"convexQuery",
+			getFunctionName(query),
+			{
+				...args,
+				cursor: null,
+				limit
+			}
+		];
+		return queryClient.getQueryData(serverQueryKey) ?? null;
+	}, [
+		query,
+		JSON.stringify(args),
+		limit,
+		queryClient
+	]);
+	const skip = !prefetchedFirstPage && (isAuthLoading || enabled === false);
+	const getPaginationState = useCallback((key) => {
+		const queryKey = [PAGINATION_KEY_PREFIX, key];
+		return queryClient.getQueryData(queryKey);
+	}, [queryClient]);
+	const setPaginationState = useCallback((key, state) => {
+		const queryKey = [PAGINATION_KEY_PREFIX, key];
+		queryClient.setQueryData(queryKey, state);
+	}, [queryClient]);
+	const argsObject = useMemo(() => skip ? {} : args, [skip, JSON.stringify(args)]);
+	const storeKey = useMemo(() => JSON.stringify({
+		query: getFunctionName(query),
+		args: argsObject
+	}), [query, argsObject]);
+	const createInitialState = useCallback(() => {
+		const id = getOrCreatePaginationId(storeKey);
+		return {
+			id,
+			nextPageKey: 1,
+			pageKeys: skip ? [] : [0],
+			queries: skip ? {} : { 0: { args: {
+				...argsObject,
+				cursor: null,
+				limit,
+				__paginationId: id
+			} } },
+			version: 0
+		};
+	}, [
+		storeKey,
+		skip,
+		argsObject,
+		limit
+	]);
+	const prevArgsRef = useRef(null);
+	const [state, setLocalState] = useState(() => {
+		if (skip) return {
+			id: 0,
+			nextPageKey: 1,
+			pageKeys: [],
+			queries: {},
+			version: 0
+		};
+		const existingState = getPaginationState(storeKey);
+		if (existingState) return existingState;
+		return createInitialState();
+	});
+	const setState = useCallback((updater) => {
+		setLocalState((prev) => {
+			const newState = typeof updater === "function" ? updater(prev) : updater;
+			setPaginationState(storeKey, newState);
+			return newState;
+		});
+	}, [storeKey, setPaginationState]);
+	useEffect(() => {
+		const prev = prevArgsRef.current;
+		const isFirstRun = prev === null;
+		const argsChanged = prev !== null && (prev.storeKey !== storeKey || prev.skip !== skip);
+		const skipBecameFalse = prev?.skip && !skip;
+		prevArgsRef.current = {
+			storeKey,
+			skip
+		};
+		if (skip) return;
+		if (isFirstRun) {
+			setPaginationState(storeKey, state);
+			return;
+		}
+		if (skipBecameFalse) {
+			const existingState = getPaginationState(storeKey);
+			if (existingState) {
+				setLocalState(existingState);
+				return;
+			}
+			const newState = createInitialState();
+			setLocalState(newState);
+			setPaginationState(storeKey, newState);
+			return;
+		}
+		if (argsChanged) {
+			const existingState = getPaginationState(storeKey);
+			if (existingState) {
+				setLocalState(existingState);
+				return;
+			}
+			const newState = createInitialState();
+			setLocalState(newState);
+			setPaginationState(storeKey, newState);
+		}
+	}, [
+		skip,
+		storeKey,
+		state,
+		createInitialState,
+		getPaginationState,
+		setPaginationState
+	]);
+	const combined = useQueries({
+		queries: useMemo(() => state.pageKeys.map((key, index) => {
+			const pageArgs = state.queries[key]?.args;
+			return {
+				...convexQuery(query, pageArgs ? (({ __paginationId, ...rest }) => rest)(pageArgs) : "skip", meta),
+				enabled: !skip && !!state.queries[key],
+				structuralSharing: false,
+				...queryOptions ?? {},
+				...index === 0 && prefetchedFirstPage ? { initialData: prefetchedFirstPage } : {},
+				...index === 0 && placeholderData ? { placeholderData: {
+					page: placeholderData,
+					isDone: false,
+					continueCursor: null
+				} } : {}
+			};
+		}), [
+			query,
+			state.pageKeys,
+			state.queries,
+			skip,
+			meta,
+			queryOptions,
+			prefetchedFirstPage,
+			placeholderData
+		]),
+		combine: (results) => {
+			const allItems = [];
+			const pages = [];
+			const seenIds = /* @__PURE__ */ new Set();
+			let lastPage;
+			let paginationStatus = "LoadingFirstPage";
+			for (let i = 0; i < results.length; i++) {
+				const pageQuery = results[i];
+				if (pageQuery.isLoading || pageQuery.data === void 0) {
+					paginationStatus = i === 0 ? "LoadingFirstPage" : "LoadingMore";
+					break;
+				}
+				const page = pageQuery.data;
+				lastPage = page;
+				pages.push(page.page);
+				for (const item of page.page) {
+					const id = item._id || item.id;
+					if (id && seenIds.has(id)) continue;
+					if (id) seenIds.add(id);
+					allItems.push(item);
+				}
+				paginationStatus = page.isDone ? "Exhausted" : "CanLoadMore";
+			}
+			const isPlaceholderData = results[0]?.isPlaceholderData ?? !!placeholderData;
+			const isFetching = results.some((r) => r.isFetching);
+			const dataUpdatedAt = Math.max(...results.map((r) => r.dataUpdatedAt ?? 0));
+			return {
+				...results[0] ?? {},
+				data: allItems,
+				dataUpdatedAt,
+				lastPage,
+				pages,
+				status: paginationStatus,
+				error: results.find((r) => r.isError)?.error ?? null,
+				isError: results.some((r) => r.isError),
+				isFetching,
+				isFetchNextPageError: results.length > 1 && (results.at(-1)?.isError ?? false),
+				isPlaceholderData,
+				isRefetching: isFetching && allItems.length > 0 && !isPlaceholderData,
+				_rawResults: results
+			};
+		}
+	});
+	useStaleCursorRecovery({
+		argsObject,
+		combined,
+		limit,
+		setState,
+		state
+	});
+	useEffect(() => {
+		for (let i = 0; i < combined._rawResults.length; i++) {
+			const pageQuery = combined._rawResults[i];
+			if (pageQuery.data) {
+				const page = pageQuery.data;
+				const pageKey = state.pageKeys[i];
+				const pageState = state.queries[pageKey];
+				if (page.splitCursor && pageState && !pageState.endCursor) {
+					setState((prev) => {
+						const currentPageState = prev.queries[pageKey];
+						if (!currentPageState || currentPageState.endCursor) return prev;
+						const newKey = prev.nextPageKey;
+						const splitCursor = page.splitCursor;
+						const splitPageArgs = {
+							...argsObject,
+							cursor: splitCursor,
+							limit: currentPageState.args.limit,
+							__paginationId: prev.id
+						};
+						const pageKeyIndex = prev.pageKeys.indexOf(pageKey);
+						const newPageKeys = [...prev.pageKeys];
+						newPageKeys.splice(pageKeyIndex + 1, 0, newKey);
+						return {
+							...prev,
+							nextPageKey: newKey + 1,
+							pageKeys: newPageKeys,
+							queries: {
+								...prev.queries,
+								[pageKey]: {
+									...currentPageState,
+									endCursor: splitCursor
+								},
+								[newKey]: { args: splitPageArgs }
+							}
+						};
+					});
+					return;
+				}
+			}
+		}
+	}, [
+		combined._rawResults,
+		state.pageKeys,
+		state.queries,
+		argsObject,
+		setState
+	]);
+	const loadMore = useCallback((pageLimit) => {
+		if (combined.status !== "CanLoadMore" || !combined.lastPage?.continueCursor) return;
+		setState((prev) => {
+			const newKey = prev.nextPageKey;
+			return {
+				...prev,
+				nextPageKey: newKey + 1,
+				pageKeys: [...prev.pageKeys, newKey],
+				queries: {
+					...prev.queries,
+					[newKey]: { args: {
+						...argsObject,
+						cursor: combined.lastPage.continueCursor,
+						limit: pageLimit,
+						__paginationId: prev.id
+					} }
+				}
+			};
+		});
+	}, [
+		combined.status,
+		combined.lastPage,
+		setState,
+		argsObject
+	]);
+	const { _rawResults, lastPage, ...result } = combined;
+	const hasNextPage = combined.status === "CanLoadMore";
+	const isFetchingNextPage = combined.status === "LoadingMore";
+	return {
+		...result,
+		failureReason: combined.failureReason,
+		error: combined.error instanceof Error ? combined.error : null,
+		fetchNextPage: (n) => loadMore(n ?? limit),
+		hasNextPage,
+		isFetchingNextPage
+	};
+};
+/**
+* Infinite query hook using cRPC-style options.
+* Accepts options from `crpc.posts.list.infiniteQueryOptions()`.
+*
+* @example
+* ```tsx
+* const crpc = useCRPC();
+* const { data, fetchNextPage } = useInfiniteQuery(
+*   crpc.posts.list.infiniteQueryOptions({ userId }, { limit: 20 })
+* );
+* ```
+*/
+function useInfiniteQuery(infiniteOptions) {
+	const query = infiniteOptions[FUNC_REF_SYMBOL];
+	const onQueryUnauthorized = useAuthValue("onQueryUnauthorized");
+	const { isLoading: isAuthLoading, isAuthenticated } = useSafeConvexAuth();
+	const { queryKey: _queryKey, staleTime: _staleTime, refetchInterval: _refetchInterval, refetchOnMount: _refetchOnMount, refetchOnReconnect: _refetchOnReconnect, refetchOnWindowFocus: _refetchOnWindowFocus, enabled: factoryEnabled, meta, ...queryOptions } = infiniteOptions;
+	const { queryName, args, limit, authType, skipUnauth } = meta;
+	const skipUnauthFinal = skipUnauth ?? false;
+	const isUnauthorized = authType === "required" && !isAuthLoading && !isAuthenticated;
+	const shouldSkip = factoryEnabled === false || authType === "required" && isAuthLoading || authType === "required" && !isAuthenticated;
+	const authError = useMemo(() => {
+		if (isUnauthorized && !skipUnauthFinal) return new CRPCClientError({
+			code: "UNAUTHORIZED",
+			functionName: queryName
+		});
+		return null;
+	}, [
+		isUnauthorized,
+		skipUnauthFinal,
+		queryName
+	]);
+	useEffect(() => {
+		if (isUnauthorized && !skipUnauthFinal) onQueryUnauthorized({ queryName });
+	}, [
+		isUnauthorized,
+		skipUnauthFinal,
+		queryName,
+		onQueryUnauthorized
+	]);
+	const result = useInfiniteQueryInternal(query, args, {
+		limit,
+		...queryOptions,
+		enabled: !shouldSkip
+	});
+	const authLoadingApplies = authType === "optional" || authType === "required";
+	const isClientError = isCRPCClientError(result.error);
+	const isSkippedUnauth = isUnauthorized && skipUnauthFinal;
+	return {
+		...result,
+		data: isSkippedUnauth ? [] : result.data,
+		pages: isSkippedUnauth ? [] : result.pages,
+		...authError && {
+			error: authError,
+			isError: true
+		},
+		...isSkippedUnauth && { isPlaceholderData: false },
+		isLoading: authLoadingApplies && isAuthLoading || !isClientError && !authError && !isSkippedUnauth && result.isLoading
+	};
+}
+
+//#endregion
+export { AUTH_SESSION_SYNC_GRACE_MS, AuthMutationError, AuthProvider, Authenticated, ConvexAuthBridge, ConvexProvider, ConvexProviderWithAuth, ConvexQueryClient, ConvexReactClient, FetchAccessTokenContext, MaybeAuthenticated, MaybeUnauthenticated, Unauthenticated, createAuthMutations, createCRPCContext, createCRPCOptionsProxy, createHttpProxy, createVanillaCRPCProxy, decodeJwtExp, getConvexQueryClientSingleton, getQueryClientSingleton, isAuthMutationError, isSessionSyncGraceActive, useAuth, useAuthGuard, useAuthState, useAuthStore, useAuthValue, useConvex, useConvexActionOptions, useConvexActionQueryOptions, useSafeConvexAuth as useConvexAuth, useSafeConvexAuth, useConvexAuthBridge, useConvexInfiniteQueryOptions, useConvexMutationOptions, useConvexQueryClient, useConvexQueryOptions, useFetchAccessToken, useFnMeta, useInfiniteQuery, useIsAuth, useMaybeAuth, useMeta, useUploadMutationOptions };