@multiplatform.one/web3 7.24.0 → 7.26.0

package/src/bridge/nativeHost.spec.ts

@@ -0,0 +1,165 @@
+import { describe, expect, it } from "vitest";
+import { BridgeHost } from "./BridgeHost";
+import { buildInjectScript, createNativeBridge } from "./nativeHost";
+import { createPostMessageTransport } from "./postMessageTransport";
+import { BRIDGE_PROTOCOL_VERSION } from "./protocol";
+
+/**
+ * A fake page: `inject` runs the native side's script against a fake window
+ * whose `__bridgeReceive` feeds a BridgeHost, and the host's replies come back
+ * through `native.receive` with the page's URL.
+ */
+function setup(pageUrl = "https://wallet.example.com/webview.html") {
+  const injected: string[] = [];
+  const win: { location: { origin: string }; __bridgeReceive?: (raw: string) => void } = {
+    location: { origin: new URL(pageUrl).origin },
+  };
+  let postedFrom = pageUrl;
+  const native = createNativeBridge({
+    pageUrl,
+    allowDevHosts: true,
+    inject(script) {
+      injected.push(script);
+      new Function("window", script)(win);
+    },
+  });
+  const transport = createPostMessageTransport((raw) => native.receive(raw, postedFrom));
+  win.__bridgeReceive = (raw) => transport.receive(raw);
+  const host = new BridgeHost(transport);
+  return {
+    native,
+    host,
+    injected,
+    win,
+    postFrom(url: string) {
+      postedFrom = url;
+    },
+  };
+}
+
+describe("createNativeBridge", () => {
+  it("refuses a page that is not hosted", () => {
+    expect(() =>
+      createNativeBridge({ pageUrl: "file:///webview.html", inject: () => undefined }),
+    ).toThrow(/https/);
+  });
+
+  it("refuses a plain-http dev page unless dev hosts are allowed", () => {
+    const pageUrl = "http://localhost:8099/webview.html";
+    expect(() => createNativeBridge({ pageUrl, inject: () => undefined })).toThrow(
+      /development builds/,
+    );
+    expect(
+      createNativeBridge({ pageUrl, inject: () => undefined, allowDevHosts: true }).pageOrigin,
+    ).toBe("http://localhost:8099");
+  });
+
+  it("queues requests until sys.ready, then flushes them", async () => {
+    const { native, host, injected } = setup();
+    host.register("evm", (method) => (method === "eth_chainId" ? "0x1" : null));
+    const pending = native.client.request("evm", "eth_chainId");
+    expect(injected).toHaveLength(0);
+    host.ready();
+    await expect(pending).resolves.toBe("0x1");
+    expect(injected).toHaveLength(1);
+    expect(native.peer).toEqual({ protocol: BRIDGE_PROTOCOL_VERSION, namespaces: ["evm", "sys"] });
+  });
+
+  it("drops messages posted by a page on another origin", async () => {
+    const { native, host, postFrom } = setup();
+    host.register("evm", () => "0x1");
+    postFrom("https://evil.example/");
+    host.ready();
+    expect(native.peer).toBeNull();
+    postFrom("https://wallet.example.com/other");
+    host.ready();
+    expect(native.peer).not.toBeNull();
+  });
+
+  it("drops messages that name no sender", () => {
+    const { native, postFrom, host } = setup();
+    postFrom("");
+    host.ready();
+    expect(native.peer).toBeNull();
+  });
+
+  it("delivers nothing into a document on another origin", async () => {
+    const { native, host, injected, win } = setup();
+    host.register("evm", () => "0x1");
+    host.ready();
+    win.location.origin = "https://evil.example";
+    const lost = native.client.request("evm", "eth_chainId", undefined, { timeoutMs: 20 });
+    expect(injected).toHaveLength(1);
+    await expect(lost).rejects.toThrow();
+  });
+
+  it("a top-frame load on another origin fails what is in flight and stops delivery", async () => {
+    const { native, host, injected } = setup();
+    host.register("evm", (method) =>
+      method === "eth_chainId" ? "0x1" : new Promise(() => undefined),
+    );
+    host.ready();
+    const lost = native.client.request("evm", "eth_requestAccounts");
+    expect(native.navigated("https://wallet.example.com/webview.html")).toBe(false);
+    expect(native.navigated("about:blank")).toBe(false);
+    expect(native.peer).not.toBeNull();
+    expect(native.navigated("https://evil.example/form")).toBe(true);
+    await expect(lost).rejects.toThrow(/went away/);
+    expect(native.peer).toBeNull();
+    const before = injected.length;
+    const next = native.client.request("evm", "eth_chainId");
+    expect(injected).toHaveLength(before);
+    host.ready();
+    await expect(next).resolves.toBe("0x1");
+  });
+
+  it("fails requests in flight when the page announces itself again", async () => {
+    const { native, host } = setup();
+    host.register("evm", () => new Promise(() => undefined));
+    host.ready();
+    const lost = native.client.request("evm", "eth_requestAccounts");
+    host.ready();
+    await expect(lost).rejects.toThrow(/reloaded/);
+  });
+
+  it("pageGone fails what is in flight and queues until the next ready", async () => {
+    const { native, host, injected } = setup();
+    host.register("evm", (method) =>
+      method === "eth_chainId" ? "0x1" : new Promise(() => undefined),
+    );
+    host.ready();
+    const lost = native.client.request("evm", "eth_requestAccounts");
+    native.pageGone();
+    await expect(lost).rejects.toThrow(/went away/);
+    const before = injected.length;
+    const next = native.client.request("evm", "eth_chainId");
+    expect(injected).toHaveLength(before);
+    host.ready();
+    await expect(next).resolves.toBe("0x1");
+  });
+
+  it("asks for the page back twice at most until it announces itself again", () => {
+    const { native, host } = setup();
+    host.ready();
+    expect(native.navigated("https://evil.example/")).toBe(true);
+    expect(native.navigated("https://evil.example/")).toBe(true);
+    expect(native.navigated("https://evil.example/")).toBe(false);
+    host.ready();
+    expect(native.navigated("https://evil.example/")).toBe(true);
+  });
+
+  it("exposes the page origin", () => {
+    expect(setup("http://localhost:8099/webview.html").native.pageOrigin).toBe(
+      "http://localhost:8099",
+    );
+  });
+
+  it("buildInjectScript survives quotes and newlines", () => {
+    const received: string[] = [];
+    const raw = 'he said "hi"\nline2\\end </script>';
+    new Function("window", buildInjectScript(raw))({
+      __bridgeReceive: (s: string) => received.push(s),
+    });
+    expect(received).toEqual([raw]);
+  });
+});

