create-miden-app 1.0.4 → 1.0.6

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

@@ -0,0 +1,128 @@
+---
+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()],
+});
+```
+
+`midenVitePlugin()` accepts an options object:
+
+```typescript
+midenVitePlugin({ crossOriginIsolation: true })
+// Enables COOP/COEP headers in dev server. Defaults to false to avoid breaking OAuth popups.
+```
+
+## What midenVitePlugin() Handles
+
+`@miden-sdk/vite-plugin` abstracts all 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
+
+You do not need to install or configure `vite-plugin-wasm`, `vite-plugin-top-level-await`, or dexie aliases manually.
+
+## Required Dependencies
+
+```json
+{
+  "dependencies": {
+    "@miden-sdk/react": "^0.13.0",
+    "@miden-sdk/miden-sdk": "^0.13.0"
+  },
+  "devDependencies": {
+    "@miden-sdk/vite-plugin": "^0.13.0"
+  }
+}
+```
+
+## 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" | Missing COOP/COEP headers | Use `midenVitePlugin({ crossOriginIsolation: true })` in dev; set headers on production server |
+| 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` |
+| 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) |

package/template/.env.example

@@ -0,0 +1,5 @@
+# Miden RPC endpoint (default: "testnet")
+VITE_MIDEN_RPC_URL=testnet
+
+# Miden prover (default: "testnet", alternative: "local")
+VITE_MIDEN_PROVER=testnet

package/template/CLAUDE.md

