@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/next-ssr/src/app/account/CertifiedBalances.tsx

@@ -0,0 +1,58 @@
+// Scenario 5: a slower section, streamed in with Suspense.
+//
+// The /account page waits for the plain balances, which are in the first
+// HTML it sends, and renders this inside <Suspense>: React sends the fallback
+// with the rest of the page, then streams this section into the same response
+// once its reads are done. A certified read is a replicated call that goes
+// through consensus, a second or two on mainnet: the section worth streaming.
+//
+// Why an awaited async Server Component, and not `useSuspenseQuery` in a
+// client component over a server prefetch that is not awaited (TanStack
+// Query's dehydration of pending queries)? Both stream, and both keep bigints
+// exact: TanStack runs the client's serializer on a pending query's result
+// too. But with this library the Server Component is the one that holds up:
+// - A failure stays on the server, where `isReactorError` reads its kind into
+//   the row (src/server/read-balances.ts). A pending query that fails reaches
+//   the browser as an error TanStack redacts unless told otherwise, and React
+//   carries no error's fields from the server to the browser: no kind there.
+// - Its HTML does not depend on who the browser is signed in as. The browser
+//   keys every read by its own caller, so a signed-in visitor would never use
+//   the promise the server dehydrated for the anonymous caller, and would read
+//   everything again.
+// It gets the request's client from `requestClient()`: the same client, and
+// cache, the page used. The two sections share no read, though: a certified
+// canister's keys are its own, so this section reads `icrc1_decimals` and
+// `icrc1_symbol` again, certified, rather than take the page's uncertified
+// answers for them.
+import type { Principal } from "@meantjs/schema"
+import { BalanceTable } from "@/components/BalanceTable"
+import { LEDGERS } from "@/ledgers"
+import { readBalances } from "@/server/read-balances"
+import { requestClient } from "@/server/request-client"
+
+export async function CertifiedBalances({ owner }: { owner: Principal }) {
+  const rows = await readBalances(requestClient(), owner, LEDGERS, {
+    certified: true,
+  })
+  return (
+    <BalanceTable
+      caption="Certified balances: replicated reads, streamed in"
+      section="certified"
+      rows={rows}
+    />
+  )
+}
+
+/** What the page shows until the certified balances arrive. */
+export function CertifiedFallback() {
+  return (
+    <p className="muted" data-section="certified-fallback">
+      Reading certified balances through consensus…
+      <noscript>
+        {" "}
+        This section streams in after the rest of the page, and showing it takes
+        JavaScript. The balances above are in the HTML as it is.
+      </noscript>
+    </p>
+  )
+}

package/examples/next-ssr/src/app/account/account.test.tsx

