@ozura/elements 0.1.0-beta.6 → 1.0.0

package/dist/react/index.esm.js

@@ -131,6 +131,15 @@ function mergeStyleConfigs(a, b) {
  * Resolution order: theme defaults → variable overrides.
  * The returned config is then used as the "base appearance" that
  * per-element `style` overrides merge on top of.
+ *
+ * @remarks
+ * - `appearance: undefined` → no styles injected (element iframes use their
+ *   own minimal built-in defaults).
+ * - `appearance: {}` or `appearance: { variables: {...} }` without an explicit
+ *   `theme` → the `'default'` theme is used as the base. Omitting `theme`
+ *   does NOT mean "no theme" — it means `theme: 'default'`. To opt out of
+ *   the preset themes entirely, use per-element `style` overrides without
+ *   passing an `appearance` prop at all.
  */
 function resolveAppearance(appearance) {
     var _a, _b;
@@ -156,7 +165,117 @@ function mergeAppearanceWithElementStyle(appearance, elementStyle) {
     return mergeStyleConfigs(appearance, elementStyle);
 }
 
-const BLOCKED_CSS_PATTERNS = /url\s*\(|expression\s*\(|javascript\s*:|vbscript\s*:|@import|behavior\s*:|binding\s*:|-moz-binding|-webkit-binding|<\s*script|<\s*style|\\[0-9a-fA-F]/i;
+/**
+ * errors.ts — error types and normalisation for OzElements.
+ *
+ * Three normalisation functions:
+ *  - normalizeVaultError      — maps raw vault /tokenize errors to user-facing messages (card flows)
+ *  - normalizeBankVaultError   — maps raw vault /tokenize errors to user-facing messages (bank/ACH flows)
+ *  - normalizeCardSaleError    — maps raw cardSale API errors to user-facing messages
+ *
+ * Error keys in normalizeCardSaleError are taken directly from checkout's
+ * errorMapping.ts so the same error strings produce the same user-facing copy.
+ */
+const OZ_ERROR_CODES = new Set(['network', 'timeout', 'auth', 'validation', 'server', 'config', 'unknown']);
+/** Returns true and narrows to OzErrorCode when `value` is a valid member of the union. */
+function isOzErrorCode(value) {
+    return typeof value === 'string' && OZ_ERROR_CODES.has(value);
+}
+class OzError extends Error {
+    constructor(message, raw, errorCode) {
+        super(message);
+        this.name = 'OzError';
+        this.raw = raw !== null && raw !== void 0 ? raw : message;
+        this.errorCode = errorCode !== null && errorCode !== void 0 ? errorCode : 'unknown';
+        this.retryable = this.errorCode === 'network' || this.errorCode === 'timeout' || this.errorCode === 'server';
+    }
+}
+/** Shared patterns that apply to both card and bank vault errors. */
+function normalizeCommonVaultError(msg) {
+    if (msg.includes('api key') || msg.includes('unauthorized') || msg.includes('authentication') || msg.includes('forbidden')) {
+        return 'Authentication failed. Check your vault API key configuration.';
+    }
+    if (msg.includes('network') || msg.includes('failed to fetch') || msg.includes('networkerror')) {
+        return 'A network error occurred. Please check your connection and try again.';
+    }
+    if (msg.includes('timeout') || msg.includes('timed out')) {
+        return 'The request timed out. Please try again.';
+    }
+    if (msg.includes('http 5') || msg.includes('500') || msg.includes('502') || msg.includes('503')) {
+        return 'A server error occurred. Please try again shortly.';
+    }
+    return null;
+}
+/**
+ * Maps a raw vault /tokenize error string to a user-facing message for card flows.
+ * Falls back to the original string if no pattern matches.
+ */
+function normalizeVaultError(raw) {
+    const msg = raw.toLowerCase();
+    if (msg.includes('card number') || msg.includes('invalid card') || msg.includes('luhn')) {
+        return 'The card number is invalid. Please check and try again.';
+    }
+    if (msg.includes('expir')) {
+        return 'The card expiration date is invalid or the card has expired.';
+    }
+    if (msg.includes('cvv') || msg.includes('cvc') || msg.includes('security code')) {
+        return 'The CVV code is invalid. Please check and try again.';
+    }
+    if (msg.includes('insufficient') || msg.includes('funds')) {
+        return 'Your card has insufficient funds. Please use a different card.';
+    }
+    if (msg.includes('declined') || msg.includes('do not honor')) {
+        return 'Your card was declined. Please try a different card or contact your bank.';
+    }
+    const common = normalizeCommonVaultError(msg);
+    if (common)
+        return common;
+    return raw;
+}
+/**
+ * Maps a raw vault /tokenize error string to a user-facing message for bank (ACH) flows.
+ * Uses bank-specific pattern matching so card-specific messages are never shown for
+ * bank errors. Falls back to the original string if no pattern matches.
+ */
+function normalizeBankVaultError(raw) {
+    const msg = raw.toLowerCase();
+    if (msg.includes('account number') || msg.includes('account_number') || msg.includes('invalid account')) {
+        return 'The bank account number is invalid. Please check and try again.';
+    }
+    if (msg.includes('routing number') || msg.includes('routing_number') || msg.includes('invalid routing') || /\baba\b/.test(msg)) {
+        return 'The routing number is invalid. Please check and try again.';
+    }
+    const common = normalizeCommonVaultError(msg);
+    if (common)
+        return common;
+    return raw;
+}
+
+/**
+ * Generates a RFC 4122 v4 UUID.
+ *
+ * Uses `crypto.randomUUID()` when available (Chrome 92+, Firefox 95+,
+ * Safari 15.4+, Node 14.17+) and falls back to `crypto.getRandomValues()`
+ * for older environments (Safari 14, some embedded WebViews, older Node).
+ *
+ * Both paths use the same CSPRNG — the difference is only in API surface.
+ *
+ * @internal
+ */
+function uuid() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    // Fallback: build UUID v4 from random bytes
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant RFC 4122
+    const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+const BLOCKED_CSS_PATTERNS = /url\s*\(|expression\s*\(|javascript\s*:|vbscript\s*:|@import|behavior\s*:|binding\s*:|-moz-binding|-webkit-binding|<\s*script|<\s*style|\\[0-9a-fA-F]|var\s*\(/i;
 const CSS_BREAKOUT = /[{};<>]/;
 const MAX_CSS_VALUE_LEN = 200;
 function sanitizeStyleObj(obj) {
@@ -188,6 +307,11 @@ function sanitizeStyles(style) {
 function sanitizeOptions(options) {
     var _a;
     const result = Object.assign(Object.assign({}, options), { placeholder: (_a = options.placeholder) === null || _a === void 0 ? void 0 : _a.slice(0, 100) });
+    // Coerce to boolean so a string "false" (truthy in JS) does not accidentally
+    // disable the input when the SDK is consumed from plain JavaScript.
+    if (options.disabled !== undefined) {
+        result.disabled = Boolean(options.disabled);
+    }
     // Only set style when provided; omitting it avoids clobbering existing style
     // when merging (e.g. update({ placeholder: 'new' }) must not overwrite style with undefined).
     if (options.style !== undefined) {
@@ -215,7 +339,7 @@ class OzElement {
         this.frameOrigin = new URL(frameBaseUrl).origin;
         this.fonts = fonts;
         this.appearanceStyle = appearanceStyle;
-        this.frameId = `oz-${elementType}-${Math.random().toString(36).slice(2, 10)}`;
+        this.frameId = `oz-${elementType}-${uuid()}`;
     }
     /** The element type this proxy represents. */
     get type() {
@@ -233,22 +357,27 @@ class OzElement {
     mount(target) {
         var _a;
         if (this._destroyed)
-            throw new Error('OzElements: cannot mount a destroyed element.');
+            throw new OzError('Cannot mount a destroyed element.');
         if (this.iframe)
             this.unmount();
         const container = typeof target === 'string'
             ? document.querySelector(target)
             : target;
         if (!container)
-            throw new Error(typeof target === 'string'
-                ? `OzElements: mount target not found — no element matches "${target}"`
-                : `OzElements: mount target not found — the provided HTMLElement is null or undefined`);
+            throw new OzError(typeof target === 'string'
+                ? `Mount target not found — no element matches "${target}"`
+                : 'Mount target not found — the provided HTMLElement is null or undefined');
         const iframe = document.createElement('iframe');
         iframe.setAttribute('frameborder', '0');
         iframe.setAttribute('scrolling', 'no');
         iframe.setAttribute('allowtransparency', 'true');
         iframe.style.cssText = 'border:none;width:100%;height:46px;display:block;overflow:hidden;';
         iframe.title = `Secure ${this.elementType} input`;
+        // Note: the `sandbox` attribute is intentionally NOT set. Field values are
+        // delivered to the tokenizer iframe via a MessageChannel port (transferred
+        // in OZ_BEGIN_COLLECT), so no window.parent named-frame lookup is needed.
+        // The security boundary is the vault URL hardcoded at build time and the
+        // origin checks on every postMessage, not the sandbox flag.
         // Use hash instead of query string — survives clean-URL redirects from static servers.
         // parentOrigin lets the frame target postMessage to the merchant origin instead of '*'.
         const parentOrigin = typeof window !== 'undefined' ? window.location.origin : '';
@@ -264,6 +393,11 @@ class OzElement {
             }
         }, timeout);
     }
+    /**
+     * Subscribe to an element event. Returns `this` for chaining.
+     * @param event - Event name: `'change'`, `'focus'`, `'blur'`, `'ready'`, or `'loaderror'`.
+     * @param callback - Handler invoked with the event payload.
+     */
     on(event, callback) {
         if (this._destroyed)
             return this;
@@ -272,6 +406,10 @@ class OzElement {
         this.handlers.get(event).push(callback);
         return this;
     }
+    /**
+     * Remove a previously registered event handler.
+     * Has no effect if the handler is not registered.
+     */
     off(event, callback) {
         const list = this.handlers.get(event);
         if (list) {
@@ -281,6 +419,10 @@ class OzElement {
         }
         return this;
     }
+    /**
+     * Subscribe to an event for a single invocation. The handler is automatically
+     * removed after it fires once.
+     */
     once(event, callback) {
         const wrapper = (payload) => {
             this.off(event, wrapper);
@@ -288,13 +430,24 @@ class OzElement {
         };
         return this.on(event, wrapper);
     }
+    /**
+     * Dynamically update element options (placeholder, style, etc.) without
+     * re-mounting the iframe. Only the provided keys are merged; omitted keys
+     * retain their current values.
+     */
     update(options) {
         if (this._destroyed)
             return;
         const safe = sanitizeOptions(options);
+        // Re-merge vault appearance when style is updated so focus/invalid/complete/
+        // placeholder buckets from the theme are not stripped by a partial style object.
+        if (safe.style !== undefined) {
+            safe.style = mergeAppearanceWithElementStyle(this.appearanceStyle, safe.style);
+        }
         this.options = Object.assign(Object.assign({}, this.options), safe);
         this.post({ type: 'OZ_UPDATE', options: safe });
     }
+    /** Clear the current field value without removing the element from the DOM. */
     clear() {
         if (this._destroyed)
             return;
@@ -307,6 +460,8 @@ class OzElement {
      */
     unmount() {
         var _a;
+        if (this._destroyed)
+            return;
         if (this._loadTimer) {
             clearTimeout(this._loadTimer);
             this._loadTimer = null;
@@ -339,18 +494,31 @@ class OzElement {
         this._destroyed = true;
     }
     // ─── Called by OzVault ───────────────────────────────────────────────────
-    setTokenizerName(tokenizerName) {
-        this.post({ type: 'OZ_SET_TOKENIZER_NAME', tokenizerName });
-    }
-    beginCollect(requestId) {
-        this.post({ type: 'OZ_BEGIN_COLLECT', requestId });
+    /**
+     * Sends OZ_BEGIN_COLLECT to the element iframe, transferring `port` so the
+     * iframe can post its field value directly to the tokenizer without going
+     * through the merchant page (no named-window lookup required).
+     * @internal
+     */
+    beginCollect(requestId, port) {
+        if (this._destroyed)
+            return;
+        this.sendWithTransfer({ type: 'OZ_BEGIN_COLLECT', requestId }, [port]);
     }
-    /** Tell a CVV element how many digits to expect. Called automatically when card brand changes. */
+    /**
+     * Tell a CVV element how many digits to expect. Called automatically when card brand changes.
+     * @internal
+     */
     setCvvLength(length) {
+        if (this._destroyed)
+            return;
         this.post({ type: 'OZ_SET_CVV_LENGTH', length });
     }
+    /** @internal */
     handleMessage(msg) {
         var _a, _b;
+        if (this._destroyed)
+            return;
         switch (msg.type) {
             case 'OZ_FRAME_READY': {
                 this._ready = true;
@@ -364,6 +532,19 @@ class OzElement {
                 this.pendingMessages.forEach(m => this.send(m));
                 this.pendingMessages = [];
                 this.emit('ready', undefined);
+                // Warn if the mount container collapses to zero height — the input will
+                // be invisible but functional, which is hard to debug. Check after one
+                // animation frame so the browser has completed layout. Guard against
+                // non-rendering environments (jsdom, SSR) where all rects are zero.
+                if (typeof requestAnimationFrame !== 'undefined') {
+                    requestAnimationFrame(() => {
+                        const inRealBrowser = document.documentElement.getBoundingClientRect().height > 0;
+                        if (inRealBrowser && this.iframe && this.iframe.getBoundingClientRect().height === 0) {
+                            console.warn(`[OzElement] "${this.elementType}" mounted but has zero height. ` +
+                                `Check that the container has a visible height (not overflow:hidden or height:0).`);
+                        }
+                    });
+                }
                 break;
             }
             case 'OZ_CHANGE':
@@ -390,7 +571,12 @@ class OzElement {
                 break;
             case 'OZ_RESIZE':
                 if (this.iframe) {
-                    this.iframe.style.height = `${msg.height}px`;
+                    // Clamp to a sensible range to prevent a rogue or compromised frame
+                    // from zeroing out the input or stretching the layout.
+                    const h = typeof msg.height === 'number' ? msg.height : 0;
+                    if (h > 0 && h <= 300) {
+                        this.iframe.style.height = `${h}px`;
+                    }
                 }
                 break;
         }
@@ -398,8 +584,16 @@ class OzElement {
     // ─── Internal ────────────────────────────────────────────────────────────
     emit(event, payload) {
         const list = this.handlers.get(event);
-        if (list)
-            [...list].forEach(fn => fn(payload));
+        if (!list)
+            return;
+        [...list].forEach(fn => {
+            try {
+                fn(payload);
+            }
+            catch (err) {
+                console.error(`[OzElement] Unhandled error in '${event}' listener:`, err);
+            }
+        });
     }
     post(data) {
         const msg = Object.assign({ __oz: true, vaultId: this.vaultId }, data);
@@ -414,87 +608,18 @@ class OzElement {
         var _a;
         (_a = this._frameWindow) === null || _a === void 0 ? void 0 : _a.postMessage(msg, this.frameOrigin);
     }
-}
-
-/**
- * errors.ts — error types and normalisation for OzElements.
- *
- * Three normalisation functions:
- *  - normalizeVaultError      — maps raw vault /tokenize errors to user-facing messages (card flows)
- *  - normalizeBankVaultError   — maps raw vault /tokenize errors to user-facing messages (bank/ACH flows)
- *  - normalizeCardSaleError    — maps raw cardSale API errors to user-facing messages
- *
- * Error keys in normalizeCardSaleError are taken directly from checkout's
- * errorMapping.ts so the same error strings produce the same user-facing copy.
- */
-class OzError extends Error {
-    constructor(message, raw, errorCode) {
-        super(message);
-        this.name = 'OzError';
-        this.raw = raw !== null && raw !== void 0 ? raw : message;
-        this.errorCode = errorCode !== null && errorCode !== void 0 ? errorCode : 'unknown';
-        this.retryable = this.errorCode === 'network' || this.errorCode === 'timeout' || this.errorCode === 'server';
-    }
-}
-/** Shared patterns that apply to both card and bank vault errors. */
-function normalizeCommonVaultError(msg) {
-    if (msg.includes('api key') || msg.includes('unauthorized') || msg.includes('authentication') || msg.includes('forbidden')) {
-        return 'Authentication failed. Check your vault API key configuration.';
-    }
-    if (msg.includes('network') || msg.includes('failed to fetch') || msg.includes('networkerror')) {
-        return 'A network error occurred. Please check your connection and try again.';
-    }
-    if (msg.includes('timeout') || msg.includes('timed out')) {
-        return 'The request timed out. Please try again.';
-    }
-    if (msg.includes('http 5') || msg.includes('500') || msg.includes('502') || msg.includes('503')) {
-        return 'A server error occurred. Please try again shortly.';
-    }
-    return null;
-}
-/**
- * Maps a raw vault /tokenize error string to a user-facing message for card flows.
- * Falls back to the original string if no pattern matches.
- */
-function normalizeVaultError(raw) {
-    const msg = raw.toLowerCase();
-    if (msg.includes('card number') || msg.includes('invalid card') || msg.includes('luhn')) {
-        return 'The card number is invalid. Please check and try again.';
-    }
-    if (msg.includes('expir')) {
-        return 'The card expiration date is invalid or the card has expired.';
-    }
-    if (msg.includes('cvv') || msg.includes('cvc') || msg.includes('security code')) {
-        return 'The CVV code is invalid. Please check and try again.';
-    }
-    if (msg.includes('insufficient') || msg.includes('funds')) {
-        return 'Your card has insufficient funds. Please use a different card.';
-    }
-    if (msg.includes('declined') || msg.includes('do not honor')) {
-        return 'Your card was declined. Please try a different card or contact your bank.';
-    }
-    const common = normalizeCommonVaultError(msg);
-    if (common)
-        return common;
-    return raw;
-}
-/**
- * Maps a raw vault /tokenize error string to a user-facing message for bank (ACH) flows.
- * Uses bank-specific pattern matching so card-specific messages are never shown for
- * bank errors. Falls back to the original string if no pattern matches.
- */
-function normalizeBankVaultError(raw) {
-    const msg = raw.toLowerCase();
-    if (msg.includes('account number') || msg.includes('account_number') || msg.includes('invalid account')) {
-        return 'The bank account number is invalid. Please check and try again.';
-    }
-    if (msg.includes('routing number') || msg.includes('routing_number') || msg.includes('invalid routing') || /\baba\b/.test(msg)) {
-        return 'The routing number is invalid. Please check and try again.';
+    /** Posts a message with transferable objects (e.g. MessagePort). Bypasses the
+     *  pending-message queue — only call when the frame is already ready. */
+    sendWithTransfer(data, transfer) {
+        if (this._destroyed)
+            return;
+        if (!this._frameWindow) {
+            console.error('[OzElement] sendWithTransfer called before frame window is available — port will not be transferred. This is a bug.');
+            return;
+        }
+        const msg = Object.assign({ __oz: true, vaultId: this.vaultId }, data);
+        this._frameWindow.postMessage(msg, this.frameOrigin, transfer);
     }
-    const common = normalizeCommonVaultError(msg);
-    if (common)
-        return common;
-    return raw;
 }
 
 /**
@@ -546,6 +671,14 @@ const US_STATES = {
     'south dakota': 'SD', tennessee: 'TN', texas: 'TX', utah: 'UT',
     vermont: 'VT', virginia: 'VA', washington: 'WA', 'west virginia': 'WV',
     wisconsin: 'WI', wyoming: 'WY',
+    // US territories
+    'puerto rico': 'PR', guam: 'GU', 'virgin islands': 'VI',
+    'us virgin islands': 'VI', 'u.s. virgin islands': 'VI',
+    'american samoa': 'AS', 'northern mariana islands': 'MP',
+    'commonwealth of the northern mariana islands': 'MP',
+    // Military / diplomatic addresses
+    'armed forces europe': 'AE', 'armed forces pacific': 'AP',
+    'armed forces americas': 'AA',
 };
 const US_ABBREVS = new Set(Object.values(US_STATES));
 const CA_PROVINCES = {
@@ -654,8 +787,15 @@ function validateBilling(billing) {
             errors.push('billing.address.line2 must be 1–50 characters if provided');
         if (!isValidBillingField(city))
             errors.push('billing.address.city must be 1–50 characters');
-        if (!isValidBillingField(state))
+        if (!isValidBillingField(state)) {
             errors.push('billing.address.state must be 1–50 characters');
+        }
+        else if (country === 'US' && !US_ABBREVS.has(state)) {
+            errors.push(`billing.address.state "${state}" is not a recognized US state or territory abbreviation (e.g. "CA", "NY", "PR")`);
+        }
+        else if (country === 'CA' && !CA_ABBREVS.has(state)) {
+            errors.push(`billing.address.state "${state}" is not a recognized Canadian province or territory abbreviation (e.g. "ON", "BC", "QC")`);
+        }
         // cardSale backend uses strict enum validation on country — must be exactly 2 uppercase letters
         if (!/^[A-Z]{2}$/.test(country)) {
             errors.push('billing.address.country must be a 2-letter ISO 3166-1 alpha-2 code (e.g. "US", "CA", "GB")');
@@ -679,13 +819,31 @@ function validateBilling(billing) {
     return { valid: errors.length === 0, errors, normalized };
 }
 
-const DEFAULT_FRAME_BASE_URL = "https://lively-hill-097170c0f.4.azurestaticapps.net";
+function isCardMetadata(v) {
+    return !!v && typeof v === 'object' && typeof v.last4 === 'string';
+}
+function isBankAccountMetadata(v) {
+    return !!v && typeof v === 'object' && typeof v.last4 === 'string';
+}
+const DEFAULT_FRAME_BASE_URL = "https://elements.ozura.com";
 /**
  * The main entry point for OzElements. Creates and manages iframe-based
  * card input elements that keep raw card data isolated from the merchant page.
  *
+ * Use the static `OzVault.create()` factory — do not call `new OzVault()` directly.
+ *
  * @example
- * const vault = new OzVault('your_vault_api_key');
+ * const vault = await OzVault.create({
+ *   pubKey: 'pk_live_...',
+ *   fetchWaxKey: async (sessionId) => {
+ *     // Call your backend — which calls ozura.mintWaxKey() from @ozura/elements/server
+ *     const { waxKey } = await fetch('/api/mint-wax', {
+ *       method: 'POST',
+ *       body: JSON.stringify({ sessionId }),
+ *     }).then(r => r.json());
+ *     return waxKey;
+ *   },
+ * });
  * const cardNum = vault.createElement('cardNumber');
  * cardNum.mount('#card-number');
  * const { token, cvcSession } = await vault.createToken({
@@ -693,8 +851,14 @@ const DEFAULT_FRAME_BASE_URL = "https://lively-hill-097170c0f.4.azurestaticapps.
  * });
  */
 class OzVault {
-    constructor(apiKey, options) {
-        var _a, _b;
+    /**
+     * Internal constructor — use `OzVault.create()` instead.
+     * The constructor mounts the tokenizer iframe immediately so it can start
+     * loading in parallel while `fetchWaxKey` is being awaited.
+     * @internal
+     */
+    constructor(options, waxKey, tokenizationSessionId) {
+        var _a, _b, _c;
         this.elements = new Map();
         this.elementsByType = new Map();
         this.bankElementsByType = new Map();
@@ -707,24 +871,32 @@ class OzVault {
         this.tokenizerReady = false;
         this._tokenizing = null;
         this._destroyed = false;
+        // Tracks successful tokenizations against the per-key call budget so the SDK
+        // can proactively refresh the wax key after it has been consumed rather than
+        // waiting for the next createToken() call to fail.
+        this._tokenizeSuccessCount = 0;
         this._pendingMount = null;
+        this._storedFetchWaxKey = null;
+        this._waxRefreshing = null;
         this.loadErrorTimeoutId = null;
-        if (!apiKey || !apiKey.trim()) {
-            throw new OzError('A non-empty vault API key is required. Pass your key as the first argument to new OzVault().');
-        }
-        this.apiKey = apiKey;
+        // Proactive wax refresh on visibility restore after long idle
+        this._hiddenAt = null;
+        this.waxKey = waxKey;
+        this.tokenizationSessionId = tokenizationSessionId;
         this.pubKey = options.pubKey;
         this.frameBaseUrl = options.frameBaseUrl || DEFAULT_FRAME_BASE_URL;
         this.frameOrigin = new URL(this.frameBaseUrl).origin;
         this.fonts = (_a = options.fonts) !== null && _a !== void 0 ? _a : [];
         this.resolvedAppearance = resolveAppearance(options.appearance);
-        this.vaultId = `vault-${crypto.randomUUID()}`;
-        this.tokenizerName = `__oz_tok_${this.vaultId}`;
+        this.vaultId = `vault-${uuid()}`;
+        this._maxTokenizeCalls = (_b = options.maxTokenizeCalls) !== null && _b !== void 0 ? _b : 3;
         this.boundHandleMessage = this.handleMessage.bind(this);
         window.addEventListener('message', this.boundHandleMessage);
+        this.boundHandleVisibility = this.handleVisibilityChange.bind(this);
+        document.addEventListener('visibilitychange', this.boundHandleVisibility);
         this.mountTokenizerFrame();
         if (options.onLoadError) {
-            const timeout = (_b = options.loadTimeoutMs) !== null && _b !== void 0 ? _b : 10000;
+            const timeout = (_c = options.loadTimeoutMs) !== null && _c !== void 0 ? _c : 10000;
             this.loadErrorTimeoutId = setTimeout(() => {
                 this.loadErrorTimeoutId = null;
                 if (!this._destroyed && !this.tokenizerReady) {
@@ -732,15 +904,113 @@ class OzVault {
                 }
             }, timeout);
         }
+        this._onWaxRefresh = options.onWaxRefresh;
+        this._onReady = options.onReady;
+    }
+    /**
+     * Creates and returns a ready `OzVault` instance.
+     *
+     * Internally this:
+     * 1. Generates a `tokenizationSessionId` (UUID).
+     * 2. Starts loading the hidden tokenizer iframe immediately.
+     * 3. Calls `options.fetchWaxKey(tokenizationSessionId)` concurrently — your
+     *    backend mints a session-bound wax key from the vault and returns it.
+     * 4. Resolves with the vault instance once the wax key is stored. The iframe
+     *    has been loading the whole time, so `isReady` may already be true or
+     *    will fire shortly after.
+     *
+     * The returned vault is ready to create elements immediately. `createToken()`
+     * additionally requires `vault.isReady` (tokenizer iframe loaded).
+     *
+     * @throws {OzError} if `fetchWaxKey` throws, returns a non-string value, or returns an empty/whitespace-only string.
+     */
+    static async create(options, signal) {
+        if (!options.pubKey || !options.pubKey.trim()) {
+            throw new OzError('pubKey is required in options. Obtain your public key from the Ozura admin.');
+        }
+        if (typeof options.fetchWaxKey !== 'function') {
+            throw new OzError('fetchWaxKey must be a function. See OzVault.create() docs for the expected signature.');
+        }
+        const tokenizationSessionId = uuid();
+        // Construct the vault immediately — this mounts the tokenizer iframe so it
+        // starts loading while fetchWaxKey is in flight. The waxKey field starts
+        // empty and is set below before create() returns.
+        const vault = new OzVault(options, '', tokenizationSessionId);
+        // If the caller provides an AbortSignal (e.g. React useEffect cleanup),
+        // destroy the vault immediately on abort so the tokenizer iframe and message
+        // listener are removed synchronously rather than waiting for fetchWaxKey to
+        // settle. This eliminates the brief double-iframe window in React StrictMode.
+        const onAbort = () => vault.destroy();
+        signal === null || signal === void 0 ? void 0 : signal.addEventListener('abort', onAbort, { once: true });
+        let waxKey;
+        try {
+            waxKey = await options.fetchWaxKey(tokenizationSessionId);
+        }
+        catch (err) {
+            signal === null || signal === void 0 ? void 0 : signal.removeEventListener('abort', onAbort);
+            vault.destroy();
+            if (signal === null || signal === void 0 ? void 0 : signal.aborted)
+                throw new OzError('OzVault.create() was cancelled.');
+            // Preserve errorCode/retryable from OzError (e.g. timeout/network from createFetchWaxKey)
+            // so callers can distinguish transient failures from config errors.
+            const originalCode = err instanceof OzError ? err.errorCode : undefined;
+            const msg = err instanceof Error ? err.message : 'Unknown error';
+            throw new OzError(`fetchWaxKey threw an error: ${msg}`, undefined, originalCode);
+        }
+        signal === null || signal === void 0 ? void 0 : signal.removeEventListener('abort', onAbort);
+        if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
+            vault.destroy();
+            throw new OzError('OzVault.create() was cancelled.');
+        }
+        if (typeof waxKey !== 'string' || !waxKey.trim()) {
+            vault.destroy();
+            throw new OzError('fetchWaxKey must return a non-empty wax key string. Check your mint endpoint.');
+        }
+        // Static methods can access private fields of instances of the same class.
+        vault.waxKey = waxKey;
+        vault._storedFetchWaxKey = options.fetchWaxKey;
+        // If the tokenizer iframe fired OZ_FRAME_READY before fetchWaxKey resolved,
+        // the OZ_INIT sent at that point had an empty waxKey. Send a follow-up now
+        // so the tokenizer has the key stored before any createToken() call.
+        if (vault.tokenizerReady) {
+            vault.sendToTokenizer({ type: 'OZ_INIT', frameId: '__tokenizer__', waxKey });
+        }
+        return vault;
     }
     /**
      * True once the hidden tokenizer iframe has loaded and signalled ready.
      * Use this to gate the pay button when building custom UIs without React.
      * React consumers should use the `ready` value returned by `useOzElements()`.
+     *
+     * Once `true`, remains `true` for the lifetime of this vault instance.
+     * It only reverts to `false` after `vault.destroy()` is called, at which
+     * point the vault is unusable and a new instance must be created.
+     *
+     * @remarks
+     * This tracks **tokenizer readiness only** — it says nothing about whether
+     * the individual element iframes (card number, CVV, etc.) have loaded.
+     * A vault can be `isReady === true` while elements are still mounting.
+     * To gate a submit button correctly in vanilla JS, wait for every element's
+     * `'ready'` event in addition to this flag. In React, use the `ready` value
+     * from `useOzElements()` instead, which combines both checks automatically.
      */
     get isReady() {
         return this.tokenizerReady;
     }
+    /**
+     * Number of successful tokenize calls made against the current wax key.
+     *
+     * Resets to `0` each time the wax key is refreshed (proactively or reactively).
+     * Useful in vanilla JS integrations to display "attempts remaining" UI.
+     * In React, use `tokenizeCount` from `useOzElements()` instead.
+     *
+     * @example
+     * const remaining = 3 - vault.tokenizeCount;
+     * payButton.textContent = remaining > 0 ? `Pay (${remaining} attempts left)` : 'Pay';
+     */
+    get tokenizeCount() {
+        return this._tokenizeSuccessCount;
+    }
     /**
      * Creates a new OzElement of the given type. Call `.mount(selector)` on the
      * returned element to attach it to the DOM.
@@ -773,7 +1043,10 @@ class OzVault {
     }
     createElementInto(typeMap, type, options) {
         if (this._destroyed) {
-            throw new OzError('Cannot create elements on a destroyed vault. Create a new OzVault instance.');
+            throw new OzError('Cannot create elements on a destroyed vault. Call await OzVault.create() to get a new instance.');
+        }
+        if (this._tokenizing) {
+            throw new OzError('Cannot create or replace elements while a tokenization is in progress. Wait for the active createToken() / createBankToken() call to settle first.');
         }
         const existing = typeMap.get(type);
         if (existing) {
@@ -805,7 +1078,7 @@ class OzVault {
     async createBankToken(options) {
         var _a, _b;
         if (this._destroyed) {
-            throw new OzError('Cannot tokenize on a destroyed vault. Create a new OzVault instance.');
+            throw new OzError('Cannot tokenize on a destroyed vault. Call await OzVault.create() to get a new instance.');
         }
         if (!this.tokenizerReady) {
             throw new OzError('Vault not ready. Ensure the page is fully loaded before calling createBankToken.');
@@ -822,10 +1095,10 @@ class OzVault {
             throw new OzError('lastName is required for bank account tokenization.');
         }
         if (options.firstName.trim().length > 50) {
-            throw new OzError('firstName must be 50 characters or fewer');
+            throw new OzError('firstName must be 50 characters or fewer.');
         }
         if (options.lastName.trim().length > 50) {
-            throw new OzError('lastName must be 50 characters or fewer');
+            throw new OzError('lastName must be 50 characters or fewer.');
         }
         const accountEl = this.bankElementsByType.get('accountNumber');
         const routingEl = this.bankElementsByType.get('routingNumber');
@@ -842,30 +1115,47 @@ class OzVault {
         }
         const readyBankElements = [accountEl, routingEl];
         this._tokenizing = 'bank';
-        const requestId = `req-${Math.random().toString(36).slice(2, 10)}`;
+        const requestId = `req-${uuid()}`;
         return new Promise((resolve, reject) => {
             const cleanup = () => { this._tokenizing = null; };
             this.bankTokenizeResolvers.set(requestId, {
                 resolve: (v) => { cleanup(); resolve(v); },
                 reject: (e) => { cleanup(); reject(e); },
-            });
-            this.sendToTokenizer({
-                type: 'OZ_BANK_TOKENIZE',
-                requestId,
-                apiKey: this.apiKey,
-                pubKey: this.pubKey,
                 firstName: options.firstName.trim(),
                 lastName: options.lastName.trim(),
+                readyElements: readyBankElements,
                 fieldCount: readyBankElements.length,
             });
-            readyBankElements.forEach(el => el.beginCollect(requestId));
-            setTimeout(() => {
-                if (this.bankTokenizeResolvers.has(requestId)) {
-                    this.bankTokenizeResolvers.delete(requestId);
-                    cleanup();
-                    reject(new OzError('Bank tokenization timed out after 30 seconds', undefined, 'timeout'));
-                }
-            }, 30000);
+            try {
+                const bankChannels = readyBankElements.map(() => new MessageChannel());
+                this.sendToTokenizer({
+                    type: 'OZ_BANK_TOKENIZE',
+                    requestId,
+                    waxKey: this.waxKey,
+                    tokenizationSessionId: this.tokenizationSessionId,
+                    pubKey: this.pubKey,
+                    firstName: options.firstName.trim(),
+                    lastName: options.lastName.trim(),
+                    fieldCount: readyBankElements.length,
+                }, bankChannels.map(ch => ch.port1));
+                readyBankElements.forEach((el, i) => el.beginCollect(requestId, bankChannels[i].port2));
+                const bankTimeoutId = setTimeout(() => {
+                    if (this.bankTokenizeResolvers.has(requestId)) {
+                        this.bankTokenizeResolvers.delete(requestId);
+                        this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId });
+                        cleanup();
+                        reject(new OzError('Bank tokenization timed out after 30 seconds', undefined, 'timeout'));
+                    }
+                }, 30000);
+                const bankPendingEntry = this.bankTokenizeResolvers.get(requestId);
+                if (bankPendingEntry)
+                    bankPendingEntry.timeoutId = bankTimeoutId;
+            }
+            catch (err) {
+                this.bankTokenizeResolvers.delete(requestId);
+                cleanup();
+                reject(err instanceof OzError ? err : new OzError('Bank tokenization failed to start'));
+            }
         });
     }
     /**
@@ -877,7 +1167,7 @@ class OzVault {
     async createToken(options = {}) {
         var _a, _b;
         if (this._destroyed) {
-            throw new OzError('Cannot tokenize on a destroyed vault. Create a new OzVault instance.');
+            throw new OzError('Cannot tokenize on a destroyed vault. Call await OzVault.create() to get a new instance.');
         }
         if (!this.tokenizerReady) {
             throw new OzError('Vault not ready. Ensure the page is fully loaded before calling createToken.');
@@ -887,29 +1177,33 @@ class OzVault {
                 ? 'A bank tokenization is already in progress. Wait for it to complete before calling createToken().'
                 : 'A card tokenization is already in progress. Wait for it to complete before calling createToken() again.');
         }
-        this._tokenizing = 'card';
-        const requestId = `req-${Math.random().toString(36).slice(2, 10)}`;
-        // Only include card elements whose iframes have actually loaded — an element
-        // created but never mounted will never send OZ_FIELD_VALUE, which would
-        // cause the tokenizer to hang waiting for a value that never arrives.
-        // Explicitly exclude bank elements (accountNumber/routingNumber) that share
-        // the same this.elements map; including them would inflate fieldCount and
-        // allow the accountNumber iframe's last4 to overwrite cardMeta.last4.
-        const cardElements = new Set(this.elementsByType.values());
-        const readyElements = [...this.elements.values()].filter(el => el.isReady && cardElements.has(el));
-        if (readyElements.length === 0) {
-            this._tokenizing = null;
-            throw new OzError('No elements are mounted and ready. Mount at least one element before calling createToken.');
+        // All synchronous validation runs before _tokenizing is set so these throws
+        // need no manual cleanup — _tokenizing is still null when they fire.
+        // Collect all card elements that have been created (mounted or not) so we
+        // can require every created field to be ready before proceeding. An element
+        // that was created but whose iframe hasn't loaded yet will never send
+        // OZ_FIELD_VALUE — tokenizing without it would silently submit an empty or
+        // incomplete card and produce an opaque vault rejection.
+        // Bank elements (accountNumber/routingNumber) share this.elements but live
+        // in elementsByType under bank-only keys, so they are excluded by the Set.
+        const cardElements = [...this.elementsByType.values()];
+        if (cardElements.length === 0) {
+            throw new OzError('No card elements have been created. Call vault.createElement() for each field before calling createToken.');
+        }
+        const notReady = cardElements.filter(el => !el.isReady);
+        if (notReady.length > 0) {
+            throw new OzError(`Not all elements are ready. Wait for all fields to finish loading before calling createToken. ` +
+                `Not yet ready: ${notReady.map(el => el.type).join(', ')}.`);
         }
+        const readyElements = cardElements;
         // Validate billing details if provided and extract firstName/lastName for the vault payload.
         // billing.firstName/lastName take precedence over the deprecated top-level params.
         let normalizedBilling;
-        let firstName = (_a = options.firstName) !== null && _a !== void 0 ? _a : '';
-        let lastName = (_b = options.lastName) !== null && _b !== void 0 ? _b : '';
+        let firstName = ((_a = options.firstName) !== null && _a !== void 0 ? _a : '').trim();
+        let lastName = ((_b = options.lastName) !== null && _b !== void 0 ? _b : '').trim();
         if (options.billing) {
             const result = validateBilling(options.billing);
             if (!result.valid) {
-                this._tokenizing = null;
                 throw new OzError(`Invalid billing details: ${result.errors.join('; ')}`);
             }
             normalizedBilling = result.normalized;
@@ -918,40 +1212,57 @@ class OzVault {
         }
         else {
             if (firstName.length > 50) {
-                this._tokenizing = null;
-                throw new OzError('firstName must be 50 characters or fewer');
+                throw new OzError('firstName must be 50 characters or fewer.');
             }
             if (lastName.length > 50) {
-                this._tokenizing = null;
-                throw new OzError('lastName must be 50 characters or fewer');
+                throw new OzError('lastName must be 50 characters or fewer.');
             }
         }
+        this._tokenizing = 'card';
+        const requestId = `req-${uuid()}`;
         return new Promise((resolve, reject) => {
             const cleanup = () => { this._tokenizing = null; };
             this.tokenizeResolvers.set(requestId, {
                 resolve: (v) => { cleanup(); resolve(v); },
                 reject: (e) => { cleanup(); reject(e); },
                 billing: normalizedBilling,
-            });
-            // Tell tokenizer frame to expect N field values, then tokenize
-            this.sendToTokenizer({
-                type: 'OZ_TOKENIZE',
-                requestId,
-                apiKey: this.apiKey,
-                pubKey: this.pubKey,
                 firstName,
                 lastName,
+                readyElements,
                 fieldCount: readyElements.length,
             });
-            // Tell each ready element frame to send its raw value to the tokenizer
-            readyElements.forEach(el => el.beginCollect(requestId));
-            setTimeout(() => {
-                if (this.tokenizeResolvers.has(requestId)) {
-                    this.tokenizeResolvers.delete(requestId);
-                    cleanup();
-                    reject(new OzError('Tokenization timed out after 30 seconds', undefined, 'timeout'));
-                }
-            }, 30000);
+            try {
+                // Tell tokenizer frame to expect N field values, then tokenize
+                const cardChannels = readyElements.map(() => new MessageChannel());
+                this.sendToTokenizer({
+                    type: 'OZ_TOKENIZE',
+                    requestId,
+                    waxKey: this.waxKey,
+                    tokenizationSessionId: this.tokenizationSessionId,
+                    pubKey: this.pubKey,
+                    firstName,
+                    lastName,
+                    fieldCount: readyElements.length,
+                }, cardChannels.map(ch => ch.port1));
+                // Tell each ready element frame to send its raw value to the tokenizer
+                readyElements.forEach((el, i) => el.beginCollect(requestId, cardChannels[i].port2));
+                const cardTimeoutId = setTimeout(() => {
+                    if (this.tokenizeResolvers.has(requestId)) {
+                        this.tokenizeResolvers.delete(requestId);
+                        this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId });
+                        cleanup();
+                        reject(new OzError('Tokenization timed out after 30 seconds', undefined, 'timeout'));
+                    }
+                }, 30000);
+                const cardPendingEntry = this.tokenizeResolvers.get(requestId);
+                if (cardPendingEntry)
+                    cardPendingEntry.timeoutId = cardTimeoutId;
+            }
+            catch (err) {
+                this.tokenizeResolvers.delete(requestId);
+                cleanup();
+                reject(err instanceof OzError ? err : new OzError('Tokenization failed to start'));
+            }
         });
     }
     /**
@@ -965,6 +1276,7 @@ class OzVault {
             return;
         this._destroyed = true;
         window.removeEventListener('message', this.boundHandleMessage);
+        document.removeEventListener('visibilitychange', this.boundHandleVisibility);
         if (this._pendingMount) {
             document.removeEventListener('DOMContentLoaded', this._pendingMount);
             this._pendingMount = null;
@@ -975,11 +1287,17 @@ class OzVault {
         }
         // Reject any pending tokenize promises so callers aren't left hanging
         this._tokenizing = null;
-        this.tokenizeResolvers.forEach(({ reject }) => {
+        this.tokenizeResolvers.forEach(({ reject, timeoutId }, requestId) => {
+            if (timeoutId != null)
+                clearTimeout(timeoutId);
+            this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId });
             reject(new OzError('Vault destroyed before tokenization completed.'));
         });
         this.tokenizeResolvers.clear();
-        this.bankTokenizeResolvers.forEach(({ reject }) => {
+        this.bankTokenizeResolvers.forEach(({ reject, timeoutId }, requestId) => {
+            if (timeoutId != null)
+                clearTimeout(timeoutId);
+            this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId });
             reject(new OzError('Vault destroyed before bank tokenization completed.'));
         });
         this.bankTokenizeResolvers.clear();
@@ -988,17 +1306,49 @@ class OzVault {
         this.elementsByType.clear();
         this.bankElementsByType.clear();
         this.completionState.clear();
+        this._tokenizeSuccessCount = 0;
         (_a = this.tokenizerFrame) === null || _a === void 0 ? void 0 : _a.remove();
         this.tokenizerFrame = null;
         this.tokenizerWindow = null;
         this.tokenizerReady = false;
     }
     // ─── Private ─────────────────────────────────────────────────────────────
+    /**
+     * Proactively re-mints the wax key when the page becomes visible again after
+     * a long idle period. Wax keys have a fixed TTL (~30 minutes); a user who
+     * leaves the tab in the background and returns could have an expired key.
+     * Rather than waiting for a failed tokenization to trigger the reactive
+     * refresh path, this pre-empts the failure when the vault is idle.
+     *
+     * Threshold: 20 minutes hidden. Chosen to be comfortably inside the ~30m TTL
+     * while avoiding spurious refreshes for brief tab-switches.
+     */
+    handleVisibilityChange() {
+        if (this._destroyed)
+            return;
+        const REFRESH_THRESHOLD_MS = 20 * 60 * 1000; // 20 minutes
+        if (document.hidden) {
+            this._hiddenAt = Date.now();
+        }
+        else {
+            if (this._hiddenAt !== null &&
+                Date.now() - this._hiddenAt >= REFRESH_THRESHOLD_MS &&
+                this._storedFetchWaxKey &&
+                !this._tokenizing &&
+                !this._waxRefreshing) {
+                this.refreshWaxKey().catch((err) => {
+                    // Proactive refresh failure is non-fatal — the reactive path on the
+                    // next createToken() call will handle it, including the auth retry.
+                    console.warn('[OzVault] Proactive wax key refresh failed:', err instanceof Error ? err.message : err);
+                });
+            }
+            this._hiddenAt = null;
+        }
+    }
     mountTokenizerFrame() {
         const mount = () => {
             this._pendingMount = null;
             const iframe = document.createElement('iframe');
-            iframe.name = this.tokenizerName;
             iframe.style.cssText = 'position:absolute;top:-9999px;left:-9999px;width:1px;height:1px;';
             iframe.setAttribute('aria-hidden', 'true');
             iframe.tabIndex = -1;
@@ -1017,6 +1367,8 @@ class OzVault {
     }
     handleMessage(event) {
         var _a;
+        if (this._destroyed)
+            return;
         // Only accept messages from our frame origin (defense in depth; prevents
         // arbitrary pages from injecting OZ_TOKEN_RESULT etc. with a guessed vaultId).
         if (event.origin !== this.frameOrigin)
@@ -1034,14 +1386,17 @@ class OzVault {
         if (frameId) {
             const el = this.elements.get(frameId);
             if (el) {
+                // Reset stale completion state when an element iframe re-loads (e.g. after
+                // unmount() + mount() in a SPA). Without this, wasComplete stays true from
+                // the previous session and justCompleted never fires, breaking auto-advance.
+                if (msg.type === 'OZ_FRAME_READY') {
+                    this.completionState.set(frameId, false);
+                }
                 // Intercept OZ_CHANGE before forwarding — handle auto-advance and CVV sync
                 if (msg.type === 'OZ_CHANGE') {
                     this.handleElementChange(msg, el);
                 }
                 el.handleMessage(msg);
-                if (msg.type === 'OZ_FRAME_READY' && this.tokenizerReady) {
-                    el.setTokenizerName(this.tokenizerName);
-                }
             }
         }
     }
@@ -1055,7 +1410,7 @@ class OzVault {
         const complete = msg.complete;
         const valid = msg.valid;
         const wasComplete = (_a = this.completionState.get(el.frameId)) !== null && _a !== void 0 ? _a : false;
-        this.completionState.set(el.frameId, complete);
+        this.completionState.set(el.frameId, complete && valid);
         // Require valid too — avoids advancing at 13 digits for unknown-brand cards
         // where isComplete() fires before the user has finished typing.
         const justCompleted = complete && valid && !wasComplete;
@@ -1078,7 +1433,7 @@ class OzVault {
         }
     }
     handleTokenizerMessage(msg) {
-        var _a, _b;
+        var _a, _b, _c;
         switch (msg.type) {
             case 'OZ_FRAME_READY':
                 this.tokenizerReady = true;
@@ -1087,94 +1442,440 @@ class OzVault {
                     this.loadErrorTimeoutId = null;
                 }
                 this.tokenizerWindow = (_b = (_a = this.tokenizerFrame) === null || _a === void 0 ? void 0 : _a.contentWindow) !== null && _b !== void 0 ? _b : null;
-                this.sendToTokenizer({ type: 'OZ_INIT', frameId: '__tokenizer__' });
-                this.elements.forEach(el => el.setTokenizerName(this.tokenizerName));
+                // Deliver the wax key via OZ_INIT so the tokenizer stores it internally.
+                // If waxKey is still empty (fetchWaxKey hasn't resolved yet), it will be
+                // sent again from create() once the key is available.
+                this.sendToTokenizer(Object.assign({ type: 'OZ_INIT', frameId: '__tokenizer__' }, (this.waxKey ? { waxKey: this.waxKey } : {})));
+                (_c = this._onReady) === null || _c === void 0 ? void 0 : _c.call(this);
                 break;
             case 'OZ_TOKEN_RESULT': {
+                if (typeof msg.requestId !== 'string' || !msg.requestId) {
+                    console.error('[OzVault] OZ_TOKEN_RESULT missing requestId — discarding message.');
+                    break;
+                }
                 const pending = this.tokenizeResolvers.get(msg.requestId);
                 if (pending) {
                     this.tokenizeResolvers.delete(msg.requestId);
-                    const card = msg.card;
-                    pending.resolve(Object.assign(Object.assign({ token: msg.token, cvcSession: msg.cvcSession }, (card ? { card } : {})), (pending.billing ? { billing: pending.billing } : {})));
+                    if (pending.timeoutId != null)
+                        clearTimeout(pending.timeoutId);
+                    const token = msg.token;
+                    if (typeof token !== 'string' || !token) {
+                        pending.reject(new OzError('Vault returned a token result with a missing or empty token — possible vault API change.', undefined, 'server'));
+                        break;
+                    }
+                    const card = isCardMetadata(msg.card) ? msg.card : undefined;
+                    pending.resolve(Object.assign(Object.assign({ token, cvcSession: typeof msg.cvcSession === 'string' && msg.cvcSession ? msg.cvcSession : undefined }, (card ? { card } : {})), (pending.billing ? { billing: pending.billing } : {})));
+                    // Increment the per-key success counter and proactively refresh once
+                    // the budget is exhausted so the next createToken() call uses a fresh
+                    // key without waiting for a vault rejection.
+                    this._tokenizeSuccessCount++;
+                    if (this._tokenizeSuccessCount >= this._maxTokenizeCalls) {
+                        this.refreshWaxKey().catch((err) => {
+                            console.warn('[OzVault] Post-budget wax key refresh failed:', err instanceof Error ? err.message : err);
+                        });
+                    }
                 }
                 break;
             }
             case 'OZ_TOKEN_ERROR': {
+                if (typeof msg.requestId !== 'string' || !msg.requestId) {
+                    console.error('[OzVault] OZ_TOKEN_ERROR missing requestId — discarding message.');
+                    break;
+                }
+                const raw = typeof msg.error === 'string' ? msg.error : '';
+                const errorCode = isOzErrorCode(msg.errorCode) ? msg.errorCode : 'unknown';
                 const pending = this.tokenizeResolvers.get(msg.requestId);
                 if (pending) {
                     this.tokenizeResolvers.delete(msg.requestId);
-                    const raw = msg.error;
-                    const errorCode = (msg.errorCode || 'unknown');
+                    if (pending.timeoutId != null)
+                        clearTimeout(pending.timeoutId);
+                    // Auto-refresh: if the wax key expired or was consumed and we haven't
+                    // already retried for this request, transparently re-mint and retry.
+                    if (this.isRefreshableAuthError(errorCode, raw) && !pending.retried && this._storedFetchWaxKey) {
+                        this.refreshWaxKey().then(() => {
+                            if (this._destroyed) {
+                                pending.reject(new OzError('Vault destroyed during wax key refresh.'));
+                                return;
+                            }
+                            const newRequestId = `req-${uuid()}`;
+                            // _tokenizing is still 'card' (cleanup() hasn't been called yet)
+                            this.tokenizeResolvers.set(newRequestId, Object.assign(Object.assign({}, pending), { retried: true }));
+                            try {
+                                const retryCardChannels = pending.readyElements.map(() => new MessageChannel());
+                                this.sendToTokenizer({
+                                    type: 'OZ_TOKENIZE',
+                                    requestId: newRequestId,
+                                    waxKey: this.waxKey,
+                                    tokenizationSessionId: this.tokenizationSessionId,
+                                    pubKey: this.pubKey,
+                                    firstName: pending.firstName,
+                                    lastName: pending.lastName,
+                                    fieldCount: pending.fieldCount,
+                                }, retryCardChannels.map(ch => ch.port1));
+                                pending.readyElements.forEach((el, i) => el.beginCollect(newRequestId, retryCardChannels[i].port2));
+                                const retryCardTimeoutId = setTimeout(() => {
+                                    if (this.tokenizeResolvers.has(newRequestId)) {
+                                        this.tokenizeResolvers.delete(newRequestId);
+                                        this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId: newRequestId });
+                                        pending.reject(new OzError('Tokenization timed out after wax key refresh.', undefined, 'timeout'));
+                                    }
+                                }, 30000);
+                                const retryCardEntry = this.tokenizeResolvers.get(newRequestId);
+                                if (retryCardEntry)
+                                    retryCardEntry.timeoutId = retryCardTimeoutId;
+                            }
+                            catch (setupErr) {
+                                this.tokenizeResolvers.delete(newRequestId);
+                                pending.reject(setupErr instanceof OzError ? setupErr : new OzError('Retry tokenization failed to start'));
+                            }
+                        }).catch((refreshErr) => {
+                            const msg = refreshErr instanceof Error ? refreshErr.message : 'Wax key refresh failed';
+                            pending.reject(new OzError(msg, undefined, 'auth'));
+                        });
+                        break;
+                    }
                     pending.reject(new OzError(normalizeVaultError(raw), raw, errorCode));
                 }
                 // Also check bank resolvers — both card and bank errors use OZ_TOKEN_ERROR
                 const bankPending = this.bankTokenizeResolvers.get(msg.requestId);
                 if (bankPending) {
                     this.bankTokenizeResolvers.delete(msg.requestId);
-                    const raw = msg.error;
-                    const errorCode = (msg.errorCode || 'unknown');
+                    if (bankPending.timeoutId != null)
+                        clearTimeout(bankPending.timeoutId);
+                    if (this.isRefreshableAuthError(errorCode, raw) && !bankPending.retried && this._storedFetchWaxKey) {
+                        this.refreshWaxKey().then(() => {
+                            if (this._destroyed) {
+                                bankPending.reject(new OzError('Vault destroyed during wax key refresh.'));
+                                return;
+                            }
+                            const newRequestId = `req-${uuid()}`;
+                            this.bankTokenizeResolvers.set(newRequestId, Object.assign(Object.assign({}, bankPending), { retried: true }));
+                            try {
+                                const retryBankChannels = bankPending.readyElements.map(() => new MessageChannel());
+                                this.sendToTokenizer({
+                                    type: 'OZ_BANK_TOKENIZE',
+                                    requestId: newRequestId,
+                                    waxKey: this.waxKey,
+                                    tokenizationSessionId: this.tokenizationSessionId,
+                                    pubKey: this.pubKey,
+                                    firstName: bankPending.firstName,
+                                    lastName: bankPending.lastName,
+                                    fieldCount: bankPending.fieldCount,
+                                }, retryBankChannels.map(ch => ch.port1));
+                                bankPending.readyElements.forEach((el, i) => el.beginCollect(newRequestId, retryBankChannels[i].port2));
+                                const retryBankTimeoutId = setTimeout(() => {
+                                    if (this.bankTokenizeResolvers.has(newRequestId)) {
+                                        this.bankTokenizeResolvers.delete(newRequestId);
+                                        this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId: newRequestId });
+                                        bankPending.reject(new OzError('Bank tokenization timed out after wax key refresh.', undefined, 'timeout'));
+                                    }
+                                }, 30000);
+                                const retryBankEntry = this.bankTokenizeResolvers.get(newRequestId);
+                                if (retryBankEntry)
+                                    retryBankEntry.timeoutId = retryBankTimeoutId;
+                            }
+                            catch (setupErr) {
+                                this.bankTokenizeResolvers.delete(newRequestId);
+                                bankPending.reject(setupErr instanceof OzError ? setupErr : new OzError('Retry bank tokenization failed to start'));
+                            }
+                        }).catch((refreshErr) => {
+                            const msg = refreshErr instanceof Error ? refreshErr.message : 'Wax key refresh failed';
+                            bankPending.reject(new OzError(msg, undefined, 'auth'));
+                        });
+                        break;
+                    }
                     bankPending.reject(new OzError(normalizeBankVaultError(raw), raw, errorCode));
                 }
                 break;
             }
             case 'OZ_BANK_TOKEN_RESULT': {
+                if (typeof msg.requestId !== 'string' || !msg.requestId) {
+                    console.error('[OzVault] OZ_BANK_TOKEN_RESULT missing requestId — discarding message.');
+                    break;
+                }
                 const pending = this.bankTokenizeResolvers.get(msg.requestId);
                 if (pending) {
                     this.bankTokenizeResolvers.delete(msg.requestId);
-                    const bank = msg.bank;
-                    pending.resolve(Object.assign({ token: msg.token }, (bank ? { bank } : {})));
+                    if (pending.timeoutId != null)
+                        clearTimeout(pending.timeoutId);
+                    const token = msg.token;
+                    if (typeof token !== 'string' || !token) {
+                        pending.reject(new OzError('Vault returned a bank token result with a missing or empty token — possible vault API change.', undefined, 'server'));
+                        break;
+                    }
+                    const bank = isBankAccountMetadata(msg.bank) ? msg.bank : undefined;
+                    pending.resolve(Object.assign({ token }, (bank ? { bank } : {})));
+                    // Same proactive refresh logic as card tokenization.
+                    this._tokenizeSuccessCount++;
+                    if (this._tokenizeSuccessCount >= this._maxTokenizeCalls) {
+                        this.refreshWaxKey().catch((err) => {
+                            console.warn('[OzVault] Post-budget wax key refresh failed:', err instanceof Error ? err.message : err);
+                        });
+                    }
                 }
                 break;
             }
         }
     }
-    sendToTokenizer(data) {
+    /**
+     * Returns true when an OZ_TOKEN_ERROR should trigger a wax key refresh.
+     *
+     * Primary path: vault returns 401/403 → errorCode 'auth'.
+     * Defensive path: vault returns 400 → errorCode 'validation', but the raw
+     * message contains wax-key-specific language (consumed, expired, invalid key,
+     * etc.). This avoids a hard dependency on the vault returning a unified HTTP
+     * status for consumed-key vs expired-key failures — both should refresh.
+     *
+     * Deliberately excludes 'network', 'timeout', and 'server' codes (transient
+     * errors are already retried in fetchWithRetry) and 'unknown' (too broad).
+     */
+    isRefreshableAuthError(errorCode, raw) {
+        if (errorCode === 'auth')
+            return true;
+        if (errorCode === 'validation') {
+            const msg = raw.toLowerCase();
+            // Only treat validation errors as wax-related if the message explicitly
+            // names the wax/tokenization session mechanism. A bare "session" match
+            // was too broad — any message mentioning "session" (e.g. a merchant
+            // session field error) would trigger a spurious re-mint.
+            return (msg.includes('wax') ||
+                msg.includes('expired') ||
+                msg.includes('consumed') ||
+                msg.includes('invalid key') ||
+                msg.includes('key not found') ||
+                msg.includes('tokenization session'));
+        }
+        return false;
+    }
+    /**
+     * Re-mints the wax key using the stored fetchWaxKey callback and updates
+     * the tokenizer with the new key. Used for transparent auto-refresh when
+     * the vault returns an auth error on tokenization.
+     *
+     * Only one refresh runs at a time — concurrent retries share the same promise.
+     */
+    refreshWaxKey() {
+        var _a;
+        if (this._waxRefreshing)
+            return this._waxRefreshing;
+        if (!this._storedFetchWaxKey) {
+            return Promise.reject(new OzError('Wax key expired and no fetchWaxKey callback is available for auto-refresh. Call OzVault.create() again to obtain a new vault instance.', undefined, 'auth'));
+        }
+        const newSessionId = uuid();
+        (_a = this._onWaxRefresh) === null || _a === void 0 ? void 0 : _a.call(this);
+        this._waxRefreshing = this._storedFetchWaxKey(newSessionId)
+            .then(newWaxKey => {
+            if (typeof newWaxKey !== 'string' || !newWaxKey.trim()) {
+                throw new OzError('fetchWaxKey returned an empty string during auto-refresh.', undefined, 'auth');
+            }
+            if (!this._destroyed) {
+                this.waxKey = newWaxKey;
+                this.tokenizationSessionId = newSessionId;
+                this._tokenizeSuccessCount = 0;
+            }
+            if (!this._destroyed && this.tokenizerReady) {
+                this.sendToTokenizer({ type: 'OZ_INIT', frameId: '__tokenizer__', waxKey: newWaxKey });
+            }
+        })
+            .finally(() => {
+            this._waxRefreshing = null;
+        });
+        return this._waxRefreshing;
+    }
+    sendToTokenizer(data, transfer) {
         var _a;
         const msg = Object.assign({ __oz: true, vaultId: this.vaultId }, data);
-        (_a = this.tokenizerWindow) === null || _a === void 0 ? void 0 : _a.postMessage(msg, this.frameOrigin);
+        (_a = this.tokenizerWindow) === null || _a === void 0 ? void 0 : _a.postMessage(msg, this.frameOrigin, transfer !== null && transfer !== void 0 ? transfer : []);
     }
 }
 
+/**
+ * Creates a ready-to-use `fetchWaxKey` callback for `OzVault.create()` and `<OzElements>`.
+ *
+ * Calls your backend mint endpoint with `{ sessionId }` and returns the wax key string.
+ * Throws on non-OK responses or a missing `waxKey` field so the vault can surface the
+ * error through its normal error path.
+ *
+ * Each call enforces a 10-second per-attempt timeout. On a pure network-level
+ * failure (connection refused, DNS failure, etc.) the call is retried once after
+ * 750ms before throwing. HTTP errors (4xx/5xx) are never retried — they indicate
+ * an endpoint misconfiguration or an invalid key, not a transient failure.
+ *
+ * The mint endpoint is typically the one-line `createMintWaxHandler` / `createMintWaxMiddleware`
+ * from `@ozura/elements/server`.
+ *
+ * @param mintUrl - Absolute or relative URL of your wax-key mint endpoint, e.g. `'/api/mint-wax'`.
+ *
+ * @example
+ * // Vanilla JS
+ * const vault = await OzVault.create({
+ *   pubKey: 'pk_live_...',
+ *   fetchWaxKey: createFetchWaxKey('/api/mint-wax'),
+ * });
+ *
+ * @example
+ * // React
+ * <OzElements pubKey="pk_live_..." fetchWaxKey={createFetchWaxKey('/api/mint-wax')}>
+ */
+function createFetchWaxKey(mintUrl) {
+    const TIMEOUT_MS = 10000;
+    // Each attempt gets its own AbortController so a timeout on attempt 1 does
+    // not bleed into the retry. Uses AbortController + setTimeout instead of
+    // AbortSignal.timeout() to support environments without that API.
+    const attemptFetch = (sessionId) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        return fetch(mintUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ sessionId }),
+            signal: controller.signal,
+        }).finally(() => clearTimeout(timer));
+    };
+    return async (sessionId) => {
+        let res;
+        try {
+            res = await attemptFetch(sessionId);
+        }
+        catch (firstErr) {
+            // Abort/timeout should not be retried — the server received nothing or
+            // we already waited the full timeout duration.
+            if (firstErr instanceof Error && (firstErr.name === 'AbortError' || firstErr.name === 'TimeoutError')) {
+                throw new OzError(`Wax key mint timed out after ${TIMEOUT_MS / 1000}s (${mintUrl})`, undefined, 'timeout');
+            }
+            // Pure network error (offline, DNS, connection refused) — retry once
+            // after a short pause in case of a transient blip.
+            await new Promise(resolve => setTimeout(resolve, 750));
+            try {
+                res = await attemptFetch(sessionId);
+            }
+            catch (retryErr) {
+                const msg = retryErr instanceof Error ? retryErr.message : 'Network error';
+                throw new OzError(`Could not reach wax key mint endpoint (${mintUrl}): ${msg}`, undefined, 'network');
+            }
+        }
+        const data = await res.json().catch(() => ({}));
+        if (!res.ok) {
+            throw new OzError(typeof data.error === 'string' && data.error
+                ? data.error
+                : `Wax key mint failed (HTTP ${res.status})`, undefined, res.status >= 500 ? 'server' : res.status === 401 || res.status === 403 ? 'auth' : 'validation');
+        }
+        if (typeof data.waxKey !== 'string' || !data.waxKey.trim()) {
+            throw new OzError('Mint endpoint response is missing waxKey. Check your /api/mint-wax implementation.', undefined, 'validation');
+        }
+        return data.waxKey;
+    };
+}
+
 const OzContext = createContext({
     vault: null,
+    initError: null,
     notifyReady: () => { },
     notifyUnmount: () => { },
     notifyMount: () => { },
+    notifyTokenize: () => { },
     mountedCount: 0,
     readyCount: 0,
+    tokenizeCount: 0,
 });
 /**
  * Creates and owns an OzVault instance for the lifetime of this component.
  * All `<OzCardNumber />`, `<OzExpiry />`, and `<OzCvv />` children must be
  * rendered inside this provider.
  */
-function OzElements({ apiKey, pubKey, frameBaseUrl, fonts, onLoadError, loadTimeoutMs, appearance, children }) {
+function OzElements({ fetchWaxKey, pubKey, frameBaseUrl, fonts, onLoadError, loadTimeoutMs, onWaxRefresh, onReady, appearance, maxTokenizeCalls, children }) {
     const [vault, setVault] = useState(null);
+    const [initError, setInitError] = useState(null);
     const [mountedCount, setMountedCount] = useState(0);
     const [readyCount, setReadyCount] = useState(0);
+    const [tokenizeCount, setTokenizeCount] = useState(0);
     const onLoadErrorRef = useRef(onLoadError);
     onLoadErrorRef.current = onLoadError;
+    const onWaxRefreshRef = useRef(onWaxRefresh);
+    onWaxRefreshRef.current = onWaxRefresh;
+    const onReadyRef = useRef(onReady);
+    onReadyRef.current = onReady;
+    // Keep a ref to fetchWaxKey so changes don't trigger vault recreation
+    const fetchWaxKeyRef = useRef(fetchWaxKey);
+    fetchWaxKeyRef.current = fetchWaxKey;
     const appearanceKey = useMemo(() => appearance ? JSON.stringify(appearance) : '', [appearance]);
     const fontsKey = useMemo(() => fonts ? JSON.stringify(fonts) : '', [fonts]);
     useEffect(() => {
+        let cancelled = false;
+        let createdVault = null;
         const parsedAppearance = appearanceKey ? JSON.parse(appearanceKey) : undefined;
         const parsedFonts = fontsKey ? JSON.parse(fontsKey) : undefined;
-        const v = new OzVault(apiKey, Object.assign(Object.assign(Object.assign(Object.assign({ pubKey }, (frameBaseUrl ? { frameBaseUrl } : {})), (parsedFonts ? { fonts: parsedFonts } : {})), (parsedAppearance ? { appearance: parsedAppearance } : {})), (onLoadErrorRef.current ? { onLoadError: () => { var _a; return (_a = onLoadErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onLoadErrorRef); }, loadTimeoutMs } : {})));
-        setVault(v);
-        setMountedCount(0);
-        setReadyCount(0);
+        // Guard: onLoadError must fire at most once per effect run. It can be
+        // triggered by two independent paths — the vault's iframe load timeout
+        // (inside OzVault constructor) and the .catch below when fetchWaxKey
+        // rejects after the timeout has already fired. Without this guard both
+        // paths would call the callback.
+        let loadErrorFired = false;
+        const fireLoadError = () => {
+            var _a;
+            if (loadErrorFired)
+                return;
+            loadErrorFired = true;
+            (_a = onLoadErrorRef.current) === null || _a === void 0 ? void 0 : _a.call(onLoadErrorRef);
+        };
+        // AbortController passed to create() so that if this effect's cleanup runs
+        // while fetchWaxKey is still in-flight (React StrictMode double-invoke or
+        // rapid prop churn), the tokenizer iframe and message listener are destroyed
+        // synchronously rather than waiting for the promise to settle. Without this,
+        // two hidden iframes and two window listeners briefly coexist.
+        const abortController = new AbortController();
+        OzVault.create(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ pubKey, fetchWaxKey: (sessionId) => fetchWaxKeyRef.current(sessionId) }, (frameBaseUrl ? { frameBaseUrl } : {})), (parsedFonts ? { fonts: parsedFonts } : {})), (parsedAppearance ? { appearance: parsedAppearance } : {})), (onLoadErrorRef.current ? { onLoadError: fireLoadError, loadTimeoutMs } : {})), { 
+            // Always install onWaxRefresh internally so we can reset tokenizeCount
+            // when any wax key refresh occurs (reactive TTL expiry, post-budget
+            // proactive, or visibility-change proactive). Without this the React
+            // counter accumulates across key refreshes and diverges from the vault's
+            // internal _tokenizeSuccessCount, which resets to 0 on every refresh.
+            onWaxRefresh: () => {
+                var _a;
+                setTokenizeCount(0);
+                (_a = onWaxRefreshRef.current) === null || _a === void 0 ? void 0 : _a.call(onWaxRefreshRef);
+            } }), (onReadyRef.current ? { onReady: () => { var _a; return (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef); } } : {})), (maxTokenizeCalls !== undefined ? { maxTokenizeCalls } : {})), abortController.signal).then(v => {
+            if (cancelled) {
+                v.destroy();
+                return;
+            }
+            createdVault = v;
+            setVault(v);
+            setInitError(null);
+            setMountedCount(0);
+            setReadyCount(0);
+            setTokenizeCount(0);
+        }).catch((err) => {
+            // fetchWaxKey threw, returned a non-string value, returned an empty string,
+            // or create() was cancelled via the AbortSignal — all are suppressed when
+            // cancelled is true (cleanup already ran).
+            if (cancelled)
+                return;
+            const error = err instanceof Error ? err : new OzError('OzVault.create() failed.');
+            setInitError(error);
+            if (onLoadErrorRef.current) {
+                fireLoadError();
+            }
+            else {
+                console.error('[OzElements] OzVault.create() failed. Provide an `onLoadError` prop to handle this gracefully.', err);
+            }
+        });
         return () => {
-            v.destroy();
+            cancelled = true;
+            abortController.abort(); // Destroys vault (and its iframe/listener) synchronously if create() is in-flight
+            createdVault === null || createdVault === void 0 ? void 0 : createdVault.destroy();
             setVault(null);
+            setInitError(null);
         };
-    }, [apiKey, pubKey, frameBaseUrl, loadTimeoutMs, appearanceKey, fontsKey]);
+    }, [pubKey, frameBaseUrl, loadTimeoutMs, appearanceKey, fontsKey, maxTokenizeCalls]);
     const notifyMount = useCallback(() => setMountedCount(n => n + 1), []);
     const notifyReady = useCallback(() => setReadyCount(n => n + 1), []);
     const notifyUnmount = useCallback(() => {
         setMountedCount(n => Math.max(0, n - 1));
         setReadyCount(n => Math.max(0, n - 1));
     }, []);
-    const value = useMemo(() => ({ vault, notifyMount, notifyReady, notifyUnmount, mountedCount, readyCount }), [vault, notifyMount, notifyReady, notifyUnmount, mountedCount, readyCount]);
+    const notifyTokenize = useCallback(() => setTokenizeCount(n => n + 1), []);
+    const value = useMemo(() => ({ vault, initError, notifyMount, notifyReady, notifyUnmount, notifyTokenize, mountedCount, readyCount, tokenizeCount }), [vault, initError, notifyMount, notifyReady, notifyUnmount, notifyTokenize, mountedCount, readyCount, tokenizeCount]);
     return jsx(OzContext.Provider, { value: value, children: children });
 }
 /**
@@ -1182,15 +1883,25 @@ function OzElements({ apiKey, pubKey, frameBaseUrl, fonts, onLoadError, loadTime
  * an `<OzElements>` provider tree.
  */
 function useOzElements() {
-    const { vault, mountedCount, readyCount } = useContext(OzContext);
-    const createToken = useCallback((options) => {
+    const { vault, initError, mountedCount, readyCount, notifyTokenize, tokenizeCount } = useContext(OzContext);
+    const createToken = useCallback(async (options) => {
         if (!vault) {
             return Promise.reject(new OzError('useOzElements must be called inside an <OzElements> provider.'));
         }
-        return vault.createToken(options);
-    }, [vault]);
-    const ready = vault !== null && mountedCount > 0 && readyCount >= mountedCount;
-    return { createToken, ready };
+        const result = await vault.createToken(options);
+        notifyTokenize();
+        return result;
+    }, [vault, notifyTokenize]);
+    const createBankToken = useCallback(async (options) => {
+        if (!vault) {
+            return Promise.reject(new OzError('useOzElements must be called inside an <OzElements> provider.'));
+        }
+        const result = await vault.createBankToken(options);
+        notifyTokenize();
+        return result;
+    }, [vault, notifyTokenize]);
+    const ready = vault !== null && vault.isReady && mountedCount > 0 && readyCount >= mountedCount;
+    return { createToken, createBankToken, ready, initError, tokenizeCount };
 }
 const SKELETON_STYLE = {
     height: 46,
@@ -1220,7 +1931,7 @@ const LOAD_ERROR_STYLE = {
     color: '#991b1b',
     fontSize: 13,
 };
-function OzField({ type, style, placeholder, disabled, loadTimeoutMs, onChange, onFocus, onBlur, onReady, onLoadError, className, }) {
+function OzFieldBase({ type, variant, style, placeholder, disabled, loadTimeoutMs, onChange, onFocus, onBlur, onReady, onLoadError, className, }) {
     const containerRef = useRef(null);
     const elementRef = useRef(null);
     const [loaded, setLoaded] = useState(false);
@@ -1246,7 +1957,9 @@ function OzField({ type, style, placeholder, disabled, loadTimeoutMs, onChange,
         injectShimmerCSS();
         setLoaded(false);
         setLoadError(null);
-        const element = vault.createElement(type, { style, placeholder, disabled, loadTimeoutMs });
+        const element = variant === 'bank'
+            ? vault.createBankElement(type, { style, placeholder, disabled, loadTimeoutMs })
+            : vault.createElement(type, { style, placeholder, disabled, loadTimeoutMs });
         elementRef.current = element;
         notifyMount();
         element.on('ready', () => {
@@ -1260,29 +1973,29 @@ function OzField({ type, style, placeholder, disabled, loadTimeoutMs, onChange,
         element.on('blur', () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef); });
         element.on('loaderror', (e) => {
             var _a, _b;
-            const err = (_a = e === null || e === void 0 ? void 0 : e.error) !== null && _a !== void 0 ? _a : 'Failed to load card field';
+            const err = (_a = e === null || e === void 0 ? void 0 : e.error) !== null && _a !== void 0 ? _a : (variant === 'bank' ? 'Failed to load bank field' : 'Failed to load card field');
             setLoadError(err);
             (_b = onLoadErrorRef.current) === null || _b === void 0 ? void 0 : _b.call(onLoadErrorRef, err);
         });
         element.mount(containerRef.current);
         return () => {
-            element.unmount();
+            element.destroy();
             elementRef.current = null;
             setLoaded(false);
             setLoadError(null);
             notifyUnmount();
         };
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [vault, type]);
+    }, [vault, type, loadTimeoutMs]);
     return (jsxs("div", { className: className, style: { width: '100%', position: 'relative' }, children: [loadError && jsx("div", { style: LOAD_ERROR_STYLE, role: "alert", children: loadError }), !loaded && !loadError && jsx("div", { style: SKELETON_STYLE }), jsx("div", { ref: containerRef, style: Object.assign({ width: '100%', opacity: loaded ? 1 : 0, transition: 'opacity 0.2s' }, (loadError ? { display: 'none' } : {})) })] }));
 }
 // ─── Public field components ──────────────────────────────────────────────────
 /** Renders a PCI-isolated card number input inside an Ozura iframe. */
-const OzCardNumber = (props) => jsx(OzField, Object.assign({ type: "cardNumber" }, props));
+const OzCardNumber = (props) => jsx(OzFieldBase, Object.assign({ type: "cardNumber", variant: "card" }, props));
 /** Renders a PCI-isolated expiration date input inside an Ozura iframe. */
-const OzExpiry = (props) => jsx(OzField, Object.assign({ type: "expirationDate" }, props));
+const OzExpiry = (props) => jsx(OzFieldBase, Object.assign({ type: "expirationDate", variant: "card" }, props));
 /** Renders a PCI-isolated CVV input inside an Ozura iframe. */
-const OzCvv = (props) => jsx(OzField, Object.assign({ type: "cvv" }, props));
+const OzCvv = (props) => jsx(OzFieldBase, Object.assign({ type: "cvv", variant: "card" }, props));
 const DEFAULT_ERROR_STYLE = {
     color: '#dc2626',
     fontSize: 13,
@@ -1296,6 +2009,11 @@ const DEFAULT_LABEL_STYLE = {
     marginBottom: 4,
     color: '#374151',
 };
+function renderFieldLabel(text, labelClassName, style) {
+    if (!text)
+        return null;
+    return jsx("label", { className: labelClassName, style: style, children: text });
+}
 function mergeStyles(base, override) {
     if (!override)
         return base;
@@ -1325,7 +2043,8 @@ function OzCard({ style, styles, classNames, labels, labelStyle, labelClassName,
         expiry: null,
         cvv: null,
     });
-    const readyFields = useRef(0);
+    const readyFieldTypes = useRef(new Set());
+    const onReadyFiredRef = useRef(false);
     const vaultRef = useRef(vault);
     const onChangeRef = useRef(onChange);
     const onReadyRef = useRef(onReady);
@@ -1337,17 +2056,41 @@ function OzCard({ style, styles, classNames, labels, labelStyle, labelClassName,
     useEffect(() => { onBlurRef.current = onBlur; }, [onBlur]);
     // When the vault is recreated (e.g. appearance/fonts props change on OzElements),
     // context readyCount is reset but this ref is not. Reset so onReady fires once when all 3 are ready.
+    // The cleanup resets readyFieldTypes when the component unmounts (covers React StrictMode double-invoke
+    // and SPA scenarios where the parent re-mounts this component).
     useEffect(() => {
         if (vault !== vaultRef.current) {
             vaultRef.current = vault;
-            readyFields.current = 0;
+            readyFieldTypes.current = new Set();
+            onReadyFiredRef.current = false;
         }
+        return () => {
+            readyFieldTypes.current = new Set();
+            onReadyFiredRef.current = false;
+        };
     }, [vault]);
     const [error, setError] = useState();
-    const handleFieldReady = useCallback(() => {
+    const handleCardNumberReady = useCallback(() => {
+        var _a;
+        readyFieldTypes.current.add('cardNumber');
+        if (readyFieldTypes.current.size >= 3 && !onReadyFiredRef.current) {
+            onReadyFiredRef.current = true;
+            (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef);
+        }
+    }, []);
+    const handleExpiryReady = useCallback(() => {
+        var _a;
+        readyFieldTypes.current.add('expiry');
+        if (readyFieldTypes.current.size >= 3 && !onReadyFiredRef.current) {
+            onReadyFiredRef.current = true;
+            (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef);
+        }
+    }, []);
+    const handleCvvReady = useCallback(() => {
         var _a;
-        readyFields.current++;
-        if (readyFields.current >= 3) {
+        readyFieldTypes.current.add('cvv');
+        if (readyFieldTypes.current.size >= 3 && !onReadyFiredRef.current) {
+            onReadyFiredRef.current = true;
             (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef);
         }
     }, []);
@@ -1366,29 +2109,107 @@ function OzCard({ style, styles, classNames, labels, labelStyle, labelClassName,
             fields: Object.assign({}, fieldState.current),
         });
     }, []);
-    const gapValue = typeof gap === 'number' ? gap : undefined;
     const gapStr = typeof gap === 'string' ? gap : `${gap}px`;
     const resolvedLabelStyle = labelStyle
         ? Object.assign(Object.assign({}, DEFAULT_LABEL_STYLE), labelStyle) : DEFAULT_LABEL_STYLE;
-    const renderLabel = (text) => {
-        if (!text)
-            return null;
-        return (jsx("label", { className: labelClassName, style: resolvedLabelStyle, children: text }));
-    };
+    const renderLabel = (text) => renderFieldLabel(text, labelClassName, resolvedLabelStyle);
     const showError = !hideErrors && error;
     const errorNode = showError
         ? renderError
             ? renderError(error)
             : (jsx("div", { role: "alert", className: errorClassName, style: errorStyle ? Object.assign(Object.assign({}, DEFAULT_ERROR_STYLE), errorStyle) : DEFAULT_ERROR_STYLE, children: error }))
         : null;
-    const cardNumberField = (jsxs("div", { children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.cardNumber), jsx(OzCardNumber, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.cardNumber), className: classNames === null || classNames === void 0 ? void 0 : classNames.cardNumber, placeholder: (_a = placeholders === null || placeholders === void 0 ? void 0 : placeholders.cardNumber) !== null && _a !== void 0 ? _a : 'Card number', disabled: disabled, onChange: (e) => { fieldState.current.cardNumber = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'cardNumber'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'cardNumber'); }, onReady: handleFieldReady })] }));
-    const expiryField = (jsxs("div", { style: layout === 'default' ? { flex: 1 } : undefined, children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.expiry), jsx(OzExpiry, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.expiry), className: classNames === null || classNames === void 0 ? void 0 : classNames.expiry, placeholder: (_b = placeholders === null || placeholders === void 0 ? void 0 : placeholders.expiry) !== null && _b !== void 0 ? _b : 'MM / YY', disabled: disabled, onChange: (e) => { fieldState.current.expiry = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'expiry'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'expiry'); }, onReady: handleFieldReady })] }));
-    const cvvField = (jsxs("div", { style: layout === 'default' ? { flex: 1 } : undefined, children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.cvv), jsx(OzCvv, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.cvv), className: classNames === null || classNames === void 0 ? void 0 : classNames.cvv, placeholder: (_c = placeholders === null || placeholders === void 0 ? void 0 : placeholders.cvv) !== null && _c !== void 0 ? _c : 'CVV', disabled: disabled, onChange: (e) => { fieldState.current.cvv = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'cvv'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'cvv'); }, onReady: handleFieldReady })] }));
+    const cardNumberField = (jsxs("div", { children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.cardNumber), jsx(OzCardNumber, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.cardNumber), className: classNames === null || classNames === void 0 ? void 0 : classNames.cardNumber, placeholder: (_a = placeholders === null || placeholders === void 0 ? void 0 : placeholders.cardNumber) !== null && _a !== void 0 ? _a : 'Card number', disabled: disabled, onChange: (e) => { fieldState.current.cardNumber = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'cardNumber'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'cardNumber'); }, onReady: handleCardNumberReady })] }));
+    const expiryField = (jsxs("div", { style: layout === 'default' ? { flex: 1 } : undefined, children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.expiry), jsx(OzExpiry, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.expiry), className: classNames === null || classNames === void 0 ? void 0 : classNames.expiry, placeholder: (_b = placeholders === null || placeholders === void 0 ? void 0 : placeholders.expiry) !== null && _b !== void 0 ? _b : 'MM / YY', disabled: disabled, onChange: (e) => { fieldState.current.expiry = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'expiry'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'expiry'); }, onReady: handleExpiryReady })] }));
+    const cvvField = (jsxs("div", { style: layout === 'default' ? { flex: 1 } : undefined, children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.cvv), jsx(OzCvv, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.cvv), className: classNames === null || classNames === void 0 ? void 0 : classNames.cvv, placeholder: (_c = placeholders === null || placeholders === void 0 ? void 0 : placeholders.cvv) !== null && _c !== void 0 ? _c : 'CVV', disabled: disabled, onChange: (e) => { fieldState.current.cvv = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'cvv'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'cvv'); }, onReady: handleCvvReady })] }));
     if (layout === 'rows') {
         return (jsxs("div", { className: className, style: { width: '100%', display: 'flex', flexDirection: 'column', gap: gapStr }, children: [cardNumberField, expiryField, cvvField, errorNode] }));
     }
