@ic-reactor/mcp 0.0.0-stage → 0.0.0

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

@@ -0,0 +1,58 @@
+/// <reference types="vite/client" />
+import {
+  createRootRouteWithContext,
+  HeadContent,
+  Outlet,
+  Scripts,
+} from "@tanstack/react-router"
+import type { ReactElement, ReactNode } from "react"
+import { AppShell } from "../components/AppShell.tsx"
+import type { RouterContext } from "../router.tsx"
+import stylesUrl from "../styles.css?url"
+
+// The brand mark as the tab icon, inline: the app serves no static files.
+const FAVICON = `data:image/svg+xml,${encodeURIComponent(
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><rect x="2" y="2" width="20" height="20" rx="6" fill="#4f46e5"/><path d="M8 9.5 5.5 12 8 14.5M16 9.5l2.5 2.5-2.5 2.5M13.2 8l-2.4 8" fill="none" stroke="#fff" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"/></svg>'
+)}`
+
+export const Route = createRootRouteWithContext<RouterContext>()({
+  head: () => ({
+    meta: [
+      { charSet: "utf-8" },
+      { name: "viewport", content: "width=device-width, initial-scale=1" },
+      { title: "Canister Studio" },
+      {
+        name: "description",
+        content:
+          "Automatic forms and safe calls for any Internet Computer canister: typed canisters, live certified interfaces, server-rendered results.",
+      },
+      { name: "color-scheme", content: "light dark" },
+    ],
+    links: [
+      { rel: "stylesheet", href: stylesUrl },
+      { rel: "icon", type: "image/svg+xml", href: FAVICON },
+    ],
+  }),
+  shellComponent: RootDocument,
+  component: RootLayout,
+})
+
+function RootLayout(): ReactElement {
+  return <Outlet />
+}
+
+// The document itself. The shell wraps every route's component, and its
+// not-found and error components too, so the app frame stays on those pages.
+function RootDocument({ children }: { children: ReactNode }): ReactElement {
+  return (
+    <html lang="en">
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        <AppShell>{children}</AppShell>
+        <Scripts />
+      </body>
+    </html>
+  )
+}

package/examples/canister-studio/src/routes/canister.$canisterId.index.tsx

