@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/canister-studio/src/routes/playground.tsx

@@ -0,0 +1,286 @@
+import { createFileRoute } from "@tanstack/react-router"
+import { useId, useMemo, useState, type ReactElement } from "react"
+import { z } from "zod"
+import { ActionButton } from "../components/ActionButton.tsx"
+import { Card } from "../components/Card.tsx"
+import { useCanisterIdInput } from "../components/canister-id-input.ts"
+import { Notice } from "../components/Notice.tsx"
+import { PlaygroundForms } from "../components/playground/PlaygroundForms.tsx"
+import {
+  PlaygroundCompat,
+  PlaygroundModule,
+  PlaygroundProject,
+} from "../components/playground/PlaygroundTools.tsx"
+import { SAMPLE_DID } from "../components/playground/sample.ts"
+import { ProvenanceBadge } from "../components/ProvenanceBadge.tsx"
+import { RouteError } from "../components/RouteError.tsx"
+import { Spinner } from "../components/Spinner.tsx"
+import { Tabs } from "../components/Tabs.tsx"
+import { useTask } from "../components/use-task.ts"
+import { compileDidInBrowser } from "../interface/browser.ts"
+import { useCanisterInterface } from "../interface/load.ts"
+import type { InterfacePayload } from "../interface/types.ts"
+import { formatByteSize, groupDigits } from "../lib/format.ts"
+import { KNOWN_CANISTERS } from "../lib/registry.ts"
+
+const searchSchema = z.object({
+  // Prefills the target canister (the canister page links here when a
+  // canister publishes no interface). Checked again as it is typed.
+  target: z.string().max(64).optional().catch(undefined),
+})
+
+type ToolTab = "forms" | "typescript" | "project" | "compatibility"
+
+const encoder = new TextEncoder()
+
+/** A message ended as a sentence, so another can follow it. */
+const asSentence = (text: string): string =>
+  /[.!?]$/.test(text) ? text : `${text}.`
+
+export const Route = createFileRoute("/playground")({
+  validateSearch: searchSchema,
+  head: () => ({
+    meta: [
+      { title: "Playground · Canister Studio" },
+      {
+        name: "description",
+        content:
+          "Paste a .did, compile it in the browser, and get forms, a TypeScript module, a projection and a compatibility check against a live canister.",
+      },
+    ],
+  }),
+  errorComponent: (props) => (
+    <RouteError {...props} title="The playground failed" />
+  ),
+  component: PlaygroundPage,
+})
+
+type Compiled = Extract<InterfacePayload, { ok: true }>
+
+function PlaygroundPage(): ReactElement {
+  const search = Route.useSearch()
+  const ids = useId()
+  const [did, setDid] = useState(SAMPLE_DID)
+  const [compiledDid, setCompiledDid] = useState<string | undefined>(undefined)
+  const compile = useTask<InterfacePayload>()
+  const target = useCanisterIdInput(search.target ?? "")
+  const targetId = target.verdict.state === "ok" ? target.verdict.id : undefined
+
+  const runCompile = (): void => {
+    const text = did
+    setCompiledDid(text)
+    compile.run(() => compileDidInBrowser(text))
+  }
+
+  const state = compile.state
+  const payload = state.status === "done" ? state.value : undefined
+
+  return (
+    <div className="page playground">
+      <header className="page-header">
+        <h1 className="page-title">Playground</h1>
+        <p className="page-subtitle">
+          Paste a .did and compile it in your browser (the compiler’s WASM loads
+          on first use). Every method gets a form; give a canister id to call it
+          on mainnet.
+        </p>
+      </header>
+
+      <div className="grid grid-2 pg-inputs">
+        <Card title=".did source" headingLevel={2}>
+          <div className="field">
+            <label htmlFor={`${ids}-did`} className="sr-only">
+              Candid interface
+            </label>
+            <textarea
+              id={`${ids}-did`}
+              className="textarea mono pg-source"
+              spellCheck={false}
+              value={did}
+              onChange={(event) => setDid(event.target.value)}
+              aria-describedby={`${ids}-did-hint`}
+            />
+            <p id={`${ids}-did-hint`} className="field-hint tabular">
+              {formatByteSize(encoder.encode(did).length)}; compiled in this
+              tab, never sent to a server.
+            </p>
+          </div>
+          <div className="row">
+            <ActionButton
+              className="btn btn-primary"
+              onClick={runCompile}
+              unavailable={did.trim() === "" || state.status === "running"}
+            >
+              {state.status === "running" ? "Compiling…" : "Compile"}
+            </ActionButton>
+            <button
+              type="button"
+              className="btn btn-ghost"
+              onClick={() => setDid(SAMPLE_DID)}
+              disabled={did === SAMPLE_DID}
+            >
+              Restore the sample
+            </button>
+            {state.status === "running" && (
+              <Spinner size="sm" label="Compiling" />
+            )}
+            {payload !== undefined && compiledDid !== did && (
+              <span className="text-xs muted">
+                Edited since the last compile.
+              </span>
+            )}
+          </div>
+        </Card>
+
+        <Card title="Target canister (optional)" headingLevel={2}>
+          <div className="field">
+            <label htmlFor={`${ids}-target`} className="field-label">
+              Canister id
+            </label>
+            <input
+              id={`${ids}-target`}
+              className="input mono"
+              type="text"
+              autoComplete="off"
+              autoCapitalize="off"
+              autoCorrect="off"
+              spellCheck={false}
+              placeholder="Leave empty to encode only"
+              list={`${ids}-known`}
+              value={target.text}
+              onChange={(event) => target.setText(event.target.value)}
+              // Leaving the field is when a mistyped id is said to be one:
+              // it is dropped otherwise, and the forms only encode.
+              onBlur={() => {
+                if (target.text.trim() !== "") target.attempt()
+              }}
+              aria-invalid={target.showProblem}
+              aria-describedby={`${ids}-target-hint`}
+            />
+            <datalist id={`${ids}-known`}>
+              {KNOWN_CANISTERS.map((known) => (
+                <option key={known.id} value={known.id}>
+                  {known.name}
+                </option>
+              ))}
+            </datalist>
+            <p
+              id={`${ids}-target-hint`}
+              className={target.showProblem ? "field-error" : "field-hint"}
+            >
+              {target.verdict.state === "invalid"
+                ? target.showProblem
+                  ? `${asSentence(target.verdict.message)} Until it is a canister id, forms only encode.`
+                  : "Not a canister id yet: forms only encode."
+                : targetId !== undefined
+                  ? "Forms call this canister on mainnet."
+                  : "Without one, a form shows the exact Candid message it would send."}
+            </p>
+          </div>
+          {targetId !== undefined && (
+            <Notice tone="warn" title="Nothing ties the paste to this canister">
+              <p>
+                Calls encode with the pasted types and decode replies with them.
+                If the canister’s real interface differs, a call fails (
+                <code className="code-inline">invalid_reply</code>) or worse,
+                means something else: check compatibility first.
+              </p>
+            </Notice>
+          )}
+        </Card>
+      </div>
+
+      {state.status === "failed" && (
+        <Notice tone="danger" title="The compiler did not run">
+          <p className="break-all">{state.message}</p>
+        </Notice>
+      )}
+      {payload !== undefined && !payload.ok && (
+        <CompileFailure payload={payload} />
+      )}
+      {payload !== undefined && payload.ok && compiledDid !== undefined && (
+        <CompiledTools
+          key={payload.didSha256}
+          payload={payload}
+          did={compiledDid}
+          target={targetId}
+        />
+      )}
+    </div>
+  )
+}
+
+function CompileFailure({
+  payload,
+}: {
+  payload: Extract<InterfacePayload, { ok: false }>
+}): ReactElement {
+  return (
+    <Notice tone="danger" title="The .did did not compile">
+      <p className="break-all">{payload.message}</p>
+      {payload.diagnostics !== undefined && payload.diagnostics.length > 0 && (
+        <ul className="list-plain stack-xs">
+          {payload.diagnostics.map((diagnostic, i) => (
+            <li key={`${diagnostic.code}-${i}`} className="break-all">
+              <span className="mono">{diagnostic.code}</span>:{" "}
+              {diagnostic.message}
+            </li>
+          ))}
+        </ul>
+      )}
+    </Notice>
+  )
+}
+
+function CompiledTools({
+  payload,
+  did,
+  target,
+}: {
+  payload: Compiled
+  did: string
+  target: string | undefined
+}): ReactElement {
+  const [tab, setTab] = useState<ToolTab>("forms")
+  // The interface calls the target, or nothing: a pasted interface is
+  // rebuilt per target (its canister id is part of the interface).
+  const targeted = useMemo<Compiled>(
+    () => ({ ...payload, canisterId: target ?? "" }),
+    [payload, target]
+  )
+  const iface = useCanisterInterface(targeted)
+  if (iface === undefined) return <></>
+
+  return (
+    <section className="stack" aria-label="Compiled interface">
+      <div className="row">
+        <ProvenanceBadge source={iface.source} />
+        <span className="text-sm muted">
+          {groupDigits(iface.methods.length)}{" "}
+          {iface.methods.length === 1 ? "method" : "methods"}
+          {iface.omitted.length > 0
+            ? `, ${groupDigits(iface.omitted.length)} left out`
+            : ""}
+        </span>
+      </div>
+      <Tabs<ToolTab>
+        label="Playground tools"
+        selected={tab}
+        onSelect={setTab}
+        tabs={[
+          { key: "forms", label: "Forms" },
+          { key: "typescript", label: "TypeScript" },
+          { key: "project", label: "Project" },
+          { key: "compatibility", label: "Compatibility" },
+        ]}
+      >
+        {tab === "forms" && <PlaygroundForms iface={iface} target={target} />}
+        {tab === "typescript" && <PlaygroundModule did={did} />}
+        {tab === "project" && <PlaygroundProject iface={iface} did={did} />}
+        {tab === "compatibility" && (
+          <PlaygroundCompat key={target ?? ""} did={did} target={target} />
+        )}
+      </Tabs>
+    </section>
+  )
+}

