@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/next-ssr/src/server/prefetch-ledgers.ts

@@ -0,0 +1,70 @@
+// Scenario 1: server prefetch with `{ id }` targets, handed to the browser.
+//
+// Rules:
+// - Keys come only from the client: every read is
+//   `client.queryOptions(ledger, method)`, never a key written by hand.
+// - A server has no `ic_env` cookie, so every canister is an `{ id }` target.
+// - `dehydrate(client.queryClient)` is JSON-safe as it is: the client's
+//   `QueryClient` dehydrates `bigint`, `Uint8Array` and the floats JSON cannot
+//   write into tagged JSON, and hydrates them back exactly (scenario 3).
+//
+// The page renders the result's `state` in a `<HydrationBoundary>`, so the
+// cards' `useQuery` calls find their data in the cache on the server render
+// and on the browser's first render. A failed read is not dehydrated (TanStack
+// dehydrates successful queries only); its ledger is in `failures`, and the
+// page renders that ledger's error on the server (scenario 8).
+import type { Client } from "@ic-reactor/core"
+import { dehydrate, type DehydratedState } from "@tanstack/react-query"
+import { actor, type Actor } from "@/canisters/icrc1"
+import type { LedgerRef } from "@/ledgers"
+import { summarizeError, type ErrorSummary } from "./error-summary"
+
+/** The reads of a ledger's card. None takes an argument. */
+export const TOKEN_READS = [
+  "icrc1_name",
+  "icrc1_symbol",
+  "icrc1_decimals",
+  "icrc1_fee",
+  "icrc1_total_supply",
+  "icrc1_minting_account",
+  "icrc1_metadata",
+] as const
+
+export interface PrefetchedLedgers {
+  /** The client's cache, dehydrated: plain JSON, for a `<HydrationBoundary>`. */
+  readonly state: DehydratedState
+  /** The ledgers whose reads failed, by canister id, with the first failure. */
+  readonly failures: Readonly<Record<string, ErrorSummary>>
+}
+
+/**
+ * Reads every token read of every ledger into `client`'s cache, then
+ * dehydrates it. `client` is the request's own (src/server/request-client.ts);
+ * nothing here holds a client of its own.
+ */
+export async function prefetchLedgers(
+  client: Client,
+  ledgers: readonly LedgerRef[]
+): Promise<PrefetchedLedgers> {
+  const reads = ledgers.flatMap(({ id }) => {
+    const ledger = client.canister<Actor>(actor, { id })
+    return TOKEN_READS.map((method) => ({
+      id,
+      options: client.queryOptions(ledger, method),
+    }))
+  })
+  // `prefetchQuery` never throws: a failed read stays in the cache with its
+  // error, read back below. A server never retries a read.
+  await Promise.all(
+    reads.map(({ options }) => client.queryClient.prefetchQuery(options))
+  )
+
+  const failures: Record<string, ErrorSummary> = {}
+  for (const { id, options } of reads) {
+    const error = client.queryClient.getQueryState(options.queryKey)?.error
+    if (error != null && failures[id] === undefined) {
+      failures[id] = summarizeError(error)
+    }
+  }
+  return { state: dehydrate(client.queryClient), failures }
+}

package/examples/next-ssr/src/server/read-balances.test.ts