@@ -0,0 +1,172 @@
+import { createFileRoute, stripSearchParams } from "@tanstack/react-router"
+import { useRef, type ReactElement } from "react"
+import { MethodList } from "../components/MethodList.tsx"
+import { Skeleton } from "../components/Spinner.tsx"
+import { MethodOverview } from "../components/canister/MethodOverview.tsx"
+import { MethodWorkspace } from "../components/canister/MethodWorkspace.tsx"
+import {
+  decodeSharedArgs,
+  methodSearchSchema,
+  readsAtOnce,
+  readWithin,
+  SHARED_READ_BUDGET_MS,
+} from "../components/canister/shared-call.ts"
+import { useCanisterPage } from "../components/canister/use-canister-page.ts"
+import {
+  pickMountsWorkspace,
+  workspaceKey,
+  type WorkspaceTarget,
+} from "../components/canister/workspace-key.ts"
+import { canisterDisplayName } from "../components/canister-names.ts"
+import { callKindOf } from "../calls/kinds.ts"
+import { readQueryOptions } from "../calls/query-options.ts"
+import { interfaceFromPayload } from "../interface/load.ts"
+import { toVars, type DynActor } from "../lib/reactor.ts"
+
+export const Route = createFileRoute("/canister/$canisterId/")({
+  validateSearch: methodSearchSchema,
+  search: {
+    middlewares: [stripSearchParams({ run: false, certified: false })],
+  },
+  loaderDeps: ({ search }) => ({
+    method: search.method,
+    args: search.args,
+    run: search.run === true,
+    certified: search.certified === true,
+  }),
+  // A shared query link (`?method=…&args=<hex>&run=1`): decode the arguments
+  // against the method's schemas and read it, so its result is in the
+  // server-rendered HTML and hydrates under the very key the page's runner
+  // asks for. Only what the runner reads at once (`readsAtOnce`), never a
+  // write. The read is bounded and can never fail the page: nothing here
+  // throws or rejects.
+  loader: async ({ context, params, deps, parentMatchPromise }) => {
+    if (!deps.run || deps.method === undefined || deps.args === undefined) {
+      return
+    }
+    const parent = await parentMatchPromise
+    const payload = parent.loaderData?.payload
+    if (payload === undefined || !payload.ok) return
+    let iface
+    try {
+      iface = interfaceFromPayload(payload)
+    } catch {
+      return
+    }
+    const method = iface.method(deps.method)
+    if (method === undefined) return
+    // The runner explains whatever it does not read at once: a query
+    // without results, a composite query asked certified, a write.
+    if (!readsAtOnce(callKindOf(iface, method), deps.certified)) return
+    const args = decodeSharedArgs(method, deps.args)
+    if (!args.ok) return
+
+    const { reactor, queryClient } = context
+    let options
+    try {
+      const can = reactor.canister<DynActor>(iface.actor, {
+        id: params.canisterId,
+        certified: deps.certified,
+      })
+      options = readQueryOptions(reactor, can, method, toVars(args.values))
+    } catch {
+      // Options the client refuses are the runner's to explain, never a
+      // reason to fail the page.
+      return
+    }
+    const run = () => queryClient.query(options)
+    if (typeof document === "undefined") {
+      await readWithin(
+        queryClient,
+        options.queryKey,
+        run,
+        SHARED_READ_BUDGET_MS
+      )
+    } else {
+      // In the browser the runner shows the read's progress itself.
+      run().catch(() => undefined)
+    }
+  },
+  head: ({ match, params }) => {
+    const name = canisterDisplayName(params.canisterId)
+    const method = match.search.method
+    return {
+      meta: [
+        {
+          title:
+            method === undefined
+              ? `${name} · Canister Studio`
+              : `${method} · ${name} · Canister Studio`,
+        },
+      ],
+    }
+  },
+  // Shown on a client navigation that waits for the parent's interface.
+  pendingComponent: MethodsPending,
+  component: MethodsPage,
+})
+
+function MethodsPage(): ReactElement {
+  const search = Route.useSearch()
+  const { iface } = useCanisterPage()
+  // Set when the reader picks a method on this page (the list, a quick
+  // read); the next workspace takes it once, to bring itself into view.
+  const picked = useRef(false)
+  if (iface === undefined) return <></>
+  const method =
+    search.method === undefined ? undefined : iface.method(search.method)
+  const onPick = (target: WorkspaceTarget): void => {
+    picked.current = pickMountsWorkspace(search, target)
+  }
+  const wasPicked = (): boolean => {
+    const was = picked.current
+    picked.current = false
+    return was
+  }
+  return (
+    <div className="layout-sidebar canister-workspace">
+      <aside className="sidebar" aria-label="Methods">
+        <MethodList
+          canisterId={iface.canisterId}
+          methods={iface.methods}
+          selected={method?.name}
+          idempotent={iface.registry?.idempotentUpdates}
+          certified={search.certified}
+          onPick={onPick}
+        />
+      </aside>
+      <div className="content">
+        {search.method === undefined ? (
+          <MethodOverview iface={iface} onPick={onPick} />
+        ) : (
+          <MethodWorkspace
+            key={workspaceKey(search)}
+            iface={iface}
+            methodName={search.method}
+            method={method}
+            argsHex={search.args}
+            run={search.run === true}
+            certified={search.certified === true}
+            wasPicked={wasPicked}
+          />
+        )}
+      </div>
+    </div>
+  )
+}
+
+function MethodsPending(): ReactElement {
+  return (
+    <div className="layout-sidebar canister-workspace" aria-busy="true">
+      <div className="sidebar stack-sm">
+        {Array.from({ length: 8 }, (_, i) => (
+          <Skeleton key={i} height="1.6rem" />
+        ))}
+      </div>
+      <div className="content stack">
+        <Skeleton height="2rem" width="min(320px, 70%)" />
+        <Skeleton height="14rem" />
+      </div>
+    </div>
+  )
+}

package/examples/canister-studio/src/routes/canister.$canisterId.interface.tsx

