@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/evals/conditions/v3/docs/llms-full.txt

@@ -0,0 +1,1053 @@
+# IC Reactor: full guide for AI coding agents
+
+> How to write correct IC Reactor code in an app: install, choose a setup, call
+> canisters from React and from plain code, cache and invalidate, sign in,
+> render on a server, handle errors, generate code, test, and the mistakes to
+> avoid.
+
+This guide is for code that uses the published packages. The short index of
+the documentation is https://ic-reactor.b3pay.net/llms.txt. Both are published
+from the main branch, so they can describe changes that no release carries
+yet; the Unreleased section of
+https://github.com/B3Pay/ic-reactor/blob/main/CHANGELOG.md lists those, with
+migration hints for behaviour changes. Each installed package also carries a
+guide for its own API at `node_modules/@ic-reactor/<package>/llms.txt`,
+written for the version installed.
+
+The rules below also ship as the `ic-reactor` Agent Skill. In Claude Code:
+`/plugin marketplace add B3Pay/ic-reactor`, then
+`/plugin install ic-reactor@ic-reactor`. For other agents:
+`npx skills add B3Pay/ic-reactor --skill ic-reactor`.
+
+Package versions this guide describes:
+
+- `@ic-reactor/core`: `3.13.0`
+- `@ic-reactor/react`: `3.13.0`
+- `@ic-reactor/candid`: `3.13.0`
+- `@ic-reactor/codegen`: `0.15.1`
+- `@ic-reactor/cli`: `0.15.1`
+- `@ic-reactor/vite-plugin`: `0.15.1`
+- `@ic-reactor/parser`: `0.6.0`
+
+## What IC Reactor Is
+
+IC Reactor calls Internet Computer canisters with end-to-end TypeScript types
+taken from the canister's Candid service type (`_SERVICE` in generated
+declarations). It caches query results in TanStack Query, gives React hooks
+and reusable query/mutation objects, unwraps Candid `Result` values into data
+or a typed error, signs users in with Internet Identity, and can generate all
+of this from `.did` files.
+
+| Package                   | Use it for                                                                                  |
+| ------------------------- | ------------------------------------------------------------------------------------------- |
+| `@ic-reactor/core`        | `ClientManager`, `Reactor`, `DisplayReactor`, errors, token helpers. No React.              |
+| `@ic-reactor/react`       | Hooks, query/mutation factories, `defineReactor`, auth. Re-exports all of core.             |
+| `@ic-reactor/candid`      | Reactors for canisters whose Candid is only known at run time; forms from Candid metadata.  |
+| `@ic-reactor/parser`      | WASM Candid parser: `didToJs`, `didToTs`, `parseDid`, `validateIDL`.                        |
+| `@ic-reactor/vite-plugin` | Generates declarations and hooks from `.did` files in a Vite app; local canister ids.       |
+| `@ic-reactor/cli`         | The `ic-reactor` command: the same generation for non-Vite projects and CI.                 |
+| `@ic-reactor/codegen`     | The generation pipeline behind the CLI and the Vite plugin; apps rarely import it directly. |
+
+## Install
+
+React apps:
+
+```bash
+pnpm add @ic-reactor/react @icp-sdk/core @tanstack/react-query
+```
+
+`@ic-reactor/react` needs `@tanstack/react-query` 5.90.2 or later and React 18
+or later. IC Reactor needs TypeScript 5.7 or later: its declarations, and those
+of `@icp-sdk/core`, use generic typed arrays such as `Uint8Array<ArrayBuffer>`,
+which TypeScript 5.7 introduced. Import the runtime (`ClientManager`,
+`Reactor`, ...) from `@ic-reactor/react` too: with the install above,
+`@ic-reactor/core` is not a direct dependency, and pnpm does not let the app
+import it.
+
+Non-React apps:
+
+```bash
+pnpm add @ic-reactor/core @icp-sdk/core @tanstack/query-core
+```
+
+Internet Identity sign-in (optional; the auth classes ship in
+`@ic-reactor/react`):
+
+```bash
+pnpm add @icp-sdk/auth@^10
+```
+
+The `@icp-sdk/auth` peer is `^8.0.0 || ^10.0.0`. Install v10: it is the first
+release to peer `@icp-sdk/core@^6`, so a strict `npm install` resolves the set
+with no `overrides`. v7 and v9 are not supported; v9 still peers
+`@icp-sdk/core@^5`. On v8, a strict `npm install` fails with `ERESOLVE`
+(stale metadata, not an actual incompatibility). For npm on v8, add to
+`package.json`:
+
+```json
+{ "overrides": { "@icp-sdk/auth": { "@icp-sdk/core": "$@icp-sdk/core" } } }
+```
+
+On v10, four constructor options are dropped with a warning because v10 has
+no equivalent: `storage`, `keyType`, `idleOptions`, `identity`. `targets` on
+`login()` is ignored by v10, so the delegation is NOT restricted to those
+canisters; pin `^8` if you depend on canister-scoped delegations.
+`maxTimeToIdle` on `login()` and `disableBrowserActivity` exist only on v10.
+On v10 a custom `identityProvider` also needs `internetIdentityId`.
+
+Dynamic Candid:
+
+```bash
+pnpm add @ic-reactor/candid @ic-reactor/core @icp-sdk/core @tanstack/query-core
+```
+
+Code generation: `pnpm add -D @ic-reactor/vite-plugin` (Vite) or
+`pnpm add -D @ic-reactor/cli` (anything else; Node.js 22.12 or later).
+
+The snippets below import `canisterId`, `idlFactory` and the `_SERVICE` type
+from `./declarations/backend`, which stands for your canister's declarations.
+`idlFactory` comes from the generated `.js` file and `_SERVICE` from the
+`.d.ts`. With the CLI or the Vite plugin those are
+`src/declarations/<name>/declarations/<did>.js` and `.d.ts`, named after the
+`.did` file; the folder's own `index.ts` exports the generated reactor and
+hooks, not `idlFactory`.
+`canisterId` is the canister's id as text: a constant, or a value from your
+build's environment.
+
+## Choose a Setup
+
+| Your app                                                    | Use                                                                               |
+| ----------------------------------------------------------- | --------------------------------------------------------------------------------- |
+| React SPA, a few canisters                                  | `defineReactor(...)` or `defineDisplayReactor(...)` at module scope               |
+| React SPA, many canisters or a `.did` that changes often    | `@ic-reactor/vite-plugin` (Vite) or `@ic-reactor/cli`, with `factories: true`     |
+| Server-rendered React (Next.js, any SSR)                    | `createReactorProvider(() => defineReactor(...))` in a `"use client"` module      |
+| React Server Component, server action, route handler        | `ClientManager` + `Reactor` built inside the request; `fetchQuery` / `callMethod` |
+| Construction order or dependency injection must be explicit | `ClientManager` + `Reactor` or `DisplayReactor` + `createActorHooks(reactor)`     |
+| No React (Node scripts, other frameworks, workers)          | `@ic-reactor/core`: `ClientManager` + `Reactor`, imperative API                   |
+| Several canisters with one interface (ICRC ledgers)         | one reactor, plus `reactor.forCanister(canisterId)` for each other canister       |
+| Canister interface known only at run time                   | `@ic-reactor/candid`                                                              |
+
+`Reactor` returns raw Candid values; `DisplayReactor` returns values a UI can
+show and a form can send:
+
+| Candid                           | `Reactor`                           | `DisplayReactor`       |
+| -------------------------------- | ----------------------------------- | ---------------------- |
+| `nat`, `int`, `nat64`, `int64`   | `bigint`                            | `string`               |
+| `nat8`..`nat32`, `int8`..`int32` | `number`                            | `number`               |
+| `principal`                      | `Principal`                         | `string`               |
+| `blob`                           | `Uint8Array`                        | hex `string`, no `0x`  |
+| `opt T`                          | `[] \| [T]`                         | `T \| undefined`       |
+| `variant { A: T }`               | `{ A: T }`                          | `{ _type: "A", A: T }` |
+| `variant { A }` (no value)       | `{ A: null }`                       | `{ _type: "A" }`       |
+| `vec record { text; T }`         | `[string, T][]`                     | `{ [key: string]: T }` |
+| `Result` (`Ok`/`Err`)            | Ok value, or throws `CanisterError` | same                   |
+
+`DisplayReactor` adds zod (about 24 kB gzipped). Until the next major,
+`defineReactor` includes it too because of its deprecated `display` flag; the
+smallest setup is `createActorHooks(new Reactor(...))`.
+
+## One-Call Setup
+
+`defineReactor` creates the `QueryClient` (with `reactorRetry` as its query
+retry), the `ClientManager`, the reactor and its hooks in one call.
+`defineDisplayReactor` takes the same options and builds a `DisplayReactor`.
+`defineReactor({ display: true })` is deprecated; never write it. Plain
+`defineReactor` is not deprecated, although typescript-eslint's
+`no-deprecated` also flags references such as `typeof defineReactor`: do not
+switch a raw-value setup to `defineDisplayReactor` to silence it.
+
+```ts
+// src/reactor.ts
+import { defineDisplayReactor } from "@ic-reactor/react"
+import { canisterId, idlFactory, type _SERVICE } from "./declarations/backend"
+
+export const backendApp = defineDisplayReactor<_SERVICE>({
+  name: "backend",
+  idlFactory,
+  // Required unless the Vite plugin injects it on a local replica.
+  canisterId,
+})
+
+export const {
+  reactor: backend,
+  useActorQuery,
+  useActorMutation,
+  useAuth,
+} = backendApp
+```
+
+The result holds the six hooks of `createActorHooks` (`useActorQuery`,
+`useActorSuspenseQuery`, `useActorInfiniteQuery`,
+`useActorSuspenseInfiniteQuery`, `useActorMutation`, `useActorMethod`),
+`useAuth`, `useAgentState`, `useUserPrincipal`, `useIdentityAttributes`, and
+`reactor`, `clientManager`, `queryClient`, `authentication` and
+`identityAttributes`. `authentication` and `identityAttributes` are lazy
+getters, so the optional `@icp-sdk/auth` peer loads only once auth is used.
+Without the peer the app still builds; webpack-family bundlers print one
+`Module not found` warning for it, silenced with
+`ignoreWarnings: [{ module: /@ic-reactor\/react/, message: /@icp-sdk\/auth/ }]`.
+
+Without `canisterId`, the reactor reads `PUBLIC_CANISTER_ID:<name>` from the
+`ic_env` cookie, which `ClientManager` trusts only on a local replica
+(loopback and `localhost` hosts) unless `allowEnvConfig: true` is passed. On a
+server or a deployed origin the constructor then throws
+`canisterId is required for "backend"`.
+
+A second canister shares the agent and the Internet Identity session when it
+gets the first result's `authentication`:
+
+```ts
+// src/ledger.ts
+import { defineReactor } from "@ic-reactor/react"
+import {
+  canisterId as ledgerId,
+  idlFactory as ledgerIdl,
+  type _SERVICE as Ledger,
+} from "./declarations/ledger"
+import { backendApp } from "./reactor"
+
+export const ledgerApp = defineReactor<Ledger>({
+  name: "ledger",
+  idlFactory: ledgerIdl,
+  canisterId: ledgerId,
+  authentication: backendApp.authentication,
+})
+export const ledger = ledgerApp.reactor
+```
+
+Passing `authentication` alone is enough; its `clientManager` is adopted.
+Passing a different `clientManager` alongside it throws, because sign-in would
+update one agent while the reactor calls through another. Do not build a
+second `AuthenticationManager` for the same app.
+
+## Manual Setup
+
+Use this when construction order must be explicit:
+
+```ts
+// src/manual.ts
+import {
+  ClientManager,
+  DisplayReactor,
+  createActorHooks,
+  reactorRetry,
+} from "@ic-reactor/react"
+import { QueryClient } from "@tanstack/react-query"
+import { canisterId, idlFactory, type _SERVICE } from "./declarations/backend"
+
+export const queryClient = new QueryClient({
+  defaultOptions: { queries: { retry: reactorRetry } },
+})
+export const clientManager = new ClientManager({ queryClient })
+
+export const backend = new DisplayReactor<_SERVICE>({
+  clientManager,
+  idlFactory,
+  name: "backend",
+  canisterId,
+})
+
+export const { useActorQuery, useActorMutation } = createActorHooks(backend)
+```
+
+Keep the `<_SERVICE>` type argument: without it every argument and result is
+`unknown` (`any` on an untyped `Reactor`). A `QueryClient` you create keeps
+TanStack's defaults unless you set `retry: reactorRetry` as above. The hooks
+bind to the reactor's own `QueryClient`; a `QueryClientProvider` is optional.
+
+## Queries and Mutations in Components
+
+```tsx
+import { skipToken } from "@ic-reactor/react"
+import { useActorMutation, useActorQuery } from "./reactor"
+
+export function ProfileCard({ userId }: { userId?: string }) {
+  const { data, isPending, error } = useActorQuery({
+    functionName: "get_profile",
+    // No call until the id exists; never `[userId!]`
+    args: userId ? [userId] : skipToken,
+  })
+  const rename = useActorMutation({
+    functionName: "update_profile",
+    // Refetch every get_profile query of this canister once it succeeds
+    invalidateQueries: [{ functionName: "get_profile" }],
+    // The canister returned Err: err.code is the variant name
+    onCanisterError: (err) => alert(`Not saved: ${err.code}`),
+  })
+
+  if (!userId) return <p>Sign in first</p>
+  if (isPending) return <p>Loading…</p>
+  if (error) return <p>{error.message}</p>
+  return (
+    <button
+      disabled={rename.isPending}
+      onClick={() => rename.mutate([{ name: "Ada" }])}
+    >
+      {data.name}: {data.likes} likes
+    </button>
+  )
+}
+```
+
+- `args` is always the method's argument tuple (`[userId]`, `[]` or omitted
+  for no arguments), in the reactor's form (display strings above).
+- `data` is the `Ok` payload of a `Result`: an `Err` becomes a `CanisterError`
+  in `error`, so never write `"Ok" in data`.
+- A query hook takes TanStack's options too (`select`, `staleTime`,
+  `refetchInterval`, `enabled`, ...) and `callConfig` (`canisterId`, `agent`,
+  `effectiveCanisterId`) for one call.
+- `skipToken` works in `useActorQuery`, `useActorInfiniteQuery` (as
+  `getArgs: owner ? (page) => [...] : skipToken`) and `createQueryFactory`.
+  The suspense hooks, `createQuery` and `createSuspenseQuery` do not take it.
+  Keep `enabled` for conditions that are not about missing args. Never call
+  `refetch()` on a skipped query.
+- Call state-changing update methods only through `useActorMutation`,
+  `useActorMethod` or `createMutation`. A query hook or factory runs its method
+  again on every refetch (mount, window focus, reconnect, invalidation), and
+  each run of an update executes on the canister. A query of an update method
+  is fine only when repeating it is safe (a certified read).
+- `useActorMethod` handles a query or an update method with one hook and an
+  imperative `call()`; use it only when that unified shape helps.
+
+## Reusable Query and Mutation Objects
+
+Define query and mutation objects once and use them in components, loaders,
+actions and tests. In a client-only app they live at module scope; in a
+server-rendered app build them inside the `createReactorProvider` factory.
+
+```ts
+// src/queries.ts
+import {
+  createMutation,
+  createQuery,
+  createQueryFactory,
+} from "@ic-reactor/react"
+import { backend } from "./reactor"
+
+export const postsQuery = createQuery(backend, { functionName: "get_posts" })
+export const getPost = createQueryFactory(backend, { functionName: "get_post" })
+
+export const createPost = createMutation(backend, {
+  functionName: "create_post",
+  invalidateQueries: [postsQuery, { functionName: "get_posts_count" }],
+})
+export const likePost = createMutation(backend, { functionName: "like_post" })
+```
+
+| Need                           | Use                                                                          |
+| ------------------------------ | ---------------------------------------------------------------------------- |
+| A query method without args    | `createQuery` (or `createSuspenseQuery`)                                     |
+| A query method whose args vary | `createQueryFactory` (or `createSuspenseQueryFactory`), called with the args |
+| Paginated reads                | `createInfiniteQuery`, `createSuspenseInfiniteQuery` (and their factories)   |
+| An update method               | `createMutation`                                                             |
+
+Inside React: `postsQuery.useQuery()`, `getPost([id]).useQuery()`,
+`createPost.useMutation(options)`; `.useSuspenseQuery()`,
+`.useInfiniteQuery()` and `.useSuspenseInfiniteQuery()` on the other kinds.
+
+Outside React:
+
+```ts
+import { createPost, getPost, postsQuery } from "./queries"
+
+export function postLoader(postId: string) {
+  // Cached and deduplicated; refetches as the new principal after a sign-in
+  return getPost([postId]).fetch()
+}
+
+export function createPostAction(title: string) {
+  // Resolves with the Ok payload after the factory's invalidateQueries ran;
+  // an Err rejects with a CanisterError
+  return createPost.execute([title])
+}
+
+export function refreshPosts() {
+  return postsQuery.invalidate() // resolves once mounted queries refetched
+}
+```
+
+A query object also has `.prefetch()`, `.getCacheData()`, `.setData()`,
+`.getQueryKey()`, `.cancel()`, `.reset()` and `.optimisticUpdate()`
+(`.prefetch()` and `.setData()` are not on infinite query objects). A query
+factory function has `getQueryKey()` (the prefix of all its queries) and
+`invalidate()`. `createQuery`, `createSuspenseQuery` and the query factories
+take `callConfig` as the hooks do:
+`createQuery(ledger, { functionName: "icrc1_symbol", callConfig: { canisterId: ckbtcId } })`.
+
+Paginated reads take TanStack's `initialPageParam` and `getNextPageParam`,
+plus `getArgs`, which turns a page param into the method's argument tuple:
+
+```ts
+import { createInfiniteQuery } from "@ic-reactor/react"
+import { backend } from "./reactor"
+
+// list_posts : (record { offset : nat; limit : nat })
+//   -> (record { posts : vec Post; next : opt nat }) query
+export const postPages = createInfiniteQuery(backend, {
+  functionName: "list_posts",
+  initialPageParam: "0", // a DisplayReactor takes a nat as text
+  getArgs: (offset) => [{ offset, limit: "20" }] as const,
+  getNextPageParam: (lastPage) => lastPage.next, // undefined: no next page
+})
+
+// In a component:
+//   const { data, fetchNextPage, hasNextPage } = postPages.useInfiniteQuery()
+//   const posts = data?.pages.flatMap((page) => page.posts) ?? []
+// In a loader: await postPages.fetch()
+```
+
+Keep `as const` on what `getArgs` returns: without it the args are inferred
+as an array rather than a tuple, and `createInfiniteQuery` rejects them.
+`useActorInfiniteQuery` takes the same fields.
+
+## Cache Invalidation and Optimistic Updates
+
+A mutation's `invalidateQueries` (on `createMutation`, `.useMutation()`,
+`useActorMutation` and `useActorMethod`) takes, per entry:
+
+- a query object: `[postsQuery]`;
+- a query factory, covering every args instance: `[getPost]`;
+- a method of the mutation's own reactor, type-checked:
+  `{ functionName: "get_post" }` for every query of the method, or
+  `{ functionName: "get_post", args: [id] }` for one. It is keyed at the
+  canister the mutation was sent to.
+
+The invalidation is awaited before `onSuccess`, so `onSuccess` reads fresh
+data. Never hand-write a key such as `["get_posts"]`: every key starts with
+the canister id, so it matches nothing. A key is the canister id and the
+method name, then segments for a non-default transform (a `DisplayReactor`),
+another agent or effective target given in `callConfig`, and the args. Build
+one with `reactor.generateQueryKey(...)` or `query.getQueryKey()` if you need
+it, and never add the canister id to a `queryKey` yourself.
+
+`query.invalidate()`, a factory's `invalidate()` and
+`reactor.invalidateQueries(...)` return a `Promise` that resolves once the
+active matches have refetched (a failed refetch does not reject it). Prefix a
+call you do not wait for with `void`.
+
+For optimistic UI, return the query's `optimisticUpdate(updater)` from
+`onMutate`, roll back in `onError`, and invalidate in `onSettled`:
+
+```tsx
+import { getPost, likePost } from "./queries"
+
+export function LikeButton({ postId }: { postId: string }) {
+  const { data: post } = getPost([postId]).useQuery()
+  const like = likePost.useMutation({
+    // Show the new count at once; undo it if the call fails
+    onMutate: ([id]) =>
+      getPost([id]).optimisticUpdate((cached) => ({
+        ...cached,
+        likes: (BigInt(cached.likes) + 1n).toString(),
+      })),
+    onError: (_error, _args, update) => update?.rollback(),
+    onSettled: (_data, _error, [id]) => getPost([id]).invalidate(),
+  })
+  return (
+    <button onClick={() => like.mutate([postId])}>
+      {post?.title}: {post?.likes}
+    </button>
+  )
+}
+```
+
+The updater gets the cached raw (pre-`select`) value and is skipped when
+nothing is cached. `rollback()` does nothing after a sign-in or sign-out,
+since the snapshot was the previous principal's. Do not hand-roll
+`cancelQueries` / `setQueryData` snapshots. When you need the `QueryClient`
+itself, use `reactor.queryClient`; `useQueryClient()` throws without a
+`QueryClientProvider`.
+
+## Inside React vs Outside React
+
+Only call hooks inside React components or custom hooks: `useActorQuery`,
+`useActorMutation`, `useActorMethod`, `useAuth`, `.useQuery()`,
+`.useMutation()`, `.useSuspenseQuery()`, `.useInfiniteQuery()`. Loaders,
+actions, services, scripts and non-hook tests use:
+
+- query objects: `.fetch()`, `.prefetch()`, `.invalidate()`,
+  `.getCacheData()`, `.setData()`, `.cancel()`, `.reset()`,
+  `.optimisticUpdate()`
+- mutation objects: `.execute(args)`
+- reactors: `.fetchQuery()`, `.getQueryData()`, `.invalidateQueries()`,
+  `.callMethod()`
+
+`query.fetch()` and `reactor.fetchQuery()` fetch again, at most three times,
+when a sign-in or sign-out switches the principal mid-fetch (after that they
+reject with a `CallError`). Wrap a fetch you write against the `QueryClient`
+yourself (`queryClient.fetchQuery`, `fetchInfiniteQuery`, `ensureQueryData`) in
+`clientManager.fetchAcrossIdentitySwitch(() => ...)`: unwrapped, a switch can
+resolve it with the previous principal's cached data. A query object's
+`.prefetch()` fetches again the same way and never rejects, and a query
+method's `call()` and `refetch()` from `useActorMethod` resolve with the new
+principal's answer (`undefined` if that fetch fails). Loaders and services
+still use `query.fetch()` or `reactor.fetchQuery()`: hooks belong in
+components.
+
+## Several Canisters of One Interface
+
+For a multi-token wallet, build one reactor and derive the others:
+`reactor.forCanister(canisterId)` returns a memoized sibling of the same class
+on the same `ClientManager`, with the same interface and validators, whose
+calls and query keys use its own canister. The same id always gives the same
+object, so it is safe in render and in `useMemo` dependencies. A single query
+can instead take `callConfig: { canisterId }`.
+
+```tsx
+import { useMemo } from "react"
+import {
+  createActorHooks,
+  formatTokenAmount,
+  type ReactorArgsOf,
+} from "@ic-reactor/react"
+import { ledger } from "./ledger"
+
+type Account = ReactorArgsOf<typeof ledger, "icrc1_balance_of">[0]
+
+export function Balance({
+  tokenId,
+  account,
+}: {
+  tokenId: string
+  account: Account
+}) {
+  const token = useMemo(
+    () => createActorHooks(ledger.forCanister(tokenId)),
+    [tokenId]
+  )
+  const { data: balance } = token.useActorQuery({
+    functionName: "icrc1_balance_of",
+    args: [account],
+  })
+  const { data: decimals } = token.useActorQuery({
+    functionName: "icrc1_decimals",
+  })
+  if (balance === undefined || decimals === undefined) return null
+  return (
+    <span>
+      {formatTokenAmount(balance, decimals, { maxFractionDigits: 4 })}
+    </span>
+  )
+}
+```
+
+Do not retarget a shared reactor with `setCanisterId`, and do not build one
+reactor per canister by hand.
+
+## Types From a Reactor
+
+Read types off the reactor instead of copying shapes:
+
+- `ReactorArgsOf<typeof ledger, "icrc1_transfer">[0]`: the first argument in
+  the reactor's form (raw or display)
+- `ReactorDataOf<typeof ledger, "icrc1_transfer">`: what `callMethod`, a
+  mutation and `execute()` resolve with
+- `ReactorErrorOf<typeof ledger, "icrc1_transfer">`: a hook's `error` type
+- `ServiceOf<typeof ledger>`, `TransformOf<typeof ledger>`
+
+They take a reactor instance's type (any `Reactor`, `DisplayReactor` or
+subclass), not a query or mutation object.
+
+## Token Amounts and Principals
+
+Ledger amounts are base units (e8s for ICP): a `bigint` from a `Reactor`,
+integer text from a `DisplayReactor`. Never convert them with `Number`,
+`parseFloat`, `Math.pow` or `toFixed`: `Math.floor(Number("0.29") * 10 ** 8)`
+is 28999999.
+
+```ts
+import { isPrincipalText, parseTokenAmount } from "@ic-reactor/react"
+import { Principal } from "@icp-sdk/core/principal"
+import { ledger } from "./ledger"
+
+export async function send(to: string, text: string, decimals: number) {
+  if (!isPrincipalText(to.trim())) throw new Error("Not a principal")
+  const amount = parseTokenAmount(text, decimals) // "0.29", 8 -> 29000000n
+  return ledger.callMethod({
+    functionName: "icrc1_transfer",
+    args: [
+      {
+        to: { owner: Principal.fromText(to.trim()), subaccount: [] },
+        amount,
+        fee: [],
+        memo: [],
+        from_subaccount: [],
+        created_at_time: [],
+      },
+    ],
+  })
+}
+```
+
+- `formatTokenAmount(value, decimals, options?)` takes the value and
+  `icrc1_decimals` as a query returns them. Options: `maxFractionDigits`,
+  `minFractionDigits`, `trimTrailingZeros`, `roundingMode`, `locale`,
+  `useGrouping`. It truncates past `maxFractionDigits` unless
+  `roundingMode: "halfExpand"`, and writes plain text (`"1234.5"`) unless given
+  a `locale`.
+- `parseTokenAmount(text, decimals)` returns a `bigint`. It throws a
+  `TypeError` for text that is not digits with at most one `.` and a
+  `RangeError` for more fraction digits than the token has or a negative
+  amount (`{ allowNegative: true }` for an `int`). Send `amount.toString()` to
+  a `DisplayReactor`.
+- `isPrincipalText(text.trim())` validates typed principal text; do not wrap
+  `Principal.fromText` in a `try`. A `DisplayReactor` takes the text, a
+  `Reactor` takes `Principal.fromText(text)`.
+- `jsonToString(value)` prints a raw result, with bigints as digits,
+  principals as text and blobs as hex.
+
+All four are plain functions in core, re-exported by `@ic-reactor/react` and by
+its `react-server` entry.
+
+## Server Rendering (SSR and RSC)
+
+A reactor owns its `QueryClient`, and query keys carry no caller principal. A
+reactor at module scope on a server is therefore one cache shared by every
+request, and a caller-scoped result (`get_my_profile`, a balance of self) is
+served to the next visitor. `AuthenticationManager` signs in on its
+`ClientManager`'s agent, so it belongs in the same request as that manager.
+Build the reactor, `ClientManager`, `AuthenticationManager` and any query or
+mutation objects inside the request. A bare `defineReactor(...)` in a module
+body is still module scope.
+
+Client components in a server-rendered app use `createReactorProvider`:
+
+```tsx
+"use client"
+import {
+  createReactorProvider,
+  defineReactor,
+  skipToken,
+} from "@ic-reactor/react"
+import { canisterId, idlFactory, type _SERVICE } from "../declarations/backend"
+
+// The factory runs once per mounted provider: once per request on a server
+export const { ReactorProvider, useReactor } = createReactorProvider(() =>
+  defineReactor<_SERVICE>({ name: "backend", idlFactory, canisterId })
+)
+
+// app/layout.tsx (a Server Component) wraps the app:
+//   <ReactorProvider>{children}</ReactorProvider>
+
+export function MyProfile() {
+  const { useActorQuery, useAuth } = useReactor()
+  const { isAuthenticated, isAuthenticating, login } = useAuth()
+  const { data } = useActorQuery({
+    functionName: "get_my_profile",
+    args: isAuthenticated ? [] : skipToken,
+  })
+  // true until the stored session has been checked, and in every server render
+  if (isAuthenticating) return <p>Checking session…</p>
+  if (!isAuthenticated)
+    return <button onClick={() => void login()}>Sign in</button>
+  return <h1>{data?.name}</h1>
+}
+```
+
+- `ReactorProvider` and `useReactor` are what the app destructures, not
+  package exports. Call `createReactorProvider` at module scope, never inside a
+  component, and take hooks from `useReactor()` rather than calling
+  `createActorHooks` or `createAuthHooks` in a component.
+- The factory may return a record (`{ backend, ledger, posts }`, with query
+  objects built inside it), read with `useReactor("ledger")`. `useReactor()` is
+  typed as the factory's return: never write `as any` hook forwarders.
+- The factory receives the provider's props other than `children`, read once
+  per mount; give the provider a new `key` to build again.
+- On unmount the provider disposes the `AuthenticationManager`s built for its
+  value and leaves managers built elsewhere alone. When the value holds
+  exactly one `QueryClient` (every reactor in it built on one
+  `ClientManager`, as passing `authentication` on does), it renders a
+  `QueryClientProvider` for it, so `useQueryClient()` and `HydrationBoundary`
+  below it use the cache the hooks fill; pass `{ queryClientProvider: false }`
+  to keep your own.
+- A provider mounted by a transition (router navigation, `startTransition`)
+  needs a `<Suspense>` boundary inside it around suspending components.
+
+A React Server Component, server action or route handler imports the core
+runtime from `@ic-reactor/react`: its `react-server` export condition resolves
+to an entry that loads no React.
+
+```tsx
+// app/Supply.tsx: a React Server Component
+import { ClientManager, Reactor, formatTokenAmount } from "@ic-reactor/react"
+import { QueryClient } from "@tanstack/react-query"
+import { canisterId, idlFactory, type _SERVICE } from "../declarations/ledger"
+
+export default async function Supply() {
+  // Built inside the request: a module-scope reactor would share its cache
+  // with every visitor
+  const clientManager = new ClientManager({
+    queryClient: new QueryClient(),
+    agentOptions: { host: "https://ic0.app" },
+  })
+  const ledger = new Reactor<_SERVICE>({
+    name: "ledger",
+    clientManager,
+    idlFactory,
+    canisterId,
+  })
+  const [supply, decimals] = await Promise.all([
+    ledger.fetchQuery({ functionName: "icrc1_total_supply" }),
+    ledger.fetchQuery({ functionName: "icrc1_decimals" }),
+  ])
+  return <p>{formatTokenAmount(supply, decimals, { maxFractionDigits: 0 })}</p>
+}
+```
+
+Hooks, `defineReactor`, `defineDisplayReactor`, `createReactorProvider`,
+`createActorHooks`, the query/mutation factories, `skipToken`, the auth classes
+and the identity-attribute helpers are missing exports in the `react-server`
+graph (`next build`: "Export X doesn't exist in target module"). When the RSC
+bundler ignores the `react-server` condition, add `@ic-reactor/core` as a
+dependency and import the runtime from it instead. Generated canister modules
+(hooks and `factories: true` objects) import hooks, so a server component must
+not import them.
+
+Module scope stays correct in client-only apps.
+
+## Authentication
+
+`defineReactor` already returns `useAuth`, `useAgentState`,
+`useUserPrincipal`, `useIdentityAttributes`, `authentication` and
+`identityAttributes`. With a manual setup:
+
+```ts
+import {
+  AuthenticationManager,
+  IdentityAttributesManager,
+  createAuthHooks,
+  createIdentityAttributeHooks,
+  hexToUint8Array,
+} from "@ic-reactor/react"
+import { backend, clientManager } from "./manual"
+
+export const authentication = new AuthenticationManager({ clientManager })
+export const { useAuth, useAgentState, useUserPrincipal } =
+  createAuthHooks(authentication)
+
+export const identityAttributes = new IdentityAttributesManager(authentication)
+export const { useIdentityAttributes } =
+  createIdentityAttributeHooks(identityAttributes)
+
+// In a click handler: pass the nonce as a callback so the popup opens within
+// the user gesture. A DisplayReactor returns a blob as hex.
+export const requestEmail = () =>
+  identityAttributes.request({
+    keys: ["email"],
+    nonce: async () =>
+      hexToUint8Array(
+        await backend.callMethod({ functionName: "register_begin" })
+      ),
+  })
+```
+
+- `createAuthHooks` takes an `AuthenticationManager`, never a `ClientManager`,
+  and returns exactly `useAuth`, `useAgentState` and `useUserPrincipal`.
+  `useIdentityAttributes` comes only from `createIdentityAttributeHooks`.
+- `useAuth()` returns `login`, `logout`, `authenticate`, `isAuthenticated`,
+  `isAuthenticating`, `principal`, `identity` and `error`. Read the principal
+  from it (or `useUserPrincipal()`), not from `identity.getPrincipal()` in
+  your own state.
+- `useAuth()` reports `isAuthenticating: true` from the first render, and in
+  every server render, until the first session restore settles (a failed
+  restore counts as settled). Guard a protected route with
+  `if (isAuthenticating)` before `if (!isAuthenticated)`.
+- Awaiting a nonce before `request()` ends the user gesture, and the browser
+  blocks the Internet Identity window; pass the nonce as a callback. With a raw
+  `Reactor`, the blob is already a `Uint8Array`:
+  `nonce: () => backend.callMethod({ ... })`.
+- `authentication.dispose()` releases the auth client the manager built. It
+  does not sign out, and a later `login()` builds a new client, so it is safe
+  in a StrictMode effect cleanup. `createReactorProvider` calls it for you.
+- On `@icp-sdk/auth` v10 a manager follows sign-outs and account switches made
+  in other tabs.
+- A sign-in, sign-out or account switch cancels the fetches in flight of
+  every canister the `ClientManager` has a reactor for, removes their inactive
+  cache entries and refetches mounted queries as the new principal. A renewed
+  delegation for the same principal keeps the cache.
+
+Local Internet Identity:
+`localInternetIdentityProvider(port, canisterId?, authorizePath?)` builds
+`http://<canisterId>.localhost:<port>/authorize`, and
+`authentication.prepareClient()` probes the canister for `/authorize` or the
+legacy `/#authorize`. Only Internet Identity builds up to `release-2026-03-16`
+serve a local frontend; a login that hangs on the gateway's "Response
+Verification Error" page is an unsupported build.
+
+## Errors and Retries
+
+| Error             | Source                                                      | Handle with                                                      |
+| ----------------- | ----------------------------------------------------------- | ---------------------------------------------------------------- |
+| `CanisterError`   | the canister returned `Err`                                 | `onCanisterError` on mutations, `isCanisterError(e)` elsewhere   |
+| `CallError`       | network, agent, certificate, a trap, a validator that threw | `onError`, `isCallError(e)`                                      |
+| `ValidationError` | a `DisplayReactor` validator refused the arguments          | `isValidationError(e)`, `mapValidationErrors(e)` for form fields |
+
+```ts
+import {
+  isCallError,
+  isCanisterError,
+  isValidationError,
+} from "@ic-reactor/react"
+import { backend } from "./reactor"
+
+export async function rename(name: string) {
+  try {
+    return await backend.callMethod({
+      functionName: "update_profile",
+      args: [{ name }],
+    })
+  } catch (error) {
+    if (isCanisterError(error)) {
+      // The canister's Err value: error.err, variant name: error.code
+      return `Refused: ${error.code}`
+    }
+    if (isValidationError(error)) return `Invalid: ${error.message}`
+    if (isCallError(error)) return `Network or agent failure: ${error.message}`
+    throw error
+  }
+}
+```
+
+`CanisterError` carries the canister's error value on `.err`, not `.detail`,
+`.data` or `.message`. `.code` is the variant key, or the `code` field when the
+payload has the API shape (`code`, `message`, `details`). `.details` is that
+payload's `details` field as decoded, never a `Map`. The guards also recognise
+errors from another copy of the package; prefer them to `instanceof`.
+
+Retries:
+
+- `reactorRetry` (predicate `isRetryableReactorError`) is the query retry of
+  the `QueryClient` that `defineReactor` and `defineDisplayReactor` create. In
+  a browser it retries transport, certificate, HTTP 5xx/408/429 and
+  `SysTransient`/`SysUnknown` failures up to 3 times, and never a
+  `CanisterError`, a `ValidationError`, an encode/decode failure or another
+  HTTP 4xx (an expired delegation's 400, a 403).
+- A query of an update method with no `retry` of its own retries only a
+  `SysTransient` rejection, within the `QueryClient`'s retry default.
+- Mutations retry nothing unless `retry` is set on them or as the
+  `QueryClient`'s `mutations.retry` default, which also reaches
+  `createMutation().execute()` and `useActorMethod` update calls. Each retry
+  of an update is a new call the canister runs, so use
+  `retry: reactorUpdateRetry` (predicate `isRetryableUpdateError`), which
+  retries only `SysTransient`, never a number.
+- `reactorRetry` and `reactorUpdateRetry` return `false` wherever there is no
+  `window` (Node scripts, server rendering, web workers), as TanStack Query
+  retries nothing on a server by default; the agent still resends a failed
+  HTTP request itself (3 times by default). For query retries in a Node
+  script, pass the predicate:
+  `retry: (count, error) => count < 3 && isRetryableReactorError(error)`.
+
+## Code Generation
+
+Use generated code when there are many canisters, `.did` files change often,
+or you want consistent typed exports.
+
+| Tool                      | Use when                                                              |
+| ------------------------- | --------------------------------------------------------------------- |
+| `@ic-reactor/vite-plugin` | Vite app: generates on start and on `.did` changes, injects local ids |
+| `@ic-reactor/cli`         | Any other project, CI, or explicit `ic-reactor generate` runs         |
+| `@ic-reactor/codegen`     | Custom tooling only (`runCanisterPipeline`)                           |
+
+```ts
+// vite.config.ts
+import { defineConfig, loadEnv } from "vite"
+import { icReactor } from "@ic-reactor/vite-plugin"
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), "")
+  return {
+    plugins: [
+      icReactor({
+        canisters: [
+          {
+            name: "backend",
+            didFile: "./backend/backend.did",
+            factories: true,
+            // Written into the generated reactor, and used under `vite dev`
+            // too in place of the local id: set it per environment
+            canisterId: env.CANISTER_ID_BACKEND,
+          },
+        ],
+      }),
+    ],
+  }
+})
+```
+
+The CLI reads the same per-canister fields from `ic-reactor.json`
+(`pnpm exec ic-reactor init`, then `pnpm exec ic-reactor generate`). Each
+canister's output directory holds:
+
+- `declarations/`: the IDL factory and `_SERVICE` types;
+- `index.generated.ts` (managed, rewritten on every run): the reactor
+  (`backendReactor`, a `DisplayReactor` unless `mode` names another class) and
+  six bound hooks named after the canister (`useBackendQuery`,
+  `useBackendMutation`, ...);
+- `index.factories.generated.ts` (managed, only with `factories: true` and
+  `target: "react"`): a `<method>Query` per query method (`createQuery`, or
+  `createQueryFactory` when it takes args) and a `<method>Mutation`
+  (`createMutation`) per update or oneway method, each `/* @__PURE__ */` so
+  unused ones are tree-shaken;
+- `index.ts` (created once, yours to edit): re-exports `index.generated.ts`,
+  and the factories file with `factories: true`. Put custom factories,
+  invalidation wiring and helpers here; an export with the same name replaces
+  the generated one.
+
+Never edit the managed files. Prefer `factories: true` over hand-written
+per-method factory modules. The generated modules are module scope, so they
+are client-only; on a server build the reactor per request. Without
+`canisterId`, the generated reactor reads its id from the `ic_env` cookie,
+which works only on a local replica (or with `allowEnvConfig: true`), so
+importing it throws `canisterId is required` in Node, during SSR and on a
+deployed origin.
+
+## Dynamic Candid and the Parser
+
+Use `@ic-reactor/candid` for explorers, dev tools and forms over canisters
+whose interface is known only at run time: `CandidAdapter` fetches and parses
+Candid, `CandidReactor` / `CandidDisplayReactor` call it dynamically, and
+`MetadataReactor` / `MetadataDisplayReactor` produce form and result metadata.
+`forCanister` works on all four. `@ic-reactor/parser` is a dependency of
+candid and loads on first parse. To parse Candid yourself, import it from its
+single entrypoint:
+
+```ts
+import init, { didToJs, parseDid, validateIDL } from "@ic-reactor/parser"
+
+await init() // required on the web build (browsers, bundlers); a no-op on Node
+const schema = parseDid("service : { greet : (text) -> (text) query }")
+console.log(schema.service?.methods) // [{ name: "greet", mode: "query", ... }]
+```
+
+There are no `/web`, `/nodejs` or `/bundler` subpaths; conditional exports pick
+the browser or Node build. Do not deep-import `dist/`. `validateIDL` throws the
+parser's message for invalid Candid instead of returning `false`, and
+`didToJs` / `didToTs` return source strings.
+
+## Testing
+
+Run the real reactor and hooks against the fake replica from
+`@ic-reactor/react/testing` (`@ic-reactor/core/testing` without React). Do not
+stub a reactor with `as unknown as Reactor`, and do not hard-code query keys in
+tests.
+
+```ts
+import { afterEach, beforeEach, expect, it } from "vitest"
+import { QueryClient } from "@tanstack/react-query"
+import { ClientManager, Reactor, isCanisterError } from "@ic-reactor/react"
+import {
+  createTestCanister,
+  installFakeReplica,
+  type FakeReplica,
+} from "@ic-reactor/react/testing"
+import { canisterId, idlFactory, type _SERVICE } from "./declarations/backend"
+
+let replica: FakeReplica
+let backend: Reactor<_SERVICE>
+
+beforeEach(() => {
+  // Install the fake before any ClientManager or agent is built
+  replica = installFakeReplica({
+    canisters: {
+      [canisterId]: createTestCanister<_SERVICE>(idlFactory, {
+        // Handlers get the decoded args and { caller } and return raw Candid
+        greet: ([name]) => `Hello, ${name}!`,
+        update_profile: () => ({ Err: { NotFound: null } }),
+      }),
+    },
+  })
+  backend = new Reactor<_SERVICE>({
+    clientManager: new ClientManager({
+      queryClient: new QueryClient(),
+      agentOptions: { host: replica.host },
+    }),
+    name: "backend",
+    canisterId,
+    idlFactory,
+  })
+})
+afterEach(() => replica.restore())
+
+it("greets", async () => {
+  await expect(
+    backend.fetchQuery({ functionName: "greet", args: ["Ada"] })
+  ).resolves.toBe("Hello, Ada!")
+})
+
+it("turns an Err into a CanisterError", async () => {
+  const error = await backend
+    .callMethod({ functionName: "update_profile", args: [{ name: "" }] })
+    .catch((e: unknown) => e)
+  expect(isCanisterError(error) && error.code).toBe("NotFound")
+})
+```
+
+- A handler returns `{ Err: ... }` for a `CanisterError`, and throws for the
+  `CallError` of a trap.
+- For a module-scope `defineReactor(...)`, install the fake at the top of the
+  test file (or in a setup file) and `await import(...)` the components after
+  it. With no `host` on either side, both use the page origin in jsdom or
+  happy-dom. Reset a shared reactor between tests with `queryClient.clear()`.
+- Generated code is module scope too: its entry imports your `clientManager`.
+  Import `idlFactory` and `_SERVICE` from the canister's `declarations/`
+  folder (it builds nothing), key the fake by the `canisterId` the generator
+  wrote into `index.generated.ts`, and `await import(...)` the entry and the
+  components after the fake. Vitest runs `vite.config.ts` (unless a
+  `vitest.config.ts` replaces it), so the Vite plugin generates again in mode
+  `test`: set the variable a `loadEnv` `canisterId` comes from in
+  `.env.test`, or importing the regenerated entry throws
+  `canisterId is required`.
+- Test a signed-in user with `clientManager.updateAgent(identity)`, for
+  example `Ed25519KeyIdentity.generate()`; the kit does not simulate Internet
+  Identity.
+- The kit signs with `@noble/curves`, an optional peer that `@icp-sdk/core`
+  already installs; add it as a devDependency under a strict install.
+
+## Do Not
+
+- Call hooks in loaders, actions, services or scripts.
+- Create hooks (`createActorHooks`, `createAuthHooks`) on every render: build
+  them at module scope, in a `useMemo` keyed by what they depend on, or take
+  them from `useReactor()`.
+- Put a state-changing update method in a query hook or query factory
+  (`useActorQuery`, `createQuery`, `createQueryFactory`, the infinite and
+  suspense variants); use a mutation.
+- Give an update mutation, `useActorMethod` or a `mutations.retry` default a
+  numeric `retry`; use `retry: reactorUpdateRetry`.
+- Hand-write query keys (`["get_posts"]`) or add the canister id to a
+  `queryKey`; pass query objects, query factories or
+  `{ functionName, args? }` to `invalidateQueries`.
+- Write `args: [userId!]`, placeholder args, or `as any` plus `enabled` for
+  args not known yet; pass `skipToken`.
+- Check `"Ok" in data`: a `Result` is already unwrapped, and an `Err` throws.
+- Do token math with `Number(x) / 10 ** decimals`, `parseFloat`, `Math.pow` or
+  `toFixed`; use `formatTokenAmount` / `parseTokenAmount`.
+- Retarget a shared reactor with `setCanisterId`; use
+  `reactor.forCanister(canisterId)`.
+- Write `defineReactor({ display: true })`; use `defineDisplayReactor`.
+- Build a reactor, `ClientManager` or `AuthenticationManager` at module scope
+  in a server-rendered app, or import hooks into a server component.
+- Pass a `ClientManager` to `createAuthHooks`, or build a second
+  `AuthenticationManager` instead of passing `authentication` on.
+- Use `useQueryClient()` for cache writes, or hand-roll `setQueryData`
+  snapshots for optimistic UI; use `reactor.queryClient` and
+  `optimisticUpdate`.
+- Stub a `Reactor` with `as unknown as Reactor` in tests.
+- Edit `index.generated.ts` or `index.factories.generated.ts`, or repeat
+  per-method factories that `factories: true` generates.
+- Leave out the `<_SERVICE>` type argument, or cast hooks to `any`.
+
+## Links
+
+- Documentation: https://ic-reactor.b3pay.net/v3/
+- Index for agents: https://ic-reactor.b3pay.net/llms.txt
+- Changelog: https://github.com/B3Pay/ic-reactor/blob/main/CHANGELOG.md
+- Agent skill: https://github.com/B3Pay/ic-reactor/tree/main/skill-packages/ic-reactor
+- React setup: https://ic-reactor.b3pay.net/v3/framework/react-setup.md
+- Queries: https://ic-reactor.b3pay.net/v3/framework/queries.md
+- Mutations: https://ic-reactor.b3pay.net/v3/framework/mutations.md
+- Authentication: https://ic-reactor.b3pay.net/v3/guides/authentication.md
+- Error handling: https://ic-reactor.b3pay.net/v3/guides/error-handling.md
+- Testing: https://ic-reactor.b3pay.net/v3/guides/testing.md
+- createReactorProvider: https://ic-reactor.b3pay.net/v3/reference/createReactorProvider.md
+- Next.js App Router example: https://ic-reactor.b3pay.net/v3/examples/nextjs-app-router.md