test(e2e): add Playwright + Anvil E2E infrastructure

Standalone /e2e/ package (not in pnpm workspace) with:
- Playwright config: desktop + mobile projects, workers=1 in CI
- Custom EIP-1193 provider injection adapted from frontwise/testwise:
  forwards JSON-RPC to local Anvil fork, bridges signing to ethers
  Wallet via page.exposeFunction, announces via EIP-6963
- Anvil scripts: Foundry Docker (local) and native binary (CI)
- Risk-provider mock fixture: page.route pattern for Blowfish, Blockaid,
  GoPlus API responses driven by JSON fixtures
- Smoke spec verifying provider injection works end-to-end

Real component flows land in subsequent commits per Phase 2 of the
testing strategy plan.

Author: mike-diamond

e2e/.env.example

@@ -0,0 +1,7 @@
+# Sepolia upstream RPC for Anvil fork. Public endpoints rate-limit Anvil's
+# fetch pattern; use a dedicated key (Alchemy free tier covers our usage).
+SEPOLIA_RPC_URL=https://eth-sepolia.g.alchemy.com/v2/YOUR_ALCHEMY_KEY
+
+# Override the playground URL for smoke tests against production.
+# Leave unset for local dev (Playwright auto-starts story dev server).
+# E2E_BASE_URL=https://story.txkit.dev

e2e/.gitignore

@@ -0,0 +1,5 @@
+node_modules
+test-results
+playwright-report
+.env
+*.tsbuildinfo

e2e/README.md

@@ -0,0 +1,117 @@
+# txkit-e2e
+
+End-to-end tests for txKit, run with Playwright against the story
+playground and a local Anvil fork.
+
+**Standalone package** — not part of the pnpm workspace. Has its own
+`node_modules`. See [plans/txkit-testing-strategy-v0.1.md](../plans/txkit-testing-strategy-v0.1.md)
+for the full architecture rationale.
+
+## Setup
+
+```bash
+# 1. Install isolated deps
+cd e2e
+pnpm install --ignore-workspace
+
+# 2. Install Playwright browsers
+pnpm exec playwright install chromium
+
+# 3. Configure RPC for Anvil fork
+cp .env.example .env
+# Edit .env, paste your Alchemy/QuickNode Sepolia URL into SEPOLIA_RPC_URL
+
+# 4. Verify Foundry is available
+anvil --version || curl -L https://foundry.paradigm.xyz | bash && foundryup
+```
+
+## Run
+
+```bash
+pnpm test               # all projects (desktop + mobile)
+pnpm test:desktop       # desktop chrome 1280x800
+pnpm test:mobile        # iPhone 14 viewport
+pnpm test:headed        # non-headless (watch the browser)
+pnpm test:debug         # interactive Playwright debugger
+pnpm report             # open last HTML report
+```
+
+Playwright auto-starts both the story dev server (`pnpm --filter @txkit/story dev`)
+and Anvil fork (`./scripts/anvil-ci.sh`). Just run `pnpm test`.
+
+For smoke tests against the deployed playground:
+
+```bash
+E2E_BASE_URL=https://story.txkit.dev pnpm test
+```
+
+## Architecture
+
+- **EIP-1193 injection** — `helpers/eip1193-provider.js` replaces
+  `window.ethereum` with a stub that forwards to Anvil and bridges
+  signing to ethers `Wallet` via `page.exposeFunction`. Adapted from
+  StakeWise testwise.
+- **Anvil fork** — Sepolia fork at `localhost:8545`, block-time 2s.
+  `anvil_impersonateAccount` + `anvil_setBalance` give each test a
+  funded address without needing a real private key.
+- **EIP-6963 announce** — the injected provider announces itself so
+  wagmi's connector discovery picks it up automatically.
+- **Risk fixtures** — `fixtures/risk/*.json` capture real Blowfish /
+  Blockaid / GoPlus responses. `risk.use('blowfish-warn-token-drain')`
+  routes outbound API calls to the fixture instead of upstream.
+
+## Writing a new spec
+
+```ts
+import { test, expect } from '../../fixtures'
+
+
+test('TransactionButton runs full happy path', async ({ page, wallet }) => {
+  await wallet.init({ chain: 'sepolia' })
+  await page.goto('/?state=pending')
+  await wallet.connect()
+
+  await page.locator('[data-testid="transaction-button-main"]').click()
+
+  await expect(
+    page.locator('[data-testid="transaction-button-main"]')
+  ).toHaveAttribute('data-state', 'completed', { timeout: 30_000 })
+})
+```
+
+State of the world is controlled via URL search params (story reads
+them in `useControls()`):
+
+```
+?state=signing                    # force a specific TransactionButton state
+?safetyDelayMs=5000               # safety countdown
+?warnMaxApproval=true             # max-approval risk warning enabled
+?riskMode=warn                    # mock risk-provider mode
+?clearSigning=registry|fallback   # ERC-7730 vs ABI fallback
+```
+
+## Debugging a failing test
+
+```bash
+# Replay the trace from a failed run
+pnpm exec playwright show-trace test-results/.../trace.zip
+
+# Or step through interactively
+pnpm test:debug -g "your test name"
+```
+
+Each retry produces a video (`test-results/.../video.webm`) and
+screenshot for forensics.
+
+## CI
+
+Single Playwright workflow runs both projects with `workers=1` (Anvil
+shared state). Foundry preinstalled via
+`foundry-rs/foundry-toolchain@v1` action. See `.github/workflows/e2e.yml`.
+
+## Conventions
+
+- Test files end in `.spec.ts`, never `.test.ts`
+- Imports through `../../fixtures` (extended `test`, not raw Playwright)
+- Wallet init **before** `page.goto` so injection happens on first frame
+- Test names use plain ASCII (`->` not `→`); they appear in CI logs

