@raf-query/react 0.0.6 → 0.0.8

package/CHANGELOG.md

@@ -1,8 +1,18 @@
 # Changelog
 
+## [0.0.8](https://github.com/KATT/raf-query/compare/0.0.7...0.0.8) (2026-10-12)
+
+* rename the TanStack Query experiment to make clear it's experimental and unpublished ([#11](https://github.com/KATT/raf-query/issues/11)) ([146c3be](https://github.com/KATT/raf-query/commit/146c3be5034f8c4c642ea9faea693a7558ca4aac))
+
+## [0.0.7](https://github.com/KATT/raf-query/compare/0.0.6...0.0.7) (2026-10-12)
+
+### Features
+
+- **react:** add @raf-query/react/devtools ([#7](https://github.com/KATT/raf-query/issues/7)) ([e325d76](https://github.com/KATT/raf-query/commit/e325d76305e29f935228a2dbad6834b0309229e4))
+
 ## [0.0.6](https://github.com/KATT/raf-query/compare/0.0.5...0.0.6) (2026-10-12)
 
-* experimental @raf-query/tanstack-react-query on TanStack Query ([#8](https://github.com/KATT/raf-query/issues/8)) ([9d909c4](https://github.com/KATT/raf-query/commit/9d909c46ca030fd465d7af0fcd9591818356dd80))
+- experimental @raf-query/tanstack-react-query on TanStack Query ([#8](https://github.com/KATT/raf-query/issues/8)) ([9d909c4](https://github.com/KATT/raf-query/commit/9d909c46ca030fd465d7af0fcd9591818356dd80))
 
 ## [0.0.5](https://github.com/KATT/raf-query/compare/0.0.4...0.0.5) (2026-10-12)
 

package/README.md

@@ -17,13 +17,14 @@ Early. Both packages are on npm at `0.0.x`, and the API can still change between
 | `@raf-query/core`  | Framework-agnostic: `QueryClient`, cache, `queryOptions` / `infiniteQueryOptions`, handles, dehydrate / hydrate stream, `allKeyed` |
 | `@raf-query/react` | Hooks and provider. Re-exports everything from `@raf-query/core`, so apps install and import only this package                     |
 
-`@raf-query/react` subpath entries for framework integrations:
+`@raf-query/react` subpath entries for framework integrations and tooling:
 
 | Entry                              | Use                                                                    |
 | ---------------------------------- | ---------------------------------------------------------------------- |
 | `@raf-query/react/tanstack-router` | Streams the router's query cache to the client during SSR              |
 | `@raf-query/react/rsc`             | `HydrationBoundary` for passing server-component queries to the client |
 | `@raf-query/react/next`            | `QueryProvider` for Next.js App Router                                 |
+| `@raf-query/react/devtools`        | [Devtools](#devtools) panel for inspecting the cache in development    |
 
 ## Principles
 
@@ -470,21 +471,64 @@ const program = Effect.gen(function* () {
 
 `watch` counts as a reader while it runs, so invalidation and window focus refetch the entry.
 
+## Devtools
+
+`@raf-query/react/devtools` shows the browser's query cache as it changes. Render `QueryDevtools` anywhere under the provider:
+
+```tsx
+import { QueryDevtools } from "@raf-query/react/devtools";
+
+<QueryClientProvider client={queryClient}>
+	{props.children}
+	<QueryDevtools />
+</QueryClientProvider>;
+```
+
+In Next.js, put it inside `QueryProvider` in the root layout. It's a client component, so a server-component layout can render it.
+
+A button in the corner opens a panel docked to the edge of the viewport. The panel lists every entry with its observer count (mounted readers) and status:
+
+| Status     | Meaning                                    |
+| ---------- | ------------------------------------------ |
+| `fetching` | A request is in flight                     |
+| `error`    | The last request failed                    |
+| `stale`    | Read, and older than `staleTime`           |
+| `fresh`    | Read, and within `staleTime`               |
+| `inactive` | Nothing reads it; it's removed at `gcTime` |
+
+Select an entry to see its key, input, data, error, and last update, and to **Refetch**, **Invalidate**, **Reset** (drop its data, so readers suspend and refetch) or **Remove** it. The header filters entries by key, sorts them, and has **Invalidate all** and **Clear cache**. The panel keeps its open state and size in `localStorage`.
+
+`QueryDevtools` props, all optional:
+
+| Prop             | Values (default first)                                         |
+| ---------------- | -------------------------------------------------------------- |
+| `client`         | The nearest `QueryClientProvider`'s client, or another one     |
+| `initialIsOpen`  | `false`, `true`. Applies until the user opens or closes it     |
+| `buttonPosition` | `"bottom-right"`, `"bottom-left"`, `"top-right"`, `"top-left"` |
+| `position`       | `"bottom"`, `"top"`, `"left"`, `"right"`: the docked edge      |
+| `theme`          | `"system"`, `"dark"`, `"light"`                                |
+
+`QueryDevtoolsPanel` is the panel alone, to place in your own layout. It takes `client`, `theme`, `style`, and `onClose`, which adds a close button.
+
+Both render nothing on the server, since the server's cache isn't the browser's. They also render nothing when `process.env.NODE_ENV` is `"production"`, and bundlers drop the panel's code from production builds. To ship the panel in production, for example lazily behind a flag, import from `@raf-query/react/devtools/production`.
+
 ## API reference
 
 `QueryClient`:
 
-| Member                                  | Use                                                                             |
-| --------------------------------------- | ------------------------------------------------------------------------------- |
-| `new QueryClient(config?)`              | `config.defaults` (query options below), `config.onError`, `config.isServer`    |
-| `prefetch`, `ensure`, `fetch`           | [Start queries](#starting-queries)                                              |
-| `invalidate`, `setData`, `getData`      | [Write and read the cache](#mutations)                                          |
-| `effect`                                | [Effect versions](#effect) of `ensure`, `fetch`, `invalidate`, plus `watch`     |
-| `subscribe(listener)`                   | Cache events: `added`, `updated`, `removed`, and `failed` (with the `error`)    |
-| `getAll()`, `getQuery(factory, input?)` | Cache entries, for devtools and integrations                                    |
-| `clear()`                               | Drop every entry and abort in-flight requests                                   |
-| `mount()`                               | Start window-focus and reconnect refetching. The providers call it              |
-| `isServer`                              | Detected from `window`. Server clients don't retry, never gc, skip stale timers |
+| Member                                      | Use                                                                                                                     |
+| ------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| `new QueryClient(config?)`                  | `config.defaults` (query options below), `config.onError`, `config.isServer`                                            |
+| `prefetch`, `ensure`, `fetch`               | [Start queries](#starting-queries)                                                                                      |
+| `invalidate`, `setData`, `getData`          | [Write and read the cache](#mutations)                                                                                  |
+| `reset(factory, input)` / `reset(filter)`   | Drop data and errors; read queries suspend and refetch. Resolves when they settle                                       |
+| `remove(factory, input)` / `remove(filter)` | Remove entries and abort their requests                                                                                 |
+| `effect`                                    | [Effect versions](#effect) of `ensure`, `fetch`, `invalidate`, plus `watch`                                             |
+| `subscribe(listener)`                       | Cache events: `added`, `updated`, `observers` (a reader subscribed or left), `removed`, and `failed` (with the `error`) |
+| `getAll()`, `getQuery(factory, input?)`     | Cache entries, for devtools and integrations                                                                            |
+| `clear()`                                   | Drop every entry and abort in-flight requests                                                                           |
+| `mount()`                                   | Start window-focus and reconnect refetching. The providers call it                                                      |
+| `isServer`                                  | Detected from `window`. Server clients don't retry, never gc, skip stale timers                                         |
 
 Query options, accepted by `queryOptions`, `infiniteQueryOptions` and `config.defaults`:
 

package/dist/devtools-panel.d.mts

@@ -0,0 +1,38 @@
+import { QueryClient } from "@raf-query/core";
+import { CSSProperties } from "react";
+//#region src/devtools-panel.d.ts
+export type DevtoolsTheme = "dark" | "light" | "system";
+export interface QueryDevtoolsPanelProps {
+  /** The client to inspect. Default: the nearest `QueryClientProvider`'s. */
+  readonly client?: QueryClient;
+  /** Shows a close button that calls this. */
+  readonly onClose?: () => void;
+  /** Styles for the panel's root element, e.g. its height. */
+  readonly style?: CSSProperties;
+  /** Default: `"system"`. */
+  readonly theme?: DevtoolsTheme;
+}
+export interface QueryDevtoolsProps {
+  /** Corner of the toggle button. Default: `"bottom-right"`. */
+  readonly buttonPosition?: "bottom-left" | "bottom-right" | "top-left" | "top-right";
+  /** The client to inspect. Default: the nearest `QueryClientProvider`'s. */
+  readonly client?: QueryClient;
+  /** Open on the first visit. Later visits remember the last open state. */
+  readonly initialIsOpen?: boolean;
+  /** Edge of the viewport the panel docks to. Default: `"bottom"`. */
+  readonly position?: "bottom" | "left" | "right" | "top";
+  /** Default: `"system"`. */
+  readonly theme?: DevtoolsTheme;
+}
+/**
+ * The devtools panel on its own, to place anywhere in the page. Renders
+ * nothing on the server, since the server's cache isn't the browser's.
+ */
+export declare function QueryDevtoolsPanel(props: QueryDevtoolsPanelProps): import("react").JSX.Element | null;
+/**
+ * A toggle button that opens the devtools panel docked to an edge of the
+ * viewport. Renders nothing on the server. Open state and size are kept in
+ * `localStorage`.
+ */
+export declare function QueryDevtools(props: QueryDevtoolsProps): import("react").JSX.Element | null;
+//#endregion

package/dist/devtools-panel.mjs

@@ -0,0 +1,878 @@
+"use client";
+import { useOptionalQueryClient } from "./provider.mjs";
+import { countByStatus, sortOrders, statuses, useQueryRows, visibleRows } from "./devtools-store.mjs";
+import { useState, useSyncExternalStore } from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { Predicate } from "effect";
+//#region src/devtools-panel.tsx
+const palettes = {
+	dark: {
+		accent: "#38bdf8",
+		background: "#0f172a",
+		boolean: "#c084fc",
+		border: "#334155",
+		muted: "#94a3b8",
+		number: "#fbbf24",
+		raised: "#1e293b",
+		selected: "#1e3a5f",
+		string: "#4ade80",
+		text: "#e2e8f0"
+	},
+	light: {
+		accent: "#0369a1",
+		background: "#ffffff",
+		boolean: "#7e22ce",
+		border: "#cbd5e1",
+		muted: "#64748b",
+		number: "#b45309",
+		raised: "#f1f5f9",
+		selected: "#dbeafe",
+		string: "#15803d",
+		text: "#0f172a"
+	}
+};
+const statusColors = {
+	error: "#dc2626",
+	fetching: "#2563eb",
+	fresh: "#16a34a",
+	inactive: "#64748b",
+	stale: "#ca8a04"
+};
+const sortLabels = {
+	hash: "Key",
+	status: "Status",
+	updated: "Last updated"
+};
+const fontFamily = "ui-sans-serif, system-ui, -apple-system, \"Segoe UI\", Roboto, sans-serif";
+const monoFamily = "ui-monospace, SFMono-Regular, Menlo, Consolas, \"Liberation Mono\", monospace";
+/** Entries an expanded object, array, map, or set lists before "… more". */
+const maxChildren = 100;
+const minSize = 120;
+const defaultSize = 320;
+const storageKeys = {
+	open: "raf-query-devtools:open",
+	size: "raf-query-devtools:size"
+};
+const noop = () => {};
+const subscribeNever = () => noop;
+/** `false` on the server and while hydrating, then `true`. */
+function useIsClient() {
+	return useSyncExternalStore(subscribeNever, () => true, () => false);
+}
+function subscribeColorScheme(onChange) {
+	const media = window.matchMedia("(prefers-color-scheme: dark)");
+	media.addEventListener("change", onChange);
+	return () => media.removeEventListener("change", onChange);
+}
+function prefersDark() {
+	return window.matchMedia("(prefers-color-scheme: dark)").matches;
+}
+function usePalette(theme = "system") {
+	const systemDark = useSyncExternalStore(subscribeColorScheme, prefersDark, () => true);
+	if (theme === "system") return systemDark ? palettes.dark : palettes.light;
+	return palettes[theme];
+}
+function useDevtoolsClient(client) {
+	const contextClient = useOptionalQueryClient();
+	const resolved = client ?? contextClient;
+	if (!resolved) throw new Error("raf-query devtools: pass `client` or render inside a QueryClientProvider");
+	return resolved;
+}
+function readStored(key) {
+	try {
+		return window.localStorage.getItem(key);
+	} catch {
+		return null;
+	}
+}
+function writeStored(key, value) {
+	try {
+		window.localStorage.setItem(key, value);
+	} catch {}
+}
+function formatTime(updatedAt) {
+	return updatedAt === 0 ? "never" : new Date(updatedAt).toLocaleTimeString();
+}
+/** One-line form of a value, for leaves and collapsed nodes. */
+function preview(value) {
+	if (Predicate.isString(value)) return JSON.stringify(value);
+	if (Predicate.isBigInt(value)) return `${value}n`;
+	if (Predicate.isSymbol(value)) return value.toString();
+	if (Predicate.isFunction(value)) return `ƒ ${value.name || "anonymous"}()`;
+	if (Predicate.isDate(value)) return Number.isNaN(value.getTime()) ? "Invalid Date" : value.toISOString();
+	if (Predicate.isError(value)) return `${value.name}: ${value.message}`;
+	if (Predicate.isRegExp(value)) return String(value);
+	if (Predicate.isPromiseLike(value)) return "Promise";
+	if (Array.isArray(value)) return `Array(${value.length})`;
+	if (Predicate.isMap(value)) return `Map(${value.size})`;
+	if (Predicate.isSet(value)) return `Set(${value.size})`;
+	if (Predicate.isObject(value)) {
+		const size = Object.keys(value).length;
+		return size === 1 ? "{1 key}" : `{${size} keys}`;
+	}
+	return String(value);
+}
+/** Labelled children of a value the explorer can expand, else `undefined`. */
+function childrenOf(value) {
+	if (Array.isArray(value)) return value.map((item, index) => [String(index), item]);
+	if (Predicate.isMap(value)) return [...value].map(([key, item]) => [preview(key), item]);
+	if (Predicate.isSet(value)) return [...value].map((item, index) => [String(index), item]);
+	if (!Predicate.isObject(value) || Predicate.isDate(value) || Predicate.isError(value) || Predicate.isRegExp(value) || Predicate.isPromiseLike(value)) return;
+	return Object.entries(value);
+}
+function colorOf(value, palette) {
+	if (Predicate.isString(value)) return palette.string;
+	if (Predicate.isNumber(value) || Predicate.isBigInt(value)) return palette.number;
+	if (Predicate.isBoolean(value)) return palette.boolean;
+	if (Predicate.isNullish(value)) return palette.muted;
+	return palette.text;
+}
+function copyText(value) {
+	try {
+		return JSON.stringify(value, null, 2) ?? String(value);
+	} catch {
+		return preview(value);
+	}
+}
+function Explorer(props) {
+	const [expanded, setExpanded] = useState(props.depth < 1);
+	const children = childrenOf(props.value);
+	const palette = props.palette;
+	const label = props.label === void 0 ? null : /* @__PURE__ */ jsx("span", {
+		style: { color: palette.accent },
+		children: `${props.label}: `
+	});
+	if (children === void 0) return /* @__PURE__ */ jsxs("div", {
+		style: { paddingLeft: 14 },
+		children: [label, /* @__PURE__ */ jsx("span", {
+			style: { color: colorOf(props.value, palette) },
+			children: preview(props.value)
+		})]
+	});
+	return /* @__PURE__ */ jsxs("div", { children: [/* @__PURE__ */ jsxs("button", {
+		"aria-expanded": expanded,
+		onClick: () => setExpanded(!expanded),
+		style: {
+			background: "none",
+			border: "none",
+			color: palette.text,
+			cursor: "pointer",
+			font: "inherit",
+			padding: 0,
+			textAlign: "left"
+		},
+		type: "button",
+		children: [
+			/* @__PURE__ */ jsx("span", {
+				"aria-hidden": true,
+				style: {
+					display: "inline-block",
+					width: 14
+				},
+				children: expanded ? "▾" : "▸"
+			}),
+			label,
+			/* @__PURE__ */ jsx("span", {
+				style: { color: palette.muted },
+				children: preview(props.value)
+			})
+		]
+	}), expanded ? /* @__PURE__ */ jsxs("div", {
+		style: { paddingLeft: 14 },
+		children: [children.slice(0, maxChildren).map(([key, item]) => /* @__PURE__ */ jsx(Explorer, {
+			depth: props.depth + 1,
+			label: key,
+			palette,
+			value: item
+		}, key)), children.length > maxChildren ? /* @__PURE__ */ jsx("div", {
+			style: {
+				color: palette.muted,
+				paddingLeft: 14
+			},
+			children: `… ${children.length - maxChildren} more`
+		}) : null]
+	}) : null] });
+}
+function StatusChip(props) {
+	return /* @__PURE__ */ jsxs("span", {
+		"data-status": props.status,
+		style: {
+			alignItems: "center",
+			background: props.palette.raised,
+			border: `1px solid ${props.palette.border}`,
+			borderRadius: 999,
+			display: "inline-flex",
+			gap: 6,
+			padding: "2px 8px"
+		},
+		children: [/* @__PURE__ */ jsx("span", {
+			"aria-hidden": true,
+			style: {
+				background: statusColors[props.status],
+				borderRadius: 999,
+				height: 8,
+				width: 8
+			}
+		}), `${props.status} ${props.count}`]
+	});
+}
+function ActionButton(props) {
+	return /* @__PURE__ */ jsx("button", {
+		disabled: props.disabled,
+		onClick: props.onClick,
+		style: {
+			background: props.color,
+			border: "none",
+			borderRadius: 4,
+			color: "#ffffff",
+			cursor: props.disabled ? "not-allowed" : "pointer",
+			font: "inherit",
+			opacity: props.disabled ? .5 : 1,
+			padding: "4px 10px"
+		},
+		type: "button",
+		children: props.label
+	});
+}
+function Heading(props) {
+	return /* @__PURE__ */ jsx("h3", {
+		style: {
+			background: props.palette.raised,
+			borderBottom: `1px solid ${props.palette.border}`,
+			borderTop: `1px solid ${props.palette.border}`,
+			fontSize: 12,
+			fontWeight: 600,
+			margin: 0,
+			padding: "4px 8px"
+		},
+		children: props.title
+	});
+}
+function Field(props) {
+	return /* @__PURE__ */ jsxs("div", {
+		style: {
+			display: "flex",
+			gap: 8,
+			justifyContent: "space-between"
+		},
+		children: [/* @__PURE__ */ jsx("dt", {
+			style: { color: props.palette.muted },
+			children: props.label
+		}), /* @__PURE__ */ jsx("dd", {
+			style: {
+				margin: 0,
+				textAlign: "right"
+			},
+			children: props.children
+		})]
+	});
+}
+function QueryDetails(props) {
+	const palette = props.palette;
+	const query = props.row.query;
+	const state = props.row.state;
+	const options = query.options;
+	const section = { padding: 8 };
+	return /* @__PURE__ */ jsxs("section", {
+		"aria-label": "Query details",
+		style: {
+			flex: 1,
+			minWidth: 0,
+			overflow: "auto"
+		},
+		children: [
+			/* @__PURE__ */ jsx(Heading, {
+				palette,
+				title: "Query details"
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				style: section,
+				children: [/* @__PURE__ */ jsx("pre", {
+					style: {
+						fontFamily: monoFamily,
+						margin: "0 0 8px",
+						whiteSpace: "pre-wrap",
+						wordBreak: "break-all"
+					},
+					children: JSON.stringify(query.key, null, 2)
+				}), /* @__PURE__ */ jsxs("dl", {
+					style: {
+						display: "grid",
+						gap: 4,
+						margin: 0
+					},
+					children: [
+						/* @__PURE__ */ jsx(Field, {
+							label: "Status",
+							palette,
+							children: props.row.status
+						}),
+						/* @__PURE__ */ jsx(Field, {
+							label: "Observers",
+							palette,
+							children: String(props.row.observers)
+						}),
+						/* @__PURE__ */ jsx(Field, {
+							label: "Last updated",
+							palette,
+							children: formatTime(state.updatedAt)
+						}),
+						/* @__PURE__ */ jsx(Field, {
+							label: "Kind",
+							palette,
+							children: options === void 0 ? "hydrated" : options.kind
+						}),
+						/* @__PURE__ */ jsx(Field, {
+							label: "Failures",
+							palette,
+							children: String(state.failureCount)
+						})
+					]
+				})]
+			}),
+			/* @__PURE__ */ jsx(Heading, {
+				palette,
+				title: "Actions"
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				style: {
+					...section,
+					display: "flex",
+					flexWrap: "wrap",
+					gap: 6
+				},
+				children: [
+					/* @__PURE__ */ jsx(ActionButton, {
+						color: statusColors.fetching,
+						disabled: options === void 0 || state.isFetching,
+						label: "Refetch",
+						onClick: () => void query.refetch()
+					}),
+					/* @__PURE__ */ jsx(ActionButton, {
+						color: statusColors.stale,
+						label: "Invalidate",
+						onClick: () => void query.invalidate()
+					}),
+					/* @__PURE__ */ jsx(ActionButton, {
+						color: statusColors.inactive,
+						label: "Reset",
+						onClick: () => void query.reset()
+					}),
+					/* @__PURE__ */ jsx(ActionButton, {
+						color: statusColors.error,
+						label: "Remove",
+						onClick: () => props.client.remove({
+							exact: true,
+							queryKey: query.key
+						})
+					})
+				]
+			}),
+			state.error == null ? null : /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx(Heading, {
+				palette,
+				title: "Error"
+			}), /* @__PURE__ */ jsxs("div", {
+				style: {
+					...section,
+					color: statusColors.error
+				},
+				children: [/* @__PURE__ */ jsx("div", { children: preview(state.error) }), Predicate.isError(state.error) && state.error.stack ? /* @__PURE__ */ jsx("pre", {
+					style: {
+						fontFamily: monoFamily,
+						fontSize: 11,
+						margin: "6px 0 0",
+						whiteSpace: "pre-wrap"
+					},
+					children: state.error.stack
+				}) : null]
+			})] }),
+			/* @__PURE__ */ jsx(Heading, {
+				palette,
+				title: "Data"
+			}),
+			/* @__PURE__ */ jsxs("div", {
+				style: {
+					...section,
+					fontFamily: monoFamily
+				},
+				children: [/* @__PURE__ */ jsx("button", {
+					onClick: () => void navigator.clipboard?.writeText(copyText(state.data)),
+					style: {
+						background: "none",
+						border: `1px solid ${palette.border}`,
+						borderRadius: 4,
+						color: palette.text,
+						cursor: "pointer",
+						float: "right",
+						font: "inherit",
+						fontFamily,
+						padding: "2px 8px"
+					},
+					type: "button",
+					children: "Copy"
+				}), /* @__PURE__ */ jsx(Explorer, {
+					depth: 0,
+					palette,
+					value: state.data
+				})]
+			}),
+			/* @__PURE__ */ jsx(Heading, {
+				palette,
+				title: "Input"
+			}),
+			/* @__PURE__ */ jsx("div", {
+				style: {
+					...section,
+					fontFamily: monoFamily
+				},
+				children: /* @__PURE__ */ jsx(Explorer, {
+					depth: 0,
+					palette,
+					value: query.handle.input
+				})
+			})
+		]
+	});
+}
+function QueryList(props) {
+	const palette = props.palette;
+	if (props.rows.length === 0) return /* @__PURE__ */ jsx("p", {
+		style: {
+			color: palette.muted,
+			margin: 0,
+			padding: 12
+		},
+		children: "No queries"
+	});
+	return /* @__PURE__ */ jsx("ul", {
+		style: {
+			listStyle: "none",
+			margin: 0,
+			padding: 0
+		},
+		children: props.rows.map((row) => /* @__PURE__ */ jsx("li", { children: /* @__PURE__ */ jsxs("button", {
+			"aria-pressed": row.hash === props.selectedHash,
+			"data-status": row.status,
+			onClick: () => props.onSelect(row.hash),
+			style: {
+				alignItems: "center",
+				background: row.hash === props.selectedHash ? palette.selected : "transparent",
+				border: "none",
+				borderBottom: `1px solid ${palette.border}`,
+				color: palette.text,
+				cursor: "pointer",
+				display: "flex",
+				font: "inherit",
+				gap: 8,
+				padding: "4px 8px",
+				textAlign: "left",
+				width: "100%"
+			},
+			title: row.status,
+			type: "button",
+			children: [/* @__PURE__ */ jsx("span", {
+				"aria-label": `${row.observers} observers`,
+				style: {
+					background: statusColors[row.status],
+					borderRadius: 4,
+					color: "#ffffff",
+					flexShrink: 0,
+					fontWeight: 600,
+					minWidth: 22,
+					padding: "1px 4px",
+					textAlign: "center"
+				},
+				children: row.observers
+			}), /* @__PURE__ */ jsx("code", {
+				style: {
+					fontFamily: monoFamily,
+					overflow: "hidden",
+					textOverflow: "ellipsis",
+					whiteSpace: "nowrap"
+				},
+				children: row.hash
+			})]
+		}) }, row.hash))
+	});
+}
+function isSortBy(value) {
+	return sortOrders.some((order) => order === value);
+}
+function Panel(props) {
+	const client = useDevtoolsClient(props.client);
+	const palette = usePalette(props.theme);
+	const rows = useQueryRows(client);
+	const [filter, setFilter] = useState("");
+	const [sortBy, setSortBy] = useState("status");
+	const [selectedHash, setSelectedHash] = useState(void 0);
+	const counts = countByStatus(rows);
+	const shown = visibleRows(rows, filter, sortBy);
+	const selected = rows.find((row) => row.hash === selectedHash);
+	const control = {
+		background: palette.raised,
+		border: `1px solid ${palette.border}`,
+		borderRadius: 4,
+		color: palette.text,
+		font: "inherit",
+		padding: "3px 6px"
+	};
+	const onClose = props.onClose;
+	return /* @__PURE__ */ jsxs("div", {
+		"data-raf-query-devtools": "",
+		style: {
+			background: palette.background,
+			boxSizing: "border-box",
+			color: palette.text,
+			colorScheme: palette === palettes.dark ? "dark" : "light",
+			display: "flex",
+			flexDirection: "column",
+			fontFamily,
+			fontSize: 12,
+			lineHeight: 1.4,
+			minHeight: 0,
+			overflow: "hidden",
+			...props.style
+		},
+		children: [/* @__PURE__ */ jsxs("header", {
+			style: {
+				alignItems: "center",
+				borderBottom: `1px solid ${palette.border}`,
+				display: "flex",
+				flexWrap: "wrap",
+				gap: 8,
+				padding: 8
+			},
+			children: [
+				/* @__PURE__ */ jsxs("strong", {
+					style: { fontSize: 13 },
+					children: ["raf-query ", /* @__PURE__ */ jsx("span", {
+						style: { color: palette.accent },
+						children: "devtools"
+					})]
+				}),
+				/* @__PURE__ */ jsx("div", {
+					style: {
+						display: "flex",
+						flexWrap: "wrap",
+						gap: 4
+					},
+					children: statuses.map((status) => /* @__PURE__ */ jsx(StatusChip, {
+						count: counts[status],
+						palette,
+						status
+					}, status))
+				}),
+				/* @__PURE__ */ jsxs("div", {
+					style: {
+						display: "flex",
+						gap: 6,
+						marginLeft: "auto"
+					},
+					children: [
+						/* @__PURE__ */ jsx("input", {
+							"aria-label": "Filter queries",
+							onChange: (event) => setFilter(event.target.value),
+							placeholder: "Filter",
+							style: control,
+							type: "search",
+							value: filter
+						}),
+						/* @__PURE__ */ jsx("select", {
+							"aria-label": "Sort queries",
+							onChange: (event) => {
+								const value = event.target.value;
+								if (isSortBy(value)) setSortBy(value);
+							},
+							style: control,
+							value: sortBy,
+							children: sortOrders.map((order) => /* @__PURE__ */ jsx("option", {
+								value: order,
+								children: sortLabels[order]
+							}, order))
+						}),
+						/* @__PURE__ */ jsx("button", {
+							onClick: () => void client.invalidate({ queryKey: [] }),
+							style: {
+								...control,
+								cursor: "pointer"
+							},
+							type: "button",
+							children: "Invalidate all"
+						}),
+						/* @__PURE__ */ jsx("button", {
+							onClick: () => client.clear(),
+							style: {
+								...control,
+								cursor: "pointer"
+							},
+							type: "button",
+							children: "Clear cache"
+						}),
+						onClose ? /* @__PURE__ */ jsx("button", {
+							"aria-label": "Close raf-query devtools",
+							onClick: () => onClose(),
+							style: {
+								...control,
+								cursor: "pointer"
+							},
+							type: "button",
+							children: "✕"
+						}) : null
+					]
+				})
+			]
+		}), /* @__PURE__ */ jsxs("div", {
+			style: {
+				display: "flex",
+				flex: 1,
+				minHeight: 0
+			},
+			children: [/* @__PURE__ */ jsx("nav", {
+				"aria-label": "Queries",
+				style: {
+					borderRight: `1px solid ${palette.border}`,
+					flex: 1,
+					minWidth: 0,
+					overflow: "auto"
+				},
+				children: /* @__PURE__ */ jsx(QueryList, {
+					onSelect: setSelectedHash,
+					palette,
+					rows: shown,
+					selectedHash
+				})
+			}), selected ? /* @__PURE__ */ jsx(QueryDetails, {
+				client,
+				palette,
+				row: selected
+			}) : /* @__PURE__ */ jsx("p", {
+				style: {
+					color: palette.muted,
+					flex: 1,
+					margin: 0,
+					padding: 12
+				},
+				children: "Select a query to inspect it"
+			})]
+		})]
+	});
+}
+/**
+* The devtools panel on its own, to place anywhere in the page. Renders
+* nothing on the server, since the server's cache isn't the browser's.
+*/
+function QueryDevtoolsPanel(props) {
+	return useIsClient() ? /* @__PURE__ */ jsx(Panel, {
+		client: props.client,
+		onClose: props.onClose,
+		style: props.style,
+		theme: props.theme
+	}) : null;
+}
+const corners = {
+	"bottom-left": {
+		bottom: 12,
+		left: 12
+	},
+	"bottom-right": {
+		bottom: 12,
+		right: 12
+	},
+	"top-left": {
+		left: 12,
+		top: 12
+	},
+	"top-right": {
+		right: 12,
+		top: 12
+	}
+};
+function clampSize(size, max) {
+	return Math.min(Math.max(size, minSize), Math.max(max - 40, minSize));
+}
+function DockedDevtools(props) {
+	const position = props.position ?? "bottom";
+	const buttonPosition = props.buttonPosition ?? "bottom-right";
+	const horizontal = position === "left" || position === "right";
+	const [isOpen, setIsOpen] = useState(() => {
+		const stored = readStored(storageKeys.open);
+		return stored === null ? props.initialIsOpen ?? false : stored === "true";
+	});
+	const [size, setSize] = useState(() => Number(readStored(storageKeys.size)) || defaultSize);
+	const palette = usePalette(props.theme);
+	const setOpen = (open) => {
+		setIsOpen(open);
+		writeStored(storageKeys.open, String(open));
+	};
+	const startResize = (event) => {
+		event.preventDefault();
+		let latest = size;
+		const onMove = (move) => {
+			const next = {
+				bottom: window.innerHeight - move.clientY,
+				left: move.clientX,
+				right: window.innerWidth - move.clientX,
+				top: move.clientY
+			}[position];
+			latest = clampSize(next, horizontal ? window.innerWidth : window.innerHeight);
+			setSize(latest);
+		};
+		const onUp = () => {
+			window.removeEventListener("pointermove", onMove);
+			window.removeEventListener("pointerup", onUp);
+			writeStored(storageKeys.size, String(latest));
+		};
+		window.addEventListener("pointermove", onMove);
+		window.addEventListener("pointerup", onUp);
+	};
+	if (!isOpen) return /* @__PURE__ */ jsxs("button", {
+		"aria-label": "Open raf-query devtools",
+		onClick: () => setOpen(true),
+		style: {
+			...corners[buttonPosition],
+			alignItems: "center",
+			background: palette.background,
+			border: `1px solid ${palette.border}`,
+			borderRadius: 999,
+			boxShadow: "0 2px 8px rgb(0 0 0 / 0.25)",
+			color: palette.text,
+			cursor: "pointer",
+			display: "flex",
+			fontFamily,
+			fontSize: 12,
+			fontWeight: 600,
+			gap: 6,
+			padding: "6px 12px",
+			position: "fixed",
+			zIndex: 99999
+		},
+		type: "button",
+		children: [/* @__PURE__ */ jsx("span", {
+			"aria-hidden": true,
+			style: {
+				background: palette.accent,
+				borderRadius: 999,
+				height: 8,
+				width: 8
+			}
+		}), "raf-query"]
+	});
+	const edge = {
+		bottom: {
+			bottom: 0,
+			height: size,
+			left: 0,
+			right: 0
+		},
+		left: {
+			bottom: 0,
+			left: 0,
+			top: 0,
+			width: size
+		},
+		right: {
+			bottom: 0,
+			right: 0,
+			top: 0,
+			width: size
+		},
+		top: {
+			height: size,
+			left: 0,
+			right: 0,
+			top: 0
+		}
+	}[position];
+	const handleEdge = {
+		bottom: {
+			height: 10,
+			left: 0,
+			right: 0,
+			top: -5
+		},
+		left: {
+			bottom: 0,
+			right: -5,
+			top: 0,
+			width: 10
+		},
+		right: {
+			bottom: 0,
+			left: -5,
+			top: 0,
+			width: 10
+		},
+		top: {
+			bottom: -5,
+			height: 10,
+			left: 0,
+			right: 0
+		}
+	}[position];
+	return /* @__PURE__ */ jsxs("aside", {
+		"aria-label": "raf-query devtools",
+		style: {
+			...edge,
+			borderColor: palette.border,
+			borderStyle: "solid",
+			borderWidth: {
+				bottom: "1px 0 0",
+				left: "0 1px 0 0",
+				right: "0 0 0 1px",
+				top: "0 0 1px"
+			}[position],
+			boxShadow: "0 0 16px rgb(0 0 0 / 0.3)",
+			position: "fixed",
+			zIndex: 99999
+		},
+		children: [/* @__PURE__ */ jsx("div", {
+			"aria-label": "Resize raf-query devtools",
+			"aria-orientation": horizontal ? "vertical" : "horizontal",
+			onPointerDown: startResize,
+			role: "separator",
+			style: {
+				...handleEdge,
+				alignItems: "center",
+				cursor: horizontal ? "ew-resize" : "ns-resize",
+				display: "flex",
+				justifyContent: "center",
+				position: "absolute",
+				touchAction: "none",
+				zIndex: 1
+			},
+			children: /* @__PURE__ */ jsx("span", {
+				"aria-hidden": true,
+				style: {
+					background: palette.border,
+					borderRadius: 999,
+					height: horizontal ? 32 : 4,
+					width: horizontal ? 4 : 32
+				}
+			})
+		}), /* @__PURE__ */ jsx(QueryDevtoolsPanel, {
+			client: props.client,
+			onClose: () => setOpen(false),
+			style: {
+				height: "100%",
+				width: "100%"
+			},
+			theme: props.theme
+		})]
+	});
+}
+/**
+* A toggle button that opens the devtools panel docked to an edge of the
+* viewport. Renders nothing on the server. Open state and size are kept in
+* `localStorage`.
+*/
+function QueryDevtools(props) {
+	return useIsClient() ? /* @__PURE__ */ jsx(DockedDevtools, {
+		buttonPosition: props.buttonPosition,
+		client: props.client,
+		initialIsOpen: props.initialIsOpen,
+		position: props.position,
+		theme: props.theme
+	}) : null;
+}
+//#endregion
+export { QueryDevtools, QueryDevtoolsPanel, preview };

package/dist/devtools-production.d.mts

@@ -0,0 +1,2 @@
+import { DevtoolsTheme, QueryDevtools, QueryDevtoolsPanel, QueryDevtoolsPanelProps, QueryDevtoolsProps } from "./devtools-panel.mjs";
+export { type DevtoolsTheme, QueryDevtools, QueryDevtoolsPanel, type QueryDevtoolsPanelProps, type QueryDevtoolsProps };

package/dist/devtools-production.mjs

@@ -0,0 +1,3 @@
+"use client";
+import { QueryDevtools, QueryDevtoolsPanel } from "./devtools-panel.mjs";
+export { QueryDevtools, QueryDevtoolsPanel };

package/dist/devtools-store.mjs

@@ -0,0 +1,103 @@
+import { useSyncExternalStore } from "react";
+//#region src/devtools-store.ts
+const statuses = [
+	"fetching",
+	"error",
+	"stale",
+	"fresh",
+	"inactive"
+];
+const sortOrders = [
+	"status",
+	"hash",
+	"updated"
+];
+const stores = /* @__PURE__ */ new WeakMap();
+function statusOf(query) {
+	const state = query.getState();
+	if (state.isFetching) return "fetching";
+	if (state.status === "error") return "error";
+	if (query.observerCount === 0) return "inactive";
+	return query.isStaleNow() ? "stale" : "fresh";
+}
+function rowOf(query) {
+	return {
+		hash: query.hash,
+		observers: query.observerCount,
+		query,
+		state: query.getState(),
+		status: statusOf(query)
+	};
+}
+function createStore(client) {
+	const listeners = /* @__PURE__ */ new Set();
+	let version = 0;
+	let snapshotVersion = -1;
+	let snapshot = [];
+	let scheduled = false;
+	client.subscribe(() => {
+		version++;
+		if (scheduled || listeners.size === 0) return;
+		scheduled = true;
+		queueMicrotask(() => {
+			scheduled = false;
+			for (const listener of listeners) listener();
+		});
+	});
+	return {
+		getSnapshot: () => {
+			if (snapshotVersion !== version) {
+				snapshotVersion = version;
+				snapshot = client.getAll().map(rowOf);
+			}
+			return snapshot;
+		},
+		subscribe: (onChange) => {
+			listeners.add(onChange);
+			return () => {
+				listeners.delete(onChange);
+			};
+		}
+	};
+}
+function storeFor(client) {
+	let store = stores.get(client);
+	if (!store) {
+		store = createStore(client);
+		stores.set(client, store);
+	}
+	return store;
+}
+/** Every cache entry, re-rendering on each batch of cache events. */
+function useQueryRows(client) {
+	const store = storeFor(client);
+	return useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+}
+function countByStatus(rows) {
+	const counts = {
+		error: 0,
+		fetching: 0,
+		fresh: 0,
+		inactive: 0,
+		stale: 0
+	};
+	for (const row of rows) counts[row.status]++;
+	return counts;
+}
+function compareRows(sortBy) {
+	return (a, b) => {
+		const primary = {
+			hash: 0,
+			status: statuses.indexOf(a.status) - statuses.indexOf(b.status),
+			updated: b.state.updatedAt - a.state.updatedAt
+		}[sortBy];
+		return primary === 0 ? a.hash.localeCompare(b.hash) : primary;
+	};
+}
+/** Rows whose hash contains `filter` (case-insensitive), sorted. */
+function visibleRows(rows, filter, sortBy) {
+	const needle = filter.trim().toLowerCase();
+	return rows.filter((row) => row.hash.toLowerCase().includes(needle)).toSorted(compareRows(sortBy));
+}
+//#endregion
+export { countByStatus, sortOrders, statusOf, statuses, useQueryRows, visibleRows };

package/dist/devtools.d.mts

@@ -0,0 +1,8 @@
+import { DevtoolsTheme, QueryDevtools as QueryDevtools$1, QueryDevtoolsPanel as QueryDevtoolsPanel$1, QueryDevtoolsPanelProps, QueryDevtoolsProps } from "./devtools-panel.mjs";
+//#region src/devtools.d.ts
+/** Toggle button plus docked panel. Renders nothing in production builds. */
+export declare const QueryDevtools: typeof QueryDevtools$1;
+/** The panel alone, to embed anywhere. Renders nothing in production builds. */
+export declare const QueryDevtoolsPanel: typeof QueryDevtoolsPanel$1;
+//#endregion
+export type { DevtoolsTheme, QueryDevtoolsPanelProps, QueryDevtoolsProps };

package/dist/devtools.mjs

@@ -0,0 +1,12 @@
+"use client";
+import { QueryDevtools as QueryDevtools$1, QueryDevtoolsPanel as QueryDevtoolsPanel$1 } from "./devtools-panel.mjs";
+//#region src/devtools.tsx
+function Nothing() {
+	return null;
+}
+/** Toggle button plus docked panel. Renders nothing in production builds. */
+const QueryDevtools = process.env.NODE_ENV === "production" ? Nothing : QueryDevtools$1;
+/** The panel alone, to embed anywhere. Renders nothing in production builds. */
+const QueryDevtoolsPanel = process.env.NODE_ENV === "production" ? Nothing : QueryDevtoolsPanel$1;
+//#endregion
+export { QueryDevtools, QueryDevtoolsPanel };

package/dist/provider.mjs

@@ -15,6 +15,10 @@ function QueryClientProvider(props) {
 		children: props.children
 	});
 }
+/** The nearest provider's client, or `null` outside one. */
+function useOptionalQueryClient() {
+	return use(QueryClientContext);
+}
 /** The client from the nearest {@link QueryClientProvider}. */
 function useQueryClient() {
 	const client = use(QueryClientContext);
@@ -22,4 +26,4 @@ function useQueryClient() {
 	return client;
 }
 //#endregion
-export { QueryClientProvider, useQueryClient };
+export { QueryClientProvider, useOptionalQueryClient, useQueryClient };

package/dist/tanstack-router.mjs

@@ -1,6 +1,6 @@
 import { canDehydrate, dehydrateQuery, hydrate } from "@raf-query/core";
-import { isRedirect } from "@tanstack/react-router";
 import { Predicate } from "effect";
+import { isRedirect } from "@tanstack/react-router";
 //#region src/tanstack-router.ts
 const noop = () => {};
 function setupServer(options) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@raf-query/react",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "React bindings for raf-query, a render-as-you-fetch query library",
   "keywords": [
     "query",
@@ -33,12 +33,14 @@
   "sideEffects": false,
   "exports": {
     ".": "./dist/index.mjs",
+    "./devtools": "./dist/devtools.mjs",
+    "./devtools/production": "./dist/devtools-production.mjs",
     "./next": "./dist/next.mjs",
     "./rsc": "./dist/rsc.mjs",
     "./tanstack-router": "./dist/tanstack-router.mjs"
   },
   "dependencies": {
-    "@raf-query/core": "0.0.6",
+    "@raf-query/core": "0.0.8",
     "effect": "^4.0.1"
   },
   "peerDependencies": {