windkit 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -1,54 +1,101 @@
 # Changelog
 
-All notable changes to this project will be documented in this file.
+## 0.3.0
 
-This project follows Semantic Versioning.
+- Added Wind Wallet in-app browser injected provider support.
+- Added `InjectedWalletSession`.
+- Added `WindClient` hybrid connector.
+- Added `connectWindWallet()` helper.
+- Keeps existing QR/VSR + PeerJS flow as fallback.
+- Exposes provider detection helpers: `getInjectedWindProvider()` and `isWindWalletInjected()`.
+
+
+All notable changes to this project are documented in this file.
+
+This project follows [Semantic Versioning](https://semver.org/).
 
 ---
 
-## [0.2.2] - 2026-03-02
+## [0.2.3] - 2026-03-02
+
+Published: 2026-03-02T14:07:04Z
 
 ### Changed
 
 - Session storage key standardized to `"vex-session"`.
-- Login identity request now stores compact app info keys:
-  - `pi` (peer id), `na` (app name), `ic` (icon), `do` (origin), optional `auth` (cached proof).
-- Request method names standardized:
-  - `signRequest`, `signMessage`, `sharedSecret`.
+- Login identity payload compacted with standardized keys:
+  - `pi` (peer id)
+  - `na` (app name)
+  - `ic` (icon)
+  - `do` (origin)
+  - optional `auth` (cached identity proof)
+- RPC method names standardized:
+  - `signRequest`
+  - `signMessage`
+  - `sharedSecret`
 
 ### Added
 
-- `clearSession()` helper.
-- Session reuse:
-  - Reuses saved `peerID` and hints (`account@permission`) when present.
+- `clearSession()` helper for manual session reset.
+- Smart session reuse:
+  - Reuses stored `peerID`
+  - Reuses permission hints (`account@permission`) when available.
 
 ### Fixed
 
-- Safer session loading (auto-clears invalid or expired payloads).
-- Improved cleanup on disconnect (best-effort destroy/disconnect).
+- Hardened session loader:
+  - Automatically clears expired or malformed session payloads.
+- Improved disconnect cleanup:
+  - Safe destroy/disconnect (best-effort, non-throwing).
 
 ### Improved
 
-- Low-memory friendly behavior:
-  - Lightweight heartbeat/ping with jitter (best-effort).
-  - Minimal allocations on message routing.
+- Optimized for low-memory environments:
+  - Lightweight heartbeat with jitter
+  - Reduced message routing allocations
+  - Lower background CPU usage on mobile devices
+
+---
+
+## [0.2.1] - 2025-10-13
+
+Published: 2025-10-13T16:28:38Z
+
+### Added
+
+- PeerJS signaling support.
+- Session persistence via `sessionStorage`.
+- Transaction signing via Vexanium Signing Request (VSR).
+- Message signing support.
+- Shared secret derivation (ECDH).
 
 ---
 
-## [0.2.1]
+## [0.2.0] - 2025-10-06
+
+Published: 2025-10-06T14:44:23Z
 
 ### Added
 
-- Initial PeerJS signaling support.
-- Session persistence via sessionStorage.
-- Transaction signing via VSR.
-- Message signing.
-- Shared secret (ECDH).
+- Structured WebRTC connection lifecycle.
+- WalletSession abstraction layer.
+- Basic login flow via embedded PeerID inside VSR.
+- Request/response routing via internal request IDs.
+
+### Improved
+
+- More predictable session initialization flow.
+- Internal protocol normalization groundwork.
 
 ---
 
-## [0.1.1]
+## [0.1.1] - 2025-08-12
+
+Published: 2025-08-12T01:33:25Z
 
 ### Added
 
 - Initial public release of WindKit.
+- Basic VSR identity login.
+- WebRTC DataConnection integration.
+- Minimal transaction signing flow.

package/README.md

@@ -7,39 +7,125 @@ WindKit is a lightweight WebRTC protocol for connecting Vexanium DApps to Wind W
 
 It enables secure cross-device login and transaction signing without requiring browser extensions.
 
+Designed for production environments, including low-RAM mobile devices.
+
 ---
 
-## Features
+## ✨ Features
 
 - Cross-device login via VSR (Vexanium Signing Request)
 - Transaction signing (single action, multiple actions, or full transaction)
-- Optional broadcast (sign-only or broadcast)
+- Optional broadcast control (sign-only or broadcast)
 - Message signing
 - Shared secret derivation (ECDH)
-- Session persistence via sessionStorage
-- Lightweight keepalive (low memory footprint)
-- Pure ESM module
+- Session persistence via `sessionStorage`
+- Low-memory heartbeat strategy
+- Pure ESM module (JavaScript-only)
+
+---
+
+## 🧩 In-App Browser Injected Provider
+
+WindKit now supports Wind Wallet's in-app DApp Browser provider, similar to MetaMask / Phantom / Rabby.
+
+When a DApp is opened inside Wind Wallet Browser, Wind Wallet injects:
+
+```js
+window.wind
+window.windwallet
+window.windWallet
+window.vexanium
+window.vex
+```
+
+Use the hybrid client to support both injected provider and QR/VSR fallback:
+
+```js
+import { WindClient } from "windkit";
+
+const wind = new WindClient();
+
+const session = await wind.connect({
+  name: "My Vexanium DApp",
+  icon: "https://example.com/icon.png",
+
+  // Called only when the DApp is opened outside Wind Wallet Browser.
+  // Render this VSR as QR, or show your existing login modal.
+  onLoginRequest(vsr) {
+    console.log("Show QR:", vsr);
+  }
+});
+
+console.log("Connected:", session.permissionLevel?.toString());
+```
+
+### Direct injected request
+
+```js
+import { InjectedWalletSession } from "windkit";
+
+if (InjectedWalletSession.isAvailable()) {
+  const session = await InjectedWalletSession.connect();
+
+  await session.signMessage("Hello Wind!");
+}
+```
+
+### Provider API
+
+Inside Wind Wallet Browser, DApps can also call the provider directly:
+
+```js
+const accounts = await window.wind.request({
+  method: "vex_requestAccounts"
+});
+
+const signature = await window.wind.request({
+  method: "vex_signMessage",
+  params: ["Hello Wind!"]
+});
+
+const result = await window.wind.request({
+  method: "signRequest",
+  params: ["vsr:..."]
+});
+```
+
+### Recommended DApp logic
+
+```txt
+1. Try injected provider first: window.wind / window.vexanium.
+2. If not available, use QR/VSR + PeerJS fallback.
+3. Keep signing approval inside Wind Wallet.
+```
+
+This keeps old QR pairing working while enabling MetaMask-style connect inside the Wind Wallet app.
 
 ---
 
-## Installation
+## 📦 Installation
 
+```bash
 npm install windkit
+```
 
-WindKit is ESM-only.
+WindKit is **ESM-only**.
 
-Your project must use:
+Your project must include:
 
+```json
 {
   "type": "module"
 }
+```
 
 ---
 
-## Quick Start
+## 🚀 Quick Start
 
 ### Create Connector
 
+```js
 import { WindConnector } from "windkit";
 
 const connector = new WindConnector();
@@ -49,29 +135,37 @@ connector.on("session", (session, proof) => {
 });
 
 await connector.connect();
+```
 
-By default, WindKit relies on PeerJS default signaling behavior (no host/port/path/secure configured).
+By default, WindKit uses PeerJS default signaling.
 
 ---
 
-### Use Your Own PeerJS Server (Optional)
+## 🌐 Custom PeerJS Server (Optional)
 
+```js
 connector.setServer("peer.yourdomain.com", 443, "/", true);
+```
 
 Signature:
 
-setServer(host, port, path, secure)
+```js
+setServer(host, port, path, secure);
+```
 
-Add custom STUN/TURN server:
+Add custom ICE server:
 
+```js
 connector.addIceServer({
   urls: "stun:stun.cloudflare.com:3478"
 });
+```
 
 ---
 
-## Login Flow (VSR)
+## 🔐 Login Flow (VSR)
 
+```js
 const vsr = connector.createLoginRequest(
   "My Vexanium DApp",
   "https://example.com/icon.png"
@@ -83,20 +177,21 @@ window.open(
   `https://wallet.windcrypto.com/login?vsr=${encodeURIComponent(payload)}`,
   "Wind Wallet"
 );