package/src/bridge/nativeHost.ts

@@ -0,0 +1,120 @@
+import { BridgeClient } from "./BridgeClient";
+import { hostedPageOrigin, parseOrigin } from "./hosting";
+import { createPostMessageTransport } from "./postMessageTransport";
+import { BRIDGE_PROTOCOL_VERSION, type BridgeReady } from "./protocol";
+
+export interface NativeBridgeOptions {
+  /** The hosted wallet page. Must pass `isHostedPageUrl`. */
+  pageUrl: string;
+  /** Accept plain http on the development hosts. Pass `__DEV__`; never true in a release build. */
+  allowDevHosts?: boolean;
+  /** Runs a script in the page: react-native-webview's `injectJavaScript`. */
+  inject(script: string): void;
+  /** Default request timeout, see BridgeClient. */
+  timeoutMs?: number;
+  /** Called once the page reports `sys.ready`. */
+  onReady?(ready: BridgeReady): void;
+}
+
+export interface NativeBridge {
+  readonly client: BridgeClient;
+  /** Origin of the hosted page; messages from any other origin are dropped. */
+  readonly pageOrigin: string;
+  /** What the page announced in `sys.ready`, or null before it has. */
+  readonly peer: BridgeReady | null;
+  /**
+   * Feed a WebView message in: `receive(e.nativeEvent.data, e.nativeEvent.url)`.
+   * A message whose `fromUrl` is missing or on another origin is dropped.
+   */
+  receive(data: string, fromUrl: string): void;
+  /**
+   * The top frame started loading `url` (react-native-webview's `onLoadStart`).
+   * A document on another origin is not the page: what is in flight fails,
+   * nothing more is delivered until the page announces itself again, and the
+   * answer is true so the host loads `pageUrl` back. Twice at most between two
+   * `sys.ready`s: a page that never comes back stays down instead of looping.
+   */
+  navigated(url: string): boolean;
+  /**
+   * The page died (WebView content process gone) or is being reloaded: fail
+   * the requests in flight and queue new ones until the next `sys.ready`.
+   */
+  pageGone(): void;
+  dispose(): void;
+}
+
+/**
+ * The script that delivers one message into the page. The raw string is
+ * embedded with JSON.stringify so quotes, newlines and backslashes survive;
+ * the trailing `true;` is react-native-webview's injectJavaScript contract.
+ * With `pageOrigin` the script delivers only while the top frame is on that
+ * origin, so a document that replaced the page never sees a message.
+ */
+export function buildInjectScript(raw: string, pageOrigin?: string): string {
+  const guard = pageOrigin
+    ? `window.location && window.location.origin === ${JSON.stringify(pageOrigin)} && `
+    : "";
+  return `${guard}window.__bridgeReceive && window.__bridgeReceive(${JSON.stringify(raw)});true;`;
+}
+
+/**
+ * The native end of the bridge for any React Native WebView host. Requests
+ * wait in a queue until the page says `sys.ready`, because the first request
+ * usually fires before the page has loaded.
+ */
+export function createNativeBridge(options: NativeBridgeOptions): NativeBridge {
+  const pageOrigin = hostedPageOrigin(options.pageUrl, { allowDevHosts: options.allowDevHosts });
+  const queue: string[] = [];
+  let peer: BridgeReady | null = null;
+  let reloads = 0;
+
+  const transport = createPostMessageTransport((raw) => {
+    if (peer) options.inject(buildInjectScript(raw, pageOrigin));
+    else queue.push(raw);
+  });
+  const offReady = transport.subscribe((message) => {
+    if (message.ns !== "sys" || message.kind !== "event" || message.method !== "ready") return;
+    // A second ready is a new document: whatever the old one was answering is lost.
+    if (peer) client.rejectPending(new Error("The wallet page reloaded"));
+    reloads = 0;
+    const params = message.params as Partial<BridgeReady> | undefined;
+    peer = {
+      protocol: typeof params?.protocol === "number" ? params.protocol : BRIDGE_PROTOCOL_VERSION,
+      namespaces: Array.isArray(params?.namespaces) ? params.namespaces : [],
+    };
+    for (const raw of queue.splice(0)) options.inject(buildInjectScript(raw, pageOrigin));
+    options.onReady?.(peer);
+  });
+  const client = new BridgeClient(transport, { timeoutMs: options.timeoutMs });
+
+  const pageGone = () => {
+    peer = null;
+    queue.length = 0;
+    client.rejectPending(new Error("The wallet page went away"));
+  };
+
+  return {
+    client,
+    pageOrigin,
+    get peer() {
+      return peer;
+    },
+    receive(data, fromUrl) {
+      if (!fromUrl || parseOrigin(fromUrl)?.origin !== pageOrigin) return;
+      transport.receive(data);
+    },
+    navigated(url) {
+      if (url.trim().toLowerCase() === "about:blank") return false;
+      if (parseOrigin(url)?.origin === pageOrigin) return false;
+      pageGone();
+      reloads += 1;
+      return reloads <= 2;
+    },
+    pageGone,
+    dispose() {
+      offReady();
+      client.dispose();
+      queue.length = 0;
+    },
+  };
+}

