@ozura/elements 0.1.0-beta.6 → 1.0.0

package/dist/oz-elements.esm.js

@@ -1,3 +1,144 @@
+/**
+ * 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',
@@ -128,6 +269,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;
@@ -153,7 +303,31 @@ 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;
+/**
+ * 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) {
@@ -185,6 +359,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) {
@@ -212,7 +391,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() {
@@ -230,22 +409,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 : '';
@@ -261,6 +445,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;
@@ -269,6 +458,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) {
@@ -278,6 +471,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);
@@ -285,13 +482,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;
@@ -304,6 +512,8 @@ class OzElement {
      */
     unmount() {
         var _a;
+        if (this._destroyed)
+            return;
         if (this._loadTimer) {
             clearTimeout(this._loadTimer);
             this._loadTimer = null;
@@ -336,18 +546,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;
@@ -361,6 +584,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':
@@ -387,7 +623,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;
         }
@@ -395,8 +636,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);
@@ -411,135 +660,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.';
-    }
-    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.';
 }
 
 /**
@@ -591,6 +723,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 = {
@@ -699,8 +839,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")');
@@ -724,13 +871,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({
@@ -738,8 +903,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();
@@ -752,24 +923,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) {
@@ -777,15 +956,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.
@@ -818,7 +1095,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) {
@@ -850,7 +1130,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.');
@@ -867,10 +1147,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');
@@ -887,30 +1167,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'));
+            }
         });
     }
     /**
@@ -922,7 +1219,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.');
@@ -932,29 +1229,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;
@@ -963,40 +1264,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'));
+            }
         });
     }
     /**
@@ -1010,6 +1328,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;
@@ -1020,11 +1339,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();
@@ -1033,17 +1358,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;
@@ -1062,6 +1419,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)
@@ -1079,14 +1438,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);
-                }
             }
         }
     }
@@ -1100,7 +1462,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;
@@ -1123,7 +1485,7 @@ class OzVault {
         }
     }
     handleTokenizerMessage(msg) {
-        var _a, _b;
+        var _a, _b, _c;
         switch (msg.type) {
             case 'OZ_FRAME_READY':
                 this.tokenizerReady = true;
@@ -1132,53 +1494,330 @@ 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 : []);
     }
 }
 
-export { OzElement, OzError, OzVault, normalizeBankVaultError, normalizeCardSaleError, normalizeVaultError };
+/**
+ * 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;
+    };
+}
+
+export { OzElement, OzError, OzVault, createFetchWaxKey, normalizeBankVaultError, normalizeCardSaleError, normalizeVaultError };
 //# sourceMappingURL=oz-elements.esm.js.map