@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/icrc-ledger/src/transfer-form.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest"
+import { SEED_2 } from "./sandbox.ts"
+import { readTransferForm, type TransferForm } from "./transfer-form.ts"
+
+const form = (overrides: Partial<TransferForm> = {}): TransferForm => ({
+  to: SEED_2,
+  amount: "1.5",
+  fee: "",
+  ...overrides,
+})
+
+describe("reading the transfer form", () => {
+  it("makes the exact argument: base units, the ledger's fee, the memo, created_at_time in ns", () => {
+    const memo = new Uint8Array(16).fill(7)
+    expect(
+      readTransferForm(form({ to: ` ${SEED_2} ` }), 8, 1_700_000_000_000, memo)
+    ).toEqual({
+      ok: true,
+      arg: {
+        to: { owner: SEED_2, subaccount: null },
+        amount: 150_000_000n,
+        fee: null,
+        memo,
+        from_subaccount: null,
+        created_at_time: 1_700_000_000_000_000_000n,
+      },
+    })
+  })
+
+  it("gives each transfer its own 16-byte memo, even in the same millisecond", () => {
+    const first = readTransferForm(form(), 8, 1_700_000_000_000)
+    const second = readTransferForm(form(), 8, 1_700_000_000_000)
+    if (!first.ok || !second.ok) throw new Error("refused")
+    expect(first.arg.memo).toHaveLength(16)
+    expect(second.arg.memo).toHaveLength(16)
+    expect(second.arg.memo).not.toEqual(first.arg.memo)
+  })
+
+  it("keeps a typed fee, also exactly", () => {
+    const read = readTransferForm(form({ amount: "0.29", fee: "0.0001" }), 8)
+    expect(read.ok && [read.arg.amount, read.arg.fee]).toEqual([
+      29_000_000n,
+      10_000n,
+    ])
+  })
+
+  it.each([
+    ["to", form({ to: "not a principal" })],
+    ["to", form({ to: SEED_2.toUpperCase() })],
+    ["amount", form({ amount: "" })],
+    ["amount", form({ amount: "1e3" })],
+    ["amount", form({ amount: "1,5" })],
+    ["amount", form({ amount: "-1" })],
+    ["amount", form({ amount: "3.141592653" })],
+    ["amount", form({ amount: "0" })],
+    ["fee", form({ fee: "ten" })],
+  ] as const)("refuses the %s field of %j", (field, typed) => {
+    const read = readTransferForm(typed, 8)
+    expect(read.ok).toBe(false)
+    expect(!read.ok && read.field).toBe(field)
+  })
+})

package/examples/icrc-ledger/src/transfer-form.ts