package/examples/canister-studio/src/routes/safety.tsx

@@ -0,0 +1,57 @@
+import { createFileRoute } from "@tanstack/react-router"
+import type { ReactElement } from "react"
+import { RouteError } from "../components/RouteError.tsx"
+import { SafetyLab } from "../safety/SafetyLab.tsx"
+
+const RULES = [
+  "A write from the anonymous principal is refused before anything is sent.",
+  "Arguments that do not encode never leave the browser, and each issue names its field.",
+  "Every failed write says whether it may have executed.",
+  "A write is never retried blindly: the only re-send is the deduplicated one resendOf offers.",
+  "A read made for one caller is never served to another.",
+] as const
+
+export const Route = createFileRoute("/safety")({
+  head: () => ({
+    meta: [
+      { title: "Safety lab · Canister Studio" },
+      {
+        name: "description",
+        content:
+          "Lost replies, traps, 429s, a caller switching mid-flight: each rule ic-reactor enforces, run against an in-memory replica in the browser.",
+      },
+    ],
+  }),
+  errorComponent: (props) => (
+    <RouteError {...props} title="The safety lab failed" />
+  ),
+  component: SafetyPage,
+})
+
+function SafetyPage(): ReactElement {
+  return (
+    <div className="page safety">
+      <header className="page-header">
+        <h1 className="page-title">Safety lab</h1>
+        <p className="page-subtitle">
+          Each scenario runs real ic-reactor calls against an in-memory replica
+          in your browser: a mock ICRC-1 ledger, no network, nothing spent. Run
+          one to see the requests, the error and what the client did about it.
+        </p>
+      </header>
+      <section className="card card-inset" aria-labelledby="rules-title">
+        <div className="card-body">
+          <h2 id="rules-title" className="card-title">
+            What the client guarantees
+          </h2>
+          <ul className="stack-xs text-sm safety-rules">
+            {RULES.map((rule) => (
+              <li key={rule}>{rule}</li>
+            ))}
+          </ul>
+        </div>
+      </section>
+      <SafetyLab />
+    </div>
+  )
+}

