create-miden-app 1.0.4 → 1.0.7

package/template/CLAUDE.md

@@ -0,0 +1,243 @@
+# 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 Hooks First
+
+ALWAYS prefer `@miden-sdk/react` hooks over low-level `WasmWebClient` methods.
+Only use the WASM client directly via `useMidenClient()` for operations not covered by hooks.
+
+### Setup — this template's actual providers (`src/providers.tsx`)
+```tsx
+import { MidenProvider } from "@miden-sdk/react";
+import { MidenFiSignerProvider } from "@miden-sdk/miden-wallet-adapter-react";
+
+<MidenFiSignerProvider
+  appName={APP_NAME}
+  network={WalletAdapterNetwork.Testnet}
+  autoConnect
+>
+  <MidenProvider
+    config={{ rpcUrl: MIDEN_RPC_URL, prover: MIDEN_PROVER }}
+    loadingComponent={<div className="loading">Loading Miden WASM...</div>}
+  >
+    <App />
+  </MidenProvider>
+</MidenFiSignerProvider>
+```
+
+> `MidenFiSignerProvider` must wrap `MidenProvider`. `MidenProvider` reads from `SignerContext` during initialization (to wire its external-keystore client), so the signer context has to exist before `MidenProvider` mounts.
+
+### 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
+```
+
+For exhaustive hook API reference, read `node_modules/@miden-sdk/react/CLAUDE.md` and `node_modules/@miden-sdk/react/README.md`.
+
+## 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 each edit via PostToolUse) — catches integration issues
+4. **Browser verification** (Playwright MCP / Claude in Chrome) — catches "compiles but doesn't work" failures
+
+### Browser verification (when needed)
+
+Two tools are available for browser verification. Use whichever is appropriate:
+
+#### Playwright MCP (visual verification, no wallet)
+Configured in `.mcp.json`. Use for checking that the UI renders correctly, no console errors, layout looks right. Cannot interact with the MidenFi wallet extension.
+
+1. Start dev server: `yarn dev`
+2. Use Playwright MCP tools to navigate to `http://localhost:5173`
+3. Take a screenshot, check for render errors
+4. Check the browser console for errors
+
+#### Claude in Chrome (full verification, with wallet)
+Use for wallet-dependent features. Connects to the user's real browser where MidenFi is installed.
+
+1. Start Claude Code with `claude --chrome` (or run `/chrome` in session)
+2. Start dev server: `yarn dev`
+3. Navigate to `http://localhost:5173`
+4. Interact with wallet connect, transaction flows, etc.
+
+## 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`
+
+## Known Temporary Workarounds
+
+One remaining upstream feature gap. The README has full rationale + removal steps; summary below.
+
+**Fixed-interval network poll** ([0xMiden/miden-client#2111](https://github.com/0xMiden/miden-client/issues/2111)): `useIncrementCounter.ts::increment` polls the counter's storage map every `NETWORK_POLL_INTERVAL_MS` (2.5 s) until the value changes or `NETWORK_POLL_TIMEOUT_MS` (30 s) elapses. `useWaitForCommit` doesn't apply because the increment is wallet-submitted and consumed externally by the network operator — the local client never sees the tx. #2111 tracks a React-SDK subscription primitive for this case (narrowed from the broader event-system discussion in #467).
+
+## 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. Automated hooks run full tests + build after each code edit
+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, direct WasmWebClient access, 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,127 @@
-# 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 live Miden testnet network counter demo that publishes an increment note via the MidenFi wallet adapter and lets the network operator auto-execute it against the counter.
 
-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). The app connects to Miden testnet out of the box and renders the current counter value. Install the [MidenFi wallet extension](https://chromewebstore.google.com/detail/midenfi), connect, and click the counter to submit an increment.
 
-- **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 (configured / unconfigured)
+│   └── ConfiguredCounter.tsx       # Counter UI when address is set
+├── hooks/
+│   └── useIncrementCounter.ts      # Note construction, wallet submission, bounded poll
+└── lib/
+    └── miden.ts                    # Shared Miden utilities
 
-### Running the Demo
+public/packages/
+├── counter_account.masp            # Compiled counter contract (MASP format v4)
+└── increment_note.masp             # Compiled increment note script
+```
 
-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.
+## Network Counter Demo
+
+The template demonstrates the Miden network-note pattern on testnet:
+
+1. A **counter account** is deployed as a network account (`AccountStorageMode::Network`) on testnet. This template ships with a live deployment at [`mtst1aqmx7qv6h3y92sqsmunh8uht4ujmfy4j`](https://testnet.midenscan.com/account/mtst1aqmx7qv6h3y92sqsmunh8uht4ujmfy4j).
+2. On button click, the frontend constructs a **public note** targeting the counter and submits it through the MidenFi wallet (the wallet signs and posts the transaction, not the in-browser client).
+3. The **network operator** picks up the note (tag + `NoteAttachment::newNetworkAccountTarget`) and executes it against the counter account, incrementing the on-chain count.
+4. The frontend polls `client.getAccount(counterAddress)` and re-reads the `StorageMap`; once the value changes it updates the UI. If the network is slow, polling falls back to a 30 s timeout.
+
+Pre-compiled `.masp` packages built with `cargo-miden 0.8.1` (matching `@miden-sdk/miden-sdk@0.14.x`) live in `public/packages/`.
+
+### Pointing at your own counter
+
+The counter address is resolved at runtime via the `VITE_MIDEN_COUNTER_ADDRESS` environment variable (`src/config.ts`):
+
+| `VITE_MIDEN_COUNTER_ADDRESS` value | Effect |
+|---|---|
+| unset / commented out (default) | Use the live testnet counter shipped with the template (`mtst1aqmx7qv6h3y92sqsmunh8uht4ujmfy4j`). |
+| empty string (`VITE_MIDEN_COUNTER_ADDRESS=`) | Unconfigured — `<Counter>` renders the "address not configured" card and makes no network calls. |
+| any bech32 string (`mtst1...`) | Uses your own deployment. |
+
+The slot-name constant is fixed in `src/config.ts` and must match the counter contract's storage map name.
+
+To redeploy (e.g. after modifying contract sources):
+
+1. In the [project-template](https://github.com/0xMiden/project-template) repo on the `migrate-clien-v014` branch, run the deployment binary:
+   ```bash
+   cargo install cargo-miden --version 0.8.1
+   cargo run -p integration --release --bin increment_count
+   ```
+   The binary builds `contracts/counter-account` + `contracts/increment-note`, creates the counter with `AccountStorageMode::Network`, and prints the bech32 address.
+2. Copy the freshly built artifacts into this template:
+   ```bash
+   cp contracts/counter-account/target/miden/release/counter_account.masp \
+      <frontend-template>/public/packages/
+   cp contracts/increment-note/target/miden/release/increment_note.masp \
+      <frontend-template>/public/packages/
+   ```
+3. Set `VITE_MIDEN_COUNTER_ADDRESS=<your bech32 address>` in `.env` (or your shell environment) — no source edit required.
+4. Verify with `.claude/hooks/check-artifacts.sh` (checks MASP format version).
+
+## Key Dependencies
+
+| Package | Version pin | Purpose |
+|---------|-------------|---------|
+| `@miden-sdk/react` | `0.14.x` | React hooks for Miden (useAccount, useSyncState, useMiden, useMidenClient, useTransaction, …) |
+| `@miden-sdk/miden-sdk` | `0.14.x` | Core SDK types (Note, NoteScript, AccountId, Word, Felt, …) |
+| `@miden-sdk/vite-plugin` | `0.14.x` | Vite plugin that handles WASM loading, top-level await, and COOP/COEP |
+| `@miden-sdk/miden-wallet-adapter-react` | `0.14.x` | MidenFi wallet adapter React context + hooks |
+| `@miden-sdk/miden-wallet-adapter-base` | `0.14.x` | `Transaction.createCustomTransaction` helper used by the increment flow |
+
+## Configuration
+
+SDK settings can be overridden via environment variables (see `.env.example`):
+
+```bash
+VITE_MIDEN_RPC_URL=testnet   # "devnet" | "testnet" | "localhost" | custom URL
+VITE_MIDEN_PROVER=testnet    # "devnet" | "testnet" | "local" | custom URL
+```
+
+## Verification
+
+Automated gates that must all stay green:
+
+```bash
+npx tsc -b --noEmit       # type check
+npx vitest --run          # 36 unit tests (components, hook, patterns)
+npx vite build            # production build (emits dist/)
+npx eslint .              # lint
+```
+
+The PostToolUse hook runs typecheck + affected tests after every edit. The Stop hook runs the full suite when a task completes.
+
+Browser-level verification (render correctness, no console errors, wallet popup, E2E increment) can be done with either:
+- **Playwright MCP** for headless render / console checks
+- **Claude in Chrome** (via the `/chrome` command) to exercise the real MidenFi extension
+
+## Known Temporary Workarounds
+
+One active workaround remains after the 0.14.4 upgrade, covering an upstream feature gap. The inline comment in `src/hooks/useIncrementCounter.ts` describes the removal steps.
+
+### Fixed-interval network poll — waiting for Network-mode account updates ([miden-client#2111](https://github.com/0xMiden/miden-client/issues/2111))
+
+After `wallet.requestTransaction` returns, `src/hooks/useIncrementCounter.ts` bounded-polls the counter's storage map until the value changes or a 30 s timeout elapses. The React SDK's `useWaitForCommit` only watches *locally-submitted* transactions — our increment is wallet-submitted and consumed externally by the network operator, so it never reaches the local client's transaction log. [`#2111`](https://github.com/0xMiden/miden-client/issues/2111) tracks a React-SDK subscription primitive for account-state updates driven by external consumers (scoped narrowly from the broader event-system discussion in [`#467`](https://github.com/0xMiden/miden-client/issues/467)).
+
+**After #2111 lands a subscription primitive:**
+1. Replace the `while` poll loop in `useIncrementCounter.ts::increment` with the new subscription / waitFor API.
+2. Remove `NETWORK_POLL_INTERVAL_MS` + `NETWORK_POLL_TIMEOUT_MS` from `src/config.ts` if no other consumer depends on them.
+3. Remove the `#2111` TODO block.
+
+## 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, testing patterns, and Miden architecture. See `CLAUDE.md` for the full developer guide.

package/template/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <link rel="icon" type="image/svg+xml" href="/vite.svg" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>miden-frontend</title>
+    <title>Miden Template</title>
   </head>
   <body>
     <div id="root"></div>

package/template/package.json

@@ -7,28 +7,38 @@
     "dev": "vite",
     "build": "tsc -b && vite build",
     "lint": "eslint .",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "test": "vitest --run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest --run --coverage"
   },
   "dependencies": {
-    "@miden-sdk/miden-sdk": "^0.13.0",
-    "dexie": "^4.2.1",
+    "@miden-sdk/miden-wallet-adapter-base": "0.14.3",
+    "@miden-sdk/miden-wallet-adapter-react": "0.14.3",
+    "@miden-sdk/miden-sdk": "0.14.4",
+    "@miden-sdk/react": "0.14.4",
     "react": "^19.1.1",
     "react-dom": "^19.1.1"
   },
   "devDependencies": {
     "@eslint/js": "^9.36.0",
+    "@miden-sdk/vite-plugin": "0.14.4",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/node": "^24.6.0",
     "@types/react": "^19.1.16",
     "@types/react-dom": "^19.1.9",
-    "@vitejs/plugin-react": "^5.0.4",
+    "@vitejs/plugin-react": "^4.7.0",
     "eslint": "^9.36.0",
     "eslint-plugin-react-hooks": "^5.2.0",
     "eslint-plugin-react-refresh": "^0.4.22",
     "globals": "^16.4.0",
-    "typescript": "~5.9.3",
+    "jsdom": "^28.1.0",
+    "typescript": "~5.7.0",
     "typescript-eslint": "^8.45.0",
-    "vite": "^7.1.7",
-    "vite-plugin-top-level-await": "^1.6.0",
-    "vite-plugin-wasm": "^3.5.0"
+    "vite": "^6.0.0",
+    "vitest": "^4.0.18"
   }
 }