@@ -0,0 +1,97 @@
+// Turns what a person typed into an ICRC-1 transfer, or refuses it. Nothing
+// here guesses: a principal must be canonical text, and an amount must be a
+// plain decimal the token's decimals can hold exactly.
+import { isPrincipal, principal } from "@meantjs/schema"
+import { parseUnits } from "@ic-reactor/core"
+import type { TransferArg } from "./canisters/icrc1.ts"
+
+export interface TransferForm {
+  /** The recipient's principal. */
+  readonly to: string
+  /** The amount, in tokens: "1.5". */
+  readonly amount: string
+  /** An explicit fee in tokens, or "" to let the ledger charge its own. */
+  readonly fee: string
+}
+
+export type ReadTransfer =
+  | { readonly ok: true; readonly arg: TransferArg }
+  | {
+      readonly ok: false
+      readonly field: keyof TransferForm
+      readonly reason: string
+    }
+
+/** The amount `text` stands for, in base units, or why it is refused. */
+function readAmount(
+  text: string,
+  decimals: number
+): { ok: true; units: bigint } | { ok: false; reason: string } {
+  try {
+    return { ok: true, units: parseUnits(text, decimals) }
+  } catch (error) {
+    if (error instanceof RangeError) {
+      return {
+        ok: false,
+        reason: text.trim().startsWith("-")
+          ? "An amount cannot be negative."
+          : `At most ${decimals} decimals.`,
+      }
+    }
+    return {
+      ok: false,
+      reason:
+        'Write plain digits with at most one "." (no exponent, grouping or sign).',
+    }
+  }
+}
+
+/**
+ * The `icrc1_transfer` argument for `form`, or the first field that is
+ * refused. `nowMs` becomes `created_at_time`, so that sending the same
+ * argument twice is answered `Duplicate` instead of moving the funds twice.
+ *
+ * `memo` is this transfer's own, 16 random bytes: the ledger takes two
+ * arguments for one only when every field matches, so two different transfers
+ * of the same amount to the same account made in the same millisecond are not
+ * taken for each other's `Duplicate`. Read the form once per transfer, and
+ * send the argument it gave again, memo included, to re-send that transfer.
+ */
+export function readTransferForm(
+  form: TransferForm,
+  decimals: number,
+  nowMs: number = Date.now(),
+  memo: Uint8Array = newMemo()
+): ReadTransfer {
+  const to = form.to.trim()
+  if (!isPrincipal(to)) {
+    return { ok: false, field: "to", reason: "Not a principal." }
+  }
+  const amount = readAmount(form.amount, decimals)
+  if (!amount.ok) return { ok: false, field: "amount", reason: amount.reason }
+  if (amount.units === 0n) {
+    return { ok: false, field: "amount", reason: "Send more than zero." }
+  }
+  let fee: bigint | null = null
+  if (form.fee.trim() !== "") {
+    const read = readAmount(form.fee, decimals)
+    if (!read.ok) return { ok: false, field: "fee", reason: read.reason }
+    fee = read.units
+  }
+  return {
+    ok: true,
+    arg: {
+      to: { owner: principal(to), subaccount: null },
+      amount: amount.units,
+      fee,
+      memo,
+      from_subaccount: null,
+      created_at_time: BigInt(nowMs) * 1_000_000n,
+    },
+  }
+}
+
+/** A memo of its own for one transfer: 16 bytes from `crypto.getRandomValues`. */
+export function newMemo(): Uint8Array {
+  return crypto.getRandomValues(new Uint8Array(16))
+}

package/examples/icrc-ledger/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "allowImportingTsExtensions": true,
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src", "scripts", "vite.config.ts", "vitest.config.ts"]
+}

package/examples/icrc-ledger/vite.config.ts

@@ -0,0 +1,44 @@
+import { icReactor } from "@ic-reactor/vite-plugin"
+import react from "@vitejs/plugin-react"
+import { defineConfig } from "vite"
+
+export default defineConfig({
+  plugins: [
+    react(),
+    // Writes src/canisters/<name>.ts (and its envelope) from each .did when
+    // `vite dev` or `vite build` starts, and again when a .did changes. The
+    // files are committed too, so `pnpm gen:check` can fail a stale copy.
+    icReactor({
+      canisters: {
+        // Any ICRC-1 ledger: the ICP ledger, ckBTC, a pasted id.
+        icrc1: { didFile: "icrc1.did", outDir: "src/canisters" },
+        // The next two are projections of mainnet canisters' interfaces to
+        // the methods the app calls, and every type they reach. They are
+        // committed, so the plugin reads them and fetches nothing: builds
+        // work offline. `IC_REACTOR_FETCH=<name>` fetches and projects one
+        // again, and `IC_REACTOR_VERIFY=1` checks both against the live
+        // canisters.
+        // The ICP ledger's own block reads, with their archive callbacks.
+        icp_ledger: {
+          didFile: "icp_ledger.did",
+          outDir: "src/canisters",
+          canisterId: "ryjl3-tyaaa-aaaaa-aaaba-cai",
+          methods: ["query_blocks"],
+        },
+        // The ckBTC minter's get_btc_address, an update read as a query.
+        ckbtc_minter: {
+          didFile: "ckbtc_minter.did",
+          outDir: "src/canisters",
+          canisterId: "mqygn-kiaaa-aaaar-qaadq-cai",
+          methods: ["get_btc_address"],
+        },
+      },
+      // Both tabs talk to a replica of their own (mainnet, or the fake one in
+      // the page), so there is no local network to ask `icp` about.
+      injectEnvironment: false,
+    }),
+  ],
+  server: { port: 5173 },
+  // The IC agent, with its BLS certificate check, is most of the main chunk.
+  build: { chunkSizeWarningLimit: 600 },
+})