@@ -0,0 +1,98 @@
+import {
+  createFileRoute,
+  Link,
+  stripSearchParams,
+} from "@tanstack/react-router"
+import type { ReactElement } from "react"
+import { z } from "zod"
+import { canisterDisplayName } from "../components/canister-names.ts"
+import { useCanisterPage } from "../components/canister/use-canister-page.ts"
+import { CandidTab } from "../components/interface/CandidTab.tsx"
+import { CompatibilityTab } from "../components/interface/CompatibilityTab.tsx"
+import { ProjectTab } from "../components/interface/ProjectTab.tsx"
+import { TypeScriptTab } from "../components/interface/TypeScriptTab.tsx"
+import type { CanisterInterface } from "../interface/types.ts"
+
+const TABS = [
+  { key: "candid", label: "Candid" },
+  { key: "typescript", label: "TypeScript" },
+  { key: "project", label: "Project" },
+  { key: "compatibility", label: "Compatibility" },
+] as const
+
+type InterfaceTab = (typeof TABS)[number]["key"]
+
+const searchSchema = z.object({
+  tab: z
+    .enum(["candid", "typescript", "project", "compatibility"])
+    .default("candid")
+    .catch("candid"),
+})
+
+export const Route = createFileRoute("/canister/$canisterId/interface")({
+  validateSearch: searchSchema,
+  // The default tab stays out of the URL.
+  search: { middlewares: [stripSearchParams({ tab: "candid" })] },
+  head: ({ params }) => ({
+    meta: [
+      {
+        title: `Interface · ${canisterDisplayName(params.canisterId)} · Canister Studio`,
+      },
+    ],
+  }),
+  component: InterfacePage,
+})
+
+function InterfacePage(): ReactElement {
+  const { tab } = Route.useSearch()
+  const { canisterId, payload, iface } = useCanisterPage()
+  if (iface === undefined || !payload.ok) return <></>
+  return (
+    <div className="stack iface-page">
+      {/* Links, not buttons: each tab has a URL, and works before hydration. */}
+      <nav className="tabs iface-tabs" aria-label="Interface tools">
+        {TABS.map((item) => (
+          <Link
+            key={item.key}
+            to="/canister/$canisterId/interface"
+            params={{ canisterId }}
+            search={{ tab: item.key }}
+            className="tab"
+            // The router marks the current one aria-current="page". Exact:
+            // the Candid link's search is stripped to {}, which a partial
+            // match finds in every tab's search.
+            activeOptions={{ exact: true }}
+            activeProps={{}}
+            replace
+          >
+            {item.label}
+          </Link>
+        ))}
+      </nav>
+      <div className="tab-panel">
+        <TabBody tab={tab} iface={iface} did={payload.did} />
+      </div>
+    </div>
+  )
+}
+
+function TabBody({
+  tab,
+  iface,
+  did,
+}: {
+  tab: InterfaceTab
+  iface: CanisterInterface
+  did: string
+}): ReactElement {
+  switch (tab) {
+    case "candid":
+      return <CandidTab iface={iface} did={did} />
+    case "typescript":
+      return <TypeScriptTab iface={iface} />
+    case "project":
+      return <ProjectTab iface={iface} />
+    case "compatibility":
+      return <CompatibilityTab iface={iface} />
+  }
+}

package/examples/canister-studio/src/routes/canister.$canisterId.tsx

@@ -0,0 +1,91 @@
+import {
+  createFileRoute,
+  notFound,
+  Outlet,
+  type ErrorComponentProps,
+  type NotFoundRouteProps,
+} from "@tanstack/react-router"
+import type { ReactElement } from "react"
+import { CanisterHeader } from "../components/CanisterHeader.tsx"
+import { CanisterLoadFailure } from "../components/canister/CanisterLoadFailure.tsx"
+import { CanisterNotFound } from "../components/canister/CanisterNotFound.tsx"
+import { CanisterPending } from "../components/canister/CanisterPending.tsx"
+import { RouteError } from "../components/RouteError.tsx"
+import { canisterDisplayName } from "../components/canister-names.ts"
+import {
+  loadInterfacePayload,
+  useCanisterInterface,
+} from "../interface/load.ts"
+import { checkCanisterId } from "../lib/ids.ts"
+
+// An interface changes only with an upgrade (and the server revalidates it by
+// module hash), so moving between methods and tabs never reloads it.
+const INTERFACE_STALE_TIME = 5 * 60_000
+
+export const Route = createFileRoute("/canister/$canisterId")({
+  // A text that is not a canister id never reaches the loader: it is a 404
+  // with the reason, on the server and in the browser alike.
+  beforeLoad: ({ params }) => {
+    const check = checkCanisterId(params.canisterId)
+    if (!check.ok) {
+      throw notFound({ data: { code: check.code, message: check.message } })
+    }
+  },
+  // Typed canisters resolve from the registry (no server call); any other
+  // goes through the fetchInterface server function. Never throws: a failed
+  // load is a payload the page explains.
+  loader: async ({ params }) => {
+    const payload = await loadInterfacePayload(params.canisterId)
+    if (!payload.ok && payload.code === "canister_not_found") {
+      throw notFound({ data: { code: payload.code, message: payload.message } })
+    }
+    return { payload }
+  },
+  staleTime: INTERFACE_STALE_TIME,
+  head: ({ params }) => {
+    const name = canisterDisplayName(params.canisterId)
+    return {
+      meta: [
+        { title: `${name} · Canister Studio` },
+        {
+          name: "description",
+          content: `Forms for every method of ${name} (${params.canisterId}) on the Internet Computer, with safe calls.`,
+        },
+      ],
+    }
+  },
+  pendingComponent: CanisterPending,
+  errorComponent: CanisterError,
+  notFoundComponent: CanisterNotFoundPage,
+  component: CanisterLayout,
+})
+
+function CanisterLayout(): ReactElement {
+  const { canisterId } = Route.useParams()
+  const { payload } = Route.useLoaderData()
+  const iface = useCanisterInterface(payload)
+
+  if (!payload.ok) {
+    return (
+      <div className="page canister-page">
+        <CanisterHeader canisterId={canisterId} />
+        <CanisterLoadFailure payload={payload} />
+      </div>
+    )
+  }
+  return (
+    <div className="page canister-page">
+      <CanisterHeader canisterId={canisterId} payload={payload} iface={iface} />
+      <Outlet />
+    </div>
+  )
+}
+
+function CanisterNotFoundPage({ data }: NotFoundRouteProps): ReactElement {
+  const { canisterId } = Route.useParams()
+  return <CanisterNotFound canisterId={canisterId} data={data} />
+}
+
+function CanisterError(props: ErrorComponentProps): ReactElement {
+  return <RouteError {...props} title="This canister page failed to load" />
+}

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