@@ -0,0 +1,210 @@
+# Miden Frontend App
+
+React 19 + TypeScript + Vite frontend for the Miden blockchain.
+
+## Project Structure
+
+- `src/` — React application source
+- `src/components/` — UI components (Counter, AppContent)
+- `src/hooks/` — Custom hooks (useIncrementCounter)
+- `src/lib/` — Shared utilities
+- `src/__tests__/` — Test infrastructure (mocks, fixtures, patterns)
+- `src/components/__tests__/` — Component tests
+- `vite.config.ts` — Vite config with midenVitePlugin() from @miden-sdk/vite-plugin
+- `vitest.config.ts` — Vitest test runner config
+- `package.json` — Dependencies: @miden-sdk/react, @miden-sdk/miden-sdk
+
+## Build, Dev & Test
+
+```
+yarn dev             # Start dev server (Vite)
+yarn build           # Type check + production build (tsc -b && vite build)
+yarn lint            # ESLint
+yarn test            # Run all tests once (vitest --run)
+yarn test:watch      # Run tests in watch mode (vitest)
+yarn test:coverage   # Run tests with coverage report
+```
+
+Type checking alone:
+```
+npx tsc -b --noEmit
+```
+
+## SDK Choice: React SDK over Raw WebClient
+
+ALWAYS prefer `@miden-sdk/react` hooks over raw `@miden-sdk/miden-sdk` WebClient methods.
+Only use WebClient directly via `useMidenClient()` for operations not covered by hooks.
+
+### Setup (main.tsx or App.tsx)
+```tsx
+import { MidenProvider } from "@miden-sdk/react";
+
+<MidenProvider config={{ rpcUrl: "testnet", prover: "testnet" }}>
+  <App />
+</MidenProvider>
+```
+
+### Query Hooks
+Each returns its own result shape plus `isLoading`, `error`, `refetch`:
+```tsx
+const { wallets, faucets } = useAccounts();
+const { account, assets, getBalance } = useAccount(accountId);
+const { notes, consumableNotes } = useNotes();
+const { syncHeight, sync } = useSyncState();
+const { assetMetadata } = useAssetMetadata(faucetId);
+```
+
+### Mutation Hooks
+Each returns its own action function plus `isLoading`, `stage`, `error`, `reset`.
+Transaction stages: `idle → executing → proving → submitting → complete`
+```tsx
+const { createWallet } = useCreateWallet();
+const { send, stage } = useSend();
+const { consume } = useConsume();
+const { mint } = useMint();
+const { swap } = useSwap();
+const { execute } = useTransaction();  // arbitrary tx requests
+```
+
+### Token Amounts Are BigInt
+```tsx
+import { formatAssetAmount, parseAssetAmount } from "@miden-sdk/react";
+const display = formatAssetAmount(balance, 8);  // bigint → string
+const amount = parseAssetAmount("1.5", 8);       // string → bigint
+```
+
+## TDD Workflow
+
+When building features, follow this test-driven cycle:
+
+1. **Write a failing test** for the feature/component
+2. **Run tests** — confirm the test fails (red)
+3. **Implement** the minimum code to make the test pass
+4. **Run tests** — confirm all tests pass (green)
+5. **Refactor** if needed, re-run tests
+6. Type checking runs automatically after each edit (PostToolUse hook)
+7. Affected tests run automatically after each edit (PostToolUse hook)
+
+### Test file conventions
+- Component tests: `src/components/__tests__/ComponentName.test.tsx`
+- Hook tests: `src/hooks/__tests__/hookName.test.ts`
+- Pattern references: `src/__tests__/patterns/` — copy and adapt these
+
+### Writing tests for Miden components
+```tsx
+// 1. Mock the SDK at module level (always required)
+vi.mock("@miden-sdk/react", () => import("@/__tests__/mocks/miden-sdk-react"));
+
+// 2. Import hooks to override per-test
+import { useAccounts } from "@miden-sdk/react";
+
+// 3. Override in individual tests
+vi.mocked(useAccounts).mockReturnValue({ wallets: [], ... });
+```
+
+See `testing-patterns` skill for full mock factory reference and fixture data.
+
+## Verification Sequence
+
+Automated verification runs in layers (each catches different failure classes):
+
+1. **TypeScript type check** (auto, per-edit) — catches type errors immediately
+2. **Affected tests** (auto, per-edit) — catches logic regressions from changes
+3. **Full test suite + type check + build** (auto, on task completion via Stop hook) — catches integration issues
+4. **Browser verification** (manual/MCP) — catches "compiles but doesn't work" failures
+
+### Browser verification (when needed)
+After completing a feature, verify in the browser:
+1. Start dev server: `yarn dev`
+2. Navigate to `http://localhost:5173`
+3. Check for render errors and console messages
+4. If wallet-dependent features: ask the PM to verify with the MidenFi wallet extension
+
+## Contract Artifact Handoff
+
+Frontend loads pre-compiled `.masp` packages from `public/packages/` at runtime.
+
+### Artifact location
+```
+public/packages/
+├── counter_account.masp    # Counter account component
+└── increment_note.masp     # Increment note script
+```
+
+### Building artifacts
+In the contract project (e.g., `project-template/`):
+```bash
+cargo miden build --release
+# Copy .masp files from contracts/*/target/miden/release/ to public/packages/
+```
+
+### Validate artifacts
+```bash
+.claude/hooks/check-artifacts.sh
+```
+
+### Failure recovery
+- **Missing artifacts**: Build contracts with `cargo miden build` or ask the PM to supply the `.masp` files
+- **Stale artifacts**: Rebuild and re-copy after contract changes
+- **Deserialization failure at runtime**: Version mismatch — rebuild contracts with the SDK version matching `@miden-sdk/miden-sdk` in `package.json`
+
+## Critical Pitfalls
+
+**WASM init must complete first**: Always use MidenProvider's `loadingComponent` or check `useMiden().isReady`. Components rendering before WASM init will crash.
+
+**Recursive WASM access crashes**: Never call client methods concurrently. Use `runExclusive()` from `useMiden()` for sequential execution. Built-in hooks handle this automatically.
+
+**COOP/COEP headers required**: WASM SharedArrayBuffer needs `Cross-Origin-Opener-Policy: same-origin` and `Cross-Origin-Embedder-Policy: require-corp` in vite.config.ts AND production server.
+
+**Token amounts are bigint, not number**: `send({ amount: 1000 })` will fail. Use `amount: 1000n` or `parseAssetAmount("10", 8)`.
+
+## PM Workflow
+
+For non-developer users building with this template:
+
+1. Clone the repository and run `yarn install`
+2. Start Claude Code in the project directory
+3. Describe the app you want to build in natural language
+4. Claude will implement features using TDD — tests are written first, then code
+5. Automated hooks verify correctness at every step
+6. When Claude says "done", the Stop hook runs full tests + build automatically
+7. Review the app in the browser: `yarn dev` → open `http://localhost:5173`
+8. If using wallet features, install the MidenFi browser extension to test
+
+### Known limitations
+- **Visual correctness**: Automated tests verify structure and behavior, not visual appearance. Review the app in the browser for styling issues.
+- **Wallet extension**: Real wallet interactions require the MidenFi browser extension. Tests mock the wallet adapter.
+- **Network-dependent features**: Some features (syncing, transaction submission) require testnet connectivity.
+
+## Miden Skills
+
+For Miden-specific guidance, Claude will auto-load these skills when relevant:
+- `react-sdk-patterns` — Complete React SDK hook API reference
+- `testing-patterns` — Test mock factory, fixtures, and TDD conventions
+- `frontend-pitfalls` — All frontend/WASM/browser pitfalls with safe/unsafe examples
+- `miden-concepts` — Miden architecture from a developer perspective
+- `vite-wasm-setup` — Vite + WASM configuration, deployment headers, troubleshooting
+- `signer-integration` — External signer setup (Para, Turnkey, MidenFi)
+
+## General Frontend Skills (Recommended)
+
+For general React, TypeScript, and design capabilities, install these official skills alongside our Miden-specific ones:
+
+```bash
+# Vercel's React/design skills
+git clone https://github.com/vercel-labs/agent-skills.git
+# Install: react-best-practices, web-design-guidelines, composition-patterns
+
+# Anthropic's frontend design skill (Claude Code plugin)
+# See: https://github.com/anthropics/claude-code/tree/main/plugins/frontend-design
+```
+
+## Advanced Development
+
+For complex applications beyond basic hook usage (custom signers, raw WebClient, advanced note flows):
+
+1. Clone `miden-client` repo alongside this project (see `frontend-source-guide` skill)
+2. Use Plan Mode first — Claude explores React SDK source + examples before coding
+3. Claude uses sub-agents to explore repos efficiently without filling main context
+
+The basic skills cover ~80% of patterns. Source repos provide the remaining 20% for advanced builders.

