create-miden-app 1.0.4 → 1.0.7

package/template/.claude/skills/signer-integration/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: signer-integration
+description: Guide to integrating external signers (Para, Turnkey, MidenFi wallet adapter) and building custom signers for Miden React frontends. Covers provider setup, passkey authentication, unified signer interface, custom SignerContext implementation, and custom account components. Use when adding wallet connection, authentication, or external key management to a Miden frontend.
+---
+
+# Miden Signer Integration
+
+## Overview
+
+By default, MidenProvider uses a **local keystore** (keys in IndexedDB, no wallet connection needed). For production apps, wrap MidenProvider with a signer provider to use external key management.
+
+Signer providers must wrap MidenProvider (outer → inner):
+```
+<SignerProvider>      ← manages keys + auth
+  <MidenProvider>     ← manages Miden client
+    <App />
+  </MidenProvider>
+</SignerProvider>
+```
+
+## Pre-Built Signer Providers
+
+### Para (EVM Wallets)
+```tsx
+import { ParaSignerProvider } from "@miden-sdk/para";
+
+<ParaSignerProvider apiKey="your-api-key" environment="PRODUCTION">
+  <MidenProvider config={{ rpcUrl: "testnet" }}>
+    <App />
+  </MidenProvider>
+</ParaSignerProvider>
+
+const { para, wallet, isConnected } = useParaSigner();
+```
+
+### Turnkey (Passkey Authentication)
+```tsx
+import { TurnkeySignerProvider } from "@miden-sdk/miden-turnkey-react";
+
+// Config is optional — defaults to https://api.turnkey.com
+// and reads VITE_TURNKEY_ORG_ID from environment
+<TurnkeySignerProvider>
+  <MidenProvider config={{ rpcUrl: "testnet" }}>
+    <App />
+  </MidenProvider>
+</TurnkeySignerProvider>
+
+// Or with explicit config:
+<TurnkeySignerProvider config={{
+  apiBaseUrl: "https://api.turnkey.com",
+  defaultOrganizationId: "your-org-id",
+}}>
+  ...
+</TurnkeySignerProvider>
+```
+
+Connect via passkey:
+```tsx
+import { useSigner } from "@miden-sdk/react";
+import { useTurnkeySigner } from "@miden-sdk/miden-turnkey-react";
+
+const { isConnected, connect, disconnect } = useSigner();
+await connect();  // triggers passkey flow, auto-selects account
+
+// Turnkey-specific extras
+const { client, account, setAccount } = useTurnkeySigner();
+```
+
+### MidenFi Wallet Adapter (Browser Extension)
+```tsx
+import { MidenFiSignerProvider } from "@miden-sdk/miden-wallet-adapter-react";
+import { WalletAdapterNetwork } from "@miden-sdk/miden-wallet-adapter-base";
+
+<MidenFiSignerProvider
+  appName="My App"                                        // optional: passed to MidenWalletAdapter
+  network={WalletAdapterNetwork.Testnet}                  // WalletAdapterNetwork enum: Devnet | Testnet | Localnet
+  autoConnect                                             // reconnect on mount. Default: false
+  accountType="RegularAccountImmutableCode"               // Default: "RegularAccountImmutableCode"
+  storageMode="public"                                    // "private" | "public" | "network". Default: "public"
+  customComponents={[myComponent]}                        // optional: custom AccountComponents
+  privateDataPermission={permission}                      // optional: private data access level
+  allowedPrivateData={allowedData}                        // optional: allowed private data types
+>
+  <MidenProvider config={{ rpcUrl: "testnet" }}>
+    <App />
+  </MidenProvider>
+</MidenFiSignerProvider>
+```
+
+With `MidenFiSignerProvider` in place, use `useSigner()` from the React SDK to manage connection state. The regular React SDK hooks (`useSend`, `useConsume`, etc.) automatically sign via the connected wallet — no additional wiring needed.
+
+### This template's MidenFi-specific pattern
+
+This template deviates from the generic `useSigner()` approach in two places — worth knowing because it's a pattern you'll likely want when the wallet extension is the primary signer:
+
+- **Wallet button uses `useMidenFiWallet()` + `WalletReadyState`** (`src/components/AppContent.tsx`). The button gates on `wallet.readyState` so it can render a disabled "Install MidenFi Wallet" state before the extension is detected. `useSigner().connect()` would silently fall through to the adapter's `window.open(adapter.url, ...)` install fallback (Chrome Web Store → Play Store redirect on some platforms); gating on `readyState` avoids that path entirely.
+- **Custom transaction flow calls `wallet.requestTransaction(...)` directly** (`src/hooks/useIncrementCounter.ts`). The counter increment builds a bespoke `TransactionRequest` (via `TransactionRequestBuilder`, a custom `Note` with `NoteAttachment.newNetworkAccountTarget`, etc.) and hands it to the wallet for signing + submission. The React SDK mutation hooks (`useSend`, `useConsume`, ...) don't cover this kind of custom note construction, and the tx is submitted by the wallet rather than the local client — so `useWaitForCommit` doesn't apply either.
+
+## Unified Signer Interface
+
+Works with any signer provider above:
+```tsx
+import { useSigner } from "@miden-sdk/react";
+
+const { isConnected, connect, disconnect, name } = useSigner();
+
+if (!isConnected) {
+  return <button onClick={connect}>Connect {name}</button>;
+}
+```
+
+## Building a Custom Signer
+
+Implement `SignerContextValue` via `SignerContext.Provider`:
+
+```tsx
+import { SignerContext } from "@miden-sdk/react";
+
+<SignerContext.Provider value={{
+  name: "MyWallet",
+  storeName: `mywallet_${userAddress}`,  // unique per user for DB isolation
+  isConnected: true,
+  accountConfig: {
+    publicKey: userPublicKeyCommitment,  // Uint8Array
+    storageMode: "private",
+  },
+  signCb: async (pubKey, signingInputs) => {
+    // Route to your signing service
+    return signature;  // Uint8Array
+  },
+  connect: async () => { /* trigger wallet connection */ },
+  disconnect: async () => { /* clear session */ },
+}}>
+  <MidenProvider config={{ rpcUrl: "testnet" }}>
+    <App />
+  </MidenProvider>
+</SignerContext.Provider>
+```
+
+**Required fields:**
+- `name` — Display name for the signer
+- `storeName` — Unique string per user (isolates IndexedDB data between users)
+- `accountConfig` — Public key commitment + storage mode
+- `signCb` — Callback that signs transaction data with your key management service
+- `connect` / `disconnect` — Session lifecycle handlers
+
+## Custom Account Components
+
+Attach application-specific `AccountComponent` instances (e.g., DEX logic from `.masp` packages) to accounts created by the signer:
+
+```tsx
+import { type SignerAccountConfig } from "@miden-sdk/react";
+import { AccountComponent } from "@miden-sdk/miden-sdk";
+
+const myDexComponent: AccountComponent = await loadCompiledComponent();
+
+const accountConfig: SignerAccountConfig = {
+  publicKeyCommitment: userPublicKeyCommitment,
+  accountType: "RegularAccountUpdatableCode",
+  storageMode: myStorageMode,
+  customComponents: [myDexComponent],
+};
+```
+
+Components are appended to the `AccountBuilder` after the default basic wallet component. The field is optional — omitting it preserves default behavior.
+
+## Which Signer to Choose
+
+| Signer | Auth Method | Keys Stored | Best For |
+|--------|-------------|-------------|----------|
+| Local keystore (default) | None | Browser IndexedDB | Development, demos |
+| Para | EVM wallet | Para servers | Apps with existing EVM users |
+| Turnkey | Passkey (biometric) | Turnkey servers | Consumer apps, no seed phrases |
+| MidenFi Wallet | Browser extension | Extension | Power users with MidenFi wallet |
+| Custom | Your choice | Your infrastructure | Enterprise, custom auth flows |
+
+**Key trade-off**: Local keystore requires no setup but keys are lost if the user clears browser data. External signers persist keys server-side but add a dependency.

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

