WizardConnect/docs/react.md

# React integration

`@wizardconnect/react` provides React components and hooks for dapp developers who want to add
WizardConnect wallet connectivity without writing relay boilerplate.

## Quick start

```tsx
import { useWizardConnect, WizardConnectQRDialog } from "@wizardconnect/react";

function App() {
  const wc = useWizardConnect({ dappName: "My Dapp" });

  return (
    <>
      <button onClick={wc.connect} disabled={wc.state !== "idle"}>
        Connect Wallet
      </button>

      {wc.uri && wc.qrUri && (
        <WizardConnectQRDialog
          show={wc.state === "connecting"}
          onClose={() => wc.disconnect()}
          uri={wc.uri}
          qrUri={wc.qrUri}
        />
      )}

      {wc.state === "connected" && (
        <p>Connected to {wc.walletName}</p>
      )}
    </>
  );
}
```

## useWizardConnect

The `useWizardConnect` hook manages the full relay lifecycle:

1. **`connect()`** — calls `initiateDappRelay()`, creates a `DappConnectionManager`, and returns
   the connection URI for QR display.
2. **Key exchange** — listens for `keyexchangecomplete` and persists the wallet's public key to
   localStorage for auto-reconnect.
3. **`walletready`** — updates `state` to `"connected"` and populates `walletName`/`walletIcon`.
4. **Auto-reconnect** — on mount, checks localStorage for a stored session with a `walletPublicKey`
   and automatically reconnects.
5. **`disconnect()`** — sends a courtesy disconnect, cleans up the relay, and clears session storage.

### Return value

```typescript
interface UseWizardConnectResult {
  state: "idle" | "connecting" | "connected" | "disconnected";
  manager: DappConnectionManager | null;
  uri: string | null;
  qrUri: string | null;
  walletName: string | null;
  walletIcon: string | null;
  connect: () => boolean;
  disconnect: () => Promise<void>;
  error: string | null;
}
```

### Using the manager

Once `state === "connected"`, the `manager` is a live `DappConnectionManager` from
`@wizardconnect/dapp`. Use it to derive addresses and request signatures:

```typescript
// Derive a receive address pubkey
const pubkey = wc.manager.getPubkey(0, 0n);

// Send a sign request
const seq = wc.manager.nextSequence();
const response = await wc.manager.sendSignRequest({ ... });
```

For most dapps, you'll wrap the manager in an app-specific wallet adapter (like
`RelayWalletDapp` in the Cauldron and Moria codebases).

## WizardConnectQRDialog

A framework-independent modal dialog for displaying the connection QR code. Uses inline styles
(no Tailwind or CSS framework dependency) with a dark theme by default.

### Customization

Colors, text, and logos are all customizable via props:

```tsx
<WizardConnectQRDialog
  show={true}
  onClose={handleClose}
  uri={connection.uri}
  qrUri={connection.qrUri}
  title="My Protocol"
  subtitle="Scan to pair your wallet"
  logoUrl="/my-logo.png"
  theme={{
    dialogBackground: "#0f172a",
    headerBackground: "#0f172a",
    borderColor: "#334155",
  }}
  onCopy={(uri) => {
    navigator.clipboard.writeText(uri);
    showToast("Copied!");
  }}
/>
```

The `onCopy` callback replaces the default `navigator.clipboard.writeText` behavior, which is
useful when the dapp has its own toast/notification system.

## AlphanumericQRCode

A standalone canvas-based QR code component. Uses QR Alphanumeric mode with error correction
level H (30% recovery), which allows a center logo overlay without breaking the code.

```tsx
<AlphanumericQRCode
  value="WIZ://..."
  size={280}
  foreground="#1e2a4a"
  background="#ffffff"
  logoUrl="/logo.png"
/>
```

## Session persistence

By default, `useWizardConnect` persists session credentials (private key, shared secret,
wallet public key, and xpub paths) to localStorage under the `wizardconnect-session` key.
This enables auto-reconnect when the user refreshes the page.

When xpub paths are cached, they are restored via `restoreSessionPaths()` on auto-reconnect
so that `getPubkey()` works immediately — before the wallet sends a new `wallet_ready`.

The persistence key and behavior can be customized:

```typescript
useWizardConnect({
  sessionKey: "my-app-wc-session",  // custom localStorage key
  persistSession: false,             // disable persistence entirely
});
```

Credentials are only stored after the key exchange completes. On disconnect, the stored session
is cleared.