@@ -0,0 +1,165 @@
+// Scenarios 5 and 6: the /account page, rendered to a stream by React's
+// server renderer, as Next renders it to HTML. The request's client is a test
+// client; `next/form` (which needs Next's router) is its plain `<form>`.
+//
+// - The owner comes from the search parameters and is validated on the
+//   server: a typo is a message, not a call.
+// - The plain balances are in the first HTML React sends, with the fallback
+//   of the certified section; the certified balances come later in the same
+//   response. The test holds the certified reads until it has read the first
+//   part, so the order is the page's, not a race.
+// - What a browser without JavaScript shows is the HTML with no script run:
+//   the balances, and the fallback's <noscript> note.
+import { principal } from "@meantjs/schema"
+import { JSDOM } from "jsdom"
+import type { ComponentProps } from "react"
+import { renderToReadableStream } from "react-dom/server"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { tokens } from "@/format"
+import { LEDGERS, SAMPLE_OWNER } from "@/ledgers"
+import {
+  BALANCES,
+  mockLedgers,
+  requestsFor,
+  tokenOf,
+  type MockLedgers,
+} from "@/testing/mock-ledgers"
+import AccountPage from "./page"
+
+const request = vi.hoisted(() => ({
+  test: undefined as MockLedgers | undefined,
+  /** Releases the certified reads; set while they are held. */
+  release: undefined as (() => void) | undefined,
+}))
+
+vi.mock("next/form", () => ({
+  default: (props: ComponentProps<"form">) => <form {...props} />,
+}))
+vi.mock("@/server/request-client", () => ({
+  requestClient: () => {
+    if (request.test === undefined) throw new Error("no request client")
+    return request.test.client
+  },
+}))
+// The real reads, with the certified ones held until the test releases them.
+vi.mock("@/server/read-balances", async (importOriginal) => {
+  const real = await importOriginal<typeof import("@/server/read-balances")>()
+  return {
+    ...real,
+    readBalances: async (...args: Parameters<typeof real.readBalances>) => {
+      if (args[3]?.certified === true) {
+        await new Promise<void>((resolve) => {
+          request.release = resolve
+        })
+      }
+      return real.readBalances(...args)
+    },
+  }
+})
+
+afterEach(() => {
+  request.test?.client.dispose()
+  request.test = undefined
+  request.release = undefined
+})
+
+const decoder = new TextDecoder()
+
+/** Renders the page for `owner`; returns the stream's reader once the shell is ready. */
+async function renderPage(owner?: string) {
+  request.test = mockLedgers()
+  const stream = await renderToReadableStream(
+    <AccountPage
+      searchParams={Promise.resolve(owner === undefined ? {} : { owner })}
+    />
+  )
+  const reader = stream.getReader()
+  const read = async () => {
+    let html = ""
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) return html
+      html += decoder.decode(value, { stream: true })
+    }
+  }
+  return { reader, read }
+}
+
+/** The text a browser without JavaScript shows of `html`. */
+function withoutJavaScript(html: string) {
+  const { document } = new JSDOM(html).window
+  for (const hidden of document.querySelectorAll(
+    "script, template, [hidden]"
+  )) {
+    hidden.remove()
+  }
+  return document
+}
+
+describe("/account", () => {
+  it("sends the plain balances first, then streams the certified ones in", async () => {
+    const { reader, read } = await renderPage(SAMPLE_OWNER)
+
+    // The shell: everything outside <Suspense>.
+    const first = await reader.read()
+    const shell = decoder.decode(first.value)
+    expect(shell).toContain('data-section="balances"')
+    expect(shell).toContain('data-section="certified-fallback"')
+    expect(shell).not.toContain('data-section="certified"')
+    expect(requestsFor(request.test!, "icrc1_balance_of")).toHaveLength(
+      LEDGERS.length
+    )
+
+    request.release?.()
+    const rest = await read()
+    expect(rest).toContain('data-section="certified"')
+
+    // The certified reads were replicated calls; the plain ones, queries.
+    expect(
+      requestsFor(request.test!, "icrc1_balance_of").map(
+        ({ endpoint }) => endpoint
+      )
+    ).toEqual([...LEDGERS.map(() => "query"), ...LEDGERS.map(() => "call")])
+
+    const page = withoutJavaScript(shell + rest)
+    const owned = BALANCES.get(principal(SAMPLE_OWNER)) ?? 0n
+    for (const ledger of LEDGERS) {
+      const { decimals, symbol } = tokenOf(ledger)
+      expect(
+        page.querySelector(
+          `[data-section="balances"] [data-ledger="${ledger.id}"] [data-field="balance"]`
+        )?.textContent
+      ).toBe(tokens(owned, decimals, symbol))
+    }
+    // Without JavaScript the streamed section stays hidden; the fallback says so.
+    expect(page.querySelector('[data-section="certified"]')).toBeNull()
+    expect(
+      page.querySelector('[data-section="certified-fallback"]')?.textContent
+    ).toContain("showing it takes JavaScript")
+  })
+
+  it("refuses a typo with a message, keeps it in the field, and calls nothing", async () => {
+    const { read } = await renderPage("not-a-principal")
+
+    const page = withoutJavaScript(await read())
+
+    expect(page.querySelector('[data-problem="owner"]')?.textContent).toContain(
+      '"not-a-principal" is not a principal'
+    )
+    expect(page.querySelector("input")?.getAttribute("value")).toBe(
+      "not-a-principal"
+    )
+    expect(page.querySelector("form")?.getAttribute("action")).toBe("/account")
+    expect(request.test!.requests).toEqual([])
+  })
+
+  it("shows only the form when no owner is asked for", async () => {
+    const { read } = await renderPage()
+
+    const page = withoutJavaScript(await read())
+
+    expect(page.querySelector("form input[name=owner]")).not.toBeNull()
+    expect(page.querySelector("table")).toBeNull()
+    expect(request.test!.requests).toEqual([])
+  })
+})

package/examples/next-ssr/src/app/account/page.tsx