@@ -0,0 +1,338 @@
+---
+name: testing-patterns
+description: Testing conventions, mock factory, fixtures, and TDD workflow for Miden frontend development. Covers Vitest + testing-library setup, @miden-sdk/react module mocking, realistic fixture data, test patterns for query and mutation hooks, and the automated verification pipeline. Use when writing, running, or debugging tests for Miden React components.
+---
+
+# Miden Frontend Testing Patterns
+
+## 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
+
+## Mock Factory: `@miden-sdk/react`
+
+All Miden SDK hooks are mocked via `src/__tests__/mocks/miden-sdk-react.ts`. This module exports mock implementations of every hook with realistic default return values.
+
+### Usage in test files
+
+```tsx
+// 1. Mock the entire module (hoisted to top by vitest)
+vi.mock("@miden-sdk/react", () => import("@/__tests__/mocks/miden-sdk-react"));
+
+// 2. Import hooks you want to override
+import { useAccounts, useSend } from "@miden-sdk/react";
+
+// 3. Override per-test
+it("shows empty state", () => {
+  vi.mocked(useAccounts).mockReturnValue({
+    accounts: [],
+    wallets: [],
+    faucets: [],
+    isLoading: false,
+    error: null,
+    refetch: vi.fn(),
+  });
+  render(<MyComponent />);
+});
+```
+
+### 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
+
+**Mutation hooks** return idle state by default:
+- `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
+
+```tsx
+// Show "proving" stage
+vi.mocked(useSend).mockReturnValue({
+  send: vi.fn(),
+  result: null,
+  isLoading: true,
+  stage: "proving",
+  error: null,
+  reset: vi.fn(),
+});
+
+// Show completed transaction - useSend returns SendResult { txId, note }
+vi.mocked(useSend).mockReturnValue({
+  send: vi.fn(),
+  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,
+  reset: vi.fn(),
+});
+```
+
+## Fixtures
+
+Realistic test data in `src/__tests__/fixtures/`:
+
+```tsx
+import {
+  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..." } - 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 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
+
+## Test Patterns (copy-adaptable)
+
+Reference tests in `src/__tests__/patterns/`:
+
+| Pattern | File | Tests |
+|---------|------|-------|
+| Provider/context setup | `provider-setup.test.tsx` | ready, loading, error states |
+| Query hook component | `query-hook.test.tsx` | data, loading, error, empty states |
+| Mutation hook component | `mutation-hook.test.tsx` | idle, stages, success, error, argument verification |
+
+### 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
+
+## Wallet connection state in tests
+
+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 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/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 }));
+```
+
+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. **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.
+
+## TDD Flow
+
+```
+1. Write test (describe expected behavior)
+   ↓
+2. yarn test           → RED (test fails)
+   ↓
+3. Implement code
+   ↓
+4. Auto hooks fire     → typecheck + affected tests
+   ↓
+5. yarn test           → GREEN (all pass)
+   ↓
+6. Refactor if needed
+   ↓
+7. Task complete       → full suite already ran after last edit
+```
+
+## Common Mistakes
+
+**Forgetting vi.clearAllMocks()**: Always call in `beforeEach` to prevent mock state leaking between tests.
+
+**Not mocking the SDK**: Components importing from `@miden-sdk/react` will fail without `vi.mock()` because the real SDK requires WASM initialization.
+
+**Using number instead of bigint**: Mock amounts must use `bigint` (`1000n`, not `1000`). The SDK enforces this at the type level.
+
+**Testing implementation details**: Test what the user sees (text, buttons, states), not internal hook calls. Use `screen.getByRole`, `screen.getByText`, not internal component state.

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

@@ -0,0 +1,134 @@
+---
+name: vite-wasm-setup
+description: Guide to configuring Vite for Miden WASM applications. Covers the midenVitePlugin() setup, COOP/COEP headers, production deployment headers, TypeScript compatibility, and troubleshooting common Vite + WASM issues. Use when setting up a new Miden frontend, debugging build or runtime errors related to WASM or Vite configuration, or deploying to production.
+---
+
+# Vite + WASM Configuration for Miden
+
+## Required vite.config.ts
+
+```typescript
+import { defineConfig } from "vite";
+import react from "@vitejs/plugin-react";
+import { midenVitePlugin } from "@miden-sdk/vite-plugin";
+
+export default defineConfig({
+  plugins: [react(), midenVitePlugin({ crossOriginIsolation: true })],
+});
+```
+
+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.
+
+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 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** — Emits `Cross-Origin-Opener-Policy: same-origin` + `Cross-Origin-Embedder-Policy: require-corp` on the dev server when `crossOriginIsolation: true`
+
+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": "<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": "<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.
+
+### Nginx
+```nginx
+add_header Cross-Origin-Opener-Policy same-origin;
+add_header Cross-Origin-Embedder-Policy require-corp;
+```
+
+### Vercel (vercel.json)
+```json
+{
+  "headers": [
+    {
+      "source": "/(.*)",
+      "headers": [
+        { "key": "Cross-Origin-Opener-Policy", "value": "same-origin" },
+        { "key": "Cross-Origin-Embedder-Policy", "value": "require-corp" }
+      ]
+    }
+  ]
+}
+```
+
+### Cloudflare Pages (_headers)
+```
+/*
+  Cross-Origin-Opener-Policy: same-origin
+  Cross-Origin-Embedder-Policy: require-corp
+```
+
+### WASM MIME Type
+Ensure your server serves `.wasm` files with `application/wasm` MIME type.
+
+## COOP/COEP Gotchas
+
+These headers break:
+- **Third-party iframes** (YouTube embeds, Twitter embeds, analytics)
+- **External scripts** without CORS headers
+- **OAuth popups** from different origins
+
+Workaround: Use `credentialless` for COEP if you need cross-origin resources:
+```
+Cross-Origin-Embedder-Policy: credentialless
+```
+
+Note: `credentialless` provides weaker isolation but allows most cross-origin resources.
+
+## TypeScript Compatibility
+
+Standard Vite-compatible tsconfig settings work with Miden. The only actual constraint is ES2020+ for `bigint` support:
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "bundler"
+  }
+}
+```
+
+`module: "ESNext"` and `moduleResolution: "bundler"` are standard Vite defaults, not Miden-specific requirements. If you're using the Vite-generated tsconfig, no changes are needed beyond ensuring `target` is ES2020+.
+
+## Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| "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; 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) |