@ozura/elements 0.1.0-beta.6 → 1.0.0

package/dist/oz-elements.umd.js

@@ -4,6 +4,147 @@
     (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.OzElements = {}));
 })(this, (function (exports) { 'use strict';
 
+    /**
+     * 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;
+    }
+    // ─── cardSale error map (mirrors checkout/src/utils/errorMapping.ts exactly) ─
+    const CARD_SALE_ERROR_MAP = [
+        ['Insufficient Funds', 'Your card has insufficient funds. Please use a different payment method.'],
+        ['Invalid card number', 'The card number you entered is invalid. Please check and try again.'],
+        ['Card expired', 'Your card has expired. Please use a different card.'],
+        ['CVV Verification Failed', 'The CVV code you entered is incorrect. Please check and try again.'],
+        ['Address Verification Failed', 'The billing address does not match your card. Please verify your address.'],
+        ['Do Not Honor', 'Your card was declined. Please contact your bank or use a different payment method.'],
+        ['Declined', 'Your card was declined. Please contact your bank or use a different payment method.'],
+        ['Surcharge is currently not supported', 'Surcharge fees are not supported at this time.'],
+        ['Surcharge percent must be between', 'Surcharge fees are not supported at this time.'],
+        ['Forbidden - API key', 'Authentication failed. Please refresh the page.'],
+        ['Api Key is invalid', 'Authentication failed. Please refresh the page.'],
+        ['API key not found', 'Authentication failed. Please refresh the page.'],
+        ['Access token expired', 'Your session has expired. Please refresh the page.'],
+        ['Access token is invalid', 'Authentication failed. Please refresh the page.'],
+        ['Unauthorized', 'Authentication failed. Please refresh the page.'],
+        ['Too Many Requests', 'Too many requests. Please wait a moment and try again.'],
+        ['Rate limit exceeded', 'System is busy. Please wait a moment and try again.'],
+        ['No processor integrations found', 'Payment processing is not configured for this merchant. Please contact the merchant for assistance.'],
+        ['processor integration', 'Payment processing is temporarily unavailable. Please try again later or contact the merchant.'],
+        ['Invalid zipcode', 'The ZIP code you entered is invalid. Please check and try again.'],
+        ['failed to save to database', 'Your payment was processed but we encountered an issue. Please contact support.'],
+        ['CASHBACK UNAVAIL', 'This transaction type is not supported. Please try again or use a different payment method.'],
+    ];
+    /**
+     * Maps a raw Ozura Pay API cardSale error string to a user-facing message.
+     *
+     * Uses the exact same error key table as checkout's `getUserFriendlyError()` in
+     * errorMapping.ts so both surfaces produce identical copy for the same errors.
+     *
+     * Falls back to the original string when it's under 100 characters, or to a
+     * generic message for long/opaque server errors — matching checkout's fallback
+     * behaviour exactly.
+     *
+     * **Trade-off:** Short unrecognised strings (e.g. processor codes like
+     * `"PROC_TIMEOUT"`) are passed through verbatim. This intentionally mirrors
+     * checkout so the same raw Pay API errors produce the same user-facing text on
+     * both surfaces. If the Pay API ever returns internal codes that should never
+     * reach the UI, the fix belongs in the Pay API error normalisation layer rather
+     * than here.
+     */
+    function normalizeCardSaleError(raw) {
+        if (!raw)
+            return 'Payment processing failed. Please try again.';
+        for (const [key, message] of CARD_SALE_ERROR_MAP) {
+            if (raw.toLowerCase().includes(key.toLowerCase())) {
+                return message;
+            }
+        }
+        // Checkout fallback: pass through short errors, genericise long ones
+        if (raw.length < 100)
+            return raw;
+        return 'Payment processing failed. Please try again or contact support.';
+    }
+
     const THEME_DEFAULT = {
         base: {
             color: '#1a1a2e',
@@ -134,6 +275,15 @@
      * 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;
@@ -159,7 +309,31 @@
         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;
+    /**
+     * 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) {
@@ -191,6 +365,11 @@
     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) {
@@ -218,7 +397,7 @@
             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() {
@@ -236,22 +415,27 @@
         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 : '';
@@ -267,6 +451,11 @@
                 }
             }, 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;
@@ -275,6 +464,10 @@
             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) {
@@ -284,6 +477,10 @@
             }
             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);
@@ -291,13 +488,24 @@
             };
             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;
@@ -310,6 +518,8 @@
          */
         unmount() {
             var _a;
+            if (this._destroyed)
+                return;
             if (this._loadTimer) {
                 clearTimeout(this._loadTimer);
                 this._loadTimer = null;
@@ -342,18 +552,31 @@
             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;
@@ -367,6 +590,19 @@
                     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':
@@ -393,7 +629,12 @@
                     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;
             }
@@ -401,8 +642,16 @@
         // ─── 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);
@@ -417,135 +666,18 @@
             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.';
-        }
-        const common = normalizeCommonVaultError(msg);
-        if (common)
-            return common;
-        return raw;
-    }
-    // ─── cardSale error map (mirrors checkout/src/utils/errorMapping.ts exactly) ─
-    const CARD_SALE_ERROR_MAP = [
-        ['Insufficient Funds', 'Your card has insufficient funds. Please use a different payment method.'],
-        ['Invalid card number', 'The card number you entered is invalid. Please check and try again.'],
-        ['Card expired', 'Your card has expired. Please use a different card.'],
-        ['CVV Verification Failed', 'The CVV code you entered is incorrect. Please check and try again.'],
-        ['Address Verification Failed', 'The billing address does not match your card. Please verify your address.'],
-        ['Do Not Honor', 'Your card was declined. Please contact your bank or use a different payment method.'],
-        ['Declined', 'Your card was declined. Please contact your bank or use a different payment method.'],
-        ['Surcharge is currently not supported', 'Surcharge fees are not supported at this time.'],
-        ['Surcharge percent must be between', 'Surcharge fees are not supported at this time.'],
-        ['Forbidden - API key', 'Authentication failed. Please refresh the page.'],
-        ['Api Key is invalid', 'Authentication failed. Please refresh the page.'],
-        ['API key not found', 'Authentication failed. Please refresh the page.'],
-        ['Access token expired', 'Your session has expired. Please refresh the page.'],
-        ['Access token is invalid', 'Authentication failed. Please refresh the page.'],
-        ['Unauthorized', 'Authentication failed. Please refresh the page.'],
-        ['Too Many Requests', 'Too many requests. Please wait a moment and try again.'],
-        ['Rate limit exceeded', 'System is busy. Please wait a moment and try again.'],
-        ['No processor integrations found', 'Payment processing is not configured for this merchant. Please contact the merchant for assistance.'],
-        ['processor integration', 'Payment processing is temporarily unavailable. Please try again later or contact the merchant.'],
-        ['Invalid zipcode', 'The ZIP code you entered is invalid. Please check and try again.'],
-        ['failed to save to database', 'Your payment was processed but we encountered an issue. Please contact support.'],
-        ['CASHBACK UNAVAIL', 'This transaction type is not supported. Please try again or use a different payment method.'],
-    ];
-    /**
-     * Maps a raw Ozura Pay API cardSale error string to a user-facing message.
-     *
-     * Uses the exact same error key table as checkout's `getUserFriendlyError()` in
-     * errorMapping.ts so both surfaces produce identical copy for the same errors.
-     *
-     * Falls back to the original string when it's under 100 characters, or to a
-     * generic message for long/opaque server errors — matching checkout's fallback
-     * behaviour exactly.
-     */
-    function normalizeCardSaleError(raw) {
-        if (!raw)
-            return 'Payment processing failed. Please try again.';
-        for (const [key, message] of CARD_SALE_ERROR_MAP) {
-            if (raw.toLowerCase().includes(key.toLowerCase())) {
-                return message;
+        /** 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);
         }
-        // Checkout fallback: pass through short errors, genericise long ones
-        if (raw.length < 100)
-            return raw;
-        return 'Payment processing failed. Please try again or contact support.';
     }
 
     /**
@@ -597,6 +729,14 @@
         '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 = {
@@ -705,8 +845,15 @@
                 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")');
@@ -730,13 +877,31 @@
         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({
@@ -744,8 +909,14 @@
      * });
      */
     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();
@@ -758,24 +929,32 @@
             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) {
@@ -783,15 +962,113 @@
                     }
                 }, 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.
@@ -824,7 +1101,10 @@
         }
         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) {
@@ -856,7 +1136,7 @@
         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.');
@@ -873,10 +1153,10 @@
                 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');
@@ -893,30 +1173,47 @@
             }
             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'));
+                }
             });
         }
         /**
@@ -928,7 +1225,7 @@
         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.');
@@ -938,29 +1235,33 @@
                     ? '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;
@@ -969,40 +1270,57 @@
             }
             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'));
+                }
             });
         }
         /**
@@ -1016,6 +1334,7 @@
                 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;
@@ -1026,11 +1345,17 @@
             }
             // 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();
@@ -1039,17 +1364,49 @@
             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;
@@ -1068,6 +1425,8 @@
         }
         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)
@@ -1085,14 +1444,17 @@
             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);
-                    }
                 }
             }
         }
@@ -1106,7 +1468,7 @@
             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;
@@ -1129,7 +1491,7 @@
             }
         }
         handleTokenizerMessage(msg) {
-            var _a, _b;
+            var _a, _b, _c;
             switch (msg.type) {
                 case 'OZ_FRAME_READY':
                     this.tokenizerReady = true;
@@ -1138,57 +1500,335 @@
                         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;
+        };
+    }
+
     exports.OzElement = OzElement;
     exports.OzError = OzError;
     exports.OzVault = OzVault;
+    exports.createFetchWaxKey = createFetchWaxKey;
     exports.normalizeBankVaultError = normalizeBankVaultError;
     exports.normalizeCardSaleError = normalizeCardSaleError;
     exports.normalizeVaultError = normalizeVaultError;