@@ -0,0 +1,55 @@
+import { ClientOnly, createFileRoute } from "@tanstack/react-router"
+import type { ReactElement } from "react"
+import { HistoryList } from "../components/history/HistoryList.tsx"
+import { RouteError } from "../components/RouteError.tsx"
+import { Skeleton } from "../components/Spinner.tsx"
+
+export const Route = createFileRoute("/history")({
+  head: () => ({
+    meta: [
+      { title: "History · Canister Studio" },
+      {
+        name: "description",
+        content:
+          "The calls made in this browser, with their exact argument bytes: replay them or share them.",
+      },
+    ],
+  }),
+  errorComponent: (props) => (
+    <RouteError {...props} title="The history failed to load" />
+  ),
+  component: HistoryPage,
+})
+
+function HistoryPage(): ReactElement {
+  return (
+    <div className="page history">
+      <header className="page-header">
+        <h1 className="page-title">History</h1>
+        <p className="page-subtitle">
+          Every call you ran or sent in this browser, newest first, with its
+          arguments as the exact Candid bytes that were sent (never
+          re-serialized JSON). The reads a page makes by itself, such as
+          balances and token metadata, are not kept. Replay a read, reopen a
+          write prefilled, or copy a link that renders the read’s result on the
+          server.
+        </p>
+      </header>
+      {/* The history lives in this browser's storage: nothing to render on a
+          server, and nothing to match while hydrating. */}
+      <ClientOnly fallback={<HistorySkeleton />}>
+        <HistoryList />
+      </ClientOnly>
+    </div>
+  )
+}
+
+function HistorySkeleton(): ReactElement {
+  return (
+    <div className="stack" aria-busy="true">
+      <span className="sr-only">Loading your history</span>
+      <Skeleton height="2.25rem" />
+      <Skeleton height="12rem" />
+    </div>
+  )
+}

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