package/examples/canister-studio/src/routes/wallet.tsx

@@ -0,0 +1,213 @@
+import { useAuth, useClient } from "@ic-reactor/react"
+import {
+  ClientOnly,
+  createFileRoute,
+  Link,
+  stripSearchParams,
+} from "@tanstack/react-router"
+import type { ReactElement } from "react"
+import { z } from "zod"
+import { Card } from "../components/Card.tsx"
+import { Notice } from "../components/Notice.tsx"
+import { RouteError } from "../components/RouteError.tsx"
+import { SectionBoundary } from "../components/SectionBoundary.tsx"
+import { Skeleton } from "../components/Spinner.tsx"
+import { BalancePanel } from "../components/wallet/BalancePanel.tsx"
+import {
+  LedgerSummary,
+  WithLedgerToken,
+} from "../components/wallet/LedgerSummary.tsx"
+import {
+  ledgerCanister,
+  ledgerMetaReads,
+  minterCanister,
+  WALLET_LEDGER_KEYS,
+  WALLET_LEDGERS,
+  type WalletLedgerKey,
+} from "../components/wallet/ledgers.ts"
+import { MinterPanel } from "../components/wallet/MinterPanel.tsx"
+import { SendPanel } from "../components/wallet/SendPanel.tsx"
+
+const searchSchema = z.object({
+  ledger: z.enum(WALLET_LEDGER_KEYS).default("icp").catch("icp"),
+})
+
+const LEDGER_LABEL: Readonly<Record<WalletLedgerKey, string>> = {
+  icp: "ICP",
+  ckbtc: "ckBTC",
+  cketh: "ckETH",
+}
+
+// How long a server render waits for the ledger's metadata. Past it, the
+// page streams it in instead, until the router's deadline for any server read
+// (SERVER_READ_DEADLINE_MS) cancels what is still in flight.
+const METADATA_BUDGET_MS = 3_000
+
+// Never fails: a read that fails here is never sent to the browser, which
+// reads it again and shows the real error.
+const settle = (pending: Promise<unknown>): Promise<unknown> =>
+  pending.catch(() => undefined)
+
+export const Route = createFileRoute("/wallet")({
+  validateSearch: searchSchema,
+  search: { middlewares: [stripSearchParams({ ledger: "icp" })] },
+  loaderDeps: ({ search }) => ({ ledger: search.ledger }),
+  // The ledger's public metadata is the same for everyone, and the whole
+  // page needs it (amounts are parsed with the ledger's own decimals): the
+  // server waits for it, briefly, so it is in the first HTML; past the
+  // budget it streams. The minter's limits are public too, and waited for
+  // with it: their panel reads without suspending, so nothing would hold the
+  // stream open for them. Balances need a caller, which a server never has,
+  // so they load in the browser after hydration.
+  loader: async ({ context: { reactor, queryClient }, deps }) => {
+    const entry = WALLET_LEDGERS[deps.ledger]
+    const reads = ledgerMetaReads(reactor, entry.id)
+    const pending = [
+      settle(queryClient.query(reads.name)),
+      settle(queryClient.query(reads.symbol)),
+      settle(queryClient.query(reads.decimals)),
+      settle(queryClient.query(reads.fee)),
+    ]
+    if (deps.ledger === "ckbtc") {
+      pending.push(
+        settle(
+          queryClient.query(
+            reactor.queryOptions(minterCanister(reactor), "get_minter_info")
+          )
+        )
+      )
+    }
+    // In the browser the page's skeleton shows the wait instead.
+    if (typeof document !== "undefined") return
+    let timer: ReturnType<typeof setTimeout> | undefined
+    await Promise.race([
+      Promise.all(pending),
+      new Promise((resolve) => {
+        timer = setTimeout(resolve, METADATA_BUDGET_MS)
+      }),
+    ])
+    clearTimeout(timer)
+  },
+  head: ({ match }) => ({
+    meta: [
+      {
+        title: `${LEDGER_LABEL[match.search.ledger]} wallet · Canister Studio`,
+      },
+      {
+        name: "description",
+        content:
+          "A typed wallet over generated ICRC-1 types: caller-scoped balances, a typed transfer form with a confirm step, and the safe re-send after an unknown outcome.",
+      },
+    ],
+  }),
+  errorComponent: (props) => (
+    <RouteError {...props} title="The wallet failed" />
+  ),
+  pendingComponent: () => (
+    <div className="page wallet">
+      <header className="page-header">
+        <h1 className="page-title">Wallet</h1>
+      </header>
+      <WalletSkeleton />
+    </div>
+  ),
+  component: WalletPage,
+})
+
+function WalletPage(): ReactElement {
+  const { ledger } = Route.useSearch()
+  const entry = WALLET_LEDGERS[ledger]
+  const auth = useAuth()
+  const client = useClient()
+  const signedIn = auth.status === "signed-in"
+
+  return (
+    <div className="page wallet">
+      <header className="page-header">
+        <h1 className="page-title">Wallet</h1>
+        <p className="page-subtitle">
+          Hand-written flows over the generated ICRC-1 module: typed reads and
+          writes, no casts. The forms come from the same schemas the calls
+          encode with.
+        </p>
+      </header>
+
+      <nav className="segmented wallet-ledgers" aria-label="Ledger">
+        {WALLET_LEDGER_KEYS.map((key) => (
+          <Link
+            key={key}
+            to="/wallet"
+            search={{ ledger: key }}
+            className="wallet-ledger-link"
+            // The router marks the current one aria-current="page". Exact:
+            // the ICP link's search is stripped to {}, which a partial match
+            // finds in every ledger's search.
+            activeOptions={{ exact: true }}
+            activeProps={{}}
+          >
+            {LEDGER_LABEL[key]}
+          </Link>
+        ))}
+      </nav>
+
+      {!signedIn && (
+        <Notice tone="info" title="You are browsing anonymously">
+          <p>
+            Reads work for anyone. Writes need a signed-in caller: the client
+            refuses a write from the anonymous principal before sending it (
+            <code className="code-inline">unauthenticated</code>), so the send
+            form stays disabled until you sign in.
+          </p>
+        </Notice>
+      )}
+
+      <SectionBoundary
+        label={`The ${LEDGER_LABEL[ledger]} ledger`}
+        fallback={<WalletSkeleton />}
+        resetKey={ledger}
+      >
+        <WithLedgerToken entry={entry}>
+          {(token) => (
+            <div className="grid grid-2 wallet-grid">
+              <div className="stack-lg">
+                <Card
+                  title={entry.name}
+                  subtitle={entry.description}
+                  headingLevel={2}
+                >
+                  <LedgerSummary entry={entry} token={token} />
+                </Card>
+                <Card title="Balance" headingLevel={2}>
+                  {/* A server has no caller: the balance is browser-only. */}
+                  <ClientOnly fallback={<Skeleton height="3rem" />}>
+                    <BalancePanel key={entry.id} entry={entry} token={token} />
+                  </ClientOnly>
+                </Card>
+              </div>
+              <Card
+                title={`Send ${token.symbol}`}
+                subtitle="icrc1_transfer, typed: TypedForm<TransferArg>"
+                headingLevel={2}
+              >
+                {/* Server-rendered too: disabled until a caller signs in. */}
+                <SendPanel key={entry.id} entry={entry} token={token} />
+              </Card>
+            </div>
+          )}
+        </WithLedgerToken>
+      </SectionBoundary>
+
+      {ledger === "ckbtc" && <MinterPanel />}
+    </div>
+  )
+}
+
+function WalletSkeleton(): ReactElement {
+  return (
+    <div className="grid grid-2 wallet-grid" aria-busy="true">
+      <span className="sr-only">Loading the ledger</span>
+      <Skeleton height="14rem" />
+      <Skeleton height="20rem" />
+    </div>
+  )
+}

