@qrlwallet/connect 3.1.1 → 3.3.0

package/README.md

@@ -18,10 +18,12 @@ All communication is end-to-end encrypted with ML-KEM-768 (FIPS 203) key encapsu
 npm install @qrlwallet/connect
 ```
 
+Want a ready-made pairing dialog (QR code, deep link, copy-code fallback) instead of building your own? Add the framework-free [`@qrlwallet/connect-ui`](ui/) web component.
+
 ## Quick start
 
 ```typescript
-import { QRLConnect } from '@qrlwallet/connect';
+import { QRLConnect, attemptWalletRedirect, getAppStoreUrl } from '@qrlwallet/connect';
 
 const qrl = new QRLConnect({
   dappMetadata: {
@@ -34,9 +36,16 @@ const qrl = new QRLConnect({
 const uri = await qrl.getConnectionURI();
 
 // Desktop: render as QR code (use any QR library)
-// Mobile: redirect to open the wallet app
+// Mobile: try to open the wallet app, with a fallback for when it is
+// not installed (a bare `window.location.href = uri` fails at the
+// unknown protocol: silently on Android, blocking alert on iOS)
 if (qrl.isMobile()) {
-  window.location.href = uri;
+  const opened = await attemptWalletRedirect(uri);
+  if (!opened) {
+    // Wallet app not installed (or the user dismissed the chooser):
+    // show your QR / copy-code pairing UI plus an install link.
+    console.log('Get MyQRLWallet:', getAppStoreUrl());
+  }
 } else {
   // render uri as QR code
 }
@@ -82,6 +91,8 @@ const qrl = new QRLConnect({
   relayUrl: 'https://qrlwallet.com',  // default relay
   chainId: '0x0',                      // QRL chain ID
   autoReconnect: true,                 // reconnect on page load (default: true)
+  walletRedirectOnRequest: true,       // mobile: deep-link the wallet app awake
+                                       // for approval requests (default: true)
   debug: false,                        // console logging
 });
 ```
@@ -99,6 +110,8 @@ The main class. Creates a connection manager and EIP-1193 provider.
 | `isMobile()` | Check if the user is on a mobile browser |
 | `getAppStoreUrl()` | Get the app store link for QRL Wallet |
 | `isConnected()` | Whether the wallet is connected |
+| `isPaired()` | Whether a pairing exists, even while the wallet app is backgrounded |
+| `isWalletPresent()` | Whether the wallet is currently live in the relay channel |
 | `getAccounts()` | Get connected accounts |
 | `getStatus()` | Current connection status |
 | `hasStoredSession()` | Check if a reconnectable session exists in local storage |
@@ -115,7 +128,7 @@ The main class. Creates a connection manager and EIP-1193 provider.
 | `accountsChanged` | `string[]` | Account list changed |
 | `chainChanged` | `string` | Chain switched |
 | `statusChanged` | `ConnectionStatus` | Intermediate lifecycle states (see values below) |
-| `connection_lost` | — | Emitted after 5 failed reconnection attempts |
+| `connection_lost` | (none) | Emitted after 5 failed reconnection attempts |
 
 #### `ConnectionStatus` values
 
@@ -123,7 +136,7 @@ The main class. Creates a connection manager and EIP-1193 provider.
 |-------|---------|
 | `disconnected` | No active connection |
 | `connecting` | Connecting to relay server |
-| `waiting` | QR displayed, waiting for wallet to scan |
+| `waiting` | Waiting for the wallet: a first scan, or (when `isPaired()`) a backgrounded wallet app to return |
 | `key_exchange` | Post-quantum key exchange in progress |
 | `connected` | Wallet connected, ready for requests |
 | `reconnecting` | Attempting to restore a previous session |
@@ -142,12 +155,19 @@ The main class. Creates a connection manager and EIP-1193 provider.
 
 Sessions persist in `localStorage` for 7 days. When a user returns to your dApp, the SDK can automatically reconnect without requiring a new QR scan.
 
+A paired session also survives the wallet app being backgrounded or closed. On the same device at most one of the two apps is ever foregrounded, so the wallet's socket being absent is the normal steady state of a mobile flow, not an error:
+
+- `request()` still works while the wallet is away: the relay buffers the encrypted request for up to 5 minutes and the wallet drains it when it re-joins.
+- On mobile browsers, an approval-needing request also fires a `qrlconnect://` deep link that brings the wallet app to the foreground (disable with `walletRedirectOnRequest: false`). `qrl_requestAccounts` never redirects: dApps call it on page load without a user gesture.
+- Use `isPaired()` to tell "wallet away, session intact" apart from "never paired" when `getStatus()` is not `connected`.
+
 Recommended lifecycle:
 
 - Use `hasStoredSession()` on page load to decide whether to show reconnect state/UI
 - Keep a single `QRLConnect` instance for the page lifetime
 - Use `newConnection()` when the user explicitly wants to pair a different wallet
 - Use `statusChanged` for UI state transitions instead of relying on internals
+- On a `disconnect` event, check `hasStoredSession()`: if a session is still stored the wallet is merely unreachable (revived by any request); only re-pair when it is gone
 
 ## How the relay works
 
@@ -195,7 +215,7 @@ node test-e2e.mjs
 
 The `example/` directory contains a Vite test dApp with QR code generation, transaction sending, message signing, and read-only RPC calls.
 
-> **Want to try it without any setup?** The same example is hosted live at [zondscan.com/dapp-example](https://zondscan.com/dapp-example) — it pairs with the production relay and MyQRLWallet mobile app out of the box.
+> **Want to try it without any setup?** The same example is hosted live at [zondscan.com/dapp-example](https://zondscan.com/dapp-example): it pairs with the production relay and MyQRLWallet mobile app out of the box.
 
 ```bash
 # 1. Build the SDK first (the example links to it locally)

package/dist/index.d.mts

@@ -182,6 +182,22 @@ declare enum ConnectionStatus {
     CONNECTED = "connected",
     RECONNECTING = "reconnecting"
 }
+/**
+ * A response for a request issued by a PREVIOUS page load. Same-device
+ * approvals bounce back via a URL open, which reloads the dApp page and
+ * destroys the awaiting promise; the SDK persists in-flight restricted
+ * request ids and surfaces their eventual responses through this event.
+ */
+interface LateResponse {
+    id: string | number;
+    method: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
 /** EIP-1193 provider events */
 interface ProviderEvents {
     connect: (info: {
@@ -198,6 +214,7 @@ interface ProviderEvents {
         data: unknown;
     }) => void;
     statusChanged: (status: ConnectionStatus) => void;
+    late_response: (payload: LateResponse) => void;
 }
 /** JSON-RPC request */
 interface JsonRpcRequest {
@@ -297,6 +314,16 @@ interface QRLConnectOptions {
     announceProvider?: boolean;
     /** Override the EIP-6963 announce metadata (name / icon / rdns). */
     providerInfo?: EIP6963ProviderInfoOverride;
+    /**
+     * On mobile browsers, deep-link (`qrlconnect://resume`) to foreground the
+     * wallet app when a restricted request is made while the wallet is absent
+     * from the relay channel. A backgrounded wallet app loses its socket
+     * within seconds; the relay buffers the request, and without the redirect
+     * it would sit there until the user remembers to switch apps on their
+     * own. Defaults to true. Set false when the dApp runs its own
+     * "open wallet" UX.
+     */
+    walletRedirectOnRequest?: boolean;
 }
 
 /**
@@ -322,6 +349,8 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
     private eip6963RequestListener;
     private resumeListener;
     private resumeDebounce;
+    private inflightKey;
+    private orphanedRequests;
     private readonly requestIdPrefix;
     private requestCounter;
     readonly isQRLConnect = true;
@@ -364,6 +393,36 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
         method: string;
         params?: unknown[];
     }): Promise<unknown>;
+    /**
+     * Redirect only for calls the user must approve, on mobile, and only when
+     * the wallet is actually absent from the channel: right after pairing its
+     * socket lingers and a pointless app flash would be jarring.
+     *
+     * qrl_requestAccounts is excluded even though it is restricted: dApps call
+     * it on page load to restore a session, so it can run with no user gesture
+     * (an unsolicited "Open in MyQRLWallet?" sheet on load) and pairing UIs
+     * already own their own deep-link step.
+     */
+    private shouldRedirectToWallet;
+    private readInflight;
+    private writeInflight;
+    private persistInflight;
+    private settleInflight;
+    private clearAllInflight;
+    /**
+     * Wake URI for the wallet app. Carries no pairing payload: the app
+     * foregrounds on any `qrlconnect:` URL and re-joins its sessions (draining
+     * the buffered request); the cid lets a future wallet jump straight to the
+     * right approval.
+     *
+     * MUST stay query-only (no host/path). The mobile app routes deep links
+     * with expo-router, which maps anything after the scheme to an in-app
+     * route: `qrlconnect://resume?...` lands on the "+not-found" screen and
+     * unmounts the WebView, so the wake achieves nothing. The hostless form
+     * routes to the WebView tab exactly like the pairing URIs
+     * (`qrlconnect://?q=...`), which is the whole point of the wake.
+     */
+    private walletWakeUri;
     /**
      * Get the current connection status.
      */
@@ -384,6 +443,15 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
      * Check if a stored session exists that can be reconnected.
      */
     hasStoredSession(): boolean;
+    /**
+     * True while a pairing exists (keys exchanged), even when the wallet app
+     * is backgrounded and its socket is out of the channel. Combine with
+     * getStatus() to tell "wallet away, session intact" (paired + WAITING)
+     * apart from "waiting for a first scan" in pairing UIs.
+     */
+    isPaired(): boolean;
+    /** True while the wallet is actually present in the relay channel. */
+    isWalletPresent(): boolean;
     /**
      * Reset the connection and start a fresh pairing with a new channel.
      * Use this when the user wants to create a new connection instead of
@@ -415,6 +483,13 @@ interface ConnectionManagerEvents {
         chainId: string;
     }) => void;
     connection_lost: () => void;
+    /**
+     * The session is dead for good (wallet TERMINATE, relay 'close', or a
+     * tombstone observed on join). Distinct from a transient DISCONNECTED:
+     * in-flight requests can never be answered and must be failed promptly
+     * instead of running out the full request timeout.
+     */
+    session_terminated: () => void;
     error: (error: Error) => void;
 }
 declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
@@ -429,12 +504,15 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     private storageKey;
     private unresponsiveTimer;
     private reconnectProbeTimer;
+    private restoreInFlight;
     private failedReconnects;
     private walletPresent;
     private pendingRestore;
     private messageQueue;
     private outboundQueue;
+    private consecutiveDecryptFailures;
     private static MAX_RECONNECT_FAILURES;
+    private static MAX_DECRYPT_FAILURES;
     constructor(options: {
         dappMetadata: DAppMetadata;
         relayUrl?: string | undefined;
@@ -453,6 +531,7 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
      * Returns false if there is nothing to restore.
      */
     reconnect(): Promise<boolean>;
+    private reconnectNow;
     /**
      * (Re)open the socket, join the persisted channel, drain buffered relay
      * messages, and settle status. Shared by the cold-restore reconnect() and
@@ -469,6 +548,25 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
      * own connect handler re-joins the channel and drains the relay buffer.
      */
     resume(): void;
+    /**
+     * Make sure the socket is open and joined to the paired session's channel
+     * so an outbound request can be routed - or relay-buffered if the wallet is
+     * currently absent (its socket dies within seconds of the app
+     * backgrounding; the relay holds channel traffic for it). Revives the
+     * socket after a probe-timeout teardown and hydrates a cold stored
+     * session. Returns false when there is no session to revive (never paired,
+     * explicit disconnect, or the channel was tombstoned).
+     */
+    ensureChannelJoined(): Promise<boolean>;
+    /**
+     * True while a pairing exists (handshake complete, session keys in
+     * memory), even when the wallet's socket is momentarily out of the
+     * channel. Survives the reconnect-probe teardown; false after an explicit
+     * disconnect or a relay tombstone.
+     */
+    isPaired(): boolean;
+    /** True while the relay roster last showed the wallet in the channel. */
+    isWalletPresent(): boolean;
     /**
      * A session was terminated for good (wallet sent a relay 'close', or the
      * join ack reported a tombstone). Clear local state and surface
@@ -478,9 +576,13 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     private armReconnectProbe;
     private clearReconnectProbe;
     /**
-     * Send a JSON-RPC request to the wallet (async, fire-and-forget).
+     * Send a JSON-RPC request to the wallet. Returns the outbound send promise
+     * (settled on the relay's ack) so callers that must sequence on delivery -
+     * e.g. the provider's wallet-wake redirect, which cannot navigate away
+     * before the ciphertext reaches the relay - can await it. Callers may also
+     * ignore it: failures are logged here either way.
      */
-    sendJsonRpc(request: JsonRpcRequest): void;
+    sendJsonRpc(request: JsonRpcRequest): Promise<void>;
     getStatus(): ConnectionStatus;
     getAccounts(): string[];
     getChainId(): string;
@@ -504,6 +606,16 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     disconnect(): Promise<void>;
     private enqueueRelayMessage;
     private handleRelayMessage;
+    /**
+     * The receive stream is cryptographically unrecoverable: the peer's send
+     * counter is ahead of our recv counter for good (relay buffer TTL/cap
+     * dropped a ciphertext), so every future message would fail its tag.
+     * An encrypted TERMINATE cannot communicate this (the desynced peer could
+     * not open it either); tombstone the channel on the relay instead so the
+     * wallet learns the pairing is dead even if it only re-joins later, then
+     * clear local state and surface the standard terminated teardown.
+     */
+    private teardownDesyncedSession;
     private handleSynAck;
     private handleDecryptedMessage;
     private sendPlaintext;
@@ -600,6 +712,20 @@ declare class SocketClient extends EventEmitter<SocketClientEvents> {
         success: boolean;
         buffered: boolean;
     }>;
+    /**
+     * Emit an event and resolve once the relay acks it, or after a bounded
+     * flush window. Lets a caller await transmission before tearing the
+     * socket down.
+     */
+    private flushEmit;
+    /**
+     * Explicitly terminate the channel on the relay (durable tombstone), as
+     * opposed to the transient leaveChannel(). Used when the session is dead
+     * in a way an encrypted TERMINATE cannot communicate (AEAD desync: the
+     * peer could not open it). Resolves once the close is flushed or the
+     * bounded window elapses, so the caller can safely disconnect afterwards.
+     */
+    closeChannel(): Promise<void>;
     /**
      * Leave the current channel.
      */
@@ -777,6 +903,24 @@ declare function isMobileBrowser(): boolean;
  * Falls back to app store URL after timeout.
  */
 declare function getAppStoreUrl(): string;
+/**
+ * Attempt to open a `qrlconnect://` URI in the wallet app and report whether
+ * anything handled it.
+ *
+ * A custom-scheme navigation on a device without the app installed fails
+ * silently on Android and with a blocking alert on iOS Safari, leaving the
+ * page visible either way. When the app IS installed, the OS backgrounds the
+ * browser, firing `visibilitychange`/`pagehide` almost immediately. So:
+ * navigate, then resolve `true` as soon as the page hides, or `false` if it
+ * is still visible after `timeoutMs`. On `false`, show fallback pairing UI
+ * (QR / copy-code) and an install link (`getAppStoreUrl()`).
+ *
+ * Detection is heuristic by nature: a slow device may hide the page late
+ * (harmless, the wallet still opens), and it cannot distinguish "app missing"
+ * from "user dismissed the OS chooser". Treat `false` as "show a fallback",
+ * never as proof the app is absent.
+ */
+declare function attemptWalletRedirect(uri: string, timeoutMs?: number): Promise<boolean>;
 
 declare const DEFAULT_RELAY_URL = "https://qrlwallet.com";
 declare const PROTOCOL_VERSION = 2;
@@ -795,4 +939,4 @@ declare const RESTRICTED_METHODS: Set<string>;
 /** RPC methods that can be auto-proxied without approval */
 declare const UNRESTRICTED_METHODS: Set<string>;
 
-export { type AckMessage, BLOB_LEN, CID_LEN, ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, DIGEST_LEN, type Domain, type EIP6963ProviderInfoOverride, FP_LEN, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, type Message, MessageType, PROTOCOL_VERSION, type ParsedURI, type PendingRequest, type PersistedSession, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, QRL_CONNECT_PROVIDER_INFO, type QrlSignMessageParams, type QrlSignTypedDataParams, type QrlSignedResult, type QrlSignedTypedDataResult, type QrlTypedDataPayload, RESTRICTED_METHODS, type RelayMessage, SCHEME_TAG_MSG, SCHEME_TAG_TYPED, SCHEME_VERSION_MSG, SCHEME_VERSION_TYPED, type Session, SocketClient, type StructDef, type SynAckMessage, type TypeMap, type TypedDataPayload, type TypedField, UNRESTRICTED_METHODS, type VerifyMessageParams, type VerifyTypedDataParams, bytesToHex, cidFromString, cidRandom, cidToString, computeFingerprint, computeMessageDigest, computeTypedDataDigest, concatBytes, encodeField, encodeType, fingerprintEquals, generateConnectionURI, getAppStoreUrl, hashStruct, hexToBytes, isMobileBrowser, parseConnectionURI, typeHash, verifyMessage, verifyTypedData };
+export { type AckMessage, BLOB_LEN, CID_LEN, ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, DIGEST_LEN, type Domain, type EIP6963ProviderInfoOverride, FP_LEN, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, type Message, MessageType, PROTOCOL_VERSION, type ParsedURI, type PendingRequest, type PersistedSession, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, QRL_CONNECT_PROVIDER_INFO, type QrlSignMessageParams, type QrlSignTypedDataParams, type QrlSignedResult, type QrlSignedTypedDataResult, type QrlTypedDataPayload, RESTRICTED_METHODS, type RelayMessage, SCHEME_TAG_MSG, SCHEME_TAG_TYPED, SCHEME_VERSION_MSG, SCHEME_VERSION_TYPED, type Session, SocketClient, type StructDef, type SynAckMessage, type TypeMap, type TypedDataPayload, type TypedField, UNRESTRICTED_METHODS, type VerifyMessageParams, type VerifyTypedDataParams, attemptWalletRedirect, bytesToHex, cidFromString, cidRandom, cidToString, computeFingerprint, computeMessageDigest, computeTypedDataDigest, concatBytes, encodeField, encodeType, fingerprintEquals, generateConnectionURI, getAppStoreUrl, hashStruct, hexToBytes, isMobileBrowser, parseConnectionURI, typeHash, verifyMessage, verifyTypedData };

package/dist/index.d.ts

@@ -182,6 +182,22 @@ declare enum ConnectionStatus {
     CONNECTED = "connected",
     RECONNECTING = "reconnecting"
 }
+/**
+ * A response for a request issued by a PREVIOUS page load. Same-device
+ * approvals bounce back via a URL open, which reloads the dApp page and
+ * destroys the awaiting promise; the SDK persists in-flight restricted
+ * request ids and surfaces their eventual responses through this event.
+ */
+interface LateResponse {
+    id: string | number;
+    method: string;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
 /** EIP-1193 provider events */
 interface ProviderEvents {
     connect: (info: {
@@ -198,6 +214,7 @@ interface ProviderEvents {
         data: unknown;
     }) => void;
     statusChanged: (status: ConnectionStatus) => void;
+    late_response: (payload: LateResponse) => void;
 }
 /** JSON-RPC request */
 interface JsonRpcRequest {
@@ -297,6 +314,16 @@ interface QRLConnectOptions {
     announceProvider?: boolean;
     /** Override the EIP-6963 announce metadata (name / icon / rdns). */
     providerInfo?: EIP6963ProviderInfoOverride;
+    /**
+     * On mobile browsers, deep-link (`qrlconnect://resume`) to foreground the
+     * wallet app when a restricted request is made while the wallet is absent
+     * from the relay channel. A backgrounded wallet app loses its socket
+     * within seconds; the relay buffers the request, and without the redirect
+     * it would sit there until the user remembers to switch apps on their
+     * own. Defaults to true. Set false when the dApp runs its own
+     * "open wallet" UX.
+     */
+    walletRedirectOnRequest?: boolean;
 }
 
 /**
@@ -322,6 +349,8 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
     private eip6963RequestListener;
     private resumeListener;
     private resumeDebounce;
+    private inflightKey;
+    private orphanedRequests;
     private readonly requestIdPrefix;
     private requestCounter;
     readonly isQRLConnect = true;
@@ -364,6 +393,36 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
         method: string;
         params?: unknown[];
     }): Promise<unknown>;
+    /**
+     * Redirect only for calls the user must approve, on mobile, and only when
+     * the wallet is actually absent from the channel: right after pairing its
+     * socket lingers and a pointless app flash would be jarring.
+     *
+     * qrl_requestAccounts is excluded even though it is restricted: dApps call
+     * it on page load to restore a session, so it can run with no user gesture
+     * (an unsolicited "Open in MyQRLWallet?" sheet on load) and pairing UIs
+     * already own their own deep-link step.
+     */
+    private shouldRedirectToWallet;
+    private readInflight;
+    private writeInflight;
+    private persistInflight;
+    private settleInflight;
+    private clearAllInflight;
+    /**
+     * Wake URI for the wallet app. Carries no pairing payload: the app
+     * foregrounds on any `qrlconnect:` URL and re-joins its sessions (draining
+     * the buffered request); the cid lets a future wallet jump straight to the
+     * right approval.
+     *
+     * MUST stay query-only (no host/path). The mobile app routes deep links
+     * with expo-router, which maps anything after the scheme to an in-app
+     * route: `qrlconnect://resume?...` lands on the "+not-found" screen and
+     * unmounts the WebView, so the wake achieves nothing. The hostless form
+     * routes to the WebView tab exactly like the pairing URIs
+     * (`qrlconnect://?q=...`), which is the whole point of the wake.
+     */
+    private walletWakeUri;
     /**
      * Get the current connection status.
      */
@@ -384,6 +443,15 @@ declare class QRLConnectProvider extends EventEmitter<ProviderEvents> {
      * Check if a stored session exists that can be reconnected.
      */
     hasStoredSession(): boolean;
+    /**
+     * True while a pairing exists (keys exchanged), even when the wallet app
+     * is backgrounded and its socket is out of the channel. Combine with
+     * getStatus() to tell "wallet away, session intact" (paired + WAITING)
+     * apart from "waiting for a first scan" in pairing UIs.
+     */
+    isPaired(): boolean;
+    /** True while the wallet is actually present in the relay channel. */
+    isWalletPresent(): boolean;
     /**
      * Reset the connection and start a fresh pairing with a new channel.
      * Use this when the user wants to create a new connection instead of
@@ -415,6 +483,13 @@ interface ConnectionManagerEvents {
         chainId: string;
     }) => void;
     connection_lost: () => void;
+    /**
+     * The session is dead for good (wallet TERMINATE, relay 'close', or a
+     * tombstone observed on join). Distinct from a transient DISCONNECTED:
+     * in-flight requests can never be answered and must be failed promptly
+     * instead of running out the full request timeout.
+     */
+    session_terminated: () => void;
     error: (error: Error) => void;
 }
 declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
@@ -429,12 +504,15 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     private storageKey;
     private unresponsiveTimer;
     private reconnectProbeTimer;
+    private restoreInFlight;
     private failedReconnects;
     private walletPresent;
     private pendingRestore;
     private messageQueue;
     private outboundQueue;
+    private consecutiveDecryptFailures;
     private static MAX_RECONNECT_FAILURES;
+    private static MAX_DECRYPT_FAILURES;
     constructor(options: {
         dappMetadata: DAppMetadata;
         relayUrl?: string | undefined;
@@ -453,6 +531,7 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
      * Returns false if there is nothing to restore.
      */
     reconnect(): Promise<boolean>;
+    private reconnectNow;
     /**
      * (Re)open the socket, join the persisted channel, drain buffered relay
      * messages, and settle status. Shared by the cold-restore reconnect() and
@@ -469,6 +548,25 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
      * own connect handler re-joins the channel and drains the relay buffer.
      */
     resume(): void;
+    /**
+     * Make sure the socket is open and joined to the paired session's channel
+     * so an outbound request can be routed - or relay-buffered if the wallet is
+     * currently absent (its socket dies within seconds of the app
+     * backgrounding; the relay holds channel traffic for it). Revives the
+     * socket after a probe-timeout teardown and hydrates a cold stored
+     * session. Returns false when there is no session to revive (never paired,
+     * explicit disconnect, or the channel was tombstoned).
+     */
+    ensureChannelJoined(): Promise<boolean>;
+    /**
+     * True while a pairing exists (handshake complete, session keys in
+     * memory), even when the wallet's socket is momentarily out of the
+     * channel. Survives the reconnect-probe teardown; false after an explicit
+     * disconnect or a relay tombstone.
+     */
+    isPaired(): boolean;
+    /** True while the relay roster last showed the wallet in the channel. */
+    isWalletPresent(): boolean;
     /**
      * A session was terminated for good (wallet sent a relay 'close', or the
      * join ack reported a tombstone). Clear local state and surface
@@ -478,9 +576,13 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     private armReconnectProbe;
     private clearReconnectProbe;
     /**
-     * Send a JSON-RPC request to the wallet (async, fire-and-forget).
+     * Send a JSON-RPC request to the wallet. Returns the outbound send promise
+     * (settled on the relay's ack) so callers that must sequence on delivery -
+     * e.g. the provider's wallet-wake redirect, which cannot navigate away
+     * before the ciphertext reaches the relay - can await it. Callers may also
+     * ignore it: failures are logged here either way.
      */
-    sendJsonRpc(request: JsonRpcRequest): void;
+    sendJsonRpc(request: JsonRpcRequest): Promise<void>;
     getStatus(): ConnectionStatus;
     getAccounts(): string[];
     getChainId(): string;
@@ -504,6 +606,16 @@ declare class ConnectionManager extends EventEmitter<ConnectionManagerEvents> {
     disconnect(): Promise<void>;
     private enqueueRelayMessage;
     private handleRelayMessage;
+    /**
+     * The receive stream is cryptographically unrecoverable: the peer's send
+     * counter is ahead of our recv counter for good (relay buffer TTL/cap
+     * dropped a ciphertext), so every future message would fail its tag.
+     * An encrypted TERMINATE cannot communicate this (the desynced peer could
+     * not open it either); tombstone the channel on the relay instead so the
+     * wallet learns the pairing is dead even if it only re-joins later, then
+     * clear local state and surface the standard terminated teardown.
+     */
+    private teardownDesyncedSession;
     private handleSynAck;
     private handleDecryptedMessage;
     private sendPlaintext;
@@ -600,6 +712,20 @@ declare class SocketClient extends EventEmitter<SocketClientEvents> {
         success: boolean;
         buffered: boolean;
     }>;
+    /**
+     * Emit an event and resolve once the relay acks it, or after a bounded
+     * flush window. Lets a caller await transmission before tearing the
+     * socket down.
+     */
+    private flushEmit;
+    /**
+     * Explicitly terminate the channel on the relay (durable tombstone), as
+     * opposed to the transient leaveChannel(). Used when the session is dead
+     * in a way an encrypted TERMINATE cannot communicate (AEAD desync: the
+     * peer could not open it). Resolves once the close is flushed or the
+     * bounded window elapses, so the caller can safely disconnect afterwards.
+     */
+    closeChannel(): Promise<void>;
     /**
      * Leave the current channel.
      */
@@ -777,6 +903,24 @@ declare function isMobileBrowser(): boolean;
  * Falls back to app store URL after timeout.
  */
 declare function getAppStoreUrl(): string;
+/**
+ * Attempt to open a `qrlconnect://` URI in the wallet app and report whether
+ * anything handled it.
+ *
+ * A custom-scheme navigation on a device without the app installed fails
+ * silently on Android and with a blocking alert on iOS Safari, leaving the
+ * page visible either way. When the app IS installed, the OS backgrounds the
+ * browser, firing `visibilitychange`/`pagehide` almost immediately. So:
+ * navigate, then resolve `true` as soon as the page hides, or `false` if it
+ * is still visible after `timeoutMs`. On `false`, show fallback pairing UI
+ * (QR / copy-code) and an install link (`getAppStoreUrl()`).
+ *
+ * Detection is heuristic by nature: a slow device may hide the page late
+ * (harmless, the wallet still opens), and it cannot distinguish "app missing"
+ * from "user dismissed the OS chooser". Treat `false` as "show a fallback",
+ * never as proof the app is absent.
+ */
+declare function attemptWalletRedirect(uri: string, timeoutMs?: number): Promise<boolean>;
 
 declare const DEFAULT_RELAY_URL = "https://qrlwallet.com";
 declare const PROTOCOL_VERSION = 2;
@@ -795,4 +939,4 @@ declare const RESTRICTED_METHODS: Set<string>;
 /** RPC methods that can be auto-proxied without approval */
 declare const UNRESTRICTED_METHODS: Set<string>;
 
-export { type AckMessage, BLOB_LEN, CID_LEN, ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, DIGEST_LEN, type Domain, type EIP6963ProviderInfoOverride, FP_LEN, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, type Message, MessageType, PROTOCOL_VERSION, type ParsedURI, type PendingRequest, type PersistedSession, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, QRL_CONNECT_PROVIDER_INFO, type QrlSignMessageParams, type QrlSignTypedDataParams, type QrlSignedResult, type QrlSignedTypedDataResult, type QrlTypedDataPayload, RESTRICTED_METHODS, type RelayMessage, SCHEME_TAG_MSG, SCHEME_TAG_TYPED, SCHEME_VERSION_MSG, SCHEME_VERSION_TYPED, type Session, SocketClient, type StructDef, type SynAckMessage, type TypeMap, type TypedDataPayload, type TypedField, UNRESTRICTED_METHODS, type VerifyMessageParams, type VerifyTypedDataParams, bytesToHex, cidFromString, cidRandom, cidToString, computeFingerprint, computeMessageDigest, computeTypedDataDigest, concatBytes, encodeField, encodeType, fingerprintEquals, generateConnectionURI, getAppStoreUrl, hashStruct, hexToBytes, isMobileBrowser, parseConnectionURI, typeHash, verifyMessage, verifyTypedData };
+export { type AckMessage, BLOB_LEN, CID_LEN, ConnectionManager, ConnectionStatus, type DAppMetadata, type DAppSession, DEFAULT_RELAY_URL, DIGEST_LEN, type Domain, type EIP6963ProviderInfoOverride, FP_LEN, type JsonRpcRequest, type JsonRpcResponse, KeyExchange, KeyExchangeMessageType, type Message, MessageType, PROTOCOL_VERSION, type ParsedURI, type PendingRequest, type PersistedSession, type ProviderEvents, QRLConnectProvider as QRLConnect, type QRLConnectOptions, QRLConnectProvider, QRL_CONNECT_PROVIDER_INFO, type QrlSignMessageParams, type QrlSignTypedDataParams, type QrlSignedResult, type QrlSignedTypedDataResult, type QrlTypedDataPayload, RESTRICTED_METHODS, type RelayMessage, SCHEME_TAG_MSG, SCHEME_TAG_TYPED, SCHEME_VERSION_MSG, SCHEME_VERSION_TYPED, type Session, SocketClient, type StructDef, type SynAckMessage, type TypeMap, type TypedDataPayload, type TypedField, UNRESTRICTED_METHODS, type VerifyMessageParams, type VerifyTypedDataParams, attemptWalletRedirect, bytesToHex, cidFromString, cidRandom, cidToString, computeFingerprint, computeMessageDigest, computeTypedDataDigest, concatBytes, encodeField, encodeType, fingerprintEquals, generateConnectionURI, getAppStoreUrl, hashStruct, hexToBytes, isMobileBrowser, parseConnectionURI, typeHash, verifyMessage, verifyTypedData };