-    return (jsxs("div", { className: className, style: { width: '100%' }, children: [cardNumberField, jsxs("div", { className: classNames === null || classNames === void 0 ? void 0 : classNames.row, style: { display: 'flex', gap: gapValue !== null && gapValue !== void 0 ? gapValue : gapStr, marginTop: gapValue !== null && gapValue !== void 0 ? gapValue : gapStr }, children: [expiryField, cvvField] }), errorNode] }));
+    return (jsxs("div", { className: className, style: { width: '100%' }, children: [cardNumberField, jsxs("div", { className: classNames === null || classNames === void 0 ? void 0 : classNames.row, style: { display: 'flex', gap: gapStr, marginTop: gapStr }, children: [expiryField, cvvField] }), errorNode] }));
+}
+// ─── Public bank field components ─────────────────────────────────────────────
+/** Renders a PCI-isolated bank account number input inside an Ozura iframe. */
+const OzBankAccountNumber = (props) => jsx(OzFieldBase, Object.assign({ type: "accountNumber", variant: "bank" }, props));
+/** Renders a PCI-isolated routing number input inside an Ozura iframe. */
+const OzBankRoutingNumber = (props) => jsx(OzFieldBase, Object.assign({ type: "routingNumber", variant: "bank" }, props));
+/**
+ * Combined bank account input — renders account number and routing number in a
+ * single component with built-in layout, loading skeletons, and inline error display.
+ *
+ * For maximum layout control, use `<OzBankAccountNumber />` and `<OzBankRoutingNumber />`
+ * individually instead.
+ */
+function OzBankCard({ style, styles, classNames, labels, labelStyle, labelClassName, gap = 8, hideErrors = false, errorStyle, errorClassName, renderError, onChange, onReady, onFocus, onBlur, disabled, className, placeholders, }) {
+    var _a, _b;
+    const { vault } = useContext(OzContext);
+    const fieldState = useRef({
+        accountNumber: null,
+        routingNumber: null,
+    });
+    const readyFieldTypes = useRef(new Set());
+    const onReadyFiredRef = useRef(false);
+    const vaultRef = useRef(vault);
+    const onChangeRef = useRef(onChange);
+    const onReadyRef = useRef(onReady);
+    const onFocusRef = useRef(onFocus);
+    const onBlurRef = useRef(onBlur);
+    useEffect(() => { onChangeRef.current = onChange; }, [onChange]);
+    useEffect(() => { onReadyRef.current = onReady; }, [onReady]);
+    useEffect(() => { onFocusRef.current = onFocus; }, [onFocus]);
+    useEffect(() => { onBlurRef.current = onBlur; }, [onBlur]);
+    useEffect(() => {
+        if (vault !== vaultRef.current) {
+            vaultRef.current = vault;
+            readyFieldTypes.current = new Set();
+            onReadyFiredRef.current = false;
+        }
+        return () => {
+            readyFieldTypes.current = new Set();
+            onReadyFiredRef.current = false;
+        };
+    }, [vault]);
+    const [error, setError] = useState();
+    const handleAccountReady = useCallback(() => {
+        var _a;
+        readyFieldTypes.current.add('accountNumber');
+        if (readyFieldTypes.current.size >= 2 && !onReadyFiredRef.current) {
+            onReadyFiredRef.current = true;
+            (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef);
+        }
+    }, []);
+    const handleRoutingReady = useCallback(() => {
+        var _a;
+        readyFieldTypes.current.add('routingNumber');
+        if (readyFieldTypes.current.size >= 2 && !onReadyFiredRef.current) {
+            onReadyFiredRef.current = true;
+            (_a = onReadyRef.current) === null || _a === void 0 ? void 0 : _a.call(onReadyRef);
+        }
+    }, []);
+    const emitChange = useCallback(() => {
+        var _a;
+        const { accountNumber, routingNumber } = fieldState.current;
+        const complete = !!((accountNumber === null || accountNumber === void 0 ? void 0 : accountNumber.complete) && (accountNumber === null || accountNumber === void 0 ? void 0 : accountNumber.valid) &&
+            (routingNumber === null || routingNumber === void 0 ? void 0 : routingNumber.complete) && (routingNumber === null || routingNumber === void 0 ? void 0 : routingNumber.valid));
+        const err = (accountNumber === null || accountNumber === void 0 ? void 0 : accountNumber.error) || (routingNumber === null || routingNumber === void 0 ? void 0 : routingNumber.error) || undefined;
+        setError(err);
+        (_a = onChangeRef.current) === null || _a === void 0 ? void 0 : _a.call(onChangeRef, {
+            complete,
+            error: err,
+            fields: Object.assign({}, fieldState.current),
+        });
+    }, []);
+    const gapStr = typeof gap === 'string' ? gap : `${gap}px`;
+    const resolvedLabelStyle = labelStyle
+        ? Object.assign(Object.assign({}, DEFAULT_LABEL_STYLE), labelStyle) : DEFAULT_LABEL_STYLE;
+    const renderLabel = (text) => renderFieldLabel(text, labelClassName, resolvedLabelStyle);
+    const showError = !hideErrors && error;
+    const errorNode = showError
+        ? renderError
+            ? renderError(error)
+            : (jsx("div", { role: "alert", className: errorClassName, style: errorStyle ? Object.assign(Object.assign({}, DEFAULT_ERROR_STYLE), errorStyle) : DEFAULT_ERROR_STYLE, children: error }))
+        : null;
+    return (jsxs("div", { className: className, style: { width: '100%', display: 'flex', flexDirection: 'column', gap: gapStr }, children: [jsxs("div", { children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.accountNumber), jsx(OzBankAccountNumber, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.accountNumber), className: classNames === null || classNames === void 0 ? void 0 : classNames.accountNumber, placeholder: (_a = placeholders === null || placeholders === void 0 ? void 0 : placeholders.accountNumber) !== null && _a !== void 0 ? _a : 'Account number', disabled: disabled, onChange: (e) => { fieldState.current.accountNumber = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'accountNumber'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'accountNumber'); }, onReady: handleAccountReady })] }), jsxs("div", { children: [renderLabel(labels === null || labels === void 0 ? void 0 : labels.routingNumber), jsx(OzBankRoutingNumber, { style: mergeStyles(style, styles === null || styles === void 0 ? void 0 : styles.routingNumber), className: classNames === null || classNames === void 0 ? void 0 : classNames.routingNumber, placeholder: (_b = placeholders === null || placeholders === void 0 ? void 0 : placeholders.routingNumber) !== null && _b !== void 0 ? _b : 'Routing number', disabled: disabled, onChange: (e) => { fieldState.current.routingNumber = e; emitChange(); }, onFocus: () => { var _a; return (_a = onFocusRef.current) === null || _a === void 0 ? void 0 : _a.call(onFocusRef, 'routingNumber'); }, onBlur: () => { var _a; return (_a = onBlurRef.current) === null || _a === void 0 ? void 0 : _a.call(onBlurRef, 'routingNumber'); }, onReady: handleRoutingReady })] }), errorNode] }));
 }
 
-export { OzCard, OzCardNumber, OzCvv, OzElements, OzExpiry, useOzElements };
+export { OzBankAccountNumber, OzBankCard, OzBankRoutingNumber, OzCard, OzCardNumber, OzCvv, OzElements, OzExpiry, createFetchWaxKey, useOzElements };
 //# sourceMappingURL=index.esm.js.map