e2e/fixtures/index.ts

@@ -0,0 +1,39 @@
+import { test as base, expect } from '@playwright/test'
+
+import { setupWallet, type WalletFixture } from './wallet'
+import { mockRiskProvider, type RiskMock } from './risk'
+
+
+type Fixtures = {
+  wallet: WalletFixture
+  risk: RiskMock
+}
+
+
+/**
+ * Extended Playwright test with txKit-specific fixtures.
+ *
+ * Usage:
+ *   import { test, expect } from '../../fixtures'
+ *
+ *   test('connects', async ({ page, wallet }) => {
+ *     await wallet.init({ chain: 'sepolia' })
+ *     await page.goto('/')
+ *     await wallet.connect()
+ *     // assertions...
+ *   })
+ */
+export const test = base.extend<Fixtures>({
+  wallet: async ({ page }, use) => {
+    const wallet = await setupWallet({ page })
+    await use(wallet)
+  },
+  risk: async ({ page }, use) => {
+    const mock = mockRiskProvider({ page })
+    await use(mock)
+    await mock.reset()
+  },
+})
+
+
+export { expect }

e2e/fixtures/risk.ts

@@ -0,0 +1,94 @@
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Page } from '@playwright/test'
+
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = path.dirname(__filename)
+
+const RISK_FIXTURES_DIR = path.join(__dirname, 'risk')
+
+
+// URL patterns that match real risk-provider APIs. Tests that opt into
+// `risk.use(...)` get every matching outbound request fulfilled with the
+// fixture payload instead of hitting the live API.
+const PROVIDER_PATTERNS: Record<string, string> = {
+  blowfish: '**/api.blowfish.xyz/**',
+  blockaid: '**/api.blockaid.io/**',
+  goplus: '**/api.gopluslabs.io/**',
+}
+
+
+export type RiskFixture =
+  | 'blowfish-safe'
+  | 'blowfish-warn-token-drain'
+  | 'blowfish-block-malicious'
+  | 'blockaid-phishing-domain'
+  | 'goplus-honeypot'
+
+export type RiskMock = {
+  use: (fixture: RiskFixture) => Promise<void>
+  reset: () => Promise<void>
+}
+
+
+const detectProvider = (fixture: RiskFixture): string => {
+  const provider = fixture.split('-')[0]
+
+  if (!PROVIDER_PATTERNS[provider]) {
+    throw new Error(`Unknown risk provider for fixture ${fixture}`)
+  }
+
+  return provider
+}
+
+const loadFixture = (fixture: RiskFixture): unknown => {
+  const filePath = path.join(RISK_FIXTURES_DIR, `${fixture}.json`)
+
+  if (!fs.existsSync(filePath)) {
+    throw new Error(`Risk fixture not found: ${filePath}`)
+  }
+
+  return JSON.parse(fs.readFileSync(filePath, 'utf-8'))
+}
+
+
+/**
+ * Risk-provider mock fixture. Tests that need to assert behavior on
+ * Blowfish/Blockaid/GoPlus responses register a fixture before the
+ * `transaction-button-main` click; matching outbound requests get
+ * intercepted at the network layer (no upstream call made).
+ */
+export const mockRiskProvider = ({ page }: { page: Page }): RiskMock => {
+  let activeRoute: string | null = null
+
+  return {
+    use: async (fixture: RiskFixture) => {
+      const provider = detectProvider(fixture)
+      const pattern = PROVIDER_PATTERNS[provider]
+      const payload = loadFixture(fixture)
+
+      if (activeRoute) {
+        await page.unroute(activeRoute)
+      }
+
+      await page.route(pattern, (route) => (
+        route.fulfill({
+          status: 200,
+          contentType: 'application/json',
+          body: JSON.stringify(payload),
+        })
+      ))
+
+      activeRoute = pattern
+    },
+
+    reset: async () => {
+      if (activeRoute) {
+        await page.unroute(activeRoute)
+        activeRoute = null
+      }
+    },
+  }
+}