package/examples/icrc-ledger/vitest.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from "vitest/config"
+
+// The tests run over the committed generated module (`pnpm gen:check` keeps it
+// current), so they need neither the React plugin nor the generator. The
+// sandbox's own tests run in Node; a `.test.tsx` renders the page in jsdom.
+//
+// package.json pins jsdom to 30.0.1: jsdom 30.1 subclasses the global
+// `Iterator`, which StackBlitz's WebContainer does not define, so there a jsdom
+// test fails to start with "ReferenceError: Iterator is not defined".
+export default defineConfig({
+  test: { environment: "node", include: ["src/**/*.test.{ts,tsx}"] },
+})

package/examples/next-ssr/.stackblitzrc

@@ -0,0 +1,4 @@
+{
+  "installDependencies": true,
+  "startCommand": "npm test"
+}

package/examples/next-ssr/README.md

@@ -0,0 +1,112 @@
+# Next.js SSR on ic-reactor 4
+
+A Next.js App Router app (Next 16, React 19) that reads three mainnet ICRC-1
+ledgers (ICP, ckBTC and ckETH) on the server with `@ic-reactor/core`, hands
+its cache to the browser, and reads again in the browser as whoever signs in
+with Internet Identity there. One generated module,
+`src/canisters/icrc1.ts`, serves every ledger.
+
+## Scenarios
+
+Each scenario lives in its own small file, whose header comment names the
+rule it shows. Every one is tested (`pnpm test`), and every one shows on a
+running server.
+
+| #   | Scenario                                                                    | Files                                                                                | How to see it                                                                         |
+| --- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
+| 1   | One client per request on the server; prefetch by `{ id }`; `dehydrate`     | `src/server/request-client.ts`, `src/server/prefetch-ledgers.ts`, `src/app/page.tsx` | `/`: each card says when the server read it                                           |
+| 2   | `ReactorProvider` factory in a `'use client'` module; nothing refetched     | `src/app/providers.tsx`, `src/components/server-data.ts`                             | `/` with the network panel open: no request to `icp-api.io` until you ask for one     |
+| 3   | Lossless hydration of `bigint`, principals and `Uint8Array`                 | `src/components/LedgerCard.tsx`                                                      | the run-time type after each value; mainnet returns no blob here, the tests' mocks do |
+| 4   | Renders with JavaScript disabled                                            | `scripts/smoke.ts`                                                                   | turn JavaScript off and reload `/`                                                    |
+| 5   | Streaming with Suspense: certified balances arrive after the page           | `src/app/account/CertifiedBalances.tsx`                                              | `/account?owner=rkp4c-7iaaa-aaaaa-aaaca-cai`                                          |
+| 6   | Progressive enhancement: a GET form, validated on the server                | `src/app/account/page.tsx`, `src/server/parse-owner.ts`                              | look up with JavaScript on and off; `/account?owner=not-a-principal`                  |
+| 7   | Route Handler: a client per request, amounts as text, kind as HTTP status   | `src/app/api/balance/[ledger]/[principal]/route.ts`, `src/server/balance-route.ts`   | `/api/balance/ckBTC/rkp4c-7iaaa-aaaaa-aaaca-cai`; a bad principal is a 400            |
+| 8   | Errors on the server: one section fails with its `kind`, not the page       | `src/components/LedgerError.tsx`, `src/server/error-summary.ts`                      | `/`: the "NNS governance (not a ledger)" section                                      |
+| 9   | Sign in after hydration: the new caller's keys, nothing anonymous reused    | `src/components/MyBalances.tsx`, `src/components/LedgerCard.tsx`                     | sign in with Internet Identity: "My balances" loads, each card reads again as you     |
+| 10  | A reload while signed in: hydrated from the server's data, then read as you | `src/app/providers.tsx`, `src/components/LedgerCard.tsx`                             | sign in, then reload `/`: no hydration error, then each card reads again as you       |
+
+## Run it
+
+```sh
+pnpm install && pnpm build   # once, at the repository root: the workspace packages
+cd examples/next-ssr
+pnpm dev                     # http://localhost:3001
+pnpm build && pnpm start     # http://localhost:3011
+pnpm smoke                   # checks the running start server against mainnet; Node 22.18+
+```
+
+To see scenario 4, turn JavaScript off (Chrome DevTools: the command menu,
+"Disable JavaScript") and reload `/` or `/account?owner=...`: every value is
+there, and the certified section shows its fallback, which says why.
+
+The route of scenario 7 answers a failure with a status that says whether
+asking again can help. A canister id that names no canister,
+`/api/balance/2y4s5-zaaaa-aaad7-7777q-cai/rkp4c-7iaaa-aaaaa-aaaca-cai`, is a
+502 with `kind: "not_delivered"`, `httpStatus: 400` and
+`code: "canister_not_found"`: the IC refused it for good. A rate limit or a
+5xx from the IC is a 503.
+
+The pages read mainnet when a request comes in, never during `next build`
+(`/` calls `connection()`; `/account` and the route read their parameters), so
+a build needs no network.
+
+## Test it
+
+```sh
+pnpm test        # vitest; no test reaches mainnet
+pnpm typecheck
+pnpm gen:check   # fails if src/canisters/ is stale
+```
+
+The tests run the real client on `createTestClient()` from
+`@ic-reactor/core/testing`, over in-memory replicas that mock the ledgers at
+their mainnet ids (`src/testing/mock-ledgers.ts`). A test builds one client
+for the server's request, one for the server render of the client components
+and one for the browser tab, as the app has, and reads each replica's request
+log to tell which side sent what:
+
+- `src/server/*.test.ts`: the prefetch, its JSON round trip, the account
+  reads, the owner parameter and the route handler.
+- `src/server/request-client.rsc.test.tsx`: `/account` rendered by React's
+  Flight server with the `react-server` condition, as Next renders Server
+  Components, so React's `cache()` memoizes as in a request: one client
+  serves the page and its streamed section, and the next request gets a new
+  one. It runs in vitest's `react-server` project (`vitest.config.ts`).
+- `src/components/hydration.test.tsx`: the home page rendered to HTML, read
+  with no script run, hydrated without a mismatch or a request, then signed
+  in; and hydrated in a tab that is still signed in, without a mismatch, then
+  read as the user.
+- `src/components/MyBalances.test.tsx`: sign-in, a switch of account,
+  sign-out, and a ledger whose decimals or symbol read fails.
+- `src/components/LedgerCard.test.tsx`: a card whose reads fail in the tab.
+- `src/app/providers*.test.tsx`: the real `<Providers>` on a server and in a
+  browser.
+- `src/app/account/account.test.tsx`: `/account` streamed by React's server
+  renderer, the certified section held until the first part is read.
+
+`src/canisters/` is generated from `icrc1.did` by `pnpm gen`
+(`meant gen`), committed, and never edited.
+
+## A tab that is still signed in
+
+Query keys carry the caller, and an `AuthClient` reads a stored session
+synchronously, so a tab that is still signed in from an earlier visit knows
+the user before its first render, while the server prefetched as the
+anonymous principal. The keys `useClient()` builds follow the caller React
+renders with, the one `useAuth()` returns: anonymous on the server and while
+the page hydrates. So the hydrating render finds the server's data under the
+anonymous keys, matches the server's HTML and sends nothing; then React
+renders each component that calls `useClient()` or `useAuth()` again with the
+session, and every card reads its own keys once, as the user (scenario 10).
+`src/components/hydration.test.tsx` checks it: no recoverable error, no
+console error, the server's nodes kept, no anonymous read sent, and each card
+read once as the user.
+
+That move has one cost, which this app does not pay: a Suspense boundary that
+has not hydrated yet (its streamed HTML, or its lazy code, still on the way)
+below a component that calls `useClient()` or `useAuth()` is rendered on the
+client when that component moves on, showing its fallback instead of the
+server's HTML. The streamed section of `/account` sits in a Server Component,
+and no client component above it renders with the caller, so it streams in as
+the server sent it. In your own app, keep such a boundary out from under a
+component that renders with the caller, or pass it in as `children`.