@@ -0,0 +1,82 @@
+// Scenario 6: progressive enhancement. The lookup is a form that works
+// without JavaScript and with it.
+//
+// `next/form` renders a plain `<form action="/account">`: without JavaScript
+// the browser submits it as a GET, `/account?owner=<text>`, and this page
+// renders the result on the server. With JavaScript, Next navigates to the
+// same URL on the client, so the tab's client and its cache (the root
+// layout's provider) stay alive. Either way the owner arrives as a search
+// parameter, user input that is validated here, on the server
+// (src/server/parse-owner.ts): an invalid principal is a message, not a crash
+// and not a call.
+//
+// The plain balances are awaited by the page itself, so they are in the first
+// HTML; the certified ones stream in afterwards (scenario 5,
+// ./CertifiedBalances.tsx). Reading `searchParams` makes the page render per
+// request: `next build` never calls mainnet for it.
+import Form from "next/form"
+import Link from "next/link"
+import { Suspense } from "react"
+import type { Principal } from "@meantjs/schema"
+import { BalanceTable } from "@/components/BalanceTable"
+import { LEDGERS, SAMPLE_OWNER } from "@/ledgers"
+import { parseOwner } from "@/server/parse-owner"
+import { readBalances } from "@/server/read-balances"
+import { requestClient } from "@/server/request-client"
+import { CertifiedBalances, CertifiedFallback } from "./CertifiedBalances"
+
+export default async function AccountPage(props: {
+  searchParams: Promise<Record<string, string | string[] | undefined>>
+}) {
+  const input = parseOwner((await props.searchParams).owner)
+
+  return (
+    <main>
+      <h1>Look up an account</h1>
+      <p className="lede">
+        The balance of a principal&apos;s default account on each ledger, read
+        on the server. Try{" "}
+        <Link href={`/account?owner=${SAMPLE_OWNER}`}>
+          the cycles minting canister
+        </Link>{" "}
+        or <Link href="/account?owner=not-a-principal">a typo</Link>.
+      </p>
+      <Form action="/account" className="lookup">
+        <label htmlFor="owner">Owner principal</label>
+        <div className="row">
+          <input
+            id="owner"
+            name="owner"
+            defaultValue={input.kind === "empty" ? "" : input.text}
+            placeholder={SAMPLE_OWNER}
+            aria-invalid={input.kind === "invalid"}
+            spellCheck={false}
+            autoComplete="off"
+          />
+          <button type="submit" className="primary">
+            Look up
+          </button>
+        </div>
+      </Form>
+      {input.kind === "invalid" && (
+        <p className="error" role="alert" data-problem="owner">
+          {input.reason}
+        </p>
+      )}
+      {input.kind === "valid" && (
+        <section>
+          <Balances owner={input.owner} />
+          <Suspense fallback={<CertifiedFallback />}>
+            <CertifiedBalances owner={input.owner} />
+          </Suspense>
+        </section>
+      )}
+    </main>
+  )
+}
+
+/** The plain (query) balances: awaited, so they are part of the first HTML. */
+async function Balances({ owner }: { owner: Principal }) {
+  const rows = await readBalances(requestClient(), owner, LEDGERS)
+  return <BalanceTable caption="Balances" section="balances" rows={rows} />
+}

package/examples/next-ssr/src/app/api/balance/[ledger]/[principal]/route.ts

@@ -0,0 +1,10 @@
+// Scenario 7: GET /api/balance/<ledger>/<principal>, answered as JSON by a
+// handler that builds a client for each request (src/server/balance-route.ts).
+// It reads the request's parameters, so Next runs it per request, never at
+// build time.
+import { createClient } from "@ic-reactor/core"
+import { balanceRoute } from "@/server/balance-route"
+
+export const GET = balanceRoute(() =>
+  createClient({ network: "ic", identity: "anonymous" })
+)

package/examples/next-ssr/src/app/globals.css

