create-miden-app 1.0.4 → 1.0.7

package/cli.js

@@ -39,12 +39,12 @@ async function main() {
   }
 
   console.log(`
-    ✅ Done!
-    Next steps:
-    cd ${projectName}
-    npm install
-    npm run dev
-    `);
+Done! Next steps:
+
+  cd ${projectName}
+  yarn install
+  yarn dev
+`);
 }
 
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-miden-app",
-  "version": "1.0.4",
+  "version": "1.0.7",
   "description": "A Miden Project Scaffold Template",
   "bin": {
     "create-miden-app": "cli.js"

package/template/.claude/commands/review-security.md

@@ -0,0 +1,67 @@
+---
+model: opus
+---
+
+You are a security-focused code reviewer specializing in web3, WASM, and TypeScript/Rust applications.
+
+Review the code at: $ARGUMENTS
+
+This can be a file, directory, or glob pattern. Read the relevant source files and perform a focused security audit across these dimensions, reporting only actual findings (skip any section with no issues):
+
+## 1. Input Validation & Injection
+- Are user-supplied strings (hex IDs, bech32 addresses, amounts) validated before being passed to WASM/Rust?
+- Can malformed input cause panics in Rust that propagate as unhandled exceptions in JS?
+- Are there any paths where unsanitized input reaches sensitive operations (key derivation, transaction building)?
+- Could numeric inputs overflow (e.g., BigInt conversion from plain numbers)?
+
+## 2. Key Material & Secrets
+- Is key material ever logged, serialized to JSON, or exposed in error messages?
+- Are private keys properly zeroed after use or held only in WASM memory?
+- Could keystore callbacks leak secrets through exception messages or stack traces?
+- Is seed material handled securely (not stored in localStorage, not logged)?
+
+## 3. Transaction Safety
+- Can transaction parameters be manipulated to send to unintended recipients?
+- Are there TOCTOU (time-of-check-time-of-use) issues between building and submitting transactions?
+- Could amount values be manipulated through type coercion (string→number precision loss)?
+- Are note IDs validated to prevent consuming the wrong notes?
+
+## 4. WASM Boundary
+- Are there memory safety issues at the JS↔WASM boundary?
+- Could JsValue conversions fail in ways that leave state inconsistent?
+- Are WASM errors properly caught or could they crash the runtime?
+- Is there potential for use-after-free when JS holds references to WASM objects?
+
+## 5. State & Storage
+- Is IndexedDB data integrity protected (could concurrent tabs corrupt state)?
+- Are there race conditions in async operations that could lead to double-spends or stale reads?
+- Could store export/import be used to replay old state maliciously?
+- Are database transactions (Dexie) used appropriately for atomic operations?
+
+## 6. Network & RPC
+- Are RPC responses validated before being trusted?
+- Could a malicious RPC endpoint feed incorrect block data or note metadata?
+- Is TLS enforced for RPC and prover connections?
+- Are there timing side-channels in how responses are processed?
+
+## 7. Supply Chain & Dependencies
+- Are there known vulnerable dependencies?
+- Are lockfile integrity hashes (`package-lock.json` / `yarn.lock` / `pnpm-lock.yaml`) unchanged when WASM-bundled dependencies (e.g. `@miden-sdk/*`) update?
+- Could wasm-bindgen-generated glue code introduce issues?
+
+## Output Format
+
+For each finding, use severity levels:
+- **[CRITICAL]** - Exploitable vulnerability that could cause loss of funds or key compromise
+- **[HIGH]** - Security issue that should be fixed before production use
+- **[MEDIUM]** - Weakness that could be exploited under specific conditions
+- **[LOW]** - Defense-in-depth improvement
+- **[INFO]** - Observation worth noting but not directly exploitable
+
+For each finding include:
+1. File and line number
+2. Description of the vulnerability
+3. Attack scenario (how it could be exploited)
+4. Recommended fix
+
+End with a summary: count of findings by severity, and the top 3 highest-priority items to address.

package/template/.claude/hooks/check-artifacts.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# Validates that required .masp contract artifacts exist in public/packages/.
+# Run before build or as a standalone check.
+
+cd "$CLAUDE_PROJECT_DIR" 2>/dev/null || cd "$(dirname "$0")/../.." || exit 1
+
+PACKAGES_DIR="public/packages"
+ERRORS=0
+
+if [ ! -d "$PACKAGES_DIR" ]; then
+  echo "ERROR: $PACKAGES_DIR directory does not exist"
+  exit 1
+fi
+
+# Check for .masp files
+MASP_FILES=$(find "$PACKAGES_DIR" -name "*.masp" 2>/dev/null)
+
+if [ -z "$MASP_FILES" ]; then
+  echo "ERROR: No .masp files found in $PACKAGES_DIR"
+  echo "Run 'cargo miden build' in the contract project and copy .masp files here."
+  exit 1
+fi
+
+echo "Contract artifacts in $PACKAGES_DIR:"
+while IFS= read -r file; do
+  SIZE=$(wc -c < "$file" | tr -d ' ')
+  if [ "$SIZE" -eq 0 ]; then
+    echo "  ERROR: $file is empty (0 bytes)"
+    ERRORS=$((ERRORS + 1))
+  elif [ "$SIZE" -lt 100 ]; then
+    echo "  WARN:  $file is suspiciously small ($SIZE bytes)"
+  else
+    echo "  OK:    $file ($SIZE bytes)"
+  fi
+done <<< "$MASP_FILES"
+
+if [ $ERRORS -gt 0 ]; then
+  echo ""
+  echo "$ERRORS artifact(s) have errors. Rebuild contracts with 'cargo miden build'."
+  exit 1
+fi
+
+echo ""
+echo "All artifacts valid."
+exit 0

package/template/.claude/hooks/run-affected-tests.sh

@@ -0,0 +1,31 @@
+#!/bin/bash
+# Post-edit hook: runs tests affected by changes since last commit.
+# Only triggers for .ts/.tsx files in src/. Uses vitest --changed for detection.
+
+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
+
+cd "$CLAUDE_PROJECT_DIR" || exit 0
+
+# Run tests affected by uncommitted changes (non-watch mode, no coverage)
+TEST_OUTPUT=$(npx vitest --changed --run 2>&1)
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -eq 0 ]; then
+  echo '{"hookSpecificOutput": {"additionalContext": "Affected tests passed"}}'
+  exit 0
+else
+  # Show last 30 lines of test output for context
+  TRIMMED=$(echo "$TEST_OUTPUT" | tail -30)
+  echo "{\"hookSpecificOutput\": {\"additionalContext\": \"Affected tests FAILED. Fix failing tests before continuing.\n$TRIMMED\"}}"
+  exit 2
+fi

package/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/.claude/settings.json

@@ -0,0 +1,29 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/typecheck.sh",
+            "timeout": 60,
+            "statusMessage": "Type checking modified files..."
+          },
+          {
+            "type": "command",
+            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/run-affected-tests.sh",
+            "timeout": 120,
+            "statusMessage": "Running affected tests..."
+          },
+          {
+            "type": "command",
+            "command": "cd \"$CLAUDE_PROJECT_DIR\" && npx vitest --run && npx tsc -b --noEmit && npx vite build",
+            "timeout": 300,
+            "statusMessage": "Running full test suite + type check + build..."
+          }
+        ]
+      }
+    ]
+  }
+}

package/template/.claude/settings.local.json

@@ -0,0 +1,24 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:api.github.com)",
+      "mcp__playwright__browser_navigate",
+      "mcp__playwright__browser_console_messages",
+      "mcp__playwright__browser_take_screenshot",
+      "WebFetch(domain:registry.npmjs.org)",
+      "mcp__playwright__browser_wait_for",
+      "mcp__playwright__browser_snapshot",
+      "mcp__playwright__browser_evaluate",
+      "WebFetch(domain:rpc.testnet.miden.io)",
+      "WebFetch(domain:testnet.midenscan.com)",
+      "WebFetch(domain:transport.miden.io)",
+      "mcp__playwright__browser_close",
+      "WebFetch(domain:scan-backend-testnet-miden.eu-central-8.gateway.fm)",
+      "WebFetch(domain:transport.devnet.miden.io)",
+      "WebFetch(domain:tx-prover.testnet.miden.io)",
+      "WebFetch(domain:registry.yarnpkg.com)",
+      "mcp__playwright__browser_network_requests"
+    ]
+  }
+}

package/template/.claude/skills/frontend-pitfalls/SKILL.md

@@ -0,0 +1,186 @@
+---
+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: "testnet" }}
+  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 client = useMidenClient();
+const { runExclusive } = useMiden();
+await runExclusive(async () => {
+  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.
+
+The template's source-of-truth pattern is to opt into COOP/COEP via the Vite plugin explicitly:
+
+```ts
+// vite.config.ts — template default
+import { midenVitePlugin } from "@miden-sdk/vite-plugin";
+
+export default defineConfig({
+  plugins: [react(), midenVitePlugin({ crossOriginIsolation: true })],
+});
+```
+
+Do not rely on the plugin's own default — `@miden-sdk/vite-plugin` defaults `crossOriginIsolation` to `false`, and that default has shifted across releases. Pass `true` explicitly on any route that runs Miden client code.
+
+COOP/COEP must also be set on the production server — the plugin only covers the Vite dev server. See `vite-wasm-setup` for per-host configs (Nginx, Vercel, Cloudflare).
+
+**Gotcha (opt-out path)**: Cross-origin-isolation breaks third-party iframes, external scripts without CORS, and OAuth popups. If a route must host those and cannot use Miden client code, either (a) use `Cross-Origin-Embedder-Policy: credentialless` for weaker isolation that still allows most cross-origin resources, or (b) scope `crossOriginIsolation: false` to that specific route and accept that Miden operations won't work there. Do not disable isolation globally as a convenience.
+
+## 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: "testnet" }}>
+  <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: "testnet", 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 template's source-of-truth pattern — which you should copy for any new Miden app — is:
+
+```ts
+import { midenVitePlugin } from "@miden-sdk/vite-plugin";
+
+export default defineConfig({
+  plugins: [react(), midenVitePlugin({ crossOriginIsolation: true })],
+});
+```
+
+`midenVitePlugin()` handles WASM loading, top-level await, pre-bundling exclusion, and — when `crossOriginIsolation: true` is passed — emits the COOP `same-origin` + COEP `require-corp` headers the SDK requires for `SharedArrayBuffer`.
+
+| Option | Plugin default | Template default | Purpose |
+|--------|----------------|------------------|---------|
+| `crossOriginIsolation` | `false` | **`true`** | Emit COOP/COEP headers for SharedArrayBuffer |
+
+Always pass `crossOriginIsolation: true` explicitly. The plugin's `false` default is wrong for a Miden app, and relying on it risks silent WASM-init failures if the default shifts in a future release. The opt-out path (routes that host OAuth popups or cross-origin iframes incompatible with isolation) is discussed in FP3. For production, set the same headers at the server level — see `vite-wasm-setup` for host-specific configs.
+
+## FP9: React StrictMode Double-Init (LOW)
+
+React 19 StrictMode double-invokes effects in development. MidenProvider handles this via `isInitializedRef`, but direct `WasmWebClient.createClient()` calls will initialize twice. (The SDK exports `WasmWebClient` as `WebClient` for convenience.)
+
+```tsx
+// WRONG — manual client creation in useEffect
+useEffect(() => {
+  const client = await WasmWebClient.createClient(url); // called twice in dev
+}, []);
+
+// CORRECT — always use MidenProvider
+<MidenProvider config={{ rpcUrl: "testnet" }}>
+```
+
+## 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 | Always pass `midenVitePlugin({ crossOriginIsolation: true })` — don't rely on the plugin default |
+| FP9 | StrictMode | LOW | Use MidenProvider, not manual client creation |

package/template/.claude/skills/frontend-source-guide/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: frontend-source-guide
+description: Guide for advanced Miden frontend development using source repo exploration. Covers AI development practices (Plan Mode, verification-driven development, context engineering, sub-agents) and maps the miden-client source repository for discovering advanced patterns. Use when building complex applications beyond basic hook usage, implementing custom signers, working with WasmWebClient directly, or troubleshooting SDK internals.
+---
+
+# Advanced Miden Frontend Development: Source-Guided Context Engineering
+
+## Development Approach
+
+### 1. Plan Mode First
+
+For any non-trivial frontend application, start in Plan Mode before writing code.
+
+- Explore React SDK source and examples to understand available patterns
+- Design the component hierarchy, data flow, and which hooks to use
+- Identify which built-in hooks cover your needs vs what requires direct WasmWebClient access
+- Map out the user flow: account creation, token operations, note handling
+
+Rule of thumb: if the task involves custom transactions, external signers, or patterns not covered by the basic skills, plan first.
+
+### 2. Verification-Driven Development
+
+This is the single highest-leverage practice for AI-assisted frontend development.
+
+**Type check loop**: After every file edit, run `npx tsc -b --noEmit`. The project's type check hook does this automatically. If types fail:
+1. Read the error message
+2. Search the React SDK source for the correct type signature or hook usage
+3. Adapt the working pattern to your use case
+4. Recheck
+
+**Dev server loop**: Run `npm run dev` and check the browser. When something fails:
+1. Check the browser console for WASM errors, network errors, or React errors
+2. For WASM errors: check COOP/COEP headers and Vite config (see frontend-pitfalls skill)
+3. For unexpected behavior: compare your code against the example wallet in the React SDK
+
+Never submit code that doesn't type-check. The verification loop is your quality guarantee.
+
+### 3. Context Engineering with Source Repos
+
+The basic skills (react-sdk-patterns, frontend-pitfalls, vite-wasm-setup) cover standard patterns. For anything beyond those patterns, the miden-client source repository is the knowledge base.
+
+**How to use source repos effectively**:
+- Don't load entire repos into context. Use sub-agents to explore — they search, read relevant files, and summarize findings without filling the main conversation context.
+- Read source files only when you need a specific answer (progressive disclosure)
+- Look for working examples first, then adapt. The example wallet app is the most reliable reference.
+- When you find a useful pattern in source, extract just what you need — the exact hook call, the exact type, the exact provider setup.
+
+**Using sub-agents for exploration**:
+- Launch an explore sub-agent with a specific question: "Find how useSwap handles the payback note type in the React SDK"
+- The sub-agent searches, reads the relevant files, and returns a focused summary
+- Your main context stays clean for implementation
+
+### 4. Iterative Frontend Development
+
+Break complex applications into stages. Complete each before starting the next:
+
+1. **Design** (Plan Mode) — Component hierarchy, data flow, hook selection
+2. **Provider setup** — MidenProvider config, signer integration if needed
+3. **Query components** — Account display, balance rendering, note lists
+4. **Mutation components** — Send forms, mint buttons, consume flows
+5. **Transaction UX** — Stage progress, error handling, loading states
+6. **Polish** — Auto-sync tuning, memoization, edge cases
+
+When stuck at any stage: search the React SDK source for a similar working pattern. Adapt it, don't guess.
+
+---
+
+## Miden Source Repository Map
+
+Clone this repo alongside your project for reference. Claude will explore it when needed for advanced patterns.
+
+```bash
+# Contains React SDK source, WasmWebClient WASM bindings, and working examples
+git clone --depth 1 https://github.com/0xMiden/miden-client.git ../miden-client
+```
+
+### `packages/react-sdk/` — React SDK Source
+
+The primary reference for all frontend development.
+
+- **`src/hooks/`** — All 18+ hook implementations. Each file is self-contained. Read these to understand exact parameters, error handling, and stage progression.
+- **`src/context/MidenProvider.tsx`** — Client initialization, sync loop, signer detection, runExclusive lock. Read this to understand initialization order.
+- **`src/context/SignerContext.ts`** — External signer interface. Read this when implementing custom signers.
+- **`src/store/MidenStore.ts`** — Zustand store structure. Read this to understand cached state and what triggers re-renders.
+- **`src/utils/`** — Utility implementations (amounts, notes, bech32, runExclusive, accountParsing).
+- **`src/types/index.ts`** — All TypeScript interfaces. The single source of truth for option types, result types, and configuration.
+- **`examples/wallet/`** — Complete working wallet app. The most reliable reference for how to set up MidenProvider, create accounts, display balances, claim notes, and send tokens.
+
+**Explore when**: Writing any new component, understanding exact hook behavior, finding how a specific feature works, debugging unexpected behavior.
+
+### `crates/web-client/` — WASM Client Bindings
+
+The Rust-to-WASM bridge that the React SDK wraps.
+
+- Contains the `WasmWebClient` struct and all methods available via `useMidenClient()`
+- JavaScript bindings in `js/` directory
+
+**Explore when**: A hook doesn't exist for your operation, understanding what WasmWebClient methods are available, debugging WASM-level errors.
+
+### `crates/idxdb-store/` — IndexedDB Persistence
+
+The browser storage layer for accounts, keys, notes, and transaction history.
+
+**Explore when**: Debugging data persistence issues, understanding what's stored in IndexedDB, investigating storage isolation for external signers.
+
+---
+
+## What to Explore for Each Pattern
+
+| Building This | Explore These Paths | What to Look For |
+|---|---|---|
+| Basic wallet UI | `examples/wallet/` | MidenProvider setup, useAccounts, useSend |
+| Custom transaction | `src/hooks/useTransaction.ts` | Request factory pattern, client methods |
+| External signer | `src/context/SignerContext.ts` | SignerContextValue interface, signCb |
+| Note consumption flow | `src/hooks/useConsume.ts` | NoteId parsing, filter construction |
+| Swap UI | `src/hooks/useSwap.ts` | Swap options, dual note types |
+| Token display | `src/utils/amounts.ts` | formatAssetAmount, parseAssetAmount |
+| Account ID formatting | `src/utils/accountBech32.ts` | toBech32AccountId |
+| State management | `src/store/MidenStore.ts` | Zustand selectors, cached state |
+| Direct WasmWebClient usage | `src/context/MidenProvider.tsx` | useMidenClient(), runExclusive |
+| Multi-step workflow | `src/hooks/useWaitForCommit.ts`, `useWaitForNotes.ts` | Polling, timeout patterns |
+
+---
+
+## Common Advanced Patterns
+
+### Custom Hooks Wrapping WasmWebClient
+For operations not covered by built-in hooks, create custom hooks that use useMidenClient() and runExclusive:
+```tsx
+function useBlockHeader(blockNumber: number) {
+  const client = useMidenClient();
+  const { runExclusive } = useMiden();
+  const [data, setData] = useState(null);
+  useEffect(() => {
+    // Note: runExclusive() may be simplified in a future SDK version.
+    // Check SDK changelog when upgrading.
+    runExclusive(async () => {
+      const header = await client.getBlockHeaderByNumber(blockNumber);
+      setData(header);
+    });
+  }, [blockNumber]);
+  return data;
+}
+```
+
+### Multi-Step Workflows
+Compose hooks for complex flows (mint → wait for commit → sync → consume):
+```tsx
+const { mint } = useMint();
+const { waitForCommit } = useWaitForCommit();
+const { waitForConsumableNotes } = useWaitForNotes();
+const { consume } = useConsume();
+
+const mintAndConsume = async () => {
+  const { transactionId } = await mint({ targetAccountId, faucetId, amount });
+  await waitForCommit(transactionId);
+  await waitForConsumableNotes({ accountId: targetAccountId });
+  await consume({ accountId: targetAccountId, notes: [...] });
+};
+```
+
+### Custom Signer Implementation
+Implement the SignerContextValue interface, wrap MidenProvider in your provider. Reference `src/context/SignerContext.ts` for the exact interface contract. The `storeName` field must be unique per user to ensure IndexedDB isolation.