@@ -0,0 +1,169 @@
+import { createFileRoute, Link } from "@tanstack/react-router"
+import type { ReactElement } from "react"
+import {
+  startLedgerReads,
+  startMinterReads,
+} from "../components/home/featured.ts"
+import { FeaturedLedger } from "../components/home/FeaturedLedger.tsx"
+import { OpenCanister } from "../components/home/OpenCanister.tsx"
+import { RouteError } from "../components/RouteError.tsx"
+import { REGISTRY } from "../lib/registry.ts"
+
+const FEATURED = REGISTRY.filter((entry) => entry.featured === true)
+
+export const Route = createFileRoute("/")({
+  // Starts the featured cards' reads and returns at once: the cards stream
+  // in as each read lands. Typed modules only, never a server function (the
+  // StackBlitz preview renders this page where server functions cannot
+  // run), and nothing here can throw.
+  loader: ({ context: { reactor, queryClient } }) => {
+    for (const entry of FEATURED) {
+      if (entry.kind === "ckbtc-minter") {
+        startMinterReads(reactor, queryClient, entry.id)
+      } else {
+        startLedgerReads(reactor, queryClient, entry.id)
+      }
+    }
+  },
+  head: () => ({
+    meta: [
+      { title: "Canister Studio" },
+      {
+        name: "description",
+        content:
+          "Automatic forms and safe calls for any Internet Computer canister, with live mainnet data rendered on the server.",
+      },
+    ],
+  }),
+  errorComponent: (props) => (
+    <RouteError {...props} title="The home page failed" />
+  ),
+  component: HomePage,
+})
+
+const POINTS = [
+  "Typed canisters come from committed .did files; any other canister is read live from its certified metadata, and labelled loudly when it is not.",
+  "Reads are keyed by caller and argument bytes, server-rendered, and hydrated without a second request.",
+  "Writes need a signed-in sender, are never retried blindly, and re-send only through a deduplicated offer.",
+] as const
+
+const FEATURES = [
+  {
+    to: "/canister/$canisterId",
+    params: { canisterId: "rrkah-fqaaa-aaaaa-aaaaq-cai" },
+    title: "A form for every method",
+    text: "Any canister's live, certified interface becomes a form per method: records, variants, options, vectors and blobs, with the exact Candid bytes before anything is sent.",
+    cta: "Open NNS governance",
+  },
+  {
+    to: "/wallet",
+    title: "Typed wallet",
+    text: "Hand-written flows over generated types: a caller-scoped balance, a typed transfer form, a confirm step, and the safe re-send after an unknown outcome.",
+    cta: "Open the wallet",
+  },
+  {
+    to: "/safety",
+    title: "Safety lab",
+    text: "Lost replies, traps, 429s, a caller switching mid-flight: every rule ic-reactor enforces, run against an in-memory replica in your browser.",
+    cta: "Run the scenarios",
+  },
+  {
+    to: "/playground",
+    title: "Playground",
+    text: "Paste a .did, compile it in the browser, get forms, a TypeScript module, a projection, and a compatibility check against a live canister.",
+    cta: "Paste a .did",
+  },
+  {
+    to: "/history",
+    title: "History and shared links",
+    text: "Every call you run or send is kept in this browser with its exact argument bytes. A shared query link renders its result on the server.",
+    cta: "See your calls",
+  },
+] as const
+
+function HomePage(): ReactElement {
+  return (
+    <div className="page home">
+      <section className="home-hero" aria-labelledby="home-title">
+        <div className="stack-lg home-hero-text">
+          <div className="stack-sm">
+            <p className="home-eyebrow">ic-reactor 4 + Meant</p>
+            <h1 id="home-title" className="page-title home-title">
+              Call any Internet Computer canister, safely.
+            </h1>
+            <p className="lead">
+              Automatic forms for every method, from typed modules generated at
+              build time or from a live canister’s certified interface. Every
+              write shows its sender, target and exact bytes first; every
+              failure says whether it may have executed.
+            </p>
+          </div>
+          <div className="page-actions">
+            <Link
+              to="/canister/$canisterId"
+              params={{ canisterId: "ryjl3-tyaaa-aaaaa-aaaba-cai" }}
+              className="btn btn-primary btn-lg"
+            >
+              Explore the ICP ledger
+            </Link>
+            <Link to="/safety" className="btn btn-lg">
+              See the safety rules
+            </Link>
+          </div>
+          <ul className="list-plain stack-sm home-points">
+            {POINTS.map((point) => (
+              <li key={point}>{point}</li>
+            ))}
+          </ul>
+        </div>
+        <OpenCanister />
+      </section>
+
+      <section className="section" aria-labelledby="featured-title">
+        <div className="section-header">
+          <h2 id="featured-title" className="section-title">
+            Typed canisters
+          </h2>
+          <p className="text-sm muted">
+            Live from mainnet, rendered on the server and hydrated without a
+            second read.
+          </p>
+        </div>
+        <div className="grid home-featured-grid">
+          {FEATURED.map((entry) => (
+            <FeaturedLedger key={entry.id} entry={entry} />
+          ))}
+        </div>
+      </section>
+
+      <section className="section" aria-labelledby="features-title">
+        <h2 id="features-title" className="section-title">
+          What is in the studio
+        </h2>
+        <ul className="list-plain grid home-features">
+          {FEATURES.map((feature) => (
+            <li key={feature.title} className="card home-feature">
+              <div className="card-body">
+                <h3 className="card-title">{feature.title}</h3>
+                <p className="text-sm muted grow">{feature.text}</p>
+                {"params" in feature ? (
+                  <Link
+                    to={feature.to}
+                    params={feature.params}
+                    className="home-feature-link"
+                  >
+                    {feature.cta} →
+                  </Link>
+                ) : (
+                  <Link to={feature.to} className="home-feature-link">
+                    {feature.cta} →
+                  </Link>
+                )}
+              </div>
+            </li>
+          ))}
+        </ul>
+      </section>
+    </div>
+  )
+}