@@ -0,0 +1,278 @@
+:root {
+  color-scheme: light dark;
+  --bg: #f7f7f5;
+  --card: #ffffff;
+  --text: #1c1c1a;
+  --muted: #6b6b66;
+  --line: #dcdcd6;
+  --accent: #2b59c3;
+  --error: #b3261e;
+  --error-bg: #fdecea;
+  --code-bg: #efefea;
+  --ok: #1e6b3a;
+  --ok-bg: #e7f4ec;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --bg: #131312;
+    --card: #1c1c1a;
+    --text: #ecece8;
+    --muted: #9a9a93;
+    --line: #34342f;
+    --accent: #8ab0ff;
+    --error: #ffb4ab;
+    --error-bg: #3a1d1a;
+    --code-bg: #262623;
+    --ok: #8fd6a8;
+    --ok-bg: #16301f;
+  }
+}
+
+* {
+  box-sizing: border-box;
+}
+
+body {
+  margin: 0;
+  background: var(--bg);
+  color: var(--text);
+  font:
+    16px/1.5 system-ui,
+    sans-serif;
+}
+
+a {
+  color: var(--accent);
+}
+
+header.top {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 1rem;
+  max-width: 48rem;
+  margin: 0 auto;
+  padding: 1rem 1rem 0;
+}
+
+header.top nav {
+  display: flex;
+  gap: 1rem;
+}
+
+main {
+  max-width: 48rem;
+  margin: 0 auto;
+  padding: 1rem 1rem 3rem;
+}
+
+h1 {
+  margin: 0;
+  font-size: 1.6rem;
+}
+
+h2 {
+  margin: 0 0 0.75rem;
+  font-size: 1.1rem;
+}
+
+.lede {
+  margin: 0.25rem 0 1.5rem;
+  color: var(--muted);
+}
+
+section {
+  background: var(--card);
+  border: 1px solid var(--line);
+  border-radius: 10px;
+  padding: 1rem;
+  margin-bottom: 1rem;
+}
+
+label {
+  display: block;
+  margin: 0 0 0.25rem;
+  font-size: 0.85rem;
+  color: var(--muted);
+}
+
+input {
+  flex: 1;
+  min-width: 16rem;
+  padding: 0.5rem 0.6rem;
+  font:
+    0.9rem ui-monospace,
+    monospace;
+  color: inherit;
+  background: var(--card);
+  border: 1px solid var(--line);
+  border-radius: 6px;
+}
+
+input[aria-invalid="true"] {
+  border-color: var(--error);
+}
+
+.row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+form.lookup {
+  margin-bottom: 1rem;
+}
+
+button {
+  padding: 0.3rem 0.8rem;
+  font: inherit;
+  color: inherit;
+  background: var(--bg);
+  border: 1px solid var(--line);
+  border-radius: 999px;
+  cursor: pointer;
+}
+
+button:disabled {
+  opacity: 0.5;
+  cursor: default;
+}
+
+button.primary {
+  background: var(--accent);
+  border-color: var(--accent);
+  color: var(--card);
+  font-weight: 600;
+}
+
+code {
+  font:
+    0.85rem ui-monospace,
+    monospace;
+  background: var(--code-bg);
+  padding: 0.05rem 0.3rem;
+  border-radius: 4px;
+  overflow-wrap: anywhere;
+}
+
+dl {
+  margin: 0;
+}
+
+.kv {
+  display: flex;
+  flex-wrap: wrap;
+  justify-content: space-between;
+  gap: 0.25rem 1rem;
+  padding: 0.4rem 0;
+  border-top: 1px solid var(--line);
+}
+
+.kv:first-child {
+  border-top: 0;
+}
+
+dt {
+  color: var(--muted);
+}
+
+dd {
+  margin: 0;
+  text-align: right;
+  font-variant-numeric: tabular-nums;
+  overflow-wrap: anywhere;
+}
+
+.type {
+  display: inline-block;
+  padding: 0 0.4rem;
+  border-radius: 999px;
+  background: var(--ok-bg);
+  color: var(--ok);
+  font:
+    0.75rem ui-monospace,
+    monospace;
+}
+
+.metadata {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.origin {
+  margin: 0.75rem 0 0;
+  padding-top: 0.6rem;
+  border-top: 1px solid var(--line);
+  color: var(--muted);
+  font-size: 0.85rem;
+}
+
+.origin[data-origin="browser"] {
+  color: var(--accent);
+}
+
+.muted {
+  margin: 0 0 0.75rem;
+  color: var(--muted);
+}
+
+.error {
+  margin: 0.4rem 0 0;
+  padding: 0.5rem 0.7rem;
+  color: var(--error);
+  background: var(--error-bg);
+  border-radius: 6px;
+  font-size: 0.9rem;
+  overflow-wrap: anywhere;
+}
+
+.error p {
+  margin: 0.25rem 0 0;
+}
+
+.error .plain {
+  margin: 0;
+  color: var(--text);
+}
+
+.pill {
+  display: inline-block;
+  padding: 0.05rem 0.6rem;
+  border-radius: 999px;
+  background: var(--code-bg);
+  font-size: 0.85rem;
+  font-weight: 600;
+}
+
+.pill[data-status="signed-in"] {
+  color: var(--ok);
+  background: var(--ok-bg);
+}
+
+table.balances {
+  width: 100%;
+  margin-bottom: 1rem;
+  border-collapse: collapse;
+  font-variant-numeric: tabular-nums;
+}
+
+table.balances caption {
+  text-align: left;
+  font-weight: 600;
+  padding-bottom: 0.4rem;
+}
+
+table.balances th,
+table.balances td {
+  padding: 0.35rem 0.4rem;
+  border-top: 1px solid var(--line);
+  text-align: left;
+  overflow-wrap: anywhere;
+}
+
+table.balances td.error {
+  border-radius: 0;
+}

package/examples/next-ssr/src/app/layout.tsx

@@ -0,0 +1,34 @@
+// The root layout, a Server Component. It renders the client module that owns
+// the tab's client (./providers.tsx) around every page, so the client and its
+// cache stay alive across client-side navigations.
+import type { Metadata } from "next"
+import Link from "next/link"
+import type { ReactNode } from "react"
+import { SessionBadge } from "@/components/SessionBadge"
+import { Providers } from "./providers"
+import "./globals.css"
+
+export const metadata: Metadata = {
+  title: "Next.js SSR on ic-reactor 4",
+  description:
+    "Mainnet ICRC-1 ledgers read on the server, hydrated losslessly, and read again as the signed-in user.",
+}
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>
+          <header className="top">
+            <nav>
+              <Link href="/">Ledgers</Link>
+              <Link href="/account">Account lookup</Link>
+            </nav>
+            <SessionBadge />
+          </header>
+          {children}
+        </Providers>
+      </body>
+    </html>
+  )
+}