@@ -0,0 +1,103 @@
+// Scenarios 5 and 6 on the server: the /account page's reads. Plain reads are
+// queries; certified ones are replicated calls with keys of their own; a
+// failing ledger costs one row; and one request reads a ledger's decimals and
+// symbol once, whichever section asks.
+import { principal } from "@meantjs/schema"
+import { formatUnits } from "@ic-reactor/core"
+import { afterEach, describe, expect, it } from "vitest"
+import { actor, type Actor } from "@/canisters/icrc1"
+import { LEDGERS, NOT_A_LEDGER, SAMPLE_OWNER } from "@/ledgers"
+import {
+  BALANCES,
+  mockLedgers,
+  requestsFor,
+  tokenOf,
+  type MockLedgers,
+} from "@/testing/mock-ledgers"
+import { readBalances } from "./read-balances"
+
+const OWNER = principal(SAMPLE_OWNER)
+const EXPECTED = BALANCES.get(OWNER) ?? 0n
+
+let server: MockLedgers
+afterEach(() => server.client.dispose())
+
+describe("readBalances", () => {
+  it("reads the owner's balance, decimals and symbol on every ledger, as queries", async () => {
+    server = mockLedgers()
+
+    const rows = await readBalances(server.client, OWNER, LEDGERS)
+
+    expect(rows).toEqual(
+      LEDGERS.map((ledger) => ({
+        ledger,
+        ok: true,
+        balance: EXPECTED,
+        decimals: tokenOf(ledger).decimals,
+        symbol: tokenOf(ledger).symbol,
+      }))
+    )
+    const balances = requestsFor(server, "icrc1_balance_of")
+    expect(balances.map(({ endpoint }) => endpoint)).toEqual(
+      LEDGERS.map(() => "query")
+    )
+    // Exact past 2^53: 12345678901234567890123 base units.
+    expect(formatUnits(EXPECTED, 8)).toBe("123456789012345.67890123")
+  })
+
+  it("certified, sends every read as a replicated call and caches it under its own keys", async () => {
+    server = mockLedgers()
+
+    const rows = await readBalances(server.client, OWNER, LEDGERS, {
+      certified: true,
+    })
+
+    expect(rows.every((row) => row.ok)).toBe(true)
+    for (const method of [
+      "icrc1_balance_of",
+      "icrc1_decimals",
+      "icrc1_symbol",
+    ]) {
+      expect(
+        requestsFor(server, method).map(({ endpoint }) => endpoint)
+      ).toEqual(LEDGERS.map(() => "call"))
+    }
+    const ledger = server.client.canister<Actor>(actor, {
+      id: LEDGERS[0]!.id,
+      certified: true,
+    })
+    const key = server.client.queryOptions(ledger, "icrc1_balance_of", {
+      owner: OWNER,
+      subaccount: null,
+    }).queryKey
+    expect(key.at(-1)).toBe("certified")
+    expect(server.client.queryClient.getQueryData(key)).toBe(EXPECTED)
+  })
+
+  it("gives a failing ledger a row with its kind, and the others their balances", async () => {
+    server = mockLedgers()
+
+    const rows = await readBalances(server.client, OWNER, [
+      ...LEDGERS,
+      NOT_A_LEDGER,
+    ])
+
+    expect(rows.slice(0, LEDGERS.length).every((row) => row.ok)).toBe(true)
+    expect(rows.at(-1)).toMatchObject({
+      ledger: NOT_A_LEDGER,
+      ok: false,
+      error: { kind: "rejected", rejectCode: 5 },
+    })
+  })
+
+  it("reads decimals and symbol once per request, however many sections ask", async () => {
+    server = mockLedgers()
+
+    // The page's section and a second one in the same request.
+    await readBalances(server.client, OWNER, LEDGERS)
+    await readBalances(server.client, OWNER, LEDGERS)
+
+    expect(requestsFor(server, "icrc1_decimals")).toHaveLength(LEDGERS.length)
+    expect(requestsFor(server, "icrc1_symbol")).toHaveLength(LEDGERS.length)
+  })
+})

package/examples/next-ssr/src/server/read-balances.ts