package/examples/next-ssr/icrc1.did

@@ -0,0 +1,88 @@
+type BlockIndex = nat;
+type Subaccount = blob;
+// Number of nanoseconds since the UNIX epoch in UTC timezone.
+type Timestamp = nat64;
+// Number of nanoseconds between two [Timestamp]s.
+type Duration = nat64;
+type Tokens = nat;
+
+type Account = record {
+    owner : principal;
+    subaccount : opt Subaccount;
+};
+
+type TransferArg = record {
+    from_subaccount : opt Subaccount;
+    to : Account;
+    amount : Tokens;
+    fee : opt Tokens;
+    memo : opt blob;
+    created_at_time: opt Timestamp;
+};
+
+type TransferError = variant {
+    BadFee : record { expected_fee : Tokens };
+    BadBurn : record { min_burn_amount : Tokens };
+    InsufficientFunds : record { balance : Tokens };
+    TooOld;
+    CreatedInFuture : record { ledger_time : nat64 };
+    TemporarilyUnavailable;
+    Duplicate : record { duplicate_of : BlockIndex };
+    GenericError : record { error_code : nat; message : text };
+};
+
+type TransferResult = variant {
+    Ok : BlockIndex;
+    Err : TransferError;
+};
+
+// The value returned from the [icrc1_metadata] endpoint.
+type Value = variant {
+    Nat : nat;
+    Int : int;
+    Text : text;
+    Blob : blob;
+};
+
+// The initialization parameters of the Ledger
+type InitArgs = record {
+    minting_account : Account;
+    transfer_fee : nat64;
+    token_symbol : text;
+    token_name : text;
+    metadata : vec record { text; Value };
+    initial_balances : vec record { Account; nat64 };
+    archive_options : record {
+        num_blocks_to_archive : nat64;
+        trigger_threshold : nat64;
+        max_message_size_bytes : opt nat64;
+        cycles_for_archive_creation : opt nat64;
+        node_max_memory_size_bytes : opt nat64;
+        controller_id : principal;
+    };
+};
+
+type UpgradeArgs = record {
+    metadata : opt vec record { text; Value };
+    token_symbol : opt text;
+    token_name : opt text;
+    transfer_fee : opt nat64;
+};
+
+type LedgerArg = variant {
+    Init: InitArgs;
+    Upgrade: opt UpgradeArgs;
+};
+
+service : (ledger_arg : LedgerArg) -> {
+    icrc1_name : () -> (text) query;
+    icrc1_symbol : () -> (text) query;
+    icrc1_decimals : () -> (nat8) query;
+    icrc1_metadata : () -> (vec record { text; Value }) query;
+    icrc1_total_supply : () -> (Tokens) query;
+    icrc1_fee : () -> (Tokens) query;
+    icrc1_minting_account : () -> (opt Account) query;
+    icrc1_balance_of : (Account) -> (Tokens) query;
+    icrc1_transfer : (TransferArg) -> (TransferResult);
+    icrc1_supported_standards : () -> (vec record { name : text; url : text }) query;
+}

