zeldwallet 0.1.0

package/README.md

@@ -0,0 +1,305 @@
+# ZeldWallet
+
+[![Lint](https://github.com/ouziel-slama/zeldwallet/actions/workflows/lint.yml/badge.svg)](https://github.com/ouziel-slama/zeldwallet/actions/workflows/lint.yml)
+[![Test](https://github.com/ouziel-slama/zeldwallet/actions/workflows/test.yml/badge.svg)](https://github.com/ouziel-slama/zeldwallet/actions/workflows/test.yml)
+[![codecov](https://codecov.io/gh/ouziel-slama/zeldwallet/graph/badge.svg?token=L5P886HP35)](https://codecov.io/gh/ouziel-slama/zeldwallet)
+[![npm version](https://img.shields.io/npm/v/zeldwallet.svg)](https://www.npmjs.com/package/zeldwallet)
+
+Lightweight JavaScript library for creating a Bitcoin wallet directly in the browser.
+
+ZeldWallet combines Bitcoin key generation, secure storage (IndexedDB + Web Crypto API), and WBIP004 standard compatibility to be detected by existing Bitcoin applications like sats-connect.
+
+## Features
+
+- 🔐 **Secure Storage**: AES-256-GCM encryption with PBKDF2 key derivation
+- 🔑 **BIP Standards**: Full support for BIP32/39/44/49/84/86
+- 🌐 **Browser Native**: No extensions needed, works directly in the browser
+- 📱 **WBIP Compatible**: Works with sats-connect and other WBIP004-compatible apps
+- ⚡ **Multiple Address Types**: Legacy, SegWit, Nested SegWit, and Taproot
+- 🔓 **Flexible Security**: Start passwordless for quick onboarding, add password later
+
+## Installation
+
+```bash
+npm install zeldwallet
+```
+
+## Quick Start
+
+### Create a New Wallet
+
+```typescript
+import { ZeldWallet, ConfirmationModal } from 'zeldwallet';
+
+const wallet = new ZeldWallet();
+
+// Optional: use the built-in modal confirmation UI (auto-enabled in browsers)
+wallet.useDefaultConfirmationModal();
+
+// Quick creation WITHOUT password (simple onboarding)
+const { mnemonic } = await wallet.create();
+console.log('Backup:', mnemonic); // IMPORTANT: User must save this!
+
+// OR with password (more secure)
+const { mnemonic: securedMnemonic } = await wallet.create('my-secure-password');
+
+// User can add a password later
+await wallet.setPassword('my-secure-password');
+
+// Make the wallet discoverable by sats-connect
+wallet.registerProvider({
+  id: 'ZeldWallet',
+  name: 'Zeld Wallet',
+  icon: 'data:image/svg+xml;base64,...'
+});
+```
+
+### Restore from Mnemonic
+
+```typescript
+const wallet = new ZeldWallet();
+await wallet.restore('your twelve word mnemonic phrase goes here ...', 'optional-password');
+```
+
+### Backup & Restore
+
+```typescript
+// Export (requires wallet password – disable the button until hasPassword() is true)
+if (!(await wallet.hasPassword())) {
+  await wallet.setPassword('my-secure-password');
+}
+const backupString = await wallet.exportBackup('backup-password');
+
+// Import (walletPassword is required to hydrate storage)
+await wallet.importBackup(backupString, 'backup-password', 'my-secure-password');
+```
+Gate the “Export backup” action behind a password prompt or disable it until `await wallet.hasPassword()` resolves to `true` to avoid confusing users.
+
+### Get Addresses
+
+```typescript
+const addresses = wallet.getAddresses(['payment', 'ordinals']);
+console.log(addresses);
+// [
+//   { address: 'bc1q...', publicKey: '...', purpose: 'payment', addressType: 'p2wpkh', derivationPath: "m/84'/0'/0'/0/0" },
+//   { address: 'bc1p...', publicKey: '...', purpose: 'ordinals', addressType: 'p2tr', derivationPath: "m/86'/0'/0'/0/0" }
+// ]
+```
+
+### Sign a Message
+
+```typescript
+const signature = await wallet.signMessage('Hello Bitcoin!', 'bc1q...');
+console.log(signature); // Base64 encoded signature
+```
+
+### Sign a PSBT
+
+```typescript
+const signedPsbt = await wallet.signPsbt(psbtBase64, [
+  { index: 0, address: 'bc1q...' }
+]);
+```
+
+### WBIP Provider Registration
+
+```typescript
+// Register as a WBIP provider (makes wallet detectable by sats-connect)
+wallet.registerProvider({
+  id: 'ZeldWallet',
+  name: 'Zeld Wallet',
+  icon: 'data:image/svg+xml;base64,...'
+});
+
+// Now apps using sats-connect can discover and use ZeldWallet!
+```
+
+### Confirmation UI
+
+```typescript
+import { ConfirmationModal } from 'zeldwallet';
+
+const modal = new ConfirmationModal();
+wallet.useConfirmationModal(modal); // or wallet.useDefaultConfirmationModal();
+```
+
+ZeldWallet uses the provided confirmation handler for connect/sign flows. In browsers the built-in modal is enabled automatically; in SSR/native contexts plug in your own handler instead of relying on `window.confirm`.
+
+### Web Component
+
+`<zeld-wallet-ui>` is a native web component that silently creates/unlocks a wallet (passwordless by default), registers the WBIP provider, and renders payment + ordinals addresses. If the wallet is password-protected it switches to a locked state with a password form.
+
+```html
+<script type="module">
+  import { defineZeldWalletUI } from 'zeldwallet';
+  defineZeldWalletUI(); // no-op if already defined
+</script>
+
+<zeld-wallet-ui lang="en" autoconnect="true"></zeld-wallet-ui>
+```
+
+Attributes / props:
+- `lang`: i18n (`en` default, `fr` available, falls back `en`)
+- `network`: `mainnet` or `testnet` (applied after unlock)
+- `autoconnect`: defaults to `true`; set `autoconnect="false"` to require a manual `connect()`
+
+CSS hooks (shadow DOM classes): `zeldwallet-card`, `zeldwallet-header`, `zeldwallet-title`, `zeldwallet-subtitle`, `zeldwallet-rows`, `zeldwallet-row`, `zeldwallet-label`, `zeldwallet-value`, `zeldwallet-copy`, `zeldwallet-status`, `zeldwallet-status--error`, `zeldwallet-status--loading`, `zeldwallet-password-form`, `zeldwallet-password-fields`, `zeldwallet-password-input`, `zeldwallet-password-button`, `zeldwallet-password-error`.
+
+See `examples/web-component.html` for a complete demo with language toggle and style overrides.
+
+### React Component
+
+`ZeldWalletCard` is a thin React wrapper around the **same** `<zeld-wallet-ui>` custom element; there is no separate React UI to maintain. It autoconnects by default, registers the WBIP provider, and exposes a `connect(password?)` imperative handle via `ref`.
+
+```tsx
+import { ZeldWalletCard, type ZeldWalletCardRef } from 'zeldwallet';
+import { useRef } from 'react';
+
+const walletRef = useRef<ZeldWalletCardRef>(null);
+
+<ZeldWalletCard ref={walletRef} lang="en" network="mainnet" variant="dark" autoconnect />;
+```
+
+Props:
+- `lang`: `en` or `fr` (defaults to `en`)
+- `network`: `mainnet` | `testnet` (applied after unlock)
+- `autoconnect`: defaults to `true`; set `false` to require manual `connect()`
+- `variant`: `light` (default) or `dark` to mirror the web component classes
+- `className`: optional custom wrapper class
+
+See `examples/react` for a Vite demo with language toggle, dark mode, destroy/remount, and message signing.
+
+## Examples
+
+- Run `npm run build` once to refresh `dist/zeldwallet.es.js`, then `npm run dev`.
+- Open http://localhost:5173/ (examples root) to pick the Web Component, sats-connect, or React demos.
+
+## API Reference
+
+### Lifecycle Methods
+
+| Method | Description |
+|--------|-------------|
+| `create(password?)` | Create a new wallet, returns mnemonic |
+| `restore(mnemonic, password?)` | Restore wallet from mnemonic |
+| `unlock(password?)` | Unlock an existing wallet |
+| `lock()` | Lock the wallet, clear sensitive data |
+| `exists()` | Check if a wallet exists |
+| `destroy()` | Permanently delete all wallet data |
+
+### Password Management
+
+| Method | Description |
+|--------|-------------|
+| `setPassword(password)` | Add password protection |
+| `changePassword(old, new)` | Change the password |
+| `removePassword(current)` | Remove password protection |
+| `hasPassword()` | Check if password protected |
+
+### Address & Signing
+
+| Method | Description |
+|--------|-------------|
+| `getAddresses(purposes)` | Get addresses for purposes |
+| `signMessage(message, address, protocol?)` | Sign a message |
+| `signPsbt(psbt, inputsToSign)` | Sign a PSBT |
+
+### Network & Backup
+
+| Method | Description |
+|--------|-------------|
+| `getNetwork()` | Get current network |
+| `setNetwork(network)` | Set network (mainnet/testnet) |
+| `exportMnemonic()` | Export the mnemonic phrase |
+| `exportBackup(password)` | Export encrypted backup |
+| `importBackup(backup, backupPwd, walletPwd?)` | Import backup |
+
+### Events
+
+| Event | Description |
+|-------|-------------|
+| `lock` | Wallet was locked |
+| `unlock` | Wallet was unlocked |
+| `accountsChanged` | Addresses changed |
+| `networkChanged` | Network changed |
+
+## Security Considerations
+
+| Mode | Protection Level | Best For |
+|------|-----------------|----------|
+| No password | AES key stored in IndexedDB | Quick onboarding, small amounts |
+| With password | Key derived via PBKDF2 (600k iterations) | Medium amounts |
+| Hardware wallet | (not supported yet) | Large amounts |
+
+### ⚠️ Important Security Notes
+
+- **Backup your mnemonic**: The 12/24 word phrase is the only way to recover your wallet
+- **Designed for small amounts**: For large sums, use a hardware wallet
+- **Browser storage**: Data persists in IndexedDB, vulnerable to XSS if site is compromised
+- **Add a password**: Protects against casual physical access and some browser extensions
+- **Passwordless mode is weaker**: When the browser cannot persist a non-extractable key (e.g., some Safari/Firefox versions), a raw key envelope is stored in IndexedDB. Malicious extensions could exfiltrate it—set a password to harden the wallet.
+- **Lock when idle**: `wallet.lock()` wipes keys from memory and closes storage handles.
+- **No key logging**: The library avoids logging secrets; keep your app logs clean too.
+- **CSP**: Ship a strict Content-Security-Policy (no inline/eval) to reduce XSS risk around IndexedDB/crypto usage.
+
+### Security posture comparison
+
+| Aspect | ZeldWallet (no password, no backup) | ZeldWallet (password, no backup) | ZeldWallet (password + backup) | Extension wallet (e.g., Xverse) | Custodial wallet (e.g., Web3Auth) |
+|---|---|---|---|---|---|
+| Key custody | Fully self-custodial | Fully self-custodial | Fully self-custodial | Self-custodial | Custodial / shared custody |
+| Secrets at rest | Raw AES key envelope in IndexedDB; weak against device malware/XSS | AES key derived via PBKDF2 (600k); stronger against casual access, still in IndexedDB | Encrypted at rest; off-device backup available with backup password | Stored in extension storage/background page; exposed to extension supply-chain risks | Keys or recovery shares held by service; relies on server/cloud security |
+| Exposure surface | Browser tab + other extensions; XSS can read storage | Same surface, but password gates decryption | Same as passworded; backup allows cold copy off the device | Extension APIs and any installed extensions; phishing of extension permissions | Web/app auth; service infrastructure; phishing of login factors |
+| Device loss | Funds lost (no recovery) | Funds lost (no recovery) | Recoverable via mnemonic or encrypted backup | Recoverable via seed; loss if no seed backup | Recoverable via account recovery / service-managed backup |
+| Recommended use | Only for throwaway/test funds | Small/medium amounts; add backup ASAP | Primary mode for non-custodial users; safer against loss | Small/medium amounts; depends on extension supply chain | Convenience; mitigates device loss; trust placed in provider |
+
+Using ZeldWallet inside a web page means the wallet shares the page’s security boundary: a compromised site, injected script (XSS), or malicious extension can try to read IndexedDB data or page memory. Browser extensions like Xverse run with background-page storage and stricter isolation, so they are less exposed to the host site—but they add their own supply-chain and permission phishing risks. Use a strong CSP, avoid untrusted extensions, and prefer password + backup for ZeldWallet.
+
+### Integration checklist for developers
+
+- Enforce CSP: start with `default-src 'self'; script-src 'self' 'nonce-{random}'; style-src 'self' 'nonce-{random}'; object-src 'none'; base-uri 'self'; form-action 'self'; frame-ancestors 'none';` and add only the `connect-src`, `img-src`, `font-src` you truly need. Avoid `'unsafe-inline'`/`'unsafe-eval'`; use nonces or hashes for any inline script/style you must keep.
+- Avoid inline scripts/styles in your app and in any ZeldWallet integration code; keep everything external or nonce-based.
+- Minimize third-party scripts/extensions on pages hosting ZeldWallet; treat every added script as part of your attack surface.
+- Always enable wallet password and encourage users to export an encrypted backup; lock the wallet when idle.
+- Do not log secrets; scrub request/response bodies and console logs around signing flows.
+- If embedding ZeldWallet in an iframe, set `sandbox` appropriately and restrict `allow` attributes; prefer same-origin frames to reduce cross-context exposure.
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Development server
+npm run dev
+
+# Build for production
+npm run build
+
+# Run tests
+npm test
+```
+
+## Build Outputs
+
+`npm run build` emits to `dist/`:
+- ES module: `zeldwallet.es.js` (used by `exports.import` and `main`)
+- TypeScript declarations: `index.d.ts` and nested `.d.ts` files
+
+## Standards
+
+- [BIP32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki) - HD Wallets
+- [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) - Mnemonic code
+- [BIP44](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki) - Multi-Account HD
+- [BIP84](https://github.com/bitcoin/bips/blob/master/bip-0084.mediawiki) - Native SegWit
+- [BIP86](https://github.com/bitcoin/bips/blob/master/bip-0086.mediawiki) - Taproot
+- [WBIP004](https://wbips.netlify.app) - Browser Wallet Standard
+
+## License
+
+This project is licensed under either of:
+
+- [Apache License, Version 2.0](LICENSE-APACHE)
+- [MIT License](LICENSE-MIT)
+
+at your option.
+

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from './src/index'
+export {}
+import ZeldWallet from './src/index'
+export default ZeldWallet
+export * from './src/index'
+export {}

package/dist/src/ZeldWallet.d.ts

@@ -0,0 +1,254 @@
+import { ConfirmationHandler } from './provider/WBIPProvider';
+import { ConfirmationModal } from './ui/Modal';
+import { AddressPurpose, AddressInfo, NetworkType, WalletEvent, EventHandler, SignInputOptions, WBIPProviderOptions } from './types';
+export * from './types';
+export { SecureStorage } from './storage/SecureStorage';
+export { KeyManager } from './keys/KeyManager';
+export { ConfirmationModal } from './ui/Modal';
+/**
+ * Main ZeldWallet class
+ *
+ * Provides a simple API for wallet creation, management, and signing.
+ */
+export declare class ZeldWallet {
+    private static defaultInstance;
+    private storage;
+    private keyManager;
+    private provider;
+    private eventHandlers;
+    private unlocked;
+    private lastProviderId;
+    private config;
+    private defaultModal?;
+    constructor();
+    /**
+     * Create a new wallet
+     * @param password - Optional password for encryption. If not provided, uses browser-stored key.
+     * @returns The generated mnemonic phrase (MUST be backed up by user!)
+     */
+    create(password?: string, mnemonicPassphrase?: string): Promise<{
+        mnemonic: string;
+    }>;
+    /**
+     * Restore a wallet from a mnemonic phrase
+     * @param mnemonic - The BIP39 mnemonic phrase
+     * @param password - Optional password for encryption
+     * @param mnemonicPassphrase - Optional BIP39 passphrase
+     * @param customPaths - Optional custom derivation paths for payment and ordinals addresses
+     */
+    restore(mnemonic: string, password?: string, mnemonicPassphrase?: string, customPaths?: {
+        payment?: string;
+        ordinals?: string;
+    }): Promise<void>;
+    /**
+     * Unlock an existing wallet
+     * @param password - The password (if password-protected)
+     */
+    unlock(password?: string, mnemonicPassphrase?: string): Promise<void>;
+    /**
+     * Lock the wallet - clear sensitive data from memory
+     */
+    lock(): void;
+    /**
+     * Check if a wallet exists in storage
+     */
+    exists(): Promise<boolean>;
+    /**
+     * Destroy the wallet - permanently delete all data
+     */
+    destroy(): Promise<void>;
+    /**
+     * Add password protection to a passwordless wallet
+     */
+    setPassword(password: string): Promise<void>;
+    /**
+     * Change the wallet password
+     */
+    changePassword(oldPassword: string, newPassword: string, options?: {
+        iterations?: number;
+    }): Promise<void>;
+    /**
+     * Remove password protection (revert to passwordless mode)
+     */
+    removePassword(currentPassword: string): Promise<void>;
+    /**
+     * Check if the wallet has password protection
+     */
+    hasPassword(): Promise<boolean>;
+    /**
+     * Check if the wallet has ever produced a backup
+     */
+    hasBackup(): Promise<boolean>;
+    /**
+     * Mark the wallet as backed up (e.g., when restoring from mnemonic)
+     */
+    markBackupCompleted(timestamp?: number): Promise<void>;
+    /**
+     * Get addresses for the specified purposes
+     */
+    getAddresses(purposes: AddressPurpose[]): AddressInfo[];
+    /**
+     * Sign a message with the private key of the specified address
+     */
+    signMessage(message: string, address: string, protocol?: 'ecdsa' | 'bip322-simple'): Promise<string>;
+    /**
+     * Sign a PSBT (Partially Signed Bitcoin Transaction)
+     */
+    signPsbt(psbtBase64: string, inputsToSign: SignInputOptions[]): Promise<string>;
+    /**
+     * Configure address lookup windows used when resolving addresses to paths.
+     * Useful for wallets with large index gaps.
+     */
+    setAddressLookupConfig(config: Partial<{
+        maxAccount: number;
+        receiveWindow: number;
+        changeWindow: number;
+    }>): void;
+    /**
+     * Get the current network
+     */
+    getNetwork(): NetworkType;
+    /**
+     * Set the network (mainnet or testnet)
+     */
+    setNetwork(network: NetworkType): Promise<void>;
+    /**
+     * Export the mnemonic phrase
+     * WARNING: This exposes the seed - use with caution and always re-encrypt!
+     */
+    exportMnemonic(): string;
+    /**
+     * Export wallet backup as a portable string
+     */
+    exportBackup(backupPassword: string): Promise<string>;
+    /**
+     * Import wallet from backup string
+     */
+    importBackup(backupString: string, backupPassword: string, walletPassword?: string, options?: {
+        overwrite?: boolean;
+    }): Promise<void>;
+    /**
+     * Subscribe to wallet events
+     */
+    on<T = unknown>(event: WalletEvent, handler: EventHandler<T>): void;
+    /**
+     * Unsubscribe from wallet events
+     */
+    off<T = unknown>(event: WalletEvent, handler: EventHandler<T>): void;
+    /**
+     * Emit an event
+     */
+    private emit;
+    /**
+     * Emit the latest accounts snapshot to listeners (used after unlock/create).
+     */
+    private emitAccountsSnapshot;
+    /**
+     * Parse a backup envelope or fall back to legacy format.
+     */
+    private parseBackupEnvelope;
+    /**
+     * Lightweight structural validation of a backup envelope to catch tampering.
+     */
+    private isValidBackupEnvelope;
+    /**
+     * Load persisted configuration (network, custom paths, etc.) from storage.
+     */
+    private applyStoredConfig;
+    /**
+     * Persist current configuration to storage.
+     */
+    private persistConfig;
+    /**
+     * Check if the wallet is currently unlocked
+     */
+    isUnlocked(): boolean;
+    /**
+     * Ensure the wallet is unlocked before performing operations
+     */
+    private ensureUnlocked;
+    /**
+     * Enforce basic password strength for new passwords/backups.
+     * Existing (possibly weak) passwords are still accepted for decryption flows.
+     * In test environments, allow shorter passwords to keep fixtures lightweight.
+     */
+    private assertPasswordStrength;
+    private isTestEnvironment;
+    /**
+     * Get the shared singleton instance used by static helpers.
+     */
+    private static getDefaultInstance;
+    static create(password?: string, mnemonicPassphrase?: string): Promise<{
+        mnemonic: string;
+    }>;
+    static restore(mnemonic: string, password?: string, mnemonicPassphrase?: string, customPaths?: {
+        payment?: string;
+        ordinals?: string;
+    }): Promise<void>;
+    static unlock(password?: string, mnemonicPassphrase?: string): Promise<void>;
+    static lock(): void;
+    static exists(): Promise<boolean>;
+    static destroy(): Promise<void>;
+    static registerProvider(options: WBIPProviderOptions): void;
+    static unregisterProvider(id?: string): void;
+    static setConfirmationHandler(handler?: ConfirmationHandler): void;
+    static useConfirmationModal(modal: ConfirmationModal): void;
+    static useDefaultConfirmationModal(): void;
+    static setPassword(password: string): Promise<void>;
+    static changePassword(oldPassword: string, newPassword: string, options?: {
+        iterations?: number;
+    }): Promise<void>;
+    static removePassword(currentPassword: string): Promise<void>;
+    static hasPassword(): Promise<boolean>;
+    static hasBackup(): Promise<boolean>;
+    static markBackupCompleted(timestamp?: number): Promise<void>;
+    static exportBackup(backupPassword: string): Promise<string>;
+    static importBackup(backup: string, backupPassword: string, walletPassword?: string, options?: {
+        overwrite?: boolean;
+    }): Promise<void>;
+    static getAddresses(purposes: AddressPurpose[]): AddressInfo[];
+    static signMessage(message: string, address: string, protocol?: 'ecdsa' | 'bip322-simple'): Promise<string>;
+    static signPsbt(psbt: string, options: SignInputOptions[]): Promise<string>;
+    static on(event: WalletEvent, handler: EventHandler): void;
+    static off(event: WalletEvent, handler: EventHandler): void;
+    static isUnlocked(): boolean;
+    static getNetwork(): NetworkType;
+    static setNetwork(network: NetworkType): Promise<void>;
+    static setAddressLookupConfig(config: Partial<{
+        maxAccount: number;
+        receiveWindow: number;
+        changeWindow: number;
+    }>): void;
+    /**
+     * Override the confirmation handler used by the WBIP provider.
+     * Useful to plug in custom modals or native prompts.
+     */
+    setConfirmationHandler(handler?: ConfirmationHandler): void;
+    /**
+     * Use a provided ConfirmationModal instance for UX prompts.
+     */
+    useConfirmationModal(modal: ConfirmationModal): void;
+    /**
+     * Use the built-in modal when running in a browser environment.
+     */
+    useDefaultConfirmationModal(): void;
+    /**
+     * Register as a WBIP provider
+     * This makes the wallet discoverable by apps using sats-connect
+     */
+    registerProvider(options: WBIPProviderOptions): void;
+    /**
+     * Unregister as a WBIP provider
+     */
+    unregisterProvider(id?: string): void;
+    /**
+     * Reset provider access grants (used on lock/destroy).
+     */
+    private resetProviderAccess;
+    /**
+     * Enable the default modal confirmation handler when the DOM is available.
+     */
+    private tryEnableDefaultConfirmation;
+}
+export default ZeldWallet;
+//# sourceMappingURL=ZeldWallet.d.ts.map

package/dist/src/ZeldWallet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZeldWallet.d.ts","sourceRoot":"","sources":["../../src/ZeldWallet.ts"],"names":[],"mappings":"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"}

package/dist/src/component/ZeldWalletUI.d.ts

@@ -0,0 +1,56 @@
+import { NetworkType } from '../types';
+import { BaseElement } from './constants';
+export declare class ZeldWalletUI extends BaseElement {
+    private controller;
+    private snapshot;
+    private unsubscribe?;
+    private shadowRootRef?;
+    private initialVariant;
+    private variantApplied;
+    private boundActivityHandler?;
+    /**
+     * Activity events that reset the idle timer (for shadow DOM).
+     */
+    private static readonly ACTIVITY_EVENTS;
+    private applyVariant;
+    constructor();
+    static get observedAttributes(): string[];
+    get lang(): string;
+    set lang(value: string);
+    get network(): NetworkType;
+    set network(value: NetworkType);
+    get variant(): 'light' | 'dark';
+    set variant(value: 'light' | 'dark');
+    get autoconnect(): boolean;
+    set autoconnect(value: boolean);
+    get electrsUrl(): string | null;
+    set electrsUrl(value: string | null);
+    get zeldhashApiUrl(): string | null;
+    set zeldhashApiUrl(value: string | null);
+    attributeChangedCallback(name: string, _oldValue: string | null, newValue: string | null): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /**
+     * Set up activity event listeners on the shadow DOM root.
+     * These events bubble up from the shadow DOM and notify the controller.
+     */
+    private setupActivityListeners;
+    /**
+     * Remove activity event listeners from the shadow DOM root.
+     */
+    private teardownActivityListeners;
+    /**
+     * Public API to set the locale programmatically.
+     */
+    setLocale(lang?: string): void;
+    /**
+     * Public API to trigger (or retry) connection manually.
+     */
+    connect(password?: string): Promise<void>;
+    private render;
+}
+/**
+ * Helper to define the custom element with an optional custom tag name.
+ */
+export declare function defineZeldWalletUI(tagName?: string): string;
+//# sourceMappingURL=ZeldWalletUI.d.ts.map

package/dist/src/component/ZeldWalletUI.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ZeldWalletUI.d.ts","sourceRoot":"","sources":["../../../src/component/ZeldWalletUI.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,UAAU,CAAC;AAY5C,OAAO,EAAE,WAAW,EAAoB,MAAM,aAAa,CAAC;AAK5D,qBAAa,YAAa,SAAQ,WAAW;IAC3C,OAAO,CAAC,UAAU,CAAuB;IACzC,OAAO,CAAC,QAAQ,CAAqB;IACrC,OAAO,CAAC,WAAW,CAAC,CAAa;IACjC,OAAO,CAAC,aAAa,CAAC,CAAa;IACnC,OAAO,CAAC,cAAc,CAAuB;IAC7C,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,oBAAoB,CAAC,CAAa;IAE1C;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAQ5B;IAEX,OAAO,CAAC,YAAY;;IAgCpB,MAAM,KAAK,kBAAkB,IAAI,MAAM,EAAE,CAExC;IAED,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,IAAI,IAAI,CAAC,KAAK,EAAE,MAAM,EAMrB;IAED,IAAI,OAAO,IAAI,WAAW,CAEzB;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,WAAW,EAM7B;IAED,IAAI,OAAO,IAAI,OAAO,GAAG,MAAM,CAE9B;IAED,IAAI,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,EAOlC;IAED,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,IAAI,WAAW,CAAC,KAAK,EAAE,OAAO,EAG7B;IAED,IAAI,UAAU,IAAI,MAAM,GAAG,IAAI,CAE9B;IAED,IAAI,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAMlC;IAED,IAAI,cAAc,IAAI,MAAM,GAAG,IAAI,CAElC;IAED,IAAI,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAMtC;IAED,wBAAwB,CAAC,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI;IA6B/F,iBAAiB,IAAI,IAAI;IAazB,oBAAoB,IAAI,IAAI;IAM5B;;;OAGG;IACH,OAAO,CAAC,sBAAsB;IAU9B;;OAEG;IACH,OAAO,CAAC,yBAAyB;IASjC;;OAEG;IACH,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI;IAQ9B;;OAEG;IACG,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C,OAAO,CAAC,MAAM;CAuGf;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,MAAyB,GAAG,MAAM,CAQ7E"}

package/dist/src/component/balance.d.ts

@@ -0,0 +1,41 @@
+import { AddressInfo } from '../types';
+export type UtxoResponse = {
+    txid: string;
+    vout: number;
+    value: number;
+    status: {
+        confirmed: boolean;
+        block_height?: number;
+    };
+};
+export type ZeldBalanceResponse = {
+    txid: string;
+    vout: number;
+    balance: number;
+};
+export type BalanceResult = {
+    btcSats: number;
+    zeldBalance: number;
+    /** BTC balance in sats for payment address only (first address if multiple) */
+    btcPaymentSats?: number;
+};
+/**
+ * Fetches combined balance for multiple addresses.
+ * Explicitly identifies the payment address by purpose to avoid ordering issues.
+ */
+export declare function fetchBalances(addresses: AddressInfo[], electrsUrl?: string, zeldhashApiUrl?: string): Promise<BalanceResult>;
+/**
+ * Formats satoshis to BTC string with 8 decimal places.
+ * Uses locale-aware thousand separators when locale is provided.
+ */
+export declare function formatBtc(sats: number, locale?: string): string;
+/**
+ * Formats ZELD balance (stored in minimal units, 8 decimals).
+ * Uses locale-aware thousand separators when locale is provided.
+ */
+export declare function formatZeld(balance: number, locale?: string): string;
+/**
+ * Truncates an address for display (first 6 + … + last 6 characters).
+ */
+export declare function truncateAddress(address: string, prefixLen?: number, suffixLen?: number): string;
+//# sourceMappingURL=balance.d.ts.map