@raf-query/react 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,14 +1,42 @@
 # Changelog
 
+## [0.13.0](https://github.com/KATT/raf-query/compare/0.12.0...0.13.0) (2026-11-10)
+
+### ⚠ BREAKING CHANGES
+
+* **core:** paging lives in core; useInfiniteQuery reads core's PageControls ([#246](https://github.com/KATT/raf-query/issues/246))
+
+### Features
+
+* **core:** paging lives in core; useInfiniteQuery reads core's PageControls ([#246](https://github.com/KATT/raf-query/issues/246)) ([f6b4ed2](https://github.com/KATT/raf-query/commit/f6b4ed210340b4b25bf3316ef08a9c8ceb9ed112))
+* **core:** pass the client making the request to queryFn ([#241](https://github.com/KATT/raf-query/issues/241)) ([8c85746](https://github.com/KATT/raf-query/commit/8c85746c230bc3d8a426b32a130a260fa7e8ca62))
+* **core:** replay cached entries to a new client subscriber ([#243](https://github.com/KATT/raf-query/issues/243)) ([1455eed](https://github.com/KATT/raf-query/commit/1455eed2612fe69f0f10bfec08cfd552ef90c786))
+* **core:** ssr: false for queries only a browser can run ([#240](https://github.com/KATT/raf-query/issues/240)) ([077de62](https://github.com/KATT/raf-query/commit/077de6223a92b8bd8d35f7df043d1efe147ca403))
+
+### Bug Fixes
+
+* **core:** infer factories built inline by a generic maker in setData ([#244](https://github.com/KATT/raf-query/issues/244)) ([da87c07](https://github.com/KATT/raf-query/commit/da87c07a3463a919c154ac3ac5fba3d546b3231e))
+* **core:** keep data written while a request ran ([#239](https://github.com/KATT/raf-query/issues/239)) ([4cb7cc0](https://github.com/KATT/raf-query/commit/4cb7cc0605a2d4637591eb365153c5e955eb41a8))
+* **core:** start features once for providers that share a client ([#242](https://github.com/KATT/raf-query/issues/242)) ([d5968fb](https://github.com/KATT/raf-query/commit/d5968fb140429a1b2e7fb94662c266a52e877cc0))
+
+### Documentation
+
+* every example is the blog's posts, comments and authors ([#236](https://github.com/KATT/raf-query/issues/236)) ([2551e97](https://github.com/KATT/raf-query/commit/2551e9710aa7b149be333a1675dae31d9d1f5efd)), references [#230](https://github.com/KATT/raf-query/issues/230)
+
+### Miscellaneous Chores
+
+* **lint:** require a docs link on every public export ([#237](https://github.com/KATT/raf-query/issues/237)) ([b5c8133](https://github.com/KATT/raf-query/commit/b5c8133c129e0412e82cd2f24da6a2516b4a2012))
+* unblock CI: [@see](https://github.com/see) links and the RSC test's build ([#245](https://github.com/KATT/raf-query/issues/245)) ([84927e4](https://github.com/KATT/raf-query/commit/84927e4a900f7608e1e17b022e28afadbe00e4ae)), references [#243](https://github.com/KATT/raf-query/issues/243) [#246](https://github.com/KATT/raf-query/issues/246) [#240](https://github.com/KATT/raf-query/issues/240) [#238](https://github.com/KATT/raf-query/issues/238)
+
 ## [0.12.0](https://github.com/KATT/raf-query/compare/0.11.1...0.12.0) (2026-11-08)
 
 ### ⚠ BREAKING CHANGES
 
-* greenfield rewrite on a promise kernel, with load() handles and opt-in behaviors ([#230](https://github.com/KATT/raf-query/issues/230))
+- greenfield rewrite on a promise kernel, with load() handles and opt-in behaviors ([#230](https://github.com/KATT/raf-query/issues/230))
 
 ### Features
 
-* greenfield rewrite on a promise kernel, with load() handles and opt-in behaviors ([#230](https://github.com/KATT/raf-query/issues/230)) ([e2a6f85](https://github.com/KATT/raf-query/commit/e2a6f85297992dc8a5cdd3f871a54452393ae978))
+- greenfield rewrite on a promise kernel, with load() handles and opt-in behaviors ([#230](https://github.com/KATT/raf-query/issues/230)) ([e2a6f85](https://github.com/KATT/raf-query/commit/e2a6f85297992dc8a5cdd3f871a54452393ae978))
 
 ## [0.11.1](https://github.com/KATT/raf-query/compare/0.11.0...0.11.1) (2026-10-17)
 

package/dist/bind.d.mts

@@ -14,6 +14,8 @@ import { RootOf } from "@raf-query/core/internal";
  * It returns `useQueryClient` itself; only the types change. It isn't a
  * hook, so call it at module level. This module has no `"use client"`, so a
  * server module can import the file that binds it.
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features#typing-meta-by-its-root
  */
 export declare function bindUseQueryClient<T>(): () => QueryClient<RootOf<T>>;
 //#endregion

package/dist/bind.mjs

@@ -13,6 +13,8 @@ import { useQueryClient } from "./provider.mjs";
 * It returns `useQueryClient` itself; only the types change. It isn't a
 * hook, so call it at module level. This module has no `"use client"`, so a
 * server module can import the file that binds it.
+*
+* @see https://raf-query.katt.dev/docs/links-and-features#typing-meta-by-its-root
 */
 function bindUseQueryClient() {
 	return useQueryClient;

package/dist/devtools.d.mts

@@ -1,6 +1,11 @@
 import { QueryClient } from "@raf-query/core";
 import { CSSProperties } from "react";
 //#region src/devtools.d.ts
+/**
+ * Props of {@link QueryDevtoolsPanel}.
+ *
+ * @see https://raf-query.katt.dev/docs/devtools#props
+ */
 export interface QueryDevtoolsPanelProps {
   /** The client to inspect. Default: the nearest `QueryClientProvider`'s. */
   readonly client?: QueryClient;
@@ -9,6 +14,11 @@ export interface QueryDevtoolsPanelProps {
   /** Styles for the panel's root element, e.g. its height. */
   readonly style?: CSSProperties;
 }
+/**
+ * Props of {@link QueryDevtools}.
+ *
+ * @see https://raf-query.katt.dev/docs/devtools
+ */
 export interface QueryDevtoolsProps {
   /** Corner of the toggle button. Default: `"bottom-right"`. */
   readonly buttonPosition?: "bottom-left" | "bottom-right" | "top-left" | "top-right";
@@ -17,8 +27,16 @@ export interface QueryDevtoolsProps {
   /** Open on the first render. */
   readonly initialIsOpen?: boolean;
 }
-/** The devtools panel, to place in your own layout. */
+/**
+ * The devtools panel, to place in your own layout.
+ *
+ * @see https://raf-query.katt.dev/docs/devtools#embedding-the-panel
+ */
 export declare function QueryDevtoolsPanel(props: QueryDevtoolsPanelProps): import("react").JSX.Element;
-/** A toggle button that opens the devtools panel over the page. */
+/**
+ * A toggle button that opens the devtools panel over the page.
+ *
+ * @see https://raf-query.katt.dev/docs/devtools
+ */
 export declare function QueryDevtools(props: QueryDevtoolsProps): import("react").JSX.Element;
 //#endregion

package/dist/devtools.mjs

@@ -179,7 +179,11 @@ function Panel(props) {
 		})]
 	});
 }
-/** The devtools panel, to place in your own layout. */
+/**
+* The devtools panel, to place in your own layout.
+*
+* @see https://raf-query.katt.dev/docs/devtools#embedding-the-panel
+*/
 function QueryDevtoolsPanel(props) {
 	const nearest = useOptionalQueryClient();
 	const client = props.client ?? nearest;
@@ -207,7 +211,11 @@ const corners = {
 		top: 12
 	}
 };
-/** A toggle button that opens the devtools panel over the page. */
+/**
+* A toggle button that opens the devtools panel over the page.
+*
+* @see https://raf-query.katt.dev/docs/devtools
+*/
 function QueryDevtools(props) {
 	const [open, setOpen] = useState(props.initialIsOpen ?? false);
 	const corner = corners[props.buttonPosition ?? "bottom-right"];

package/dist/hydration-boundary/hydration-boundary-react-server.d.mts

@@ -10,6 +10,8 @@ import { HydrationBoundaryProps } from "./hydration-boundary.mjs";
  * It also marks the client components' server render: from there on, a read
  * of a query nothing sent renders its Suspense fallback on the server and
  * loads in the browser, instead of fetching where nothing would send it.
+ *
+ * @see https://raf-query.katt.dev/docs/react-server-components#setup
  */
 export declare function HydrationBoundary(props: HydrationBoundaryProps): import("react").JSX.Element;
 //#endregion

package/dist/hydration-boundary/hydration-boundary-react-server.mjs

@@ -22,6 +22,8 @@ function sentHashes(client) {
 * It also marks the client components' server render: from there on, a read
 * of a query nothing sent renders its Suspense fallback on the server and
 * loads in the browser, instead of fetching where nothing would send it.
+*
+* @see https://raf-query.katt.dev/docs/react-server-components#setup
 */
 function HydrationBoundary(props) {
 	const client = props.client;

package/dist/hydration-boundary/hydration-boundary.d.mts

@@ -1,6 +1,11 @@
 import { DehydrateOptions, DehydratedState, QueryClient } from "@raf-query/core";
 import { ReactNode } from "react";
 //#region src/hydration-boundary/hydration-boundary.d.ts
+/**
+ * Props of {@link HydrationBoundary}: a dehydrated `state`, or in server components the request's `client`.
+ *
+ * @see https://raf-query.katt.dev/docs/react-router#server-loaders
+ */
 export type HydrationBoundaryProps = {
   readonly children?: ReactNode;
   /**
@@ -39,6 +44,8 @@ export type HydrationBoundaryProps = {
  * With loaders, such as React Router Framework Mode, pass the `state` the
  * loader dehydrated. Pending entries cross as promises when the framework's
  * serializer supports them (React Router's Single Fetch does).
+ *
+ * @see https://raf-query.katt.dev/docs/react-router#server-loaders
  */
 export declare function HydrationBoundary(props: HydrationBoundaryProps): import("react").JSX.Element;
 //#endregion

package/dist/hydration-boundary/hydration-boundary.mjs

@@ -24,6 +24,8 @@ import { jsx } from "react/jsx-runtime";
 * With loaders, such as React Router Framework Mode, pass the `state` the
 * loader dehydrated. Pending entries cross as promises when the framework's
 * serializer supports them (React Router's Single Fetch does).
+*
+* @see https://raf-query.katt.dev/docs/react-router#server-loaders
 */
 function HydrationBoundary(props) {
 	if (props.state === void 0) throw new Error("HydrationBoundary needs `state` here. `client` works only in server components.");

package/dist/index-react-server.d.mts

@@ -1,10 +1,10 @@
 import { QueryDevtools, QueryDevtoolsPanel, QueryDevtoolsPanelProps, QueryDevtoolsProps } from "./devtools.mjs";
 import { QueryClientProvider } from "./provider.mjs";
 import { QueryState, QueryValue, UseQueryOptions } from "./use-query.mjs";
-import { InfiniteQueryState, PageControls } from "./use-infinite-query.mjs";
+import { InfiniteQueryState } from "./use-infinite-query.mjs";
 import "./index-shared.mjs";
 import { HydrationBoundaryProps } from "./hydration-boundary/hydration-boundary.mjs";
 import { HydrationBoundary } from "./hydration-boundary/hydration-boundary-react-server.mjs";
 import { bindUseQueryClient, useInfiniteQuery, useIsFetching, useQuery, useQueryClient } from "./react-server-hooks.mjs";
 export * from "@raf-query/core";
-export { HydrationBoundary, type HydrationBoundaryProps, type InfiniteQueryState, type PageControls, QueryClientProvider, QueryDevtools, QueryDevtoolsPanel, type QueryDevtoolsPanelProps, type QueryDevtoolsProps, type QueryState, type QueryValue, type UseQueryOptions, bindUseQueryClient, useInfiniteQuery, useIsFetching, useQuery, useQueryClient };
+export { HydrationBoundary, type HydrationBoundaryProps, type InfiniteQueryState, QueryClientProvider, QueryDevtools, QueryDevtoolsPanel, type QueryDevtoolsPanelProps, type QueryDevtoolsProps, type QueryState, type QueryValue, type UseQueryOptions, bindUseQueryClient, useInfiniteQuery, useIsFetching, useQuery, useQueryClient };

package/dist/index-shared.d.mts

@@ -1,6 +1,6 @@
 import { QueryDevtools, QueryDevtoolsPanel, QueryDevtoolsPanelProps, QueryDevtoolsProps } from "./devtools.mjs";
 import { QueryClientProvider } from "./provider.mjs";
 import { QueryState, QueryValue, UseQueryOptions } from "./use-query.mjs";
-import { InfiniteQueryState, PageControls } from "./use-infinite-query.mjs";
+import { InfiniteQueryState } from "./use-infinite-query.mjs";
 export * from "@raf-query/core";
-export { type InfiniteQueryState, type PageControls, QueryClientProvider, QueryDevtools, QueryDevtoolsPanel, type QueryDevtoolsPanelProps, type QueryDevtoolsProps, type QueryState, type QueryValue, type UseQueryOptions };
+export { type InfiniteQueryState, QueryClientProvider, QueryDevtools, QueryDevtoolsPanel, type QueryDevtoolsPanelProps, type QueryDevtoolsProps, type QueryState, type QueryValue, type UseQueryOptions };

package/dist/index.d.mts

@@ -1,10 +1,10 @@
 import { QueryDevtools, QueryDevtoolsPanel, QueryDevtoolsPanelProps, QueryDevtoolsProps } from "./devtools.mjs";
 import { QueryClientProvider, useQueryClient } from "./provider.mjs";
 import { QueryState, QueryValue, UseQueryOptions, useQuery } from "./use-query.mjs";
-import { InfiniteQueryState, PageControls, useInfiniteQuery } from "./use-infinite-query.mjs";
+import { InfiniteQueryState, useInfiniteQuery } from "./use-infinite-query.mjs";
 import "./index-shared.mjs";
 import { HydrationBoundary, HydrationBoundaryProps } from "./hydration-boundary/hydration-boundary.mjs";
 import { useIsFetching } from "./use-is-fetching.mjs";
 import { bindUseQueryClient } from "./bind.mjs";
 export * from "@raf-query/core";
-export { HydrationBoundary, type HydrationBoundaryProps, type InfiniteQueryState, type PageControls, QueryClientProvider, QueryDevtools, QueryDevtoolsPanel, type QueryDevtoolsPanelProps, type QueryDevtoolsProps, type QueryState, type QueryValue, type UseQueryOptions, bindUseQueryClient, useInfiniteQuery, useIsFetching, useQuery, useQueryClient };
+export { HydrationBoundary, type HydrationBoundaryProps, type InfiniteQueryState, QueryClientProvider, QueryDevtools, QueryDevtoolsPanel, type QueryDevtoolsPanelProps, type QueryDevtoolsProps, type QueryState, type QueryValue, type UseQueryOptions, bindUseQueryClient, useInfiniteQuery, useIsFetching, useQuery, useQueryClient };

package/dist/provider.d.mts

@@ -4,11 +4,17 @@ import { ReactNode } from "react";
 /**
  * Provides a client to the tree, and runs its features (focus and
  * reconnect refetching, polling, …) while mounted.
+ *
+ * @see https://raf-query.katt.dev/docs/ssr-and-hydration#the-provider
  */
 export declare function QueryClientProvider(props: {
   readonly children?: ReactNode;
   readonly client: QueryClient;
 }): import("react").JSX.Element;
-/** The client from the nearest {@link QueryClientProvider}. */
+/**
+ * The client from the nearest {@link QueryClientProvider}.
+ *
+ * @see https://raf-query.katt.dev/docs/api-reference#providers
+ */
 export declare function useQueryClient(): QueryClient;
 //#endregion

package/dist/provider.mjs

@@ -7,6 +7,8 @@ const QueryClientContext = createContext(null);
 /**
 * Provides a client to the tree, and runs its features (focus and
 * reconnect refetching, polling, …) while mounted.
+*
+* @see https://raf-query.katt.dev/docs/ssr-and-hydration#the-provider
 */
 function QueryClientProvider(props) {
 	const client = props.client;
@@ -20,7 +22,11 @@ function QueryClientProvider(props) {
 function useOptionalQueryClient() {
 	return use(QueryClientContext);
 }
-/** The client from the nearest {@link QueryClientProvider}. */
+/**
+* The client from the nearest {@link QueryClientProvider}.
+*
+* @see https://raf-query.katt.dev/docs/api-reference#providers
+*/
 function useQueryClient() {
 	const client = useOptionalQueryClient();
 	if (!client) throw new Error("useQueryClient: no QueryClientProvider above this component");

package/dist/react-server-hooks.d.mts

@@ -5,13 +5,39 @@ import { useIsFetching as useIsFetching$1 } from "./use-is-fetching.mjs";
 import { QueryClient } from "@raf-query/core";
 import { RootOf } from "@raf-query/core/internal";
 //#region src/react-server-hooks.d.ts
+/**
+ * `useQuery` in a server component: throws, since hooks belong in client
+ * components.
+ *
+ * @see https://raf-query.katt.dev/docs/react-server-components
+ */
 export declare const useQuery: typeof useQuery$1;
+/**
+ * `useInfiniteQuery` in a server component: throws, since hooks belong in client
+ * components.
+ *
+ * @see https://raf-query.katt.dev/docs/react-server-components
+ */
 export declare const useInfiniteQuery: typeof useInfiniteQuery$1;
+/**
+ * `useIsFetching` in a server component: throws, since hooks belong in client
+ * components.
+ *
+ * @see https://raf-query.katt.dev/docs/react-server-components
+ */
 export declare const useIsFetching: typeof useIsFetching$1;
+/**
+ * `useQueryClient` in a server component: throws, since hooks belong in client
+ * components.
+ *
+ * @see https://raf-query.katt.dev/docs/react-server-components
+ */
 export declare const useQueryClient: typeof useQueryClient$1;
 /**
  * `bindUseQueryClient` runs at module level in a file server modules may
  * import too, so it works here and returns the throwing `useQueryClient`.
+ *
+ * @see https://raf-query.katt.dev/docs/links-and-features#typing-meta-by-its-root
  */
 export declare function bindUseQueryClient<T>(): () => QueryClient<RootOf<T>>;
 //#endregion

package/dist/react-server-hooks.mjs

@@ -4,13 +4,39 @@ function clientOnly(name) {
 		throw new Error(`${name} reads in client components: move this into a file with "use client". Server components start queries with load() and send them with <HydrationBoundary>.`);
 	};
 }
+/**
+* `useQuery` in a server component: throws, since hooks belong in client
+* components.
+*
+* @see https://raf-query.katt.dev/docs/react-server-components
+*/
 const useQuery = /* @__PURE__ */ clientOnly("useQuery");
+/**
+* `useInfiniteQuery` in a server component: throws, since hooks belong in client
+* components.
+*
+* @see https://raf-query.katt.dev/docs/react-server-components
+*/
 const useInfiniteQuery = /* @__PURE__ */ clientOnly("useInfiniteQuery");
+/**
+* `useIsFetching` in a server component: throws, since hooks belong in client
+* components.
+*
+* @see https://raf-query.katt.dev/docs/react-server-components
+*/
 const useIsFetching = /* @__PURE__ */ clientOnly("useIsFetching");
+/**
+* `useQueryClient` in a server component: throws, since hooks belong in client
+* components.
+*
+* @see https://raf-query.katt.dev/docs/react-server-components
+*/
 const useQueryClient = /* @__PURE__ */ clientOnly("useQueryClient");
 /**
 * `bindUseQueryClient` runs at module level in a file server modules may
 * import too, so it works here and returns the throwing `useQueryClient`.
+*
+* @see https://raf-query.katt.dev/docs/links-and-features#typing-meta-by-its-root
 */
 function bindUseQueryClient() {
 	return useQueryClient;

package/dist/tanstack-router-browser.d.mts

@@ -5,6 +5,8 @@ import { AnyRouter } from "@tanstack/react-router";
  * The browser build of `@raf-query/react/tanstack-router` (the `browser`
  * export condition): the client half only, so the server's dehydration
  * stream stays out of the app bundle.
+ *
+ * @see https://raf-query.katt.dev/docs/tanstack-start#setup
  */
 export declare function setupRouterIntegration<TRouter extends AnyRouter>(options: RouterIntegrationOptions<TRouter>): void;
 //#endregion

package/dist/tanstack-router-browser.mjs

@@ -4,6 +4,8 @@ import { handleRedirects, setupClient } from "./tanstack-router-shared.mjs";
 * The browser build of `@raf-query/react/tanstack-router` (the `browser`
 * export condition): the client half only, so the server's dehydration
 * stream stays out of the app bundle.
+*
+* @see https://raf-query.katt.dev/docs/tanstack-start#setup
 */
 function setupRouterIntegration(options) {
 	setupClient(options);

package/dist/tanstack-router-shared.d.mts

@@ -11,6 +11,11 @@ declare module "@tanstack/react-router" {
     rafQueryHandle: QueryHandle;
   }
 }
+/**
+ * Options for `setupRouterIntegration`.
+ *
+ * @see https://raf-query.katt.dev/docs/tanstack-start#setup
+ */
 export interface RouterIntegrationOptions<TRouter extends AnyRouter> {
   readonly dehydrateOptions?: DehydrateOptions;
   /** Navigate when a `queryFn` throws `redirect()`. Default `true`. */

package/dist/tanstack-router.d.mts

@@ -11,6 +11,8 @@ import { AnyRouter } from "@tanstack/react-router";
  * - Turns `redirect()` thrown from a `queryFn` into a navigation.
  *
  * Call it in `getRouter`, which runs once per request on the server.
+ *
+ * @see https://raf-query.katt.dev/docs/tanstack-start#setup
  */
 export declare function setupRouterIntegration<TRouter extends AnyRouter>(options: RouterIntegrationOptions<TRouter>): void;
 //#endregion

package/dist/tanstack-router.mjs

@@ -45,6 +45,8 @@ function setupServer(options) {
 * - Turns `redirect()` thrown from a `queryFn` into a navigation.
 *
 * Call it in `getRouter`, which runs once per request on the server.
+*
+* @see https://raf-query.katt.dev/docs/tanstack-start#setup
 */
 function setupRouterIntegration(options) {
 	if (options.router.isServer) setupServer(options);

package/dist/use-infinite-query.d.mts

@@ -1,18 +1,12 @@
 import { QueryState, QueryValue, UseQueryOptions } from "./use-query.mjs";
-import { InfiniteQueryFactory, QueryHandle } from "@raf-query/core";
+import { InfiniteQueryFactory, PageControls, QueryHandle } from "@raf-query/core";
 //#region src/use-infinite-query.d.ts
-/** The paging half of what `useInfiniteQuery` returns. */
-export interface PageControls {
-  /** Load the page after the last one. Resolves when it's there. */
-  fetchNextPage(): Promise<void>;
-  /** Load the page before the first one. Resolves when it's there. */
-  fetchPreviousPage(): Promise<void>;
-  readonly hasNextPage: boolean;
-  readonly hasPreviousPage: boolean;
-  readonly isFetchingNextPage: boolean;
-  readonly isFetchingPreviousPage: boolean;
-}
-/** What `useInfiniteQuery` returns next to the data. */
+/**
+ * What `useInfiniteQuery` returns next to the data: core's paging controls
+ * and the query's state.
+ *
+ * @see https://raf-query.katt.dev/docs/infinite-queries#reading-pages
+ */
 export interface InfiniteQueryState<TFactory extends InfiniteQueryFactory = InfiniteQueryFactory> extends PageControls, QueryState<TFactory> {}
 /**
  * Read a paged query (`infiniteQueryOptions`) by its handle. The data is
@@ -22,6 +16,8 @@ export interface InfiniteQueryState<TFactory extends InfiniteQueryFactory = Infi
  * const [pagesThenable, pagesState] = useInfiniteQuery(commentsQuery, handles.comments);
  * const pages = use(pagesThenable);
  * ```
+ *
+ * @see https://raf-query.katt.dev/docs/infinite-queries#reading-pages
  */
 export declare function useInfiniteQuery<TFactory extends InfiniteQueryFactory>(factory: TFactory, handle: QueryHandle<TFactory>, options?: UseQueryOptions): readonly [QueryValue<TFactory>, InfiniteQueryState<TFactory>];
 //#endregion

package/dist/use-infinite-query.mjs

@@ -1,21 +1,14 @@
-import { settled, useQueryRead } from "./use-query.mjs";
-import { fetchEntry, pageParamAfter } from "@raf-query/core/internal";
+import { useQueryRead } from "./use-query.mjs";
+import { fetchPage, pageState } from "@raf-query/core/internal";
 //#region src/use-infinite-query.ts
-function hasPage(entry, state, direction) {
-	return state.hasData && pageParamAfter(entry.options, state.data, direction) !== void 0;
-}
+/** Core's paging controls, split into stable actions and tracked fields. */
 function pageFields(entry, state) {
 	return {
 		actions: {
-			fetchNextPage: () => settled(fetchEntry(entry, { direction: "next" })),
-			fetchPreviousPage: () => settled(fetchEntry(entry, { direction: "previous" }))
+			fetchNextPage: () => fetchPage(entry, "next"),
+			fetchPreviousPage: () => fetchPage(entry, "previous")
 		},
-		fields: {
-			hasNextPage: hasPage(entry, state, "next"),
-			hasPreviousPage: hasPage(entry, state, "previous"),
-			isFetchingNextPage: state.fetchingDirection === "next",
-			isFetchingPreviousPage: state.fetchingDirection === "previous"
-		}
+		fields: { ...pageState(entry, state) }
 	};
 }
 /**
@@ -26,6 +19,8 @@ function pageFields(entry, state) {
 * const [pagesThenable, pagesState] = useInfiniteQuery(commentsQuery, handles.comments);
 * const pages = use(pagesThenable);
 * ```
+*
+* @see https://raf-query.katt.dev/docs/infinite-queries#reading-pages
 */
 function useInfiniteQuery(factory, handle, options) {
 	const read = useQueryRead(factory, handle, options, pageFields);

package/dist/use-is-fetching.d.mts

@@ -5,6 +5,8 @@ import { AnyFactory, AnyTarget } from "@raf-query/core/internal";
  * How many queries have a request in flight: all of them, or a factory's,
  * a group's or a target's. For a global loading indicator. Always `0` on
  * the server and while hydrating, so the HTML matches the first browser render.
+ *
+ * @see https://raf-query.katt.dev/docs/background-fetching-indicators#useisfetching
  */
 export declare function useIsFetching(target?: AnyFactory | AnyTarget | Group): number;
 //#endregion

package/dist/use-is-fetching.mjs

@@ -7,6 +7,8 @@ const serverCount = () => 0;
 * How many queries have a request in flight: all of them, or a factory's,
 * a group's or a target's. For a global loading indicator. Always `0` on
 * the server and while hydrating, so the HTML matches the first browser render.
+*
+* @see https://raf-query.katt.dev/docs/background-fetching-indicators#useisfetching
 */
 function useIsFetching(target) {
 	const client = useQueryClient();

package/dist/use-query.d.mts

@@ -2,6 +2,11 @@ import "./tracked.mjs";
 import { DataOf, InputOf, QueryFactory, QueryHandle, SingleQueryFactory, Thenable } from "@raf-query/core";
 import "@raf-query/core/internal";
 //#region src/use-query.d.ts
+/**
+ * Options for `useQuery` and `useInfiniteQuery`.
+ *
+ * @see https://raf-query.katt.dev/docs/url-state-and-pagination#what-shows-while-the-new-input-loads
+ */
 export interface UseQueryOptions {
   /**
    * While a new handle's query has no data: `"suspend"` (the default) shows
@@ -10,7 +15,11 @@ export interface UseQueryOptions {
    */
   readonly whilePending?: "previous" | "suspend";
 }
-/** What `useQuery` returns next to the data. */
+/**
+ * What `useQuery` returns next to the data.
+ *
+ * @see https://raf-query.katt.dev/docs/reading-queries#state
+ */
 export interface QueryState<TFactory extends QueryFactory = QueryFactory> {
   /** The last request's error while it's the latest outcome. */
   readonly error: unknown;
@@ -33,19 +42,23 @@ export interface QueryState<TFactory extends QueryFactory = QueryFactory> {
  * to pass to `use()`.
  * A loader can't promise the data is still cached when a component renders
  * (a write can reset or remove it), so the read may suspend.
+ *
+ * @see https://raf-query.katt.dev/docs/reading-queries
  */
 export type QueryValue<TFactory extends QueryFactory> = Thenable<DataOf<TFactory>>;
 /**
  * Read a query by its handle.
  *
  * ```tsx
- * const [issueThenable, issueState] = useQuery(issueQuery, handles.issue);
- * const issue = use(issueThenable);
+ * const [postThenable, postState] = useQuery(postQuery, handles.post);
+ * const post = use(postThenable);
  * ```
  *
  * Reading never refetches stale data: loaders decide freshness. A query no
  * loader started fetches while rendering, which is a waterfall (see
  * `waterfallHandle`). Paged queries read with `useInfiniteQuery`.
+ *
+ * @see https://raf-query.katt.dev/docs/reading-queries
  */
 export declare function useQuery<TFactory extends SingleQueryFactory>(factory: TFactory, handle: QueryHandle<TFactory>, options?: UseQueryOptions): readonly [QueryValue<TFactory>, QueryState<TFactory>];
 //#endregion

package/dist/use-query.mjs

@@ -1,7 +1,7 @@
 import { useQueryClient } from "./provider.mjs";
 import { browserRender, leavesUnstartedToBrowser } from "./browser-render.mjs";
 import { createTracker, renderedChanged, trackedState } from "./tracked.mjs";
-import { entryOf, fetchEntry, isInvalidated, isStale, isWaterfallHandle, mapThenable, subscribeEntry } from "@raf-query/core/internal";
+import { entryOf, fetchEntry, isBrowserOnly, isInvalidated, isStale, isWaterfallHandle, mapThenable, subscribeEntry } from "@raf-query/core/internal";
 import { useCallback, useState, useSyncExternalStore } from "react";
 //#region src/use-query.ts
 /** Whether nothing is loading the entry: no data, no error, no request in flight. */
@@ -13,19 +13,27 @@ function isIdle(entry, state) {
 * waterfall handle, or of a query the cache dropped. A server render fed by
 * server components leaves it to the browser: nothing would send its data.
 */
+/**
+* Whether a server render leaves this idle entry to the browser: on a client
+* fed by server components, or a query only the browser runs (`ssr: false`).
+*/
+function leftToBrowser(entry) {
+	return leavesUnstartedToBrowser(entry.client) || isBrowserOnly(entry);
+}
 function startIfMissing(entry, state, waterfall) {
 	const client = entry.client;
-	if (!isIdle(entry, state) || leavesUnstartedToBrowser(client)) return;
-	if (process.env.NODE_ENV !== "production" && !waterfall && !client.isServer) console.warn(`raf-query: ${entry.hash} was read before anything loaded it, so it fetches while rendering. Start it in a loader with load(), or build the handle with waterfallHandle() to make the waterfall explicit.`);
+	if (!isIdle(entry, state) || leftToBrowser(entry)) return;
+	const expected = waterfall || entry.options?.ssr === false;
+	if (process.env.NODE_ENV !== "production" && !expected && !client.isServer) console.warn(`raf-query: ${entry.hash} was read before anything loaded it, so it fetches while rendering. Start it in a loader with load(), or build the handle with waterfallHandle() to make the waterfall explicit.`);
 	fetchEntry(entry);
 }
 /**
-* In a server render fed by server components, an entry `startIfMissing`
-* left to the browser reads as a rejection: a `use()` of it inside Suspense
-* renders that boundary's fallback, and the browser renders the content.
+* In a server render, an entry `startIfMissing` left to the browser reads as
+* a rejection: a `use()` of it inside Suspense renders that boundary's
+* fallback, and the browser renders the content.
 */
 function readOf(entry, state) {
-	return leavesUnstartedToBrowser(entry.client) && isIdle(entry, state) ? browserRender(entry) : entry.thenable;
+	return leftToBrowser(entry) && isIdle(entry, state) ? browserRender(entry) : entry.thenable;
 }
 function settled(promise) {
 	return promise.then(() => {});
@@ -95,17 +103,19 @@ function useQueryRead(factory, handle, options, extra) {
 * Read a query by its handle.
 *
 * ```tsx
-* const [issueThenable, issueState] = useQuery(issueQuery, handles.issue);
-* const issue = use(issueThenable);
+* const [postThenable, postState] = useQuery(postQuery, handles.post);
+* const post = use(postThenable);
 * ```
 *
 * Reading never refetches stale data: loaders decide freshness. A query no
 * loader started fetches while rendering, which is a waterfall (see
 * `waterfallHandle`). Paged queries read with `useInfiniteQuery`.
+*
+* @see https://raf-query.katt.dev/docs/reading-queries
 */
 function useQuery(factory, handle, options) {
 	const read = useQueryRead(factory, handle, options);
 	return [read.thenable, read.controls];
 }
 //#endregion
-export { settled, useQuery, useQueryRead };
+export { useQuery, useQueryRead };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/react",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "React bindings for raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",
@@ -47,7 +47,7 @@
     }
   },
   "dependencies": {
-    "@raf-query/core": "0.12.0"
+    "@raf-query/core": "0.13.0"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.170.0",