package/examples/next-ssr/src/app/page.tsx

@@ -0,0 +1,46 @@
+// The home page, a Server Component. Per request it builds the request's
+// client (scenario 1, src/server/request-client.ts), prefetches every token
+// read of the three ledgers and of a canister that is not a ledger
+// (src/server/prefetch-ledgers.ts), and hands the dehydrated cache to the
+// client components below through <HydrationBoundary>. The cards render the
+// values on the server, so the HTML has them without JavaScript (scenario
+// 4); the not-a-ledger section shows its error kind (scenario 8); "My
+// balances" waits for a sign-in in the browser (scenario 9).
+import { HydrationBoundary } from "@tanstack/react-query"
+import Link from "next/link"
+import { connection } from "next/server"
+import { LedgerSections } from "@/components/LedgerSections"
+import { MyBalances } from "@/components/MyBalances"
+import { LEDGERS, NOT_A_LEDGER, SAMPLE_OWNER } from "@/ledgers"
+import { prefetchLedgers } from "@/server/prefetch-ledgers"
+import { requestClient } from "@/server/request-client"
+
+const SECTIONS = [...LEDGERS, NOT_A_LEDGER]
+
+export default async function Home() {
+  // Read mainnet when a request comes in, never while `next build` prerenders:
+  // a build must not call mainnet, and its answer would be stale anyway.
+  await connection()
+  const { state, failures } = await prefetchLedgers(requestClient(), SECTIONS)
+
+  return (
+    <main>
+      <h1>ICRC-1 ledgers, rendered on the server</h1>
+      <p className="lede">
+        This page read every value below on the server, as the anonymous
+        principal, then handed its cache to the browser. Turn JavaScript off and
+        reload: it is all in the HTML. Look up any account on the{" "}
+        <Link href={`/account?owner=${SAMPLE_OWNER}`}>account page</Link>, or as
+        JSON from{" "}
+        <a href={`/api/balance/ICP/${SAMPLE_OWNER}`}>
+          /api/balance/ICP/{SAMPLE_OWNER}
+        </a>
+        .
+      </p>
+      <HydrationBoundary state={state}>
+        <LedgerSections ledgers={SECTIONS} failures={failures} />
+        <MyBalances ledgers={LEDGERS} />
+      </HydrationBoundary>
+    </main>
+  )
+}