package/template/README.md

@@ -1,22 +1,61 @@
-# React + TypeScript + Vite + Miden
+# Miden Frontend Template
 
-This template provides a minimal example on how to work with Miden using Vite.
+Minimal Vite + React + TypeScript template for building Miden frontends. Includes a network counter demo that publishes an increment note via the MidenFi wallet adapter.
 
-This repository is based on the actual [create-vite NPM template](https://www.npmjs.com/package/create-vite).
+## Getting Started
 
-## Demo Client Interaction
+```bash
+yarn install
+yarn dev
+```
 
-The project includes a simple example of Miden client interactions in `src/miden/lib/demo.ts`. This demo file showcases a workflow for interacting with the Miden network, including:
+Open [http://localhost:5173](http://localhost:5173). Connect your MidenFi wallet and click the counter button to publish an increment note.
 
-- **Client Initialization**: Connecting to the Miden Testnet
-- **Account Creation**: Creating new wallet accounts (Alice)
-- **Faucet Setup**: Creating a fungible token faucet with custom tokens
-- **Token Minting**: Minting tokens to an account via P2ID notes
-- **Note Consumption**: Consuming notes to receive fungible assets
-- **Token Transfers**: Sending tokens between accounts
+## Project Structure
 
-The demo is a practical reference for building client-side applications that interact with the Miden rollup network, demonstrating the key primitives and transaction flows available through the Miden SDK.
+```
+src/
+├── App.tsx                         # Root component
+├── providers.tsx                   # MidenProvider + wallet adapter setup
+├── config.ts                       # Constants (counter address, explorer URL, SDK config)
+├── components/
+│   ├── AppContent.tsx              # Page layout, logos, wallet button
+│   └── Counter.tsx                 # Counter UI
+├── hooks/
+│   └── useIncrementCounter.ts      # Note construction, wallet submission, re-sync
+└── lib/
+    └── miden.ts                    # Shared Miden utilities
+```
 
-### Running the Demo
+## Network Counter Demo
 
-To explore the demo implementation, check out `src/miden/lib/demo.ts`. This file can serve as a starting point for building your own Miden-enabled applications.
+The template demonstrates the network note pattern on Miden testnet:
+
+1. A **counter account** is deployed as a network account (`AccountStorageMode::Network`) at [`mtst1aru8adnrqspgcsr3drk2n990lyc070ll`](https://testnet.midenscan.com/account/mtst1aru8adnrqspgcsr3drk2n990lyc070ll)
+2. On button click, the frontend constructs a **public note** targeting the counter and submits it through the wallet adapter
+3. The **network operator** picks up the note and executes it against the counter account, incrementing the on-chain count
+4. The frontend re-syncs and reads the updated count from the counter's `StorageMap`
+
+Pre-compiled `.masp` packages for the counter account and increment note are in `public/packages/`.
+
+## Key Dependencies
+
+| Package | Purpose |
+|---------|---------|
+| `@miden-sdk/react` | React hooks for Miden (useAccount, useSyncState, useImportAccount, etc.) |
+| `@miden-sdk/miden-sdk` | Core SDK types (Note, NoteScript, AccountId, Word, etc.) |
+| `@miden-sdk/vite-plugin` | Vite plugin handling WASM loading, top-level await, and COOP/COEP |
+| `@miden-sdk/miden-wallet-adapter` | MidenFi wallet adapter for transaction submission |
+
+## Configuration
+
+SDK settings can be overridden via environment variables (see `.env.example`):
+
+```bash
+VITE_MIDEN_RPC_URL=testnet    # "testnet" | "localhost" | custom URL
+VITE_MIDEN_PROVER=testnet     # "testnet" | "local"
+```
+
+## AI Developer Experience
+
+This template ships with `.claude/` skills for AI coding tools. Skills cover React SDK patterns, frontend pitfalls, Vite + WASM setup, signer integration, and Miden architecture. See `CLAUDE.md` for the full developer guide.

package/template/create-miden-app/template/.claude/hooks/typecheck.sh

@@ -0,0 +1,27 @@
+#!/bin/bash
+# Post-edit hook: runs TypeScript type checking when .ts/.tsx files in src/ are modified.
+# Reads JSON input from stdin (Claude Code hook protocol).
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // .tool_input.filePath // empty')
+
+# Only trigger for TypeScript/React files in src/
+if [[ -z "$FILE_PATH" ]] || [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.tsx ]]; then
+  exit 0
+fi
+
+if [[ "$FILE_PATH" != *"/src/"* ]]; then
+  exit 0
+fi
+
+# Run TypeScript type checking from project root
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+if npx tsc -b --noEmit 2>&1; then
+  echo '{"hookSpecificOutput": {"additionalContext": "TypeScript type check passed"}}'
+  exit 0
+else
+  CHECK_OUTPUT=$(npx tsc -b --noEmit 2>&1 | tail -30)
+  echo "{\"hookSpecificOutput\": {\"additionalContext\": \"TypeScript type check FAILED. Fix type errors before continuing.\n$CHECK_OUTPUT\"}}"
+  exit 2
+fi

package/template/create-miden-app/template/.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/typecheck.sh",
+            "timeout": 60,
+            "statusMessage": "Type checking modified files..."
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/create-miden-app/template/.claude/skills/frontend-pitfalls/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: frontend-pitfalls
+description: Critical pitfalls and safety rules for Miden frontend development. Covers WASM initialization, concurrent access crashes, COOP/COEP headers, BigInt handling, Bech32 network mismatches, IndexedDB state loss, auto-sync side effects, Vite configuration, and React rendering race conditions. Use when reviewing, debugging, or writing Miden frontend code.
+---
+
+# Miden Frontend Pitfalls
+
+## FP1: WASM Initialization Race (CRITICAL)
+
+Components that use Miden hooks before MidenProvider finishes WASM initialization will crash.
+
+```tsx
+// WRONG — crashes if WASM not ready
+function App() {
+  const { data } = useAccounts(); // throws before init
+  return <div>{data?.wallets.length}</div>;
+}
+
+// CORRECT — use loadingComponent or check isReady
+<MidenProvider
+  config={{ rpcUrl: "devnet" }}
+  loadingComponent={<p>Loading WASM...</p>}
+>
+  <App />
+</MidenProvider>
+
+// CORRECT — guard with isReady
+function App() {
+  const { isReady } = useMiden();
+  if (!isReady) return <p>Loading...</p>;
+  return <WalletView />;
+}
+```
+
+## FP2: Recursive WASM Access Crash (CRITICAL)
+
+The WASM client is single-threaded. Concurrent calls crash with "recursive use of an object detected".
+
+```tsx
+// WRONG — two operations running simultaneously
+const handleClick = async () => {
+  sync();                    // fires async
+  await send({ ... });       // runs concurrently — CRASH
+};
+
+// CORRECT — use runExclusive for sequential execution
+const { runExclusive } = useMiden();
+await runExclusive(async (client) => {
+  await client.syncState();
+  // now safe to do next operation
+});
+```
+
+Built-in hooks (useSend, useConsume, etc.) already use runExclusive internally. This pitfall applies when using `useMidenClient()` directly or mixing manual client calls with hook mutations.
+
+## FP3: COOP/COEP Headers Missing (CRITICAL)
+
+WASM SharedArrayBuffer requires these headers. Without them, WASM init silently fails.
+
+```ts
+// REQUIRED in vite.config.ts
+server: {
+  headers: {
+    "Cross-Origin-Opener-Policy": "same-origin",
+    "Cross-Origin-Embedder-Policy": "require-corp",
+  },
+},
+
+// ALSO REQUIRED on production server (nginx, Vercel, Cloudflare)
+// See vite-wasm-setup skill for deployment configs
+```
+
+**Gotcha**: These headers break third-party iframes, external scripts without CORS, and OAuth popups. Use `credentialless` for COEP if cross-origin resources are needed.
+
+**Note**: `midenVitePlugin()` from `@miden-sdk/vite-plugin` handles COOP/COEP automatically via its `crossOriginIsolation` option (defaults to `false` to avoid breaking OAuth popups). Enable it instead of setting headers manually.
+
+## FP4: BigInt Type Mismatch (HIGH)
+
+All token amounts in the SDK are `bigint`. Passing `number` causes TypeScript errors or runtime failures.
+
+```tsx
+// WRONG
+await send({ from, to, assetId, amount: 1000 });        // number — fails
+await createFaucet({ maxSupply: 1000000, ... });          // number — fails
+
+// CORRECT
+await send({ from, to, assetId, amount: 1000n });        // bigint literal
+await createFaucet({ maxSupply: BigInt(1000000), ... });  // BigInt constructor
+
+// CORRECT — use parseAssetAmount for user input
+import { parseAssetAmount } from "@miden-sdk/react";
+const amount = parseAssetAmount(inputValue, 8);           // string → bigint
+```
+
+**Gotcha**: `JSON.stringify` cannot serialize `bigint`. Use a custom replacer or convert to string first.
+
+## FP5: Bech32 Network Mismatch (HIGH)
+
+Bech32-encoded account IDs include the network. A devnet address on testnet points to a different or nonexistent account.
+
+```tsx
+// WRONG — hardcoding a bech32 address used across networks
+const ADMIN = "miden1qy35..."; // this is network-specific!
+
+// CORRECT — use hex format for cross-network compatibility
+const ADMIN = "0x1234567890abcdef";
+
+// CORRECT — derive bech32 per network
+account.bech32id(); // returns correct bech32 for current network
+```
+
+Both hex and bech32 formats work in all hooks. Prefer hex for constants, bech32 for display.
+
+## FP6: Auto-Sync Side Effects (MEDIUM)
+
+Default `autoSyncInterval` is 15000ms (15 seconds). Each sync triggers re-renders in useAccounts, useAccount, useNotes, etc.
+
+```tsx
+// PROBLEM — form resets every 15 seconds because parent re-renders
+<MidenProvider config={{ rpcUrl: "devnet" }}>
+  <SendForm />  {/* re-renders on every sync */}
+</MidenProvider>
+
+// SOLUTION 1 — preferred: use stable keys and memoization
+const MemoizedForm = React.memo(SendForm);
+
+// SOLUTION 2 — disable auto-sync for manual control
+<MidenProvider config={{ rpcUrl: "devnet", autoSyncInterval: 0 }}>
+```
+
+## FP7: IndexedDB State Loss (MEDIUM)
+
+The client persists accounts, keys, and notes in IndexedDB. Browser "Clear site data", private browsing, or storage pressure can delete everything.
+
+- Warn users that clearing browser data deletes their wallet
+- Consider external signers (Para, Turnkey) for production — keys are server-side
+- Implement account export/backup for local keystore users
+
+## FP8: Vite Configuration Requirements (MEDIUM)
+
+The `@miden-sdk/vite-plugin` package handles all Miden-specific Vite config.
+The minimal setup is:
+
+```ts
+import { midenVitePlugin } from "@miden-sdk/vite-plugin";
+
+export default defineConfig({
+  plugins: [react(), midenVitePlugin()],
+});
+```
+
+`midenVitePlugin()` handles: WASM loading, top-level await, WASM pre-bundling exclusion,
+and optionally COOP/COEP headers (via the `crossOriginIsolation` option, defaults to `false`
+to avoid breaking OAuth popups).
+
+| Option | Default | Purpose |
+|--------|---------|---------|
+| `crossOriginIsolation` | `false` | Add COOP/COEP headers for SharedArrayBuffer |
+
+Enable `crossOriginIsolation: true` only if your app doesn't use OAuth or cross-origin iframes.
+For production COOP/COEP, set headers at the server level (see vite-wasm-setup skill).
+
+## FP9: React StrictMode Double-Init (LOW)
+
+React 19 StrictMode double-invokes effects in development. MidenProvider handles this via `isInitializedRef`, but direct `WebClient.createClient()` calls will initialize twice.
+
+```tsx
+// WRONG — manual client creation in useEffect
+useEffect(() => {
+  const client = await WebClient.createClient(url); // called twice in dev
+}, []);
+
+// CORRECT — always use MidenProvider
+<MidenProvider config={{ rpcUrl: "devnet" }}>
+```
+
+## Quick Reference
+
+| # | Pitfall | Severity | One-Line Rule |
+|---|---------|----------|---------------|
+| FP1 | WASM init race | CRITICAL | Use loadingComponent or check isReady |
+| FP2 | Recursive WASM | CRITICAL | Use runExclusive() for all direct client access |
+| FP3 | COOP/COEP | CRITICAL | Add headers in vite.config.ts AND production server |
+| FP4 | BigInt | HIGH | All amounts are bigint (1000n not 1000) |
+| FP5 | Bech32 mismatch | HIGH | Match network in rpcUrl and addresses |
+| FP6 | Auto-sync | MEDIUM | Set autoSyncInterval: 0 if UI stability matters |
+| FP7 | IndexedDB loss | MEDIUM | Warn users; use external signers for production |
+| FP8 | Vite config | MEDIUM | Use `midenVitePlugin()` — it handles all Miden Vite config |
+| FP9 | StrictMode | LOW | Use MidenProvider, not manual client creation |