+```
 
 Wallet flow:
 
 1. Decode VSR  
 2. Connect to embedded PeerID  
-3. Send LOGIN_OK  
+3. Send `LOGIN_OK`  
 4. Emit session  
 
 ---
 
-## Session Handling
+## 🔄 Session Handling
 
+```js
 connector.on("session", (session, proof) => {
-
   session.onClose(() => {
     console.log("Wallet disconnected");
   });
@@ -107,13 +202,15 @@ connector.on("session", (session, proof) => {
 
   window.appSession = session;
 });
+```
 
 ---
 
-## Send Transaction
+## ✍️ Send Transaction
 
 ### With ABI Cache (Recommended)
 
+```js
 import { Action } from "@wharfkit/antelope";
 import { ABICache } from "@wharfkit/abicache";
 
@@ -130,7 +227,7 @@ const action = Action.from(
       from: "alice",
       to: "bob",
       quantity: "1.0000 VEX",
-      memo: "test"
+      memo: "WindKit test"
     },
     authorization: [appSession.permissionLevel]
   },
@@ -140,119 +237,145 @@ const action = Action.from(
 const result = await appSession.transact({ action });
 
 console.log(result.transaction_id ?? result.id);
+```
 
 ---
 
 ### Sign Only (No Broadcast)
 
+```js
 await appSession.transact(
   { action },
   { broadcast: false }
 );
+```
 
 ---
 
-## Sign Message
+## 📝 Sign Message
 
+```js
 const signature = await appSession.signMessage("Hello Wind!");
 console.log(signature.toString());
+```
 
 ---
 
-## Shared Secret (ECDH)
+## 🔑 Shared Secret (ECDH)
 
+```js
 import { PublicKey } from "@wharfkit/antelope";
 
 const pub = PublicKey.from("PUB_K1_...");
 const secret = await appSession.sharedSecret(pub);
 
 console.log(secret.toString());
+```
 
 ---
 
-## Session Storage
+## 💾 Session Storage
 
 WindKit stores session data in:
 
+```js
 sessionStorage["vex-session"]
+```
 
 Example structure:
 
+```json
 {
   "peerID": "VEX-xxxx",
   "permission": "account@active",
   "expiration": "2026-03-01T12:00:00",
   "auth": "base64u_identity_proof"
 }
+```
 
-To clear session manually:
+Clear session manually:
 
+```js
 import { clearSession } from "windkit";
 
 clearSession();
+```
 
 ---
 
-## Architecture
+## 🏗 Architecture
+
+### WindConnector
 
-WindConnector
 - Creates VSR identity login
 - Hosts PeerJS PeerID (DApp-side)
 - Waits for wallet connection
 - Emits session
 
-WalletSession
+### WalletSession
+
 - Sends:
-  - signRequest
-  - signMessage
-  - sharedSecret
+  - `signRequest`
+  - `signMessage`
+  - `sharedSecret`
 - Routes replies via request IDs
-- Lightweight keepalive ping
+- Lightweight heartbeat ping
 - Handles account change events
 
 ---
 
-## Protocol Notes
+## 🔎 Protocol Notes
+
+Transaction signing method:
 
-Transaction signing method name:
-"signRequest"
+```
+signRequest
+```
 
 Wallet push events handled:
+
+```
 LOGIN_OK
 ACTIVE_ACCOUNT_CHANGED
+```
 
-All communication occurs via PeerJS DataConnection.
+All communication occurs over PeerJS `DataConnection`.
 
 ---
 
-## Technical Details
+## ⚙ Technical Details
+
+Chain ID is internally fixed via:
 
-Chain ID is fixed internally via:
+```js
 WalletSession.ChainID
+```
+
+Dependencies:
+
+- `@wharfkit/signing-request`
+- `@wharfkit/antelope`
+- `peerjs`
+- `pako`
 
-Uses:
-- @wharfkit/signing-request
-- @wharfkit/antelope
-- peerjs
-- pako (zlib compression)
+Optimized for:
 
-Designed for:
 - Low-RAM mobile devices
-- Background tabs
-- Unstable WebRTC environments
+- Background browser tabs
+- Unstable WebRTC networks
 
 ---
 
-## Security Model
+## 🔐 Security Model
 
 - IdentityProof can be verified by the DApp (recommended).
 - Private keys never leave the wallet.
 - VSR ensures transaction integrity.
-- PeerID is embedded inside VSR to prevent misrouting.
+- PeerID is embedded inside the VSR payload to prevent misrouting.
 
 ---
 
-## License
+## 📄 License
 
 MIT License  
 © Wind Stack

package/index.js

@@ -1,3 +1,11 @@
 export { WindConnector } from "./src/WindConnector.js";
 export { WalletSession } from "./src/WalletSession.js";
-export { saveSession, loadSession, clearSession } from "./src/StoreSession.js";
+export {
+  InjectedWalletSession,
+  WindClient,
+  connectWindWallet,
+  getInjectedWindProvider,
+  isWindWalletInjected,
+  requestWithTimeout,
+} from "./src/InjectedWindProvider.js";
+export { saveSession, loadSession, clearSession } from "./src/StoreSession.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "windkit",
-  "version": "0.2.2",
-  "description": "Lightweight protocol to connect Vexanium DApps to Wind Wallet via PeerJS and VSR.",
+  "version": "0.3.0",
+  "description": "Hybrid protocol to connect Vexanium DApps to Wind Wallet using injected provider, PeerJS, and VSR.",
   "license": "MIT",
   "author": "windstack",
   "type": "module",
@@ -35,7 +35,11 @@
     "wharfkit",
     "signing-request",
     "vsr",
-    "blockchain"
+    "blockchain",
+    "injected-provider",
+    "in-app-browser",
+    "metamask-compatible",
+    "phantom-compatible"
   ],
   "sideEffects": false,
   "publishConfig": {
@@ -56,4 +60,4 @@
   "engines": {
     "node": ">=18"
   }
-}
+}

package/src/InjectedWindProvider.js

@@ -0,0 +1,518 @@
+// windkit/InjectedWindProvider.js
+// WindKit injected-provider bridge
+// ✅ In-app browser first (window.wind / window.windwallet / window.vexanium)
+// ✅ Keeps QR/VSR + PeerJS fallback untouched
+// ✅ MetaMask-style request({ method, params }) API for Wind Wallet browser
+// ✅ No wallet keys, no signing logic here — DApp-side transport only
+
+import { SigningRequest } from "@wharfkit/signing-request";
+import {
+  Checksum512,
+  Name,
+  PermissionLevel,
+  PublicKey,
+  Signature,
+  SignedTransaction,
+} from "@wharfkit/antelope";
+import zlib from "pako";
+
+import { WindConnector } from "./WindConnector.js";
+
+const DEFAULT_TIMEOUT_MS = 90_000;
+
+function normalizeTimeoutMs(v, fallback = DEFAULT_TIMEOUT_MS) {
+  const n = Number(v);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.max(1000, Math.trunc(n));
+}
+
+function setTimer(fn, ms) {
+  try {
+    return globalThis.setTimeout(fn, ms);
+  } catch {
+    return setTimeout(fn, ms);
+  }
+}
+
+function clearTimer(id) {
+  try {
+    globalThis.clearTimeout(id);
+  } catch {
+    clearTimeout(id);
+  }
+}
+
+function getWindowLike() {
+  try {
+    if (typeof globalThis !== "undefined") return globalThis;
+  } catch {}
+  return undefined;
+}
+
+function normalizeParams(params) {
+  if (params === undefined) return [];
+  return Array.isArray(params) ? params : [params];
+}
+
+function replyError(reply, fallback) {
+  const err = reply?.error;
+  if (typeof err === "string") return new Error(err);
+  if (err?.message) return new Error(err.message);
+  if (reply?.message) return new Error(reply.message);
+  return new Error(fallback || "Wind Wallet request failed.");
+}
+
+function parseAccountLike(value) {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (Array.isArray(value)) return parseAccountLike(value[0]);
+  if (typeof value === "object") {
+    return (
+      value.permission ||
+      value.permissionLevel ||
+      value.account ||
+      value.address ||
+      value.actor ||
+      ""
+    );
+  }
+  return "";
+}
+
+function toPermissionLevel(value) {
+  const raw = parseAccountLike(value);
+  if (!raw) return undefined;
+
+  // Vexanium permission is canonical actor@permission.
+  if (String(raw).includes("@")) {
+    return PermissionLevel.from(String(raw));
+  }
+
+  // Some injected providers may return { actor, permission } separately.
+  if (value && typeof value === "object" && value.actor && value.permission) {
+    return PermissionLevel.from(`${value.actor}@${value.permission}`);
+  }
+
+  return undefined;
+}
+
+function isRequestProvider(value) {
+  return Boolean(value && typeof value.request === "function");
+}
+
+/**
+ * Return the first Wind-compatible injected provider available in the current browser.
+ *
+ * Wind Wallet app injects several aliases for compatibility:
+ * - window.wind
+ * - window.windwallet
+ * - window.windWallet
+ * - window.vexanium
+ * - window.vex
+ */
+export function getInjectedWindProvider(scope) {
+  const w = scope || getWindowLike();
+  if (!w) return null;
+
+  const candidates = [
+    w.wind,
+    w.windwallet,
+    w.windWallet,
+    w.vexanium,
+    w.vex,
+  ];
+
+  for (const provider of candidates) {
+    if (isRequestProvider(provider)) return provider;
+  }
+
+  return null;
+}
+
+export function isWindWalletInjected(scope) {
+  const provider = getInjectedWindProvider(scope);
+  return Boolean(provider?.isWindWallet || provider?.isWind || provider?.request);
+}
+
+/**
+ * InjectedWalletSession
+ * DApp-side session object for Wind Wallet in-app browser.
+ *
+ * It intentionally mirrors WalletSession's public API:
+ * - transact()
+ * - signRequest()
+ * - signMessage()
+ * - sharedSecret()
+ * - permissionLevel
+ */
+export class InjectedWalletSession {
+  static ChainID = "f9f432b1851b5c179d2091a96f593aaed50ec7466b74f89301f957a83e56ce1f";
+
+  /** @type {any} */
+  #provider;
+
+  /** @type {{zlib:any, abiProvider?:any} | undefined} */
+  #encodingOptions;
+
+  /** @type {PermissionLevel | undefined} */
+  #permissionLevel;
+
+  /** @type {(permission: PermissionLevel) => void | undefined} */
+  #accountChangeListener;
+
+  /** @type {() => void | undefined} */
+  #closeListener;
+
+  /** @type {(error: Error) => void | undefined} */
+  #errorListener;
+
+  constructor(provider, permissionLevel) {
+    if (!isRequestProvider(provider)) {
+      throw new Error("Wind Wallet injected provider was not found.");
+    }
+
+    this.#provider = provider;
+
+    const perm = toPermissionLevel(permissionLevel);
+    if (perm) this.#permissionLevel = perm;
+
+    this.#bindProviderEvents();
+  }
+
+  static isAvailable(scope) {
+    return isWindWalletInjected(scope);
+  }
+
+  static getProvider(scope) {
+    return getInjectedWindProvider(scope);
+  }
+
+  /**
+   * Request accounts from the injected Wind Wallet provider.
+   * @param {{provider?: any, timeoutMs?: number}=} options
+   */
+  static async connect(options = {}) {
+    const provider = options.provider || getInjectedWindProvider();
+    if (!provider) throw new Error("Wind Wallet injected provider is not available.");
+
+    const result = await requestWithTimeout(
+      provider,
+      "vex_requestAccounts",
+      [],
+      options.timeoutMs
+    );
+
+    const permission = toPermissionLevel(result) || toPermissionLevel(result?.accounts);
+    return new InjectedWalletSession(provider, permission || result);
+  }
+
+  #bindProviderEvents() {
+    const provider = this.#provider;
+
+    // MetaMask-style provider events if Wind Wallet exposes them later.
+    if (typeof provider.on === "function") {
+      try {
+        provider.on("accountsChanged", (accounts) => {
+          const next = toPermissionLevel(accounts);
+          if (next) {
+            this.#permissionLevel = next;
+            this.#accountChangeListener?.(next);
+          }
+        });
+      } catch {}
+
+      try {
+        provider.on("disconnect", () => {
+          this.#closeListener?.();
+        });
+      } catch {}
+    }
+  }
+
+  setABICache(cache) {
+    this.#encodingOptions = { zlib, abiProvider: cache };
+  }
+
+  onAccountChange(listener) {
+    this.#accountChangeListener = listener;
+  }
+
+  onClose(listener) {
+    this.#closeListener = listener;
+  }
+
+  onError(listener) {
+    this.#errorListener = listener;
+  }
+
+  isOpen() {
+    return true;
+  }
+
+  close() {
+    // Injected browser sessions are page-scoped. No persistent socket to close.
+    this.#closeListener?.();
+  }
+
+  metadata() {
+    return { transport: "injected", wallet: "Wind Wallet" };
+  }
+
+  get permissionLevel() {
+    return this.#permissionLevel;
+  }
+
+  set permissionLevel(value) {
+    const perm = toPermissionLevel(value);
+    this.#permissionLevel = perm || value;
+  }
+
+  get actor() {
+    return this.#permissionLevel?.actor ?? Name.from("");
+  }
+
+  get permission() {
+    return this.#permissionLevel?.permission ?? Name.from("");
+  }
+
+  async request(method, params, timeoutMs) {
+    return await requestWithTimeout(this.#provider, method, params, timeoutMs);
+  }
+
+  /**
+   * Create a VSR signing request for a transaction and send to wallet.
+   * Matches WalletSession.transact().
+   */
+  async transact(args, options) {
+    const willBroadcast = typeof options?.broadcast === "boolean" ? options.broadcast : true;
+    const requestArgs = { ...args, chainId: InjectedWalletSession.ChainID };
+
+    const req = await SigningRequest.create(requestArgs, this.#encodingOptions);
+    req.setBroadcast(willBroadcast);
+
+    const vsr = req.encode(true, false, "vsr:");
+    return this.signRequest(vsr, options?.timeoutMs);
+  }
+
+  /**
+   * Send a VSR string to Wind Wallet approval UI.
+   */
+  async signRequest(vsr, timeoutMs) {
+    const payload = typeof vsr === "string" ? vsr : String(vsr || "");
+    let reply;
+
+    if (typeof this.#provider.signRequest === "function") {
+      reply = await withTimeout(
+        Promise.resolve(this.#provider.signRequest(payload)),
+        timeoutMs,
+        "signRequest"
+      );
+    } else {
+      reply = await this.request("signRequest", [payload], timeoutMs);
+    }
+
+    if (reply?.code === "SENT") return reply.result;
+    if (reply?.code === "SIGNED") return SignedTransaction.from(reply.result);
+    if (reply?.signatures || reply?.transaction) return SignedTransaction.from(reply);
+    if (reply?.transaction_id || reply?.processed) return reply;
+
+    throw replyError(reply, "Signing request rejected.");
+  }
+
+  async signMessage(message, timeoutMs) {
+    const reply = await this.request("vex_signMessage", [message], timeoutMs);
+
+    if (typeof reply === "string") return Signature.from(reply);
+    if (reply?.signature) return Signature.from(reply.signature);
+    if (reply?.code === "SIGNED" && reply?.result?.signature) {
+      return Signature.from(reply.result.signature);
+    }
+
+    throw replyError(reply, "Message signing rejected.");
+  }
+
+  async sharedSecret(publicKey, timeoutMs) {
+    const key = publicKey?.toString ? publicKey.toString() : String(publicKey || "");
+    const reply = await this.request("vex_sharedSecret", [key], timeoutMs);
+
+    if (typeof reply === "string") return Checksum512.from(reply);
+    if (reply?.secret) return Checksum512.from(reply.secret);
+    if (reply?.code === "CREATED" && reply?.result?.secret) {
+      return Checksum512.from(reply.result.secret);
+    }
+
+    throw replyError(reply, "Shared secret creation failed.");
+  }
+}
+
+/**
+ * Low-level helper for request({ method, params }) providers.
+ */
+export async function requestWithTimeout(provider, method, params, timeoutMs) {
+  if (!isRequestProvider(provider)) {
+    throw new Error("Wind Wallet injected provider is not available.");
+  }
+
+  const req = provider.request({
+    method: String(method || ""),
+    params: normalizeParams(params),
+  });
+
+  return await withTimeout(Promise.resolve(req), timeoutMs, method);
+}
+
+async function withTimeout(promise, timeoutMs, label = "request") {
+  const ms = normalizeTimeoutMs(timeoutMs, DEFAULT_TIMEOUT_MS);
+
+  return await new Promise((resolve, reject) => {
+    const timer = setTimer(() => {
+      reject(new Error(`${label} timed out.`));
+    }, ms);
+
+    promise.then(
+      (value) => {
+        clearTimer(timer);
+        resolve(value);
+      },
+      (error) => {
+        clearTimer(timer);
+        reject(error);
+      }
+    );
+  });
+}
+
+/**
+ * WindClient
+ * Hybrid connector for DApps.
+ *
+ * connect() chooses:
+ * 1. Injected provider when opened inside Wind Wallet browser.
+ * 2. QR/VSR + PeerJS fallback when opened in a normal browser.
+ */
+export class WindClient {
+  #connector;
+  #listeners = new Map();
+  #options;
+
+  constructor(options = {}) {
+    this.#options = { preferInjected: true, ...options };
+  }
+
+  on(event, listener) {
+    this.#listeners.set(String(event || ""), listener);
+    if (this.#connector && typeof this.#connector.on === "function") {
+      this.#connector.on(event, listener);
+    }
+  }
+
+  off(event) {
+    this.#listeners.delete(String(event || ""));
+    if (this.#connector && typeof this.#connector.off === "function") {
+      this.#connector.off(event);
+    }
+  }
+
+  get connector() {
+    return this.#connector;
+  }
+
+  isInjectedAvailable() {
+    return isWindWalletInjected();
+  }
+
+  /**
+   * Connect to Wind Wallet.
+   *
+   * @param {{
+   *   name?: string,
+   *   icon?: string,
+   *   preferInjected?: boolean,
+   *   timeoutMs?: number,
+   *   walletUrl?: string,
+   *   openWallet?: (vsr:string, connector:WindConnector)=>void,
+   *   onLoginRequest?: (vsr:string, connector:WindConnector)=>void,
+   *   peerOptions?: any
+   * }=} options
+   *
+   * For non-injected fallback, pass onLoginRequest(vsr) to show QR/modal.
+   */
+  async connect(options = {}) {
+    const opts = { ...this.#options, ...options };
+
+    if (opts.preferInjected !== false && isWindWalletInjected()) {
+      const session = await InjectedWalletSession.connect({ timeoutMs: opts.timeoutMs });
+      this.#listeners.get("session")?.(session, { transport: "injected" });
+      return session;
+    }
+
+    const connector = new WindConnector(opts.peerOptions);
+    this.#connector = connector;
+
+    for (const [event, listener] of this.#listeners.entries()) {
+      connector.on(event, listener);
+    }
+
+    await connector.connect();
+    const vsr = connector.createLoginRequest(opts.name || "Wind DApp", opts.icon || "");
+
+    return await new Promise((resolve, reject) => {
+      const cleanup = () => {
+        clearTimer(timeout);
+      };
+
+      const timeout = setTimer(() => {
+        cleanup();
+        const err = new Error("Wind Wallet peer login timed out.");
+        err.vsr = vsr;
+        reject(err);
+      }, normalizeTimeoutMs(opts.timeoutMs, DEFAULT_TIMEOUT_MS));
+
+      connector.on("session", (session, proof) => {
+        cleanup();
+        this.#listeners.get("session")?.(session, proof);
+        resolve(session);
+      });
+
+      connector.on("error", (error) => {
+        this.#listeners.get("error")?.(error);
+      });
+
+      if (typeof opts.onLoginRequest === "function") {
+        opts.onLoginRequest(vsr, connector);
+        return;
+      }
+
+      if (typeof opts.openWallet === "function") {
+        opts.openWallet(vsr, connector);
+        return;
+      }
+
+      if (opts.walletUrl && typeof globalThis?.open === "function") {
+        const payload = vsr.startsWith("vsr:") ? vsr.slice(4) : vsr;
+        const url = `${String(opts.walletUrl).replace(/\/$/, "")}/login?vsr=${encodeURIComponent(payload)}`;
+        try {
+          globalThis.open(url, "Wind Wallet");
+        } catch {}
+        return;
+      }
+
+      // No UI handler was provided. Reject with the generated VSR so the DApp can render it.
+      const err = new Error(
+        "Wind Wallet injected provider not found. Show this VSR as QR or pass onLoginRequest(vsr)."
+      );
+      err.vsr = vsr;
+      err.connector = connector;
+      cleanup();
+      reject(err);
+    });
+  }
+}
+
+/**
+ * Convenience helper.
+ */
+export async function connectWindWallet(options = {}) {
+  const client = new WindClient(options);
+  return await client.connect(options);
+}