@@ -0,0 +1,78 @@
+// The balances of one account across the ledgers, read on the server for the
+// /account page: as plain queries for the section the page waits for
+// (scenario 6), and as certified reads for the section that streams in
+// (scenario 5).
+//
+// Rules:
+// - Reads go through the request client's cache, with
+//   `client.queryClient.fetchQuery(client.queryOptions(...))`.
+//   `icrc1_decimals` and `icrc1_symbol` do not change mid-render, so they come
+//   from `ensureQueryData`: a Server Component of the same request that found
+//   them already read would not ask again. A certified canister is another
+//   object with keys of its own (they end in "certified"), so the certified
+//   section reads its own: an uncertified answer is never served where a
+//   certified one was asked for.
+// - Each ledger fails alone: its row carries the `ReactorError` kind, and the
+//   other rows still render.
+import type { Principal } from "@meantjs/schema"
+import type { Client } from "@ic-reactor/core"
+import { actor, type Actor } from "@/canisters/icrc1"
+import type { LedgerRef } from "@/ledgers"
+import { summarizeError, type ErrorSummary } from "./error-summary"
+
+/** One ledger's answer for an account, or why there is none. */
+export type BalanceRow =
+  | {
+      readonly ledger: LedgerRef
+      readonly ok: true
+      /** Base units: format them with `decimals`, never as a `number`. */
+      readonly balance: bigint
+      readonly decimals: number
+      readonly symbol: string
+    }
+  | {
+      readonly ledger: LedgerRef
+      readonly ok: false
+      readonly error: ErrorSummary
+    }
+
+/**
+ * The default account (no subaccount) of `owner` on each ledger.
+ *
+ * @param options.certified - Read through consensus, so every reply is
+ * certified: slower (a replicated call takes a second or two), and cached
+ * under keys of its own.
+ */
+export async function readBalances(
+  client: Client,
+  owner: Principal,
+  ledgers: readonly LedgerRef[],
+  options: { readonly certified?: boolean } = {}
+): Promise<BalanceRow[]> {
+  const certified = options.certified ?? false
+  return Promise.all(
+    ledgers.map(async (ref): Promise<BalanceRow> => {
+      const ledger = client.canister<Actor>(actor, { id: ref.id, certified })
+      try {
+        const [balance, decimals, symbol] = await Promise.all([
+          client.queryClient.fetchQuery(
+            client.queryOptions(ledger, "icrc1_balance_of", {
+              owner,
+              subaccount: null,
+            })
+          ),
+          // Taken from this request's cache when it holds them already.
+          client.queryClient.ensureQueryData(
+            client.queryOptions(ledger, "icrc1_decimals")
+          ),
+          client.queryClient.ensureQueryData(
+            client.queryOptions(ledger, "icrc1_symbol")
+          ),
+        ])
+        return { ledger: ref, ok: true, balance, decimals, symbol }
+      } catch (error) {
+        return { ledger: ref, ok: false, error: summarizeError(error) }
+      }
+    })
+  )
+}

package/examples/next-ssr/src/server/request-client.rsc.test.tsx

@@ -0,0 +1,110 @@
+// Scenario 1: one client per request, as Next runs Server Components.
+//
+// This file runs in vitest's "react-server" project (vitest.config.ts): `react`
+// is React's server build, and the real /account page is rendered by React's
+// Flight server (`react-server-dom-turbopack`, the renderer behind Next's
+// default bundler) into the payload Next sends for a request. So React's
+// `cache()` in src/server/request-client.ts memoizes exactly as it does in a
+// Next request, which no renderer of HTML does.
+//
+// `createClient` is replaced by a test client over the mocked ledgers, so the
+// test counts the clients a request builds and reads which client served
+// which read. `next/form` and `next/link` are client components; without
+// Next's bundler they would run here as server code, so they are plain
+// elements.
+import type { ClientOptions } from "@ic-reactor/core"
+import type { ComponentProps } from "react"
+import { renderToReadableStream } from "react-server-dom-turbopack/server"
+import { afterEach, describe, expect, it, vi } from "vitest"
+import { LEDGERS, SAMPLE_OWNER } from "@/ledgers"
+import { requestsFor, type MockLedgers } from "@/testing/mock-ledgers"
+import AccountPage from "@/app/account/page"
+
+const built = vi.hoisted(() => ({
+  /** Every test client `createClient` returned, in order, with its options. */
+  clients: [] as { options: unknown; test: MockLedgers }[],
+}))
+
+vi.mock("@ic-reactor/core", async (importOriginal) => {
+  const real = await importOriginal<typeof import("@ic-reactor/core")>()
+  const { mockLedgers } = await import("@/testing/mock-ledgers")
+  return {
+    ...real,
+    createClient: (options: ClientOptions) => {
+      const test = mockLedgers()
+      built.clients.push({ options, test })
+      return test.client
+    },
+  }
+})
+vi.mock("next/form", () => ({
+  default: (props: ComponentProps<"form">) => <form {...props} />,
+}))
+vi.mock("next/link", () => ({
+  default: (props: ComponentProps<"a">) => <a {...props} />,
+}))
+
+afterEach(() => {
+  for (const { test } of built.clients.splice(0)) test.client.dispose()
+})
+
+/** Renders /account?owner=... as one request, to the end of its payload. */
+async function request(owner: string): Promise<string> {
+  const errors: unknown[] = []
+  const stream = renderToReadableStream(
+    <AccountPage searchParams={Promise.resolve({ owner })} />,
+    {},
+    { onError: (error) => void errors.push(error) }
+  )
+  const payload = await new Response(stream).text()
+  expect(errors).toEqual([])
+  return payload
+}
+
+const endpointsOf = (test: MockLedgers, method: string) =>
+  requestsFor(test, method).map(({ endpoint }) => endpoint)
+
+describe("requestClient() in a server request", () => {
+  it("gives the page and the section it streams one anonymous mainnet client", async () => {
+    const payload = await request(SAMPLE_OWNER)
+
+    // Both sections rendered...
+    expect(payload).toContain('"data-section":"balances"')
+    expect(payload).toContain('"data-section":"certified"')
+    // ...from one client, built once for the request.
+    expect(built.clients).toHaveLength(1)
+    const [{ options, test }] = built.clients as [(typeof built.clients)[0]]
+    expect(options).toEqual({ network: "ic", identity: "anonymous" })
+    // Its replica answered the page's queries and the streamed section's
+    // replicated calls. The two share no read: a certified canister's keys
+    // are its own, so the section reads `icrc1_decimals` again, certified.
+    expect(endpointsOf(test, "icrc1_balance_of").sort()).toEqual([
+      ...LEDGERS.map(() => "call"),
+      ...LEDGERS.map(() => "query"),
+    ])
+    expect(endpointsOf(test, "icrc1_decimals").sort()).toEqual([
+      ...LEDGERS.map(() => "call"),
+      ...LEDGERS.map(() => "query"),
+    ])
+  })
+
+  it("builds a new client, with a cache of its own, for the next request", async () => {
+    await request(SAMPLE_OWNER)
+    await request(SAMPLE_OWNER)
+
+    expect(built.clients).toHaveLength(2)
+    const [first, second] = built.clients as [
+      (typeof built.clients)[0],
+      (typeof built.clients)[0],
+    ]
+    expect(second.test.client).not.toBe(first.test.client)
+    expect(second.test.client.queryClient).not.toBe(
+      first.test.client.queryClient
+    )
+    // The second request read everything itself: nothing came from the
+    // first request's cache.
+    expect(requestsFor(second.test, "icrc1_balance_of")).toHaveLength(
+      LEDGERS.length * 2
+    )
+  })
+})