package/examples/next-ssr/next.config.ts

@@ -0,0 +1,10 @@
+import type { NextConfig } from "next"
+
+const nextConfig: NextConfig = {
+  reactStrictMode: true,
+  // `next dev` would otherwise write an AGENTS.md and a CLAUDE.md into this
+  // folder when it detects a coding agent; the repository keeps its own.
+  agentRules: false,
+}
+
+export default nextConfig

package/examples/next-ssr/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "next-ssr",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "scripts": {
+    "dev": "next dev -p 3001",
+    "build": "next build",
+    "start": "next start -p 3011",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "gen": "meant gen icrc1.did -o src/canisters",
+    "gen:check": "meant gen icrc1.did -o src/canisters --check",
+    "smoke": "node scripts/smoke.ts"
+  },
+  "dependencies": {
+    "@meantjs/schema": "0.6.0",
+    "@ic-reactor/core": "^4.1.1",
+    "@ic-reactor/react": "^4.1.1",
+    "@icp-sdk/auth": "^10.0.1",
+    "@icp-sdk/core": "^6.1.0",
+    "@tanstack/react-query": "^5.102.8",
+    "next": "^16.4.2",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0"
+  },
+  "devDependencies": {
+    "@meantjs/cli": "0.5.1",
+    "@noble/curves": "^2.2.0",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.3",
+    "@types/jsdom": "^30.0.0",
+    "@types/node": "^26.5.1",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "jsdom": "30.0.1",
+    "react-server-dom-turbopack": "^19.3.0",
+    "typescript": "^6.0.3",
+    "vitest": "^5.0.0"
+  }
+}