e2e/fixtures/wallet.ts

@@ -0,0 +1,77 @@
+import { Wallet } from 'ethers'
+import type { Page } from '@playwright/test'
+
+import { initProvider } from '../helpers/initProvider'
+import type { SupportedChain } from '../helpers/chains'
+
+
+type InitInput = {
+  chain?: SupportedChain
+  privateKey?: string
+  address?: string
+}
+
+export type WalletFixture = {
+  init: (input?: InitInput) => Promise<void>
+  connect: () => Promise<void>
+  address: () => string
+}
+
+
+type Internal = {
+  address: string | null
+}
+
+
+const formatTestid = (id: string): string => `[data-testid="${id}"]`
+
+
+/**
+ * Wallet fixture. Call `wallet.init()` BEFORE `page.goto()` so that the
+ * EIP-1193 provider is injected on the first frame. After the page loads,
+ * call `wallet.connect()` to drive the ConnectWallet UI through the modal.
+ */
+export const setupWallet = async ({ page }: { page: Page }): Promise<WalletFixture> => {
+  const internal: Internal = { address: null }
+
+  return {
+    init: async (input = {}) => {
+      const privateKey = input.privateKey || Wallet.createRandom().privateKey
+      const { address } = await initProvider({
+        page,
+        chain: input.chain || 'sepolia',
+        address: input.address,
+        privateKey,
+      })
+
+      internal.address = address
+    },
+
+    connect: async () => {
+      if (!internal.address) {
+        throw new Error('wallet.connect(): call wallet.init() first')
+      }
+
+      // Click the ConnectWallet button. Top-level testid is forwarded
+      // from the `data-testid` prop in stories; sub-buttons need their
+      // own testids (added in the data-testid audit pass).
+      await page.locator(formatTestid('connect-wallet-button')).first().click()
+
+      // Pick the first wallet in the modal. Our injected provider
+      // announces itself via EIP-6963 so it lands as a top option.
+      await page.locator(formatTestid('wallet-modal')).waitFor()
+      await page.locator(formatTestid('wallet-modal-item')).first().click()
+
+      // Wait for connected state to render.
+      await page.locator(formatTestid('connected-address')).waitFor({ timeout: 10_000 })
+    },
+
+    address: () => {
+      if (!internal.address) {
+        throw new Error('wallet.address(): call wallet.init() first')
+      }
+
+      return internal.address
+    },
+  }
+}

e2e/helpers/chains.ts

@@ -0,0 +1,48 @@
+/**
+ * Chain registry for the E2E provider injection. The values match what
+ * txKit's testnet preset registers in wagmi (Sepolia + mainnet for ENS).
+ *
+ * `rpcUrl` should point at your local Anvil fork. Mainnet entry has no
+ * local fork — ENS resolution falls through to the public RPC, which is
+ * fine because tests don't write to mainnet.
+ */
+export const ANVIL_RPC_URL = 'http://localhost:8545'
+
+export type SupportedChain = 'sepolia' | 'mainnet'
+
+type ChainEntry = {
+  hexadecimalChainId: string
+  decimalChainId: number
+  name: string
+  rpcUrl: string
+}
+
+export const chains: Record<string, ChainEntry> = {
+  // Sepolia (txKit story default)
+  '0xaa36a7': {
+    hexadecimalChainId: '0xaa36a7',
+    decimalChainId: 11155111,
+    name: 'Sepolia',
+    rpcUrl: ANVIL_RPC_URL,
+  },
+  // Mainnet (ENS lookups). Public read-only endpoint - no fork.
+  '0x1': {
+    hexadecimalChainId: '0x1',
+    decimalChainId: 1,
+    name: 'Ethereum',
+    rpcUrl: 'https://ethereum-rpc.publicnode.com',
+  },
+}
+
+export const defaultChainIdHex = '0xaa36a7'
+
+export const getChain = (id: SupportedChain): ChainEntry => {
+  const hex = id === 'sepolia' ? '0xaa36a7' : '0x1'
+  const chain = chains[hex]
+
+  if (!chain) {
+    throw new Error(`Unknown chain: ${id}`)
+  }
+
+  return chain
+}