@ic-reactor/react 3.12.5 → 4.0.0-beta.1

package/README.md

@@ -1,466 +1,279 @@
 # @ic-reactor/react
 
-React bindings for IC Reactor. This package re-exports everything from
-`@ic-reactor/core` and adds hook factories, auth hooks, direct reactor hooks,
-and reusable query or mutation factories built around TanStack Query.
+> **ic-reactor 4 is a prerelease.** `4.0.0-beta.1` is published under npm's
+> `beta` dist-tag, and `latest` stays 3.x until 4.0 GA (milestone 1,
+> [#790](https://github.com/B3Pay/ic-reactor/issues/790)).
 
-## Install
+[![npm version](https://img.shields.io/npm/v/@ic-reactor/react.svg)](https://www.npmjs.com/package/@ic-reactor/react)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
-```bash
-pnpm add @ic-reactor/react @icp-sdk/core @tanstack/react-query
+The React bindings of ic-reactor 4: three `'use client'` exports over a client
+made by [`@ic-reactor/core`](../core/README.md).
 
-# Optional: Internet Identity login helpers
-pnpm add @icp-sdk/auth@^8
-```
+| Export            | What it is                                                               |
+| ----------------- | ------------------------------------------------------------------------ |
+| `ReactorProvider` | Gives a tree one client, and TanStack Query that client's `QueryClient`. |
+| `useClient`       | The client of the nearest provider, for the caller this render shows.    |
+| `useAuth`         | Who calls (`status`, `principal`), with `signIn` and `signOut`.          |
 
-> **npm needs an override to install this set.** Every published
-> `@icp-sdk/auth` peers `@icp-sdk/core@^5`, while this package needs `^6`, so a
-> strict `npm install` fails with `ERESOLVE`. The metadata is stale rather than
-> the versions being incompatible — auth v8 runs against core v6, and this
-> repository's own suite exercises that combination. pnpm and yarn install it
-> as-is; for npm, add:
->
-> ```json
-> { "overrides": { "@icp-sdk/auth": { "@icp-sdk/core": "$@icp-sdk/core" } } }
-> ```
-
-`@icp-sdk/auth` is an optional peer. `AuthenticationManager` reaches it through a
-literal `import("@icp-sdk/auth/client")`, so Vite, Rollup and webpack code-split
-it into its own async chunk. That chunk is never fetched unless something
-touches authentication, and its bytes are dropped from the output entirely in
-apps that never reference the class.
-
-Bundlers still **resolve** that specifier while building the module graph, which
-happens before any tree-shaking — so a missing peer cannot simply be optimized
-away. The import therefore sits inside a `try` block, which webpack-family
-bundlers treat as declaring an optional dependency: with the peer absent the
-build succeeds and prints one warning,
-`Module not found: Can't resolve '@icp-sdk/auth/client'`. Only the login paths
-are affected, and they throw an actionable error if they are ever called.
-
-Install the peer to remove the warning, or silence it with
-[`ignoreWarnings`](https://webpack.js.org/configuration/other-options/#ignorewarnings):
-
-```js
-// webpack.config.js / next.config.js (webpack)
-ignoreWarnings: [{ module: /@ic-reactor\/react/, message: /@icp-sdk\/auth/ }]
-```
+There is no hook that wraps `useQuery` or `useMutation`: read and write
+canisters with TanStack Query's own hooks and the options the client builds.
+The package never re-exports `@ic-reactor/core`, so every name has one import
+path. The guide for both packages ships in core:
+`node_modules/@ic-reactor/core/llms.txt`.
 
-## Quick Start
+## Install
 
-```tsx
-// src/reactor.ts
-import { ClientManager, Reactor, createActorHooks } from "@ic-reactor/react"
-import { QueryClient } from "@tanstack/react-query"
-import { canisterId, idlFactory, type _SERVICE } from "./declarations/backend"
+```bash
+npm install @ic-reactor/core@beta @ic-reactor/react@beta @tanstack/react-query
+```
 
-export const queryClient = new QueryClient()
+Peers: `react` 18 or newer, `@tanstack/react-query` 5, and `@ic-reactor/core` at
+exactly this package's version (the two are released together).
 
-export const clientManager = new ClientManager({
-  queryClient,
-})
+## Provide a client
 
-export const backend = new Reactor<_SERVICE>({
-  clientManager,
-  idlFactory,
-  name: "backend",
-  // `dfx` writes this alongside the idlFactory. Required — omit it only when
-  // the vite-plugin injects an `ic_env` cookie for this canister; outside that
-  // flow the constructor throws.
-  canisterId,
-})
+`ReactorProvider` takes a factory, not a client, and calls it once for each
+mounted provider. When it unmounts, it disposes the client only if that factory
+call created it. Both ways of writing the factory are fine:
 
-export const {
-  useActorQuery,
-  useActorMutation,
-  useActorSuspenseQuery,
-  useActorMethod,
-} = createActorHooks(backend)
-```
+- **The provider owns the client.** A factory that creates it,
+  `client={() => createClient({ ... })}`, gives each mounted provider a client
+  of its own, and the provider disposes it when it unmounts. Use this in an
+  app that renders on a server: the factory runs once per request.
+- **The app owns the client.** A client created at module scope, one per tab
+  and used outside React too, is handed over as `client={() => client}`. The
+  provider borrows it and never disposes it, however many times it mounts and
+  unmounts: the app decides when it ends.
 
-```tsx
-// src/App.tsx
-import { QueryClientProvider } from "@tanstack/react-query"
-import { queryClient, useActorMethod, useActorQuery } from "./reactor"
-
-function Greeting() {
-  const { data, isPending } = useActorQuery({
-    functionName: "greet",
-    args: ["World"],
-  })
-
-  if (isPending) return <p>Loading...</p>
-  return <p>{data}</p>
-}
+`createClient` does no work until the client is used, so the same line runs in
+a server render (anonymous, no auth built) and in the browser (signed in).
 
-function Increment() {
-  const { call, isPending } = useActorMethod({ functionName: "increment" })
+```tsx
+"use client"
 
-  return (
-    <button disabled={isPending} onClick={() => call([])}>
-      {isPending ? "Updating..." : "Increment"}
-    </button>
-  )
-}
+import { createClient } from "@ic-reactor/core"
+import { ReactorProvider } from "@ic-reactor/react"
+import { AuthClient } from "@icp-sdk/auth/client"
+import type { ReactNode } from "react"
 
-export function App() {
+export function Providers({ children }: { children: ReactNode }) {
   return (
-    <QueryClientProvider client={queryClient}>
-      <Greeting />
-      <Increment />
-    </QueryClientProvider>
+    <ReactorProvider
+      client={() =>
+        createClient({ network: "ic", auth: () => new AuthClient() })
+      }
+    >
+      {children}
+    </ReactorProvider>
   )
 }
 ```
 
-## Main APIs
-
-- `createActorHooks(reactor)` for per-canister hooks like `useActorQuery` and
-  `useActorMutation`
-- `createAuthHooks(authentication)` for `useAuth`, `useAgentState`, and
-  `useUserPrincipal`
-- `createIdentityAttributeHooks(identityAttributes)` for signed identity
-  attribute requests
-- direct reactor hooks like `useReactorQuery` when you want to pass the reactor
-  instance at call time
-- factory helpers like `createQuery`, `createSuspenseQuery`,
-  `createInfiniteQuery`, `createSuspenseInfiniteQuery`, and `createMutation`
-  when the same operation must work both inside and outside React
-
-## Choosing the Right Pattern
-
-- Use `createActorHooks` for the simplest component-first integration.
-- Use query and mutation factories when you also need loader, action, service,
-  or test usage through `.fetch()`, `.prefetch()`, `.execute()`, `.invalidate()`,
-  `.getCacheData()`, or `.setData()`.
-- Use `DisplayReactor` when you want UI-friendly values such as strings instead
-  of `bigint` or `Principal`.
-- Use generated hooks from `@ic-reactor/vite-plugin` or `@ic-reactor/cli` when
-  you have larger canisters or frequent `.did` changes.
-
-## Factory Example
-
-```ts
-import { createSuspenseQueryFactory, createMutation } from "@ic-reactor/react"
-import { backend } from "./reactor"
-
-export const getProfile = createSuspenseQueryFactory(backend, {
-  functionName: "get_profile",
-})
-
-export const updateProfile = createMutation(backend, {
-  functionName: "update_profile",
-  onCanisterError: (err) => console.error("Canister Err variant:", err.code),
-})
-```
-
-```tsx
-const profileQuery = getProfile(["alice"])
-
-// React component
-const { data } = profileQuery.useSuspenseQuery()
-
-// Prefetch before navigating (fire-and-forget)
-profileQuery.prefetch()
-
-// Optimistic update
-profileQuery.setData({ id: "alice", name: "Alice" })
-
-// Mutation with cache invalidation
-const mutation = updateProfile.useMutation({
-  invalidateQueries: [profileQuery.getQueryKey()],
-})
-```
-
-## Internet Identity
-
-`defineReactor` wires up Internet Identity for you — `useAuth`,
-`useUserPrincipal`, `useAgentState` and `useIdentityAttributes` come back
-alongside the actor hooks:
-
-```tsx
-// src/reactor.ts
-export const { useActorQuery, useAuth, useIdentityAttributes, authentication } =
-  defineReactor<_SERVICE>({
-    name: "backend",
-    idlFactory,
-    auth: {
-      // Required when the app is served from more than one origin, so every
-      // origin resolves to the same principal.
-      derivationOrigin: "https://app.example.com",
-      // The default signs the user out and reloads after 10 minutes idle.
-      idleOptions: { disableIdle: true },
-    },
-  })
-```
-
-Auth options are forwarded to the underlying `@icp-sdk/auth` client:
-`identityProvider`, `derivationOrigin`, `windowOpenerFeatures`,
-`openIdProvider`, `storage`, `keyType`, `idleOptions`, `identity`, and
-`transport`. Only the `"google" | "apple" | "microsoft"` aliases are accepted
-for `openIdProvider`; any other value is dropped, since raw issuer URLs are
-only meaningful on `requestOpenIdAttributes`, where they scope the keys.
-
-Pass `authentication` from one reactor into another to share a single session
-across canisters. That reactor adopts the manager's `ClientManager` so sign-in
-updates the agent it calls through, so pass either `authentication` or `auth` —
-not both.
+Render it at the root of the part of the app that calls canisters. In a
+framework that renders Server Components, keep the factory in a client module
+like this one: a function cannot cross from a Server Component into a client
+one, so `<Providers>` is what the server layout renders.
 
-Set up manually when you need more control:
+A client the app owns, in a browser-only app:
 
 ```tsx
-// src/auth.ts
-import {
-  AuthenticationManager,
-  IdentityAttributesManager,
-  createAuthHooks,
-  createIdentityAttributeHooks,
-} from "@ic-reactor/react"
-import { clientManager } from "./reactor"
-
-const authentication = new AuthenticationManager({ clientManager })
-export const { useAuth, useAgentState, useUserPrincipal } =
-  createAuthHooks(authentication)
-
-const identityAttributes = new IdentityAttributesManager(authentication)
-export const { useIdentityAttributes } =
-  createIdentityAttributeHooks(identityAttributes)
-```
-
-`useAuth()` calls `authentication.prepareClient()` on mount. Outside React, do
-it yourself during startup — it preloads the auth module so `login()` can open
-the identity provider window synchronously inside a click handler, which is
-what browser popup blockers require:
+"use client"
 
-```ts
-// once, at startup — awaits the dynamic import and builds the AuthClient
-await authentication.prepareClient()
-
-// later, inside the click handler — no await before signIn(), so the popup
-// still counts as user-initiated
-button.onclick = () => authentication.login()
-```
-
-`authentication.getPreparedClient()` returns the already-built client
-synchronously, or `undefined` when the module has not loaded yet.
-
-If your bundler cannot resolve the optional peer at all, construct the client
-yourself and inject it — IC Reactor then never imports `@icp-sdk/auth`:
-
-```ts
+import { createClient } from "@ic-reactor/core"
+import { ReactorProvider } from "@ic-reactor/react"
 import { AuthClient } from "@icp-sdk/auth/client"
+import type { ReactNode } from "react"
 
-const authentication = new AuthenticationManager({
-  clientManager,
-  authClient: new AuthClient(),
-})
-```
-
-### Local Internet Identity
-
-On a local replica the provider URL is resolved for you. `prepareClient()`
-queries the local Internet Identity canister's `http_request` to see what the
-installed build actually serves, then targets `/authorize` (release-2026-01-05 …
-release-2026-03-16) or the legacy `/#authorize` (up to release-2025-03-07, which
-also logs a console warning). If the build serves neither, `login()` throws an
-actionable error rather than opening a popup onto the gateway's
-verification-error page. From `release-2026-03-23` the II frontend moved out of
-the canister, so no local build past that point can be used for sign-in — pin an
-older release in `dfx.json`.
-
-An inconclusive probe — the canister unreachable, or answering no `http_request`
-— does not throw: it keeps `/authorize`, because a diagnostic that blocks a
-login that might have worked is worse than the failure it explains. To override
-the URL yourself, `localInternetIdentityProvider(port, canisterId?, authorizePath?)`
-takes the path as its third argument.
-
-## Identity Attributes / OpenID email and profile values
-
-Identity attributes use a dedicated `IdentityAttributesManager`, with React
-bindings created by `createIdentityAttributeHooks`. Requires `@icp-sdk/auth` v8 —
-the peer range is `^8.0.0`, and the v7 compatibility path was removed in 3.12.0.
-v8 takes the nonce as a thunk (`() => Promise<Uint8Array>`); IC Reactor accepts
-either a value or a callback and adapts it, but the callback form is what
-preserves the user gesture (see below).
-
-**Pass the nonce as a callback.** Awaiting your backend before calling
-`requestOpenIdAttributes` ends the user gesture, and the browser then blocks
-the Internet Identity window:
-
-```tsx
-// ✅ window opens immediately, nonce resolves while the user is in II
-await requestOpenIdAttributes({
-  nonce: () => backend.callMethod({ functionName: "register_begin" }),
-  openIdProvider: "google",
-  keys: ["email", "name"],
+// One client for this tab, also used outside React.
+export const client = createClient({
+  network: "ic",
+  auth: () => new AuthClient(),
 })
 
-// ❌ gesture is gone by the time the window would open
-const nonce = await backend.callMethod({ functionName: "register_begin" })
-await requestOpenIdAttributes({ nonce, openIdProvider: "google", keys })
+export function Providers({ children }: { children: ReactNode }) {
+  return <ReactorProvider client={() => client}>{children}</ReactorProvider>
+}
 ```
 
+Who owns a client follows from when it was created, not from where the factory
+is written. A getter that creates the shared client on its first call
+(`client ??= createClient(...)`) makes the first provider that calls it the
+owner, and that provider disposes it when it unmounts. It can lose the client
+even before that: when React throws away the render that created it (a
+Suspense boundary above the provider that suspends), the client stays queued
+for disposal at garbage collection until the next render gets it back, so a
+collection while the fallback shows disposes the client the page then mounts
+(see [Life of the client](#life-of-the-client)). Create a shared client
+eagerly, as above. In development, a provider whose factory hands back a client
+that an earlier factory call created and no provider has committed yet, as a
+lazily shared getter does, logs a warning that names the fix (under
+`StrictMode`, which calls the factory twice, on the first render); and a
+provider that is given a client which is already disposed logs an error.
+
+## Who is signed in
+
 ```tsx
-// src/RegisterWithOpenIdProvider.tsx
-import { useIdentityAttributes } from "./auth"
-import { backend } from "./reactor"
-
-function RegisterWithOpenIdProvider() {
-  const {
-    requestOpenIdAttributes,
-    attributes,
-    isRequestingAttributes,
-    attributeError,
-  } = useIdentityAttributes()
-
-  async function handleProviderLogin() {
-    const result = await requestOpenIdAttributes({
-      nonce: () => backend.callMethod({ functionName: "register_begin" }),
-      openIdProvider: "microsoft",
-      keys: ["email", "name"],
-      // Optional: any window.open() features string, e.g. to size the popup
-      windowOpenerFeatures: "width=500,height=640",
-    })
-
-    console.log(result.decodedAttributes.email)
-    console.log(result.decodedAttributes.name)
-
-    await backend.callMethod({
-      functionName: "register_finish",
-      args: [
-        {
-          data: result.signedAttributes.data,
-          signature: result.signedAttributes.signature,
-        },
-      ],
-    })
-  }
+import { useAuth } from "@ic-reactor/react"
 
-  return (
-    <button disabled={isRequestingAttributes} onClick={handleProviderLogin}>
-      {attributes?.decodedAttributes.email ??
-        attributeError?.message ??
-        "Continue with provider"}
+export function SessionButton() {
+  const { status, principal, signIn, signOut } = useAuth()
+  return status === "signed-in" ? (
+    <button onClick={() => signOut().catch(console.error)}>
+      Sign out {principal}
     </button>
+  ) : (
+    <button onClick={() => signIn().catch(console.error)}>Sign in</button>
   )
 }
 ```
 
-Use a documented auth provider alias (`"google"`, `"apple"`, or `"microsoft"`)
-or the provider issuer URL your app expects for `openIdProvider`.
-
-Frontend decoded `email` and `name` values are for display only. Production flows
-must send `signedAttributes.data` and `signedAttributes.signature` to the backend
-or canister and verify the signature, nonce, origin, timestamp, and requested keys
-before trusting or storing the attributes.
-
-## Server-Side Rendering
-
-**Build the reactor inside the request, not at module scope.**
-
-A reactor owns its `QueryClient`. On a server a module-scope reactor is created
-once per process and shared by every request, and query keys are
-`[canisterId, functionName, args]` — they do not include the caller. So a
-cached result for a caller-scoped method (`get_my_balance`, a deposit address,
-`my_profile`) is handed to whichever request asks next:
+`status` is `"anonymous"`, `"signed-in"`, `"expired"` or `"signed-in-elsewhere"`,
+and `principal` is the principal calls go out as: the anonymous principal
+(`2vxsx-fae`) in every state but `"signed-in"`. A component that uses
+`useAuth()` renders once for each change of status or principal, and never for
+anything else; the object it returns is the same until one changes.
+
+## Keys follow the caller a render shows
+
+Query keys carry the caller. Call `useClient()` in the body of each component
+that builds keys or read options, on every render, and build them from what it
+returns there, never from a client held at module scope. Do not keep what it
+returns past the render: while a page hydrates it is a view for the anonymous
+caller, and a view never moves on. An effect or a callback that uses it closes
+over the value of its own render and lists it in its dependencies, as the
+`react-hooks/exhaustive-deps` lint rule asks, so that it runs again with the
+client once the page has hydrated. Kept from the hydrating render anywhere
+else (`useState(client)`, `useRef(client)`, a `useMemo` or `useCallback` with
+`[]`, a module variable), it stays that view: the component shows the
+anonymous caller's data, a read it starts while the user is signed in is
+cancelled (`caller_changed`), and a write through it still signs as the live
+caller. Nothing warns about it. A nested `ReactorProvider` given it holds the
+client the view was made over.
 
 ```tsx
-// ❌ Shared by every request on the server
-export const app = defineReactor<_SERVICE>({
-  name: "backend",
-  idlFactory,
-  canisterId,
-})
-```
-
-```tsx
-// ✅ Per request: nothing is shared between users
-export default async function Page() {
-  const app = defineReactor<_SERVICE>({
-    name: "backend",
-    idlFactory,
-    canisterId,
-    queryClient: new QueryClient(),
-  })
-
-  const data = await app.reactor.fetchQuery({ functionName: "get_my_profile" })
-  return <Profile data={data} />
+import { useClient } from "@ic-reactor/react"
+import { useQuery } from "@tanstack/react-query"
+import { actor, type Actor } from "./generated/icrc1"
+
+export function Fee({ id }: { id: string }) {
+  const client = useClient()
+  const ledger = client.canister<Actor>(actor, { id })
+  const fee = useQuery(client.queryOptions(ledger, "icrc1_fee"))
+  return <span>{fee.data?.toString() ?? "…"}</span>
 }
 ```
 
-Two further constraints on the App Router specifically:
-
-- Hooks are client-only, like every React hook — call them from a `"use client"`
-  module. A server component may import `Reactor` / `ClientManager` and make
-  imperative calls; that path works.
-- Hooks bind to their reactor's own `QueryClient` rather than to a
-  `QueryClientProvider`, so `HydrationBoundary` prefetch does not feed them
-  unless the provider's client _is_ that reactor's client. Next.js also
-  evaluates a shared module twice on the server (the RSC and SSR graphs), so a
-  module-scope reactor is two different instances there.
-
-If none of that applies — a client-only SPA — module-scope reactors are exactly
-right and none of this is a concern.
-
-## Query Result Methods
-
-Every object returned by `createQuery`, `createSuspenseQuery`, and their
-factory variants exposes:
-
-| Method                              | Description                                                                                     |
-| ----------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `fetch()`                           | Cache-first fetch — returns data, populates cache. Use in route loaders.                        |
-| `prefetch()`                        | Fire-and-forget cache warm-up. Use on hover or before navigation.                               |
-| `invalidate()`                      | Invalidates the cache entry (triggers refetch if query is mounted).                             |
-| `getQueryKey()`                     | Returns the TanStack Query key for this query.                                                  |
-| `getCacheData(select?)`             | Read directly from cache without fetching. Returns `undefined` if not cached.                   |
-| `setData(updater)`                  | Write raw data into the cache. Accepts a value or updater function. Use for optimistic updates. |
-| `useQuery()` / `useSuspenseQuery()` | React hook for the query.                                                                       |
-
-## Canister Error Handling
-
-Canister methods can return `Result { Err: E }` variants. These are surfaced
-as `CanisterError` and can be handled separately from network or agent errors
-via `onCanisterError`. This callback is supported on both `createMutation` and
-the direct `useActorMutation` hook:
-
-```tsx
-// Via createActorHooks
-const { mutate } = useActorMutation({
-  functionName: "transfer",
-  onCanisterError: (err, vars) => {
-    // err.code — the Err variant key (e.g. "InsufficientFunds")
-    // err.err  — the typed Err value
-    console.error(`Transfer failed: ${err.code}`, vars)
-  },
-  onError: (err) => {
-    // Fires for ALL errors: canister Err variants, network failures, etc.
-    console.error("Unexpected error", err)
-  },
-})
-
-// Via createMutation factory
-const transferMutation = createMutation(backend, {
-  functionName: "transfer",
-  onCanisterError: (err) => toast.error(`${err.code}`),
-})
-```
-
-## Re-exports
-
-`@ic-reactor/react` re-exports the core runtime, so you can import these from a
-single package:
-
-- `ClientManager`
-- `Reactor`
-- `DisplayReactor`
-- `CallError`
-- `CanisterError`
-- `ValidationError`
-
-## See Also
-
-- Docs: https://ic-reactor.b3pay.net/v3/packages/react
-- `@ic-reactor/core`: ../core/README.md
-- `@ic-reactor/vite-plugin`: ../vite-plugin/README.md
-- `@ic-reactor/cli`: ../cli/README.md
+`useClient()` follows the client's caller, so a component that calls it renders
+again on a sign-in, a switch of account and a sign-out, and builds the new
+caller's keys; a change of status that leaves the caller as it is (a session
+that expired, or one signed in elsewhere, both call anonymously) renders
+nothing. It returns the provider's client object itself, except while a page
+hydrates in a browser that holds a session (below). A client built with
+`identity` keeps its caller for good and is always returned as it is.
+
+## On a server
+
+- **One client per request.** A server renders each request as a tree of its
+  own, so a factory that creates the client runs once per request, and no
+  cache or caller is shared between two users. Never build the client at
+  module scope on a server: a module-scope client is for a browser-only app.
+- **Anonymous while hydrating.** `useAuth()` is `anonymous` on a server and
+  while a page hydrates, even when the browser holds a session: the server has
+  none, and the HTML has to match. `useClient()` builds keys for that same
+  anonymous caller there: in a browser that holds a session (an `AuthClient`
+  reads a stored one synchronously), the hydrating render gets a view of the
+  client whose `queryKey`, `queryOptions`, `caller()` and `authState()` are
+  the anonymous caller's, so the page finds what the server prefetched and
+  dehydrated, matches its HTML, and sends nothing. Canisters, writes,
+  `signIn`, `signOut` and the `QueryClient` are the client's own, and a write
+  signs as the caller current when it runs. Right after hydrating, React
+  renders each component that calls `useClient()` or `useAuth()` again with
+  the session, and each read loads the user's keys once: until the user's data
+  arrives, a read shows its loading state, and a `useSuspenseQuery` read its
+  boundary's fallback. A tab whose caller
+  is anonymous anyway (no session, or one that expired or is signed in
+  elsewhere) renders no `useClient()` component again, and no `useAuth()`
+  component either unless its status differs. Show the same thing signed out
+  and while the session is read, and the page does not flicker into a
+  different layout.
+- **Nothing runs on a server but the render.** The auth factory is never called,
+  nothing reads `window` or `localStorage`, and no effect runs, so no timer or
+  listener outlives the request.
+
+### What a signed-in reload costs
+
+Three consequences of that move to the session are accepted, and tested:
+
+- **A Suspense boundary still dehydrated below a component that renders with
+  the caller is rendered on the client.** When a component that calls
+  `useClient()` or `useAuth()` moves on to the session, the update reaches the
+  boundaries it renders. A boundary that has not hydrated yet, because its
+  lazy code is still loading or its streamed HTML has not arrived, is then
+  rendered on the client: it shows its fallback instead of
+  the server's HTML until its content is ready, and React 18 reports a
+  recoverable error. Its data is still the user's, and nothing is sent as
+  anyone else. A `useAuth()` component moves on, and costs the same, in a tab
+  whose session expired or is signed in elsewhere too. To keep the server's HTML, render such a boundary where no
+  component that renders with the caller sits above it (a `useAuth()` header
+  beside it is fine), or pass it in as `children`: a component's own update
+  does not render its `children` prop again.
+- **A read the hydrating render built may run once and be cancelled.**
+  TanStack Query refetches stale data on mount, and an effect may fetch with
+  the hydrating render's options. Such a read is for the anonymous caller
+  while the user is current, so it is cancelled before anything is sent. A
+  key that holds data (the server's) keeps it as it was, and a fetch of it
+  resolves with that data. A key with none fails, with `kind` `"cancelled"`
+  and `code` `"caller_changed"`, until the anonymous caller is current again.
+  The hydrating render's own reads never show that error, but a `QueryCache`
+  `onError`, an effect that awaits the fetch and, for a `useSuspenseQuery`
+  read the server rendered without dehydrating its data, React's
+  `onRecoverableError` (as the reported error's `cause` on React 19) see it:
+  ignore `kind` `"cancelled"` there.
+- **A `useSuspenseQuery` read needs a Suspense boundary above it, on React 18
+  and 19 alike.** The move to the session is a synchronous update, and a
+  `useSuspenseQuery` read with none of the user's data yet suspends it. With a
+  boundary above the read, the boundary shows its fallback until the user's
+  data arrives, then the data, and the rest of the page responds meanwhile.
+  With none, React 18 refuses the update ("A component suspended while
+  responding to synchronous input") and unmounts the root: a signed-in reload
+  renders nothing. React 19 keeps the server's HTML on screen, but until the
+  user's data arrives, however long the read and its retries take, a click or
+  any other update outside a transition commits nothing, and neither does a
+  transition that renders the reading component again. React expects a
+  boundary above any component that suspends anyway: put one there.
+
+## Life of the client
+
+The provider disposes a client its factory created when it unmounts: the
+client stops listening to the auth, disposes it, and clears the `QueryClient`.
+React's development double-mount (`StrictMode` unmounts and mounts every
+component at once) does not dispose a client in use, because the disposal is
+scheduled for the next macrotask and the second mount cancels it. A client the
+app owns is never disposed by a provider.
+
+React runs no cleanup for a render it throws away before committing it, such
+as a provider's first render below a Suspense boundary that suspends. A client
+the factory built for such a render, whose auth a `useAuth()` below may
+already have built, is disposed once that render's state is garbage collected
+(through a `FinalizationRegistry`, in a browser): later than an unmount would,
+but its auth and listeners do not outlive it. A client the factory returns
+again, or that a mounted provider runs on, is never disposed this way, whoever
+created it.
+
+Only the factory of the first render is used: passing another function on a
+later render does not rebuild the client. To replace the client, give the
+provider another `key`.
+
+When React shows a hidden `Activity` again after the client the provider owns
+was disposed, the provider builds another one with the same factory. That
+client starts with an empty cache: hiding a provider inside an `Activity` drops
+everything it had fetched, because React cannot tell a hidden subtree from an
+unmounted one when it cleans up. To keep the cache across hiding, render the
+provider above the `Activity`, or give it a client the app owns.
+
+## 3.x
+
+The released 3.x package, with its hook factories and auth hooks, is documented
+at https://ic-reactor.b3pay.net/v3/packages/react. Its source and security fixes
+live on the `main` branch.