package/examples/next-ssr/scripts/smoke.ts

@@ -0,0 +1,169 @@
+// Scenario 4: the pages render with JavaScript disabled. Checks a running
+// production server (`pnpm build && pnpm start`) against mainnet, reading each
+// page the way a browser with JavaScript off sees it: the HTML as it arrives,
+// no script run, nothing that a script would reveal. Also checks the account
+// lookup and its streamed section (scenarios 5 and 6), the error section
+// (scenario 8) and the JSON route (scenario 7).
+//
+//   pnpm smoke                          # http://localhost:3011
+//   pnpm smoke http://localhost:3001    # another server, such as `pnpm dev`
+//
+// Node strips the types itself (22.18 or newer). It calls mainnet, so it is
+// not part of `pnpm test`.
+import assert from "node:assert/strict"
+import { createClient, formatUnits } from "@ic-reactor/core"
+import { JSDOM } from "jsdom"
+import { actor, type Actor } from "../src/canisters/icrc1.ts"
+import {
+  LEDGERS,
+  NO_CANISTER,
+  NOT_A_LEDGER,
+  SAMPLE_OWNER,
+} from "../src/ledgers.ts"
+
+const base = process.argv[2] ?? "http://localhost:3011"
+const mainnet = createClient({ network: "ic", identity: "anonymous" })
+
+/** The page at `path` as a browser without JavaScript shows it. */
+async function withoutJavaScript(path: string) {
+  const response = await fetch(new URL(path, base))
+  assert.equal(response.status, 200, `GET ${path}`)
+  const { document } = new JSDOM(await response.text()).window
+  for (const node of document.querySelectorAll("script, template, [hidden]")) {
+    node.remove()
+  }
+  return document
+}
+
+// The home page: every ledger's values are in the HTML, and they are
+// mainnet's, read again here directly.
+const home = await withoutJavaScript("/")
+for (const ref of LEDGERS) {
+  const ledger = mainnet.canister<Actor>(actor, { id: ref.id })
+  const [name, symbol, decimals, fee, minter] = await Promise.all([
+    ledger.icrc1_name(),
+    ledger.icrc1_symbol(),
+    ledger.icrc1_decimals(),
+    ledger.icrc1_fee(),
+    ledger.icrc1_minting_account(),
+  ])
+  const card = home.querySelector(`[data-ledger="${ref.id}"]`)
+  const read = (method: string) =>
+    card?.querySelector(`[data-read="${method}"]`)?.textContent ?? ""
+  assert.equal(read("icrc1_name"), `${name} string`)
+  assert.equal(read("icrc1_symbol"), `${symbol} string`)
+  assert.equal(read("icrc1_decimals"), `${decimals} number`)
+  assert.equal(
+    read("icrc1_fee"),
+    `${formatUnits(fee, decimals)} ${symbol} bigint`
+  )
+  assert.match(
+    read("icrc1_total_supply"),
+    new RegExp(`^\\d+(\\.\\d+)? ${symbol} bigint$`)
+  )
+  assert.ok(
+    read("icrc1_minting_account").startsWith(`${minter?.owner} principal text`)
+  )
+  const origin = card?.querySelector("[data-origin]")
+  assert.equal(origin?.getAttribute("data-origin"), "server")
+  console.log(
+    `${ref.label.padEnd(6)} ${read("icrc1_total_supply").replace(/ bigint$/, "")}, fee ${read("icrc1_fee").replace(/ bigint$/, "")}, ${origin?.textContent?.replace(/ Read again in this tab$/, "")}`
+  )
+}
+const failed = home.querySelector(
+  `[data-ledger="${NOT_A_LEDGER.id}"] [data-kind]`
+)
+assert.equal(failed?.textContent, "rejected")
+console.log(
+  `${NOT_A_LEDGER.label}: ${failed?.textContent}, rendered by the server`
+)
+assert.equal(home.querySelector(".pill")?.textContent, "anonymous")
+
+// The account page: the plain balances are in the first part of the
+// response; the certified ones arrive later in the same response.
+const started = Date.now()
+const response = await fetch(new URL(`/account?owner=${SAMPLE_OWNER}`, base))
+assert.equal(response.status, 200)
+let html = ""
+const arrivals: Record<string, number> = {}
+const decoder = new TextDecoder()
+for await (const chunk of response.body ?? []) {
+  html += decoder.decode(chunk, { stream: true })
+  for (const marker of ["balances", "certified-fallback", "certified"]) {
+    if (
+      arrivals[marker] === undefined &&
+      html.includes(`data-section="${marker}"`)
+    ) {
+      arrivals[marker] = Date.now() - started
+    }
+  }
+}
+assert.ok(arrivals.balances !== undefined && arrivals.certified !== undefined)
+assert.ok(
+  arrivals.certified > arrivals.balances,
+  "the certified balances stream in after the plain ones"
+)
+console.log(
+  `/account: balances at ${arrivals.balances} ms, certified balances streamed in at ${arrivals.certified} ms`
+)
+const account = new JSDOM(html).window.document
+const visible = (section: string) => {
+  const table = account.querySelector(`[data-section="${section}"]`)
+  return table !== null && table.closest("[hidden]") === null
+}
+assert.ok(visible("balances"), "the plain balances show without JavaScript")
+assert.ok(
+  !visible("certified"),
+  "the streamed section needs JavaScript to show"
+)
+const icp = account.querySelector(
+  `[data-section="balances"] [data-ledger="${LEDGERS[0]?.id}"] [data-field="balance"]`
+)?.textContent
+assert.match(icp ?? "", /^\d+(\.\d+)? ICP$/)
+console.log(`/account: ${SAMPLE_OWNER} holds ${icp}`)
+
+// A typo in the search parameter is a message in the page.
+const typo = await withoutJavaScript("/account?owner=not-a-principal")
+const problem = typo.querySelector('[data-problem="owner"]')?.textContent ?? ""
+assert.match(problem, /"not-a-principal" is not a principal/)
+assert.equal(typo.querySelector("table"), null)
+console.log(`/account?owner=not-a-principal: ${problem.slice(0, 40)}…`)
+
+// The route handler.
+const api = async (path: string) => {
+  const reply = await fetch(new URL(path, base))
+  return {
+    status: reply.status,
+    body: (await reply.json()) as Record<string, unknown>,
+  }
+}
+const ok = await api(`/api/balance/ckBTC/${SAMPLE_OWNER}`)
+assert.equal(ok.status, 200)
+assert.equal(
+  ok.body.balance,
+  formatUnits(BigInt(String(ok.body.baseUnits)), Number(ok.body.decimals))
+)
+console.log(
+  `/api/balance/ckBTC/${SAMPLE_OWNER}: ${ok.status} ${JSON.stringify(ok.body)}`
+)
+const bad = await api("/api/balance/ICP/not-a-principal")
+assert.equal(bad.status, 400)
+console.log(
+  `/api/balance/ICP/not-a-principal: ${bad.status} ${JSON.stringify(bad.body)}`
+)
+const notALedger = await api(`/api/balance/${NOT_A_LEDGER.id}/${SAMPLE_OWNER}`)
+assert.equal(notALedger.status, 502)
+console.log(
+  `/api/balance/${NOT_A_LEDGER.id}/…: ${notALedger.status} kind ${JSON.stringify((notALedger.body.error as { kind?: string }).kind)}`
+)
+// A canister that does not exist: refused for good, so a 502 and not a 503.
+const missing = await api(`/api/balance/${NO_CANISTER}/${SAMPLE_OWNER}`)
+const refusal = missing.body.error as { kind?: string; httpStatus?: number }
+assert.equal(missing.status, 502)
+assert.equal(refusal.kind, "not_delivered")
+assert.equal(refusal.httpStatus, 400)
+console.log(
+  `/api/balance/${NO_CANISTER}/…: ${missing.status} kind "${refusal.kind}", HTTP ${refusal.httpStatus} from the IC`
+)
+
+console.log("smoke: every check passed")