package/examples/canister-studio/src/safety/LabTransferForm.tsx

@@ -0,0 +1,84 @@
+import { useMemo, useState, type JSX } from "react"
+import { ErrorPanel } from "../calls/ErrorPanel.tsx"
+import { issuesFromReactorError } from "../forms/engine.ts"
+import { heuristicHints } from "../forms/hints.ts"
+import { MethodForm } from "../forms/MethodForm.tsx"
+import type { MethodInfo } from "../interface/types.ts"
+import { groupDigits } from "../lib/format.ts"
+import { LAB_UNITS, labMethod } from "./mock-ledger.ts"
+import { RequestLog } from "./RequestLog.tsx"
+import { sendTransferInLab, type LabSend } from "./scenarios.ts"
+
+const HINTS = heuristicHints({ units: LAB_UNITS })
+
+type SendState =
+  | { readonly status: "idle" }
+  | { readonly status: "sending" }
+  | { readonly status: "done"; readonly outcome: LabSend }
+
+/**
+ * The refused transfer in the studio's automatic form, with the
+ * `invalid_args` issues on the fields their `$args[0]…` paths name. Fixing
+ * them and submitting sends the corrected transfer to a fresh lab.
+ */
+export function LabTransferForm(props: {
+  readonly method: string
+  readonly values: readonly unknown[]
+  readonly error: unknown
+}): JSX.Element {
+  const method: MethodInfo | undefined = labMethod(props.method)
+  const issues = useMemo(
+    () => issuesFromReactorError(props.error),
+    [props.error]
+  )
+  const [state, setState] = useState<SendState>({ status: "idle" })
+
+  if (method === undefined) {
+    return <p className="muted">The mock ledger has no {props.method}.</p>
+  }
+
+  const submit = (call: { vars: unknown }): void => {
+    setState({ status: "sending" })
+    void sendTransferInLab(call.vars).then((outcome) =>
+      setState({ status: "done", outcome })
+    )
+  }
+
+  return (
+    <div className="stack">
+      <MethodForm
+        method={method}
+        hints={HINTS}
+        initialValues={props.values}
+        externalIssues={issues}
+        submitLabel="Send the corrected transfer in the lab"
+        busy={state.status === "sending"}
+        onSubmit={submit}
+      />
+      {state.status === "done" && (
+        <div className="stack-sm" aria-live="polite">
+          {state.outcome.ok ? (
+            <div className="notice notice-success" role="status">
+              <p className="notice-title">Sent: it encodes now</p>
+              <p>
+                The lab ledger answered Ok with block index{" "}
+                <span className="mono">{groupDigits(state.outcome.block)}</span>
+                .
+              </p>
+            </div>
+          ) : (
+            <ErrorPanel
+              error={state.outcome.error}
+              method={method}
+              units={LAB_UNITS}
+            />
+          )}
+          <RequestLog
+            requests={state.outcome.requests}
+            caption="Requests of the corrected transfer"
+          />
+        </div>
+      )}
+    </div>
+  )
+}