package/template/src/App.tsx

@@ -1,63 +1,10 @@
-import { useState } from "react";
-import reactLogo from "./assets/react.svg";
-import midenLogo from "./assets/miden.svg";
-import viteLogo from "/vite.svg";
-import "./App.css";
-import { demo } from "./miden/lib/demo";
-
-function App() {
-  const [count, setCount] = useState(0);
-  const [isRunning, setIsRunning] = useState(false);
-  const [result, setResult] = useState<string>("");
-
-  const handleDemoClick = async () => {
-    setIsRunning(true);
-    setResult("");
-    try {
-      await demo();
-      setResult("Demo executed successfully! Check console for output.");
-    } catch (error) {
-      setResult(
-        `Error: ${error instanceof Error ? error.message : String(error)}`
-      );
-    } finally {
-      setIsRunning(false);
-    }
-  };
+import { AppProviders } from "@/providers";
+import { AppContent } from "@/components/AppContent";
 
+export default function App() {
   return (
-    <>
-      <div>
-        <a href="https://vite.dev" target="_blank">
-          <img src={viteLogo} className="logo" alt="Vite logo" />
-        </a>
-        <a href="https://react.dev" target="_blank">
-          <img src={reactLogo} className="logo react" alt="React logo" />
-        </a>
-        <a href="https://docs.miden.xyz" target="_blank">
-          <img src={midenLogo} className="logo miden" alt="Miden logo" />
-        </a>
-      </div>
-      <h1>Vite + React + Miden</h1>
-      <div className="card">
-        <button onClick={() => setCount((count) => count + 1)}>
-          count is {count}
-        </button>
-        <p>
-          Edit <code>src/App.tsx</code> and save to test HMR
-        </p>
-      </div>
-      <div className="card">
-        <button onClick={handleDemoClick} disabled={isRunning}>
-          {isRunning ? "Running Demo..." : "Run Miden Demo"}
-        </button>
-        {result && <p style={{ marginTop: "1rem" }}>{result}</p>}
-      </div>
-      <p className="read-the-docs">
-        Click on the Vite, React, and Miden logos to learn more
-      </p>
-    </>
+    <AppProviders>
+      <AppContent />
+    </AppProviders>
   );
 }
-
-export default App;

package/template/src/__tests__/fixtures/accounts.ts

@@ -0,0 +1,68 @@
+/**
+ * Test fixtures for Miden frontend tests.
+ * Uses hex IDs (network-agnostic) and BigInt amounts matching real SDK shapes.
+ * These are mock values — never parsed by the real SDK at runtime.
+ */
+
+export const WALLET_ID_1 = "0x0a00000000000001";
+export const WALLET_ID_2 = "0x0a00000000000002";
+export const FAUCET_ID = "0x0a00000000000003";
+export const COUNTER_ID = "0x0a00000000000004";
+
+export const MOCK_WALLET_HEADER = {
+  id: WALLET_ID_1,
+  nonce: 1n,
+  storageCommitment: "0x0000000000000000000000000000000000000000000000000000000000000001",
+};
+
+export const MOCK_WALLET_HEADER_2 = {
+  id: WALLET_ID_2,
+  nonce: 0n,
+  storageCommitment: "0x0000000000000000000000000000000000000000000000000000000000000000",
+};
+
+export const MOCK_FAUCET_HEADER = {
+  id: FAUCET_ID,
+  nonce: 5n,
+  storageCommitment: "0x0000000000000000000000000000000000000000000000000000000000000005",
+};
+
+export const MOCK_ASSET_BALANCE = {
+  assetId: FAUCET_ID,
+  amount: 1000000000n, // 10.0 tokens with 8 decimals
+  symbol: "TEST",
+  decimals: 8,
+};
+
+export const MOCK_ASSET_BALANCE_EMPTY = {
+  assetId: FAUCET_ID,
+  amount: 0n,
+  symbol: "TEST",
+  decimals: 8,
+};
+
+export const MOCK_ACCOUNT = {
+  id: WALLET_ID_1,
+  nonce: 1n,
+  bech32id: () => WALLET_ID_1,
+};
+
+export const MOCK_ASSET_METADATA = {
+  assetId: FAUCET_ID,
+  symbol: "TEST",
+  decimals: 8,
+};
+
+// TransactionResult shape — matches @miden-sdk/react types for useMint / useConsume /
+// useSwap / useMultiSend / useTransaction result payloads.
+export const MOCK_TRANSACTION_RESULT = {
+  transactionId: "0xabc123def456789012345678901234567890123456789012345678901234abcd",
+};
+
+// SendResult shape — distinct from TransactionResult. @miden-sdk/react's useSend
+// returns { txId, note }, not { transactionId }. Keep these fixtures separate so
+// mocks for useSend don't bleed into mocks for TransactionResult-typed hooks.
+export const MOCK_SEND_RESULT = {
+  txId: "0xabc123def456789012345678901234567890123456789012345678901234abcd",
+  note: null,
+};

package/template/src/__tests__/fixtures/index.ts

@@ -0,0 +1,22 @@
+export {
+  WALLET_ID_1,
+  WALLET_ID_2,
+  FAUCET_ID,
+  COUNTER_ID,
+  MOCK_WALLET_HEADER,
+  MOCK_WALLET_HEADER_2,
+  MOCK_FAUCET_HEADER,
+  MOCK_ASSET_BALANCE,
+  MOCK_ASSET_BALANCE_EMPTY,
+  MOCK_ACCOUNT,
+  MOCK_ASSET_METADATA,
+  MOCK_TRANSACTION_RESULT,
+  MOCK_SEND_RESULT,
+} from "./accounts";
+
+export {
+  MOCK_NOTE_ASSET,
+  MOCK_NOTE_SUMMARY,
+  MOCK_INPUT_NOTE_RECORD,
+  MOCK_CONSUMABLE_NOTE_RECORD,
+} from "./notes";

package/template/src/__tests__/fixtures/notes.ts

@@ -0,0 +1,33 @@
+/**
+ * Realistic note fixtures for Miden frontend tests.
+ */
+
+import { FAUCET_ID, WALLET_ID_1, WALLET_ID_2 } from "./accounts";
+
+export const MOCK_NOTE_ASSET = {
+  assetId: FAUCET_ID,
+  amount: 500000000n, // 5.0 tokens with 8 decimals
+  symbol: "TEST",
+  decimals: 8,
+};
+
+export const MOCK_NOTE_SUMMARY = {
+  id: "0xnote1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
+  assets: [MOCK_NOTE_ASSET],
+  sender: WALLET_ID_2,
+};
+
+export const MOCK_INPUT_NOTE_RECORD = {
+  id: () => "0xnote1234567890abcdef1234567890abcdef1234567890abcdef1234567890ab",
+  assets: () => [{ faucetId: () => FAUCET_ID, amount: () => 500000000n }],
+  metadata: () => ({
+    sender: () => ({ toBech32: () => WALLET_ID_2 }),
+    noteType: () => 1,
+  }),
+  status: () => "committed",
+};
+
+export const MOCK_CONSUMABLE_NOTE_RECORD = {
+  ...MOCK_INPUT_NOTE_RECORD,
+  accountId: WALLET_ID_1,
+};