package/examples/next-ssr/src/server/request-client.ts

@@ -0,0 +1,24 @@
+// Scenario 1: one client per request on the server.
+//
+// Rule: a server builds its client inside the request, never at module scope.
+// A client owns a cache and the agents it calls with, and query keys carry
+// the caller but not the visitor: a client in this module's scope would be
+// shared by every request the server ever handles.
+//
+// React's `cache()` memoizes for the length of one server request: the page
+// and every Server Component it renders (the streamed section of /account
+// included) get the same client, and the next request gets a new one
+// (./request-client.rsc.test.tsx renders /account as Next does to check
+// both). Outside a request, in a script or a plain test, every call builds a
+// new client. The
+// client is anonymous (`identity: "anonymous"`): a server holds no session, and
+// a read-only client refuses every update before sending it. There is nothing
+// to dispose afterwards: it built no auth, and a server's `QueryClient` sets no
+// timers, so the client is garbage once the request is done.
+import { createClient, type Client } from "@ic-reactor/core"
+import { cache } from "react"
+
+/** This request's client: the same one for every caller within a request. */
+export const requestClient = cache((): Client =>
+  createClient({ network: "ic", identity: "anonymous" })
+)

package/examples/next-ssr/src/testing/mock-ledgers.ts

@@ -0,0 +1,115 @@
+// The tests' stand-in for mainnet: a real client from `createTestClient()`
+// (`@ic-reactor/core/testing`) over an in-memory replica, with the three
+// ledgers and the not-a-ledger canister of src/ledgers.ts mocked at their real
+// ids. Each call makes a new client and replica, so a test builds one for the
+// server's request and another for the browser tab, as the app has.
+//
+// The mocked values include what JSON cannot carry: amounts past 2^53, a
+// negative `int`, a 32-byte subaccount and a `Blob` metadata entry, so that a
+// test sees them come back exactly after dehydration. `icrc1_name` answers
+// with the caller it saw, so a test can tell whose read a card shows.
+import { principal, type Principal } from "@meantjs/schema"
+import { createTestClient, type TestHandlers } from "@ic-reactor/core/testing"
+import { actor, type Account, type Actor } from "@/canisters/icrc1"
+import { LEDGERS, NOT_A_LEDGER, SAMPLE_OWNER, type LedgerRef } from "@/ledgers"
+
+export const ANONYMOUS = principal("2vxsx-fae")
+/** The principals of the test identities of seeds 1 and 2. */
+export const SEED_1 = principal(
+  "psith-oknjz-x73tv-7x3p4-a2sji-7o6lo-g2754-yfgfl-3vlqe-irrrt-4ae"
+)
+export const SEED_2 = principal(
+  "xledz-fktfc-4ywwn-gai5u-ieqce-5x4qc-7lpel-o4ubn-ucngz-7lrzo-5ae"
+)
+
+/** What each mocked ledger answers; `supply` is past 2^53 on purpose. */
+export interface MockToken {
+  readonly name: string
+  readonly symbol: string
+  readonly decimals: number
+  readonly fee: bigint
+  readonly supply: bigint
+  readonly minter: Account
+  readonly blob: Uint8Array
+}
+
+const MINTER = principal("rrkah-fqaaa-aaaaa-aaaaq-cai")
+
+/** The mocked token of each ledger of src/ledgers.ts, by canister id. */
+export const TOKENS: ReadonlyMap<string, MockToken> = new Map(
+  LEDGERS.map((ledger, index) => [
+    ledger.id,
+    {
+      name: `${ledger.label} test ledger`,
+      symbol: ledger.label,
+      decimals: ledger.label === "ckETH" ? 18 : 8,
+      fee: 10_000n + BigInt(index),
+      supply: 2n ** 70n + BigInt(index),
+      minter: {
+        owner: MINTER,
+        subaccount: new Uint8Array(32).fill(index + 1),
+      },
+      blob: new Uint8Array([0, 1, 127, 128, 254, 255, index]),
+    },
+  ])
+)
+
+/** The balance of each owner's default account, on every mocked ledger. */
+export const BALANCES: ReadonlyMap<Principal, bigint> = new Map([
+  [principal(SAMPLE_OWNER), 12_345_678_901_234_567_890_123n],
+  [SEED_1, 150_000_000n],
+  [SEED_2, 42n],
+])
+
+export const tokenOf = (ledger: LedgerRef): MockToken => {
+  const token = TOKENS.get(ledger.id)
+  if (token === undefined) throw new Error(`no mocked token for ${ledger.id}`)
+  return token
+}
+
+/** The handlers of a mocked ledger: a test can spread them and replace one. */
+export function ledgerHandlers(token: MockToken): TestHandlers<Actor> {
+  return {
+    icrc1_name: (ctx) => `${token.name}, read by ${ctx.caller}`,
+    icrc1_symbol: () => token.symbol,
+    icrc1_decimals: () => token.decimals,
+    icrc1_fee: () => token.fee,
+    icrc1_total_supply: () => token.supply,
+    icrc1_minting_account: () => token.minter,
+    icrc1_metadata: () => [
+      ["icrc1:fee", { tag: "Nat", value: token.fee }],
+      ["test:int", { tag: "Int", value: -(2n ** 64n) }],
+      ["test:blob", { tag: "Blob", value: token.blob }],
+    ],
+    icrc1_balance_of: ({ owner, subaccount }) =>
+      subaccount === null ? (BALANCES.get(owner) ?? 0n) : 0n,
+  }
+}
+
+/**
+ * A test client over a replica that runs the mocked ledgers, and NNS
+ * governance at its real id with none of their methods (every read of it
+ * traps, reject code 5, as on mainnet).
+ *
+ * @param options.signedIn - Whether the client starts signed in as seed 1.
+ * The server's client and a visitor's first load are not.
+ */
+export function mockLedgers(options: { signedIn?: boolean } = {}) {
+  const test = createTestClient({
+    network: "ic",
+    identity: 1,
+    signedIn: options.signedIn ?? false,
+  })
+  for (const ledger of LEDGERS) {
+    test.mock<Actor>(actor, ledger.id, ledgerHandlers(tokenOf(ledger)))
+  }
+  test.mock<Actor>(actor, NOT_A_LEDGER.id, {})
+  return test
+}
+
+/** A test client and its replica, as `mockLedgers()` returns them. */
+export type MockLedgers = ReturnType<typeof mockLedgers>
+
+/** The requests a test client's replica answered for `method`, if any. */
+export const requestsFor = (test: MockLedgers, method: string) =>
+  test.requests.filter((request) => request.methodName === method)

