create-miden-app 1.0.6 → 1.0.7

package/template/.claude/skills/testing-patterns/SKILL.md

@@ -7,11 +7,11 @@ description: Testing conventions, mock factory, fixtures, and TDD workflow for M
 
 ## Test Stack
 
-- **Vitest** — Test runner (extends Vite config for consistent behavior)
-- **@testing-library/react** — Component rendering and queries
-- **@testing-library/user-event** — User interaction simulation
-- **@testing-library/jest-dom** — DOM assertion matchers (toBeInTheDocument, toBeDisabled, etc.)
-- **jsdom** — Browser environment for tests
+- **Vitest** - Test runner (extends Vite config for consistent behavior)
+- **@testing-library/react** - Component rendering and queries
+- **@testing-library/user-event** - User interaction simulation
+- **@testing-library/jest-dom** - DOM assertion matchers (toBeInTheDocument, toBeDisabled, etc.)
+- **jsdom** - Browser environment for tests
 
 ## Mock Factory: `@miden-sdk/react`
 
@@ -43,17 +43,17 @@ it("shows empty state", () => {
 ### Default mock return values
 
 **Query hooks** return populated data by default:
-- `useAccounts()` — 2 wallets, 1 faucet
-- `useAccount()` — account with 10.0 TEST token balance
-- `useNotes()` — 1 input note, 1 consumable note
-- `useSyncState()` — syncHeight: 12345, not syncing
-- `useAssetMetadata()` — TEST token metadata (symbol, decimals: 8)
-- `useMiden()` — isReady: true
+- `useAccounts()` - 2 wallets, 1 faucet
+- `useAccount()` - account with 10.0 TEST token balance
+- `useNotes()` - 1 input note, 1 consumable note
+- `useSyncState()` - syncHeight: 12345, not syncing
+- `useAssetMetadata()` - TEST token metadata (symbol, decimals: 8)
+- `useMiden()` - isReady: true
 
 **Mutation hooks** return idle state by default:
-- `useSend()` — `{ send: vi.fn(), stage: "idle", isLoading: false }`
-- `useMint()`, `useConsume()`, `useSwap()`, `useTransaction()` — similar pattern
-- `useCreateWallet()` — `{ createWallet: vi.fn(), isCreating: false }`
+- `useSend()` - `{ send: vi.fn(), stage: "idle", isLoading: false }`. Its `result` type is `SendResult { txId, note }` - distinct from `TransactionResult { transactionId }` used by `useMint`/`useConsume`/`useSwap`/`useMultiSend`/`useTransaction`.
+- `useMint()`, `useConsume()`, `useSwap()`, `useTransaction()`, `useMultiSend()` - idle shape with `result: TransactionResult | null`.
+- `useCreateWallet()` - `{ createWallet: vi.fn(), isCreating: false }`.
 
 ### Simulating transaction stages
 
@@ -68,10 +68,20 @@ vi.mocked(useSend).mockReturnValue({
   reset: vi.fn(),
 });
 
-// Show completed transaction
+// Show completed transaction - useSend returns SendResult { txId, note }
 vi.mocked(useSend).mockReturnValue({
   send: vi.fn(),
-  result: { transactionId: "0xabc123" },
+  result: { txId: "0xabc123", note: null },
+  isLoading: false,
+  stage: "complete",
+  error: null,
+  reset: vi.fn(),
+});
+
+// Other mutation hooks return TransactionResult { transactionId }
+vi.mocked(useMint).mockReturnValue({
+  mint: vi.fn(),
+  result: { transactionId: "0xdef456" },
   isLoading: false,
   stage: "complete",
   error: null,
@@ -85,21 +95,22 @@ Realistic test data in `src/__tests__/fixtures/`:
 
 ```tsx
 import {
-  WALLET_ID_1,           // "mtst1qy35qfqdvpjx2e5zf9hkp4vr"
-  WALLET_ID_2,           // "mtst1qa7k9qjf8dp4x2e5zf9hkp5vr"
-  FAUCET_ID,             // "mtst1qx9y8zjf2dp4x2e5zf9hkp3vr"
-  COUNTER_ID,            // "mtst1aru8adnrqspgcsr3drk2n990lyc070ll"
+  WALLET_ID_1,           // "0x0a00000000000001"
+  WALLET_ID_2,           // "0x0a00000000000002"
+  FAUCET_ID,             // "0x0a00000000000003"
+  COUNTER_ID,            // "0x0a00000000000004"
   MOCK_WALLET_HEADER,    // { id, nonce, storageCommitment }
   MOCK_FAUCET_HEADER,    // { id, nonce, storageCommitment }
   MOCK_ASSET_BALANCE,    // { assetId, amount: 1000000000n, symbol: "TEST", decimals: 8 }
   MOCK_ACCOUNT,          // { id, nonce, bech32id() }
-  MOCK_TRANSACTION_RESULT, // { transactionId: "0x..." }
-  MOCK_NOTE_SUMMARY,    // { id, assets, sender }
+  MOCK_TRANSACTION_RESULT, // { transactionId: "0x..." } - useMint / useConsume / useSwap / useMultiSend / useTransaction
+  MOCK_SEND_RESULT,        // { txId: "0x...", note: null }  - useSend
+  MOCK_NOTE_SUMMARY,       // { id, assets, sender }
 } from "@/__tests__/fixtures";
 ```
 
 Key characteristics:
-- Account IDs use bech32 format (`mtst1...`)
+- Account IDs use hex format (`0x...`) - network-agnostic test fixtures
 - Amounts are `bigint` (e.g., `1000000000n` = 10.0 with 8 decimals)
 - Asset metadata uses TEST token with 8 decimals
 
@@ -116,35 +127,185 @@ Reference tests in `src/__tests__/patterns/`:
 ### Minimum test coverage per component
 
 Every component test should cover:
-1. **Success state** — renders correctly with data
-2. **Loading state** — shows loading indicator
-3. **Error state** — shows error message, recovery action
-4. **User interactions** — buttons, forms trigger correct handler calls
+1. **Success state** - renders correctly with data
+2. **Loading state** - shows loading indicator
+3. **Error state** - shows error message, recovery action
+4. **User interactions** - buttons, forms trigger correct handler calls
+
+## Wallet connection state in tests
 
-## Mocking the wallet adapter
+This template's wallet button (`src/components/AppContent.tsx`) drives off **`useMidenFiWallet()`** from `@miden-sdk/miden-wallet-adapter-react`, not the generic `useSigner()`. The button gates on `wallet.readyState` (from `@miden-sdk/miden-wallet-adapter-base`) so the UI can render an "Install MidenFi Wallet" state before the extension is detected, rather than falling through to the adapter's Chrome-Web-Store fallback. When testing wallet-connect UI, mock both modules and override per test.
 
-The app uses `@miden-sdk/miden-wallet-adapter`. Mock it at the module level:
+The mock factory must return the **full `WalletContextState`** shape - `useIncrementCounter` reads `address` and `requestTransaction` directly off the hook return, and the wallet button reads `wallet.readyState`. A partial mock will compile (with broad casts) and silently miss contract drift. Setup:
 
 ```tsx
-vi.mock("@miden-sdk/miden-wallet-adapter", () => ({
-  WalletMultiButton: () => <button>Connect Wallet</button>,
-  useWallet: vi.fn(() => ({
-    address: "mtst1...",
-    connected: true,
-    requestTransaction: vi.fn(),
+vi.mock("@miden-sdk/react", () => import("@/__tests__/mocks/miden-sdk-react"));
+vi.mock("@miden-sdk/miden-wallet-adapter-react", () => ({
+  useMidenFiWallet: vi.fn(() => ({
+    autoConnect: false,
+    wallets: [],
+    wallet: null,
+    address: null,
+    publicKey: null,
+    connected: false,
+    connecting: false,
+    disconnecting: false,
+    select: vi.fn(),
+    connect: vi.fn(async () => undefined),
+    disconnect: vi.fn(async () => undefined),
+    requestTransaction: vi.fn(async () => "0xtx"),
+    requestAssets: undefined,
+    requestPrivateNotes: undefined,
+    signBytes: undefined,
+    importPrivateNote: undefined,
+    requestConsumableNotes: undefined,
+    waitForTransaction: undefined,
+    requestSend: undefined,
+    requestConsume: undefined,
+    createAccount: undefined,
   })),
 }));
+vi.mock("@miden-sdk/miden-wallet-adapter-base", () => ({
+  WalletReadyState: {
+    Installed: "Installed",
+    NotDetected: "NotDetected",
+    Loadable: "Loadable",
+    Unsupported: "Unsupported",
+  },
+}));
+
+import { useMidenFiWallet } from "@miden-sdk/miden-wallet-adapter-react";
+```
+
+Use a typed factory for per-test overrides - `WalletContextState` is the `useMidenFiWallet()` return type:
+
+```tsx
+type WalletState = ReturnType<typeof useMidenFiWallet>;
+type WalletInner = NonNullable<WalletState["wallet"]>;
+
+function walletState(
+  overrides: Partial<{
+    readyState: "Installed" | "NotDetected" | "Loadable" | "Unsupported";
+    connected: boolean;
+    address: string | null;
+    requestTransaction: WalletState["requestTransaction"];
+  }> = {},
+): WalletState {
+  const {
+    readyState = "Installed",
+    connected = false,
+    address = connected ? "mtst1arwk88k8smzcq5p30upr6eerw5npmnyz" : null,
+    requestTransaction = vi.fn(async () => "0xtx"),
+  } = overrides;
+  // The inner Wallet's `adapter` is an `Adapter` (eventemitter + polling
+  // strategy) - we stub it structurally because the components under test
+  // only read `readyState` off the inner wallet object.
+  const innerWallet = {
+    adapter: {} as WalletInner["adapter"],
+    readyState,
+  } as WalletInner;
+  return {
+    autoConnect: false,
+    wallets: [innerWallet],
+    wallet: innerWallet,
+    address,
+    publicKey: null,
+    connected,
+    connecting: false,
+    disconnecting: false,
+    select: vi.fn(),
+    connect: vi.fn(async () => undefined),
+    disconnect: vi.fn(async () => undefined),
+    requestTransaction,
+    requestAssets: undefined,
+    requestPrivateNotes: undefined,
+    signBytes: undefined,
+    importPrivateNote: undefined,
+    requestConsumableNotes: undefined,
+    waitForTransaction: undefined,
+    requestSend: undefined,
+    requestConsume: undefined,
+    createAccount: undefined,
+  };
+}
+
+// extension not detected - shows disabled "Install MidenFi Wallet"
+vi.mocked(useMidenFiWallet).mockReturnValue(
+  walletState({ readyState: "NotDetected" }),
+);
+
+// installed + connected with an account - shows "Disconnect Wallet"
+vi.mocked(useMidenFiWallet).mockReturnValue(
+  walletState({ readyState: "Installed", connected: true }),
+);
+```
+
+The factory satisfies `WalletContextState` without `as unknown as` over the whole object - the only narrow `as` is the inner adapter stub, which is unavoidable until we want to construct a real `Adapter` in tests. See `src/components/__tests__/AppContent.test.tsx` for the canonical version.
+
+For app code that needs the selected signer account for client-side flows (transaction-building hooks, etc.), `useMiden()` exposes `signerAccountId` / `signerConnected` as lower-level provider state - mock those via the `@miden-sdk/react` mock factory.
+
+Vitest config externalizes `@miden-sdk/miden-wallet-adapter-react` to prevent broken transitive resolution.
+
+## Mocking Classes Called with `new` (Vitest v4)
+
+Vitest v4 enforces that mock implementations passed to `vi.fn()` must be `function` declarations (not arrow functions) when the mocked function is invoked with `new`. Arrow functions cannot be called as constructors and will throw `TypeError: ... is not a constructor`.
+
+```ts
+// WRONG: arrow function - throws when production code does `new MidenClient(...)`
+vi.mock("@miden-sdk/miden-sdk", () => ({
+  MidenClient: vi.fn(() => ({ /* ... */ })),
+}));
+
+// RIGHT: function expression - usable with `new`
+vi.mock("@miden-sdk/miden-sdk", () => ({
+  MidenClient: vi.fn(function () {
+    return { /* ... */ };
+  }),
+}));
+```
+
+This applies to any class mocked at module level that production code instantiates with `new` (`new MidenClient(...)`, `new WasmWebClient(...)`, etc.). When tests fail with `TypeError: ... is not a constructor` after a Vitest v4 upgrade, swap the arrow-function bodies for `vi.fn(function () { ... })`.
+
+For component-level wallet adapters and hooks that are function references rather than classes (the existing `vi.mock("@miden-sdk/miden-wallet-adapter-react", ...)` example above), arrow-function mocks remain fine.
+
+## Testing Time-Dependent Code (Network Sync Delay)
+
+Production code that polls or waits on chain state should accept the delay interval as an injectable parameter rather than hardcoding it. This lets tests replace the production default (e.g. `5000` ms) with `0` so the loop drains synchronously without `vi.useFakeTimers()` plumbing.
+
+Pattern:
+
+```ts
+// Production: optional delay parameter with a sensible default
+export function pollUntilCommit(
+  txId: string,
+  intervalMs = 5000,            // production default
+) {
+  // ... uses setTimeout(..., intervalMs) or `await sleep(intervalMs)`
+}
+
+// Tests: pass 0 to skip waits
+const result = await pollUntilCommit(txId, 0);
+```
+
+When the value comes from `src/config.ts` (e.g. `NETWORK_SYNC_DELAY_MS`), expose the same override there so tests can stub it via `vi.mock("@/config", ...)` without touching app code:
+
+```ts
+// src/config.ts
+export const NETWORK_SYNC_DELAY_MS = Number(import.meta.env.VITE_NETWORK_SYNC_DELAY_MS ?? 5000);
+
+// test
+vi.mock("@/config", () => ({ NETWORK_SYNC_DELAY_MS: 0 }));
 ```
 
-Vitest config externalizes `@miden-sdk/miden-wallet-adapter*` sub-packages to prevent broken transitive resolution from the reactui sub-package.
+Document the production default and the test override at the call site so the contract between app code and tests is obvious.
 
 ## Automated Verification Pipeline
 
 Hooks in `.claude/settings.json` enforce quality automatically:
 
-1. **PostToolUse: typecheck** — `npx tsc -b --noEmit` on every `.ts`/`.tsx` edit in `src/`
-2. **PostToolUse: affected tests** — `npx vitest --changed --run` on every `.ts`/`.tsx` edit in `src/`
-3. **Stop hook** — Full `vitest --run && tsc -b --noEmit && vite build` before task completion
+1. **PostToolUse: typecheck** - `npx tsc -b --noEmit` on every `.ts`/`.tsx` edit in `src/`
+2. **PostToolUse: affected tests** - `npx vitest --changed --run` on every `.ts`/`.tsx` edit in `src/`
+3. **PostToolUse: full suite** - Full `vitest --run && tsc -b --noEmit && vite build` after each edit
 
 If any hook fails (exit code 2), the agent is blocked from proceeding until the issue is fixed.
 
@@ -163,7 +324,7 @@ If any hook fails (exit code 2), the agent is blocked from proceeding until the
    ↓
 6. Refactor if needed
    ↓
-7. Task complete       → Stop hook: full suite + build
+7. Task complete       → full suite already ran after last edit
 ```
 
 ## Common Mistakes

package/template/.claude/skills/vite-wasm-setup/SKILL.md

@@ -13,42 +13,48 @@ import react from "@vitejs/plugin-react";
 import { midenVitePlugin } from "@miden-sdk/vite-plugin";
 
 export default defineConfig({
-  plugins: [react(), midenVitePlugin()],
+  plugins: [react(), midenVitePlugin({ crossOriginIsolation: true })],
 });
 ```
 
-`midenVitePlugin()` accepts an options object:
+Pass `crossOriginIsolation: true` explicitly. The Miden WASM client uses `SharedArrayBuffer` via Rust atomics, which is only available when the page is cross-origin-isolated (COOP `same-origin` + COEP `require-corp`). Don't rely on the plugin's own default — it has shifted across releases, so the template's config is source-of-truth.
 
-```typescript
-midenVitePlugin({ crossOriginIsolation: true })
-// Enables COOP/COEP headers in dev server. Defaults to false to avoid breaking OAuth popups.
-```
+If your app must host third-party iframes, OAuth popups, or other cross-origin resources that don't emit `require-corp`, either (a) embed them via `credentialless` COEP as a workaround (see the Gotchas section below), or (b) set `crossOriginIsolation: false` and accept that Miden client operations won't work on that route.
 
 ## What midenVitePlugin() Handles
 
-`@miden-sdk/vite-plugin` abstracts all Miden-specific Vite configuration:
+`@miden-sdk/vite-plugin` abstracts Miden-specific Vite configuration:
 
 - **WASM loading** — Configures Vite to correctly import `.wasm` modules
 - **Top-level await** — Enables top-level `await` required by the WASM SDK initialization
 - **optimizeDeps** — Excludes `@miden-sdk/miden-sdk` from pre-bundling (pre-bundling corrupts the WASM binary)
-- **COOP/COEP headers** — Optionally adds `Cross-Origin-Opener-Policy` and `Cross-Origin-Embedder-Policy` headers via `crossOriginIsolation` option
+- **COOP/COEP headers** — Emits `Cross-Origin-Opener-Policy: same-origin` + `Cross-Origin-Embedder-Policy: require-corp` on the dev server when `crossOriginIsolation: true`
 
-You do not need to install or configure `vite-plugin-wasm`, `vite-plugin-top-level-await`, or dexie aliases manually.
+You don't need to install or configure `vite-plugin-wasm`, `vite-plugin-top-level-await`, or dexie aliases manually.
 
 ## Required Dependencies
 
+Keep all `@miden-sdk/*` runtime packages aligned. The template's `package.json` pins them as an exact-version set; upgrade all four together and re-run the full verification suite (including the wallet-confirmed increment E2E) whenever you bump.
+
 ```json
 {
   "dependencies": {
-    "@miden-sdk/react": "^0.13.0",
-    "@miden-sdk/miden-sdk": "^0.13.0"
+    "@miden-sdk/react": "<matches miden-sdk>",
+    "@miden-sdk/miden-sdk": "<authoritative version>",
+    "@miden-sdk/miden-wallet-adapter-base": "<may lag by a patch>",
+    "@miden-sdk/miden-wallet-adapter-react": "<may lag by a patch>"
   },
   "devDependencies": {
-    "@miden-sdk/vite-plugin": "^0.13.0"
+    "@miden-sdk/vite-plugin": "<matches miden-sdk>"
   }
 }
 ```
 
+Notes:
+- **Always check `package.json` for the authoritative versions** — this skill intentionally doesn't inline them because they shift across SDK releases.
+- The wallet adapter packages are versioned separately from the core SDK. Their `peerDependencies` typically allow `^<major>.<minor>.x`, so a patch-level gap between the adapter and the core SDK is expected and fine.
+- When you bump, clean-install: `rm -rf node_modules yarn.lock && yarn install`. Vite's dep optimizer caches resolved SDK paths, and stale caches can surface as `ERR_BLOCKED_BY_RESPONSE` or spurious `Failed to fetch` errors on module workers.
+
 ## Production Deployment Headers
 
 COOP/COEP headers must be set on the production server. `midenVitePlugin({ crossOriginIsolation: true })` only affects the Vite dev server.
@@ -119,10 +125,10 @@ Standard Vite-compatible tsconfig settings work with Miden. The only actual cons
 
 | Issue | Cause | Fix |
 |-------|-------|-----|
-| "SharedArrayBuffer is not defined" | Missing COOP/COEP headers | Use `midenVitePlugin({ crossOriginIsolation: true })` in dev; set headers on production server |
+| "SharedArrayBuffer is not defined" | COOP/COEP headers not reaching the browser | Verify `midenVitePlugin({ crossOriginIsolation: true })` is in plugins; check production server headers separately |
 | WASM module not found | SDK not configured correctly | Ensure `midenVitePlugin()` is in plugins array |
 | "Top-level await not supported" | Missing plugin setup | Ensure `midenVitePlugin()` is in plugins array |
-| WASM init hangs | COEP blocking WASM fetch | Check network tab for blocked requests; enable `crossOriginIsolation` |
+| WASM init hangs | COEP blocking WASM fetch | Check network tab for blocked requests; verify COOP/COEP headers are present |
 | Build succeeds but WASM fails at runtime | Wrong MIME type | Serve .wasm as application/wasm |
 | "recursive use of an object" | Concurrent WASM access | Use runExclusive() from useMiden() |
 | Double initialization in dev | React StrictMode | Use MidenProvider (handles this internally) |