package/src/bridge/protocol.spec.ts

@@ -1,5 +1,11 @@
 import { describe, expect, it } from "vitest";
-import { isBridgeMessage, newRequestId, type BridgeMessage } from "./protocol";
+import {
+  BridgeRequestError,
+  NAMESPACES,
+  isBridgeMessage,
+  newRequestId,
+  type BridgeMessage,
+} from "./protocol";
 
 describe("protocol", () => {
   it("accepts a well-formed req", () => {
@@ -9,6 +15,23 @@ describe("protocol", () => {
   it("accepts an event without id", () => {
     expect(isBridgeMessage({ ns: "solana", kind: "event", method: "connect" })).toBe(true);
   });
+  it("accepts the sui, gpg and auth namespaces", () => {
+    expect(NAMESPACES).toEqual(["evm", "solana", "sui", "gpg", "auth", "sys"]);
+    for (const ns of ["sui", "gpg", "auth"]) {
+      expect(isBridgeMessage({ id: "1", ns, kind: "req", method: "signMessage" })).toBe(true);
+    }
+  });
+  it("BridgeRequestError keeps code and data", () => {
+    const e = new BridgeRequestError(-32002, "refused", { status: 401 });
+    expect(e).toBeInstanceOf(Error);
+    expect([e.name, e.code, e.message, e.data]).toEqual([
+      "BridgeRequestError",
+      -32002,
+      "refused",
+      { status: 401 },
+    ]);
+    expect("data" in new BridgeRequestError(1, "x")).toBe(false);
+  });
   it("rejects unknown namespace", () => {
     expect(isBridgeMessage({ ns: "btc", kind: "req", method: "x" })).toBe(false);
   });

package/src/bridge/protocol.ts

@@ -1,12 +1,36 @@
-export const NAMESPACES = ["evm", "solana", "sys"] as const;
+/**
+ * Version of the wire protocol in docs/bridge-protocol.md. The WebView sends it
+ * in `sys.ready`; bump it only for a change an existing host cannot ignore.
+ */
+export const BRIDGE_PROTOCOL_VERSION = 1;
+
+export const NAMESPACES = ["evm", "solana", "sui", "gpg", "auth", "sys"] as const;
 export type Namespace = (typeof NAMESPACES)[number];
 
 export const KINDS = ["req", "res", "event"] as const;
 export type Kind = (typeof KINDS)[number];
 
+/** Error codes a response can carry. EIP-1193 and JSON-RPC codes keep their meaning. */
+export const BridgeErrorCode = {
+  userRejected: 4001,
+  unsupportedMethod: 4200,
+  methodNotFound: -32601,
+  invalidParams: -32602,
+  internal: -32000,
+  /** The page is not served over https (or loopback http), so it cannot sign in. */
+  pageNotHosted: -32001,
+  /** Keycloak refused the request; `data` carries `status`, `error`, `errorDescription`. */
+  keycloakRefused: -32002,
+  /** No wallet or signer for the requested family is available in the page. */
+  walletUnavailable: -32003,
+  /** The account has required actions left and no onboarding client was given. */
+  profileIncomplete: -32004,
+} as const;
+
 export interface BridgeError {
   code: number;
   message: string;
+  data?: unknown;
 }
 
 export interface BridgeMessage {
@@ -20,6 +44,25 @@ export interface BridgeMessage {
   error?: BridgeError;
 }
 
+/** What the WebView announces in `sys.ready`. */
+export interface BridgeReady {
+  protocol: number;
+  namespaces: Namespace[];
+}
+
+/** An error that crosses the bridge with its code and data intact, in either direction. */
+export class BridgeRequestError extends Error {
+  readonly code: number;
+  readonly data?: unknown;
+
+  constructor(code: number, message: string, data?: unknown) {
+    super(message);
+    this.name = "BridgeRequestError";
+    this.code = code;
+    if (data !== undefined) this.data = data;
+  }
+}
+
 export function isBridgeMessage(value: unknown): value is BridgeMessage {
   if (typeof value !== "object" || value === null) return false;
   const m = value as Record<string, unknown>;

package/src/core/family.spec.ts

@@ -0,0 +1,117 @@
+import { describe, expect, it } from "vitest";
+import { testDriver } from "../../tests/core/testDriver";
+import { createFamilyRegistry, defineWalletFamily, type WalletFamilyDefinition } from "./family";
+
+const message = {
+  header: "wants you to sign in with your Solana account:",
+  statement: null,
+  chainId: "solana:mainnet",
+};
+const driver = () => testDriver("solana", [], {});
+const sol: WalletFamilyDefinition = {
+  id: "sol",
+  label: "Solana",
+  aliases: ["solana"],
+  message,
+  driver,
+};
+const gpg: WalletFamilyDefinition = {
+  id: "gpg",
+  label: "GPG",
+  message: {
+    header: "wants you to sign in with your GPG key.",
+    statement: null,
+    chainId: null,
+    address: false,
+  },
+  connectionless: true,
+};
+
+describe("defineWalletFamily", () => {
+  it("returns a frozen family with defaults filled in", () => {
+    const family = defineWalletFamily({ id: "sui", label: "Sui", message, driver });
+    expect(family).toMatchObject({ id: "sui", label: "Sui", aliases: [], connectionless: false });
+    expect(Object.isFrozen(family)).toBe(true);
+    expect(Object.isFrozen(family.aliases)).toBe(true);
+    expect(Object.isFrozen(family.message)).toBe(true);
+  });
+
+  it("does not share the caller's arrays", () => {
+    const aliases = ["solana"];
+    const family = defineWalletFamily({ ...sol, aliases });
+    aliases.push("other");
+    expect(family.aliases).toEqual(["solana"]);
+  });
+
+  it("a connectionless family has no driver", () => {
+    expect(defineWalletFamily(gpg).connectionless).toBe(true);
+    expect(() => defineWalletFamily({ ...gpg, driver })).toThrow(
+      /connectionless.*cannot have a driver/,
+    );
+  });
+
+  it("a connectable family needs a driver", () => {
+    expect(() => defineWalletFamily({ ...sol, driver: undefined })).toThrow(/needs a driver/);
+  });
+
+  it.each([
+    [{ id: "Sol" }, /id must be lowercase/],
+    [{ id: "" }, /id must be lowercase/],
+    [{ id: "9sol" }, /id must be lowercase/],
+    [{ aliases: ["Solana"] }, /alias must be lowercase/],
+    [{ aliases: ["sol"] }, /its own id as an alias/],
+    [{ label: " " }, /needs a label/],
+    [{ message: { ...message, header: "" } }, /message spec with a header/],
+  ])("refuses %o", (change, error) => {
+    expect(() => defineWalletFamily({ ...sol, ...change } as WalletFamilyDefinition)).toThrow(
+      error,
+    );
+  });
+});
+
+describe("createFamilyRegistry", () => {
+  const registry = createFamilyRegistry([defineWalletFamily(sol), defineWalletFamily(gpg)]);
+
+  it("finds a family by id or alias, in the order the app listed them", () => {
+    expect(registry.families.map((family) => family.id)).toEqual(["sol", "gpg"]);
+    expect(registry.get("sol")?.label).toBe("Solana");
+    expect(registry.get("solana")?.id).toBe("sol");
+    expect(registry.get("eth")).toBeUndefined();
+  });
+
+  it("require names the registered families when one is missing", () => {
+    expect(registry.require("solana").id).toBe("sol");
+    expect(() => registry.require("eth")).toThrow(
+      "wallet family eth is not registered; registered: sol, gpg",
+    );
+    expect(() => createFamilyRegistry([]).require("eth")).toThrow(/registered: none/);
+  });
+
+  it("carries each family's message spec", () => {
+    expect(registry.messages.families).toEqual(["sol", "gpg"]);
+    expect(registry.messages.resolve("solana")).toBe("sol");
+    expect(registry.messages.spec("gpg")?.address).toBe(false);
+  });
+
+  it("refuses a family registered twice and a name two families claim", () => {
+    expect(() => createFamilyRegistry([defineWalletFamily(sol), defineWalletFamily(sol)])).toThrow(
+      /sol is registered twice/,
+    );
+    expect(() =>
+      createFamilyRegistry([
+        defineWalletFamily(sol),
+        defineWalletFamily({ ...gpg, aliases: ["solana"] }),
+      ]),
+    ).toThrow(/"solana" is claimed by sol and gpg/);
+    expect(() =>
+      createFamilyRegistry([
+        defineWalletFamily({ ...gpg, aliases: ["sol"] }),
+        defineWalletFamily(sol),
+      ]),
+    ).toThrow(/"sol" is claimed by gpg and sol/);
+  });
+
+  it("the registry's family list cannot be changed", () => {
+    expect(Object.isFrozen(registry.families)).toBe(true);
+  });
+});

package/src/core/family.ts

@@ -0,0 +1,103 @@
+import type { ScreenDef } from "@multiplatform.one/connectkit";
+import type { ComponentType, ReactNode } from "react";
+import {
+  createMessageRegistry,
+  type WalletMessageRegistry,
+  type WalletMessageSpec,
+} from "./message";
+import { assertName, nameTable } from "./names";
+import type { ConnectionDriver } from "./types";
+
+/** What a family package hands the core: `eth({chains})`, `sol({rpcUrl})`, `gpg()`. */
+export interface WalletFamilyDefinition {
+  /** Short family id, the one the Keycloak message names: `eth`, `sol`, `sui`, `btc`, `gpg`. */
+  readonly id: string;
+  readonly label: string;
+  /** Other names callers use for the family, such as the ecosystem name `evm` for `eth`. */
+  readonly aliases?: readonly string[];
+  readonly message: WalletMessageSpec;
+  /**
+   * Makes the family's connection driver. The store calls it once, the first
+   * time it needs the family, so a family nobody touches starts nothing.
+   */
+  readonly driver?: () => ConnectionDriver;
+  /** Signs without a wallet connection (GPG). Such a family has no driver. */
+  readonly connectionless?: boolean;
+  /** Modal screens the family contributes. */
+  readonly screens?: readonly ScreenDef[];
+  /** A provider the family needs mounted around the app. */
+  readonly Provider?: ComponentType<{ children?: ReactNode }>;
+}
+
+export interface WalletFamily extends WalletFamilyDefinition {
+  readonly aliases: readonly string[];
+  readonly connectionless: boolean;
+}
+
+/** Validates a family definition and freezes it. */
+export function defineWalletFamily(definition: WalletFamilyDefinition): WalletFamily {
+  assertName("wallet family id", definition.id);
+  const aliases = [...(definition.aliases ?? [])];
+  for (const alias of aliases) {
+    assertName(`wallet family ${definition.id} alias`, alias);
+    if (alias === definition.id) {
+      throw new Error(`wallet family ${definition.id} lists its own id as an alias`);
+    }
+  }
+  if (typeof definition.label !== "string" || !definition.label.trim()) {
+    throw new Error(`wallet family ${definition.id} needs a label`);
+  }
+  const { message } = definition;
+  if (!message || typeof message.header !== "string" || !message.header) {
+    throw new Error(`wallet family ${definition.id} needs a message spec with a header`);
+  }
+  const connectionless = definition.connectionless === true;
+  if (connectionless && definition.driver) {
+    throw new Error(`wallet family ${definition.id} is connectionless and cannot have a driver`);
+  }
+  if (!connectionless && typeof definition.driver !== "function") {
+    throw new Error(`wallet family ${definition.id} needs a driver, or connectionless: true`);
+  }
+  return Object.freeze({
+    ...definition,
+    aliases: Object.freeze(aliases),
+    connectionless,
+    message: Object.freeze({ ...message }),
+    ...(definition.screens ? { screens: Object.freeze([...definition.screens]) } : {}),
+  });
+}
+
+export interface FamilyRegistry {
+  /** In the order the app listed them, which is the connect list's order. */
+  readonly families: readonly WalletFamily[];
+  /** The family for an id or alias, or undefined. */
+  get(family: string): WalletFamily | undefined;
+  /** The family for an id or alias. Throws naming the registered families. */
+  require(family: string): WalletFamily;
+  readonly messages: WalletMessageRegistry;
+}
+
+/** The families one app registered. Refuses a family, id or alias registered twice. */
+export function createFamilyRegistry(families: readonly WalletFamily[]): FamilyRegistry {
+  const list = Object.freeze([...families]);
+  const names = nameTable(list);
+  const byId = new Map(list.map((family) => [family.id, family]));
+  const get = (family: string) => {
+    const id = names.get(family);
+    return id === undefined ? undefined : byId.get(id);
+  };
+  return {
+    families: list,
+    get,
+    require(family) {
+      const found = get(family);
+      if (found === undefined) {
+        throw new Error(
+          `wallet family ${family} is not registered; registered: ${list.map((entry) => entry.id).join(", ") || "none"}`,
+        );
+      }
+      return found;
+    },
+    messages: createMessageRegistry(list),
+  };
+}

package/src/core/imports.spec.ts

@@ -0,0 +1,82 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+import { describe, expect, it } from "vitest";
+
+const src = fileURLToPath(new URL("..", import.meta.url));
+const entry = fileURLToPath(new URL("./index.ts", import.meta.url));
+
+function resolveRelative(from: string, specifier: string): string {
+  const base = join(dirname(from), specifier);
+  for (const candidate of [
+    `${base}.ts`,
+    `${base}.tsx`,
+    join(base, "index.ts"),
+    join(base, "index.tsx"),
+  ]) {
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new Error(`cannot resolve ${specifier} from ${from}`);
+}
+
+/** Specifiers a file loads at runtime: type-only imports and exports are erased. */
+function runtimeSpecifiers(file: string): string[] {
+  const source = ts.createSourceFile(
+    file,
+    readFileSync(file, "utf8"),
+    ts.ScriptTarget.Latest,
+    true,
+  );
+  const found: string[] = [];
+  const visit = (node: ts.Node) => {
+    if (ts.isImportDeclaration(node) && !node.importClause?.isTypeOnly) {
+      found.push((node.moduleSpecifier as ts.StringLiteral).text);
+    } else if (ts.isExportDeclaration(node) && node.moduleSpecifier && !node.isTypeOnly) {
+      found.push((node.moduleSpecifier as ts.StringLiteral).text);
+    } else if (
+      ts.isCallExpression(node) &&
+      (node.expression.kind === ts.SyntaxKind.ImportKeyword ||
+        (ts.isIdentifier(node.expression) && node.expression.text === "require")) &&
+      node.arguments[0] &&
+      ts.isStringLiteral(node.arguments[0])
+    ) {
+      found.push(node.arguments[0].text);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(source);
+  return found;
+}
+
+function runtimeGraph(start: string) {
+  const files = new Set<string>();
+  const packages = new Map<string, string>();
+  const walk = (file: string) => {
+    if (files.has(file)) return;
+    files.add(file);
+    for (const specifier of runtimeSpecifiers(file)) {
+      if (specifier.startsWith(".")) walk(resolveRelative(file, specifier));
+      else packages.set(specifier, relative(src, file));
+    }
+  };
+  walk(start);
+  return { files: [...files].map((file) => relative(src, file)).sort(), packages };
+}
+
+describe("the core entry", () => {
+  it("loads no chain SDK: only React and its own files", () => {
+    const { files, packages } = runtimeGraph(entry);
+    expect(Object.fromEntries(packages)).toEqual({ react: "core/react.ts" });
+    expect(files.every((file) => file.startsWith("core/") || file === "clients/types.ts")).toBe(
+      true,
+    );
+  });
+
+  it("the scan sees a runtime import it should refuse", () => {
+    const { packages } = runtimeGraph(
+      fileURLToPath(new URL("../message/index.ts", import.meta.url)),
+    );
+    expect(packages.has("viem")).toBe(true);
+  });
+});