package/examples/next-ssr/src/testing/react-server-dom-turbopack.d.ts

@@ -0,0 +1,15 @@
+// The part of React's Flight server (`react-server-dom-turbopack`, which ships
+// no types) that src/server/request-client.rsc.test.tsx renders with.
+declare module "react-server-dom-turbopack/server" {
+  import type { ReactNode } from "react"
+
+  /**
+   * Renders a Server Component tree to the RSC payload, as Next does for a
+   * request: React's `cache()` memoizes for the length of this render.
+   */
+  export function renderToReadableStream(
+    model: ReactNode,
+    turbopackMap?: Record<string, never>,
+    options?: { onError?: (error: unknown) => void }
+  ): ReadableStream<Uint8Array>
+}

package/examples/next-ssr/src/testing/setup.ts

@@ -0,0 +1,10 @@
+// Every read in these tests goes through a real client to an in-memory
+// replica that signs each reply, and the client checks those signatures: a
+// few reads take tens of milliseconds on a laptop, and several times that on
+// a CI runner that runs the examples' suites side by side. testing-library's
+// `waitFor` gives up after 1 s by default, which a slow runner can exceed with
+// nothing wrong; 5 s leaves room for that and still fails a read that never
+// lands.
+import { configure } from "@testing-library/react"
+
+configure({ asyncUtilTimeout: 5_000 })

package/examples/next-ssr/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "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,
+    "allowJs": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": true,
+    "erasableSyntaxOnly": true,
+    "incremental": true,
+    "types": ["node"],
+    "plugins": [{ "name": "next" }],
+    "paths": { "@/*": ["./src/*"] }
+  },
+  "include": [
+    "next-env.d.ts",
+    "**/*.ts",
+    "**/*.tsx",
+    ".next/types/**/*.ts",
+    ".next/dev/types/**/*.ts"
+  ],
+  "exclude": ["node_modules"]
+}

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

@@ -0,0 +1,59 @@
+import { fileURLToPath } from "node:url"
+import { configDefaults, defineConfig } from "vitest/config"
+
+const SERVER_COMPONENT_TESTS = "src/**/*.rsc.test.{ts,tsx}"
+
+// The tests run over the committed generated module (`pnpm gen:check` keeps
+// it current) and never reach mainnet: every client in them is a
+// `createTestClient()` over an in-memory replica. Server modules run in Node;
+// a test that renders for the browser says `@vitest-environment 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".
+//
+// A `*.rsc.test.tsx` file runs in the "react-server" project, as Next runs
+// Server Components: with the `react-server` export condition, so `react` is
+// React's server build, whose `cache()` memoizes for one request. Vitest
+// resolves with `ssr.resolve.conditions`, and passes them to Node as
+// `--conditions` for the packages Node loads itself (React's Flight server
+// among them). The list is Vite's default for a server plus `react-server`.
+export default defineConfig({
+  resolve: { alias: { "@": fileURLToPath(new URL("./src", import.meta.url)) } },
+  test: {
+    // Every read signs and verifies a reply on the in-memory replica; the
+    // streaming test holds reads on purpose. 5 s, Vitest's default, is short
+    // for a loaded CI runner.
+    testTimeout: 20_000,
+    projects: [
+      {
+        extends: true,
+        test: {
+          name: "app",
+          environment: "node",
+          include: ["src/**/*.test.{ts,tsx}"],
+          setupFiles: ["src/testing/setup.ts"],
+          exclude: [...configDefaults.exclude, SERVER_COMPONENT_TESTS],
+        },
+      },
+      {
+        extends: true,
+        ssr: {
+          resolve: {
+            conditions: [
+              "react-server",
+              "module",
+              "node",
+              "development|production",
+            ],
+          },
+        },
+        test: {
+          name: "react-server",
+          environment: "node",
+          include: [SERVER_COMPONENT_TESTS],
+        },
+      },
+    ],
+  },
+})

package/examples/node-agent-tool/.stackblitzrc

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