docs: align interwovenkit-react docs

docs.json

@@ -460,7 +460,10 @@
               },
               {
                 "group": "Utilities",
-                "pages": ["interwovenkit/references/utilities/inject-styles"]
+                "pages": [
+                  "interwovenkit/references/utilities/inject-styles",
+                  "interwovenkit/references/utilities/testing"
+                ]
               },
               {
                 "group": "Errors",

interwovenkit/features/autosign/api-reference.mdx

@@ -27,12 +27,16 @@ function MyComponent() {
 ```tsx
 interface AutoSign {
   isLoading: boolean
-  enable: (chainId?: string) => Promise<void>
+  enable: (chainId?: string, options?: EnableAutoSignOptions) => Promise<void>
   disable: (chainId?: string) => Promise<void>
   expiredAtByChain: Record<string, Date | null | undefined>
   isEnabledByChain: Record<string, boolean>
   granteeByChain: Record<string, string | undefined>
 }
+
+interface EnableAutoSignOptions {
+  defaultDuration?: number
+}
 ```
 
 ## Properties
@@ -157,7 +161,10 @@ function MultiChainStatus() {
 
 Enables autosign for a specific chain or the default chain.
 
-<ParamField path="enable" type="(chainId?: string) => Promise<void>">
+<ParamField
+  path="enable"
+  type="(chainId?: string, options?: EnableAutoSignOptions) => Promise<void>"
+>
   Opens a drawer for user confirmation, derives the AutoSign wallet for the
   current app origin, and creates the necessary authz and feegrant permissions.
   Returns a Promise that resolves when autosign is successfully enabled or
@@ -166,6 +173,9 @@ Enables autosign for a specific chain or the default chain.
 **Parameters:** - `chainId` (optional): Chain ID to enable autosign for. If not
 provided, uses the default chain ID from `InterwovenKitProvider`.
 
+- `options` (optional): Extra enable-flow options. `defaultDuration` preselects
+  the expiration duration shown in the enable drawer.
+
 **Returns:** Promise that resolves when autosign is enabled
 
 **Throws:** Error if user rejects the derivation or grant flow, or if the

interwovenkit/references/components/interwovenkit-provider.mdx

@@ -88,6 +88,7 @@ export function AppProviders({ children }: { children: React.ReactNode }) {
 | `disableAnalytics`       | `boolean`                             | `false` (mainnet), `true` (testnet) | When `true`, disables InterwovenKit's built‑in analytics events                                                                                                                                                      |
 | `enableAutoSign`         | `boolean \| Record<string, string[]>` | `undefined`                         | Enables AutoSign and optionally whitelists chains and message types. `true` enables the default message type for the current default chain. `Record<string, string[]>` is a per-chain allowlist of message type URLs |
 | `autoSignFeePolicy`      | `Record<string, AutoSignFeePolicy>`   | `undefined`                         | Optional per-chain fee policy overrides for AutoSign gas multiplier and allowed fee denoms                                                                                                                           |
+| `cosmosWallets`          | `CosmosWallet[]`                      | `undefined`                         | Additional Cosmos wallets shown in bridge wallet selection. Configured wallets are listed before the built-in Keplr and Leap entries, and a matching `name` replaces the built-in wallet with the same name          |
 
 ## Return Value
 
@@ -168,10 +169,11 @@ type Config = {
   disableAnalytics?: boolean
   enableAutoSign?: boolean | Record<string, string[]>
   autoSignFeePolicy?: Record<string, AutoSignFeePolicy>
+  cosmosWallets?: CosmosWallet[]
 }
 ```
 
-Types `Chain`, `GeneratedType`, `AminoConverters`, and `AutoSignFeePolicy` are
-from InterwovenKit source and its external dependencies. See
+Types `Chain`, `GeneratedType`, `AminoConverters`, `AutoSignFeePolicy`, and
+`CosmosWallet` are from InterwovenKit source and its external dependencies. See
 `@initia/initia-registry-types`, `@cosmjs/proto-signing`, and `@cosmjs/stargate`
 for related external types.

interwovenkit/references/hooks/use-interwovenkit.mdx

@@ -365,6 +365,11 @@ fees:
   Pre-calculated fee for the transaction.
 </ParamField>
 
+<ParamField path="preferredFeeDenom" type="string">
+  When AutoSign is enabled, prefers this denom for the fee if it's allowed and
+  available. Falls back to the chain's default fee denom otherwise.
+</ParamField>
+
 ### Transaction Confirmation Options
 
 The `WaitForTxOptions` interface defines parameters for tracking transaction
@@ -472,7 +477,18 @@ signing:
   Whether AutoSign status is being loaded.
 </ParamField>
 
-<ParamField path="autoSign.enable" type="(chainId?: string) => Promise<void>">
+<ParamField
+  path="autoSign.granteeByChain"
+  type="Record<string, string | undefined>"
+>
+  Map of chain IDs to the derived AutoSign wallet addresses authorized for each
+  chain.
+</ParamField>
+
+<ParamField
+  path="autoSign.enable"
+  type="(chainId?: string, options?: EnableAutoSignOptions) => Promise<void>"
+>
   Opens UI to enable AutoSign for a chain. Optionally specify a chain ID, or
   defaults to the provider's `defaultChainId` if omitted.
 </ParamField>
@@ -616,6 +632,7 @@ type TxParams = {
   memo?: string
   chainId?: string
   fee: StdFee
+  preferredFeeDenom?: string
 }
 
 type WaitForTxOptions = {
@@ -630,9 +647,13 @@ type AutoSignState = {
   isEnabledByChain: Record<string, boolean>
   granteeByChain: Record<string, string | undefined>
   isLoading: boolean
-  enable: (chainId?: string) => Promise<void>
+  enable: (chainId?: string, options?: EnableAutoSignOptions) => Promise<void>
   disable: (chainId?: string) => Promise<void>
 }
+
+type EnableAutoSignOptions = {
+  defaultDuration?: number
+}
 ```
 
 Types `OfflineAminoSigner`, `EncodeObject`, `Coin`, `StdFee`,

interwovenkit/references/index.mdx

@@ -17,6 +17,8 @@ flows. The API is organized into:
 - **Hooks**: React hooks for connection state, transactions, and data
   (`useInterwovenKit`, `useAddress`, `usePortfolio`, etc.)
 - **Utilities**: Helper functions (`injectStyles`)
+- **Testing**: Test helpers (`createTestWalletConnector`,
+  `createTestCosmosWallet`)
 - **Errors**: Error types thrown by the API (`MoveError`)
 - **Constants**: Configuration presets and default values (`MAINNET`, `TESTNET`,
   gas constants, `PRIVY_APP_ID`)
@@ -32,6 +34,9 @@ flows. The API is organized into:
   [`MAINNET`](./constants/mainnet) or [`TESTNET`](./constants/testnet)
 - **Inject styles**: Call [`injectStyles`](./utilities/inject-styles) before
   rendering InterwovenKit UI components
+- **Test helpers**: Use [`createTestWalletConnector`](./utilities/testing) and
+  [`createTestCosmosWallet`](./utilities/testing) for automated EVM and Cosmos
+  wallet tests
 - **Read connection state**: [`useAddress`](./hooks/use-address) or
   [`useInterwovenKit`](./hooks/use-interwovenkit)
 - **Open UI flows**: [`useInterwovenKit`](./hooks/use-interwovenkit)

interwovenkit/references/utilities/testing.mdx

@@ -0,0 +1,185 @@
+---
+title: Testing Helpers
+---
+
+## Overview
+
+- `createTestWalletConnector` creates a wagmi-compatible, in-memory EVM wallet
+  connector backed by a mnemonic or private key.
+- `createTestCosmosWallet` creates a Cosmos wallet entry that appears in the
+  Bridge wallet picker, derived lazily per chain prefix from a mnemonic.
+- Use these helpers when you want deterministic wallet behavior in automated
+  tests (Playwright, Cypress, Vitest) or local development without browser
+  extensions or external wallet apps.
+
+<Warning>
+  These helpers are intended for **testing and local development only**. They
+  read raw mnemonics and private keys directly from your environment. Never ship
+  them, or wallets created with them, with real user funds.
+</Warning>
+
+## Prerequisites
+
+- Must run in a browser-like environment for the EVM connector because it is
+  implemented as an injected wagmi connector.
+- Provide test credentials via environment variables (e.g. `TEST_MNEMONIC`,
+  `TEST_PRIVATE_KEY`, `TEST_COSMOS_MNEMONIC`) — never hardcode them in source.
+
+## `createTestWalletConnector`
+
+An EVM wallet connector that handles chain switching, message signing, and
+transaction submission entirely in memory. Standard contract interactions and
+RPC reads (gas estimation, receipts, etc.) are proxied to the chain's RPC node.
+
+```tsx
+import { createConfig, http } from 'wagmi'
+import { mainnet } from 'wagmi/chains'
+import { createTestWalletConnector } from '@initia/interwovenkit-react'
+
+const testConnector = createTestWalletConnector({
+  mnemonic: process.env.TEST_MNEMONIC!,
+  // Or: privateKey: process.env.TEST_PRIVATE_KEY as `0x${string}`,
+})
+
+const wagmiConfig = createConfig({
+  connectors: [testConnector],
+  chains: [mainnet],
+  transports: { [mainnet.id]: http() },
+})
+```
+
+### Config
+
+<ParamField path="mnemonic" type="string">
+  BIP-39 mnemonic phrase. Provide either `mnemonic` or `privateKey`.
+</ParamField>
+
+<ParamField path="privateKey" type="`0x${string}`">
+  Hex-encoded private key with `0x` prefix. Provide either `mnemonic` or
+  `privateKey`.
+</ParamField>
+
+<ParamField path="id" type="string" default='"testWallet"'>
+  Wagmi connector ID. Set this when running multiple test wallets in the same
+  config.
+</ParamField>
+
+<ParamField path="name" type="string" default='"Test Wallet"'>
+  Display name shown in the wallet selection UI.
+</ParamField>
+
+<ParamField path="rpcUrls" type="Record<number, string>">
+  CORS-friendly RPC URLs keyed by EVM chain ID. User-provided URLs override the
+  built-in defaults (Ethereum mainnet, Arbitrum One, Base) for matching chain
+  IDs.
+</ParamField>
+
+<ParamField path="debug" type="boolean" default="false">
+  When `true`, logs every RPC call to the console.
+</ParamField>
+
+<ParamField
+  path="sendTransactionOverrides"
+  type="{ gas?: bigint; maxFeePerGas?: bigint; maxPriorityFeePerGas?: bigint }"
+>
+  Overrides applied to every `eth_sendTransaction` call. Useful for forcing
+  failure scenarios in tests (e.g. `{ gas: 21000n }` to trigger out-of-gas
+  reverts on contract calls, or `{ maxFeePerGas: 1n }` to land below the base
+  fee).
+</ParamField>
+
+### Supported EIP-1193 methods
+
+| Method                                               | Behavior                                                                         |
+| ---------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `eth_requestAccounts`, `eth_accounts`                | Returns the derived account address                                              |
+| `eth_chainId`                                        | Returns the current chain ID (hex)                                               |
+| `personal_sign`                                      | Signs the message with the test account                                          |
+| `eth_signTypedData`, `eth_signTypedData_v4`          | Signs raw bytes (not EIP-712 compliant — sufficient for InterwovenKit's flows)   |
+| `wallet_switchEthereumChain`                         | Switches chain. Auto-registers from configured RPC URLs. Throws 4902 if unknown. |
+| `wallet_addEthereumChain`                            | Registers a new chain with its RPC URL                                           |
+| `wallet_getPermissions`, `wallet_requestPermissions` | Returns the `eth_accounts` permission                                            |
+| `eth_sendTransaction`                                | Signs locally via viem and broadcasts to the RPC node                            |
+| _Any other method_                                   | Proxied to the current chain's RPC node                                          |
+
+### Return value
+
+```ts
+function createTestWalletConnector(config: CreateTestWalletConfig): Connector
+```
+
+## `createTestCosmosWallet`
+
+Returns a `CosmosWallet` entry that appears in the Bridge wallet picker
+alongside Keplr and Leap. Pass it through the `cosmosWallets` prop on
+[`InterwovenKitProvider`](../components/interwovenkit-provider).
+
+```tsx
+import {
+  createTestCosmosWallet,
+  InterwovenKitProvider,
+  MAINNET,
+} from '@initia/interwovenkit-react'
+
+const testCosmosWallet = createTestCosmosWallet({
+  mnemonic: process.env.TEST_COSMOS_MNEMONIC!,
+})
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <InterwovenKitProvider {...MAINNET} cosmosWallets={[testCosmosWallet]}>
+      {children}
+    </InterwovenKitProvider>
+  )
+}
+```
+
+### Config
+
+<ParamField path="mnemonic" type="string" required>
+  BIP-39 mnemonic phrase used to derive Cosmos accounts.
+</ParamField>
+
+<ParamField path="name" type="string" default='"Test Cosmos Wallet"'>
+  Display name shown in the Bridge wallet selection list. A matching `name`
+  replaces the built-in wallet with the same name (e.g. naming this `Keplr`
+  replaces the Keplr entry).
+</ParamField>
+
+<ParamField path="image" type="string">
+  Wallet icon URL. Omit to show the default placeholder.
+</ParamField>
+
+<ParamField path="chains" type="Record<string, { prefix: string }>">
+  Override the bech32 prefix for specific chain IDs. By default the prefix is
+  derived from the chain ID stem (e.g. `noble-1` → `noble`). Use this for chains
+  whose prefix differs from the stem (e.g. `cosmoshub-4` → `cosmos`).
+</ParamField>
+
+<ParamField path="debug" type="boolean" default="false">
+  When `true`, logs signer creation to the console.
+</ParamField>
+
+### Return value
+
+```ts
+function createTestCosmosWallet(
+  config: CreateTestCosmosWalletConfig,
+): CosmosWallet
+```
+
+## Notes
+
+- `createTestWalletConnector` accepts either a `mnemonic` or a `privateKey`, not
+  both. Built-in CORS-safe RPCs are provided for Ethereum mainnet, Arbitrum One,
+  and Base; pass `rpcUrls` to add or override others.
+- `wallet_addEthereumChain` does **not** auto-switch to the newly added chain,
+  unlike MetaMask. Call `wallet_switchEthereumChain` afterwards to activate it.
+- `eth_signTypedData` and `eth_signTypedData_v4` sign raw bytes rather than
+  performing full EIP-712 encoding. InterwovenKit only relies on `personal_sign`
+  for key derivation, so this is sufficient for its flows but signatures will
+  not validate against on-chain EIP-712 verifiers (e.g. Permit2).
+- `createTestCosmosWallet` caches one signer per derived bech32 prefix, so
+  repeated tests are deterministic and fast.
+- See [`InterwovenKitProvider`](../components/interwovenkit-provider) for the
+  `cosmosWallets` prop and the related `CosmosWallet` type.