@ozura/elements 1.2.0 → 1.2.3

package/dist/vue/index.esm.js

@@ -0,0 +1,2327 @@
+import { defineComponent, shallowRef, ref, provide, onMounted, onUnmounted, inject, watch, h, computed } from 'vue';
+
+const THEME_DEFAULT = {
+    base: {
+        color: '#1a1a2e',
+        fontSize: '16px',
+        fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+        lineHeight: '1.5',
+        padding: '12px 14px',
+        backgroundColor: 'transparent',
+        caretColor: '#6366f1',
+        transition: 'color .15s ease',
+    },
+    focus: {
+        color: '#111827',
+    },
+    invalid: {
+        color: '#dc2626',
+    },
+    complete: {
+        color: '#16a34a',
+    },
+    placeholder: {
+        color: '#9ca3af',
+    },
+};
+const THEME_NIGHT = {
+    base: {
+        color: '#e5e7eb',
+        fontSize: '16px',
+        fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+        lineHeight: '1.5',
+        padding: '12px 14px',
+        backgroundColor: 'transparent',
+        caretColor: '#818cf8',
+        transition: 'color .15s ease',
+    },
+    focus: {
+        color: '#f9fafb',
+    },
+    invalid: {
+        color: '#fca5a5',
+    },
+    complete: {
+        color: '#86efac',
+    },
+    placeholder: {
+        color: '#6b7280',
+    },
+};
+const THEME_FLAT = {
+    base: {
+        color: '#374151',
+        fontSize: '16px',
+        fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif',
+        lineHeight: '1.5',
+        padding: '12px 14px',
+        backgroundColor: 'transparent',
+        caretColor: '#6366f1',
+        transition: 'color .15s ease',
+        borderBottom: '2px solid #d1d5db',
+        borderRadius: '0px',
+    },
+    focus: {
+        color: '#111827',
+        borderBottom: '2px solid #6366f1',
+    },
+    invalid: {
+        color: '#dc2626',
+        borderBottom: '2px solid #dc2626',
+    },
+    complete: {
+        color: '#16a34a',
+        borderBottom: '2px solid #16a34a',
+    },
+    placeholder: {
+        color: '#9ca3af',
+    },
+};
+const THEMES = {
+    default: THEME_DEFAULT,
+    night: THEME_NIGHT,
+    flat: THEME_FLAT,
+};
+function variablesToStyle(vars) {
+    const base = {};
+    const focus = {};
+    const invalid = {};
+    const complete = {};
+    const placeholder = {};
+    if (vars.colorText)
+        base.color = vars.colorText;
+    if (vars.colorBackground)
+        base.backgroundColor = vars.colorBackground;
+    if (vars.fontFamily)
+        base.fontFamily = vars.fontFamily;
+    if (vars.fontSize)
+        base.fontSize = vars.fontSize;
+    if (vars.fontWeight)
+        base.fontWeight = vars.fontWeight;
+    if (vars.letterSpacing)
+        base.letterSpacing = vars.letterSpacing;
+    if (vars.lineHeight)
+        base.lineHeight = vars.lineHeight;
+    if (vars.padding)
+        base.padding = vars.padding;
+    if (vars.colorPrimary) {
+        focus.caretColor = vars.colorPrimary;
+        base.caretColor = vars.colorPrimary;
+    }
+    if (vars.colorDanger)
+        invalid.color = vars.colorDanger;
+    if (vars.colorSuccess)
+        complete.color = vars.colorSuccess;
+    if (vars.colorPlaceholder)
+        placeholder.color = vars.colorPlaceholder;
+    return Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({}, (Object.keys(base).length > 0 ? { base } : {})), (Object.keys(focus).length > 0 ? { focus } : {})), (Object.keys(invalid).length > 0 ? { invalid } : {})), (Object.keys(complete).length > 0 ? { complete } : {})), (Object.keys(placeholder).length > 0 ? { placeholder } : {}));
+}
+function mergeStyleConfigs(a, b) {
+    return {
+        base: Object.assign(Object.assign({}, a.base), b.base),
+        focus: Object.assign(Object.assign({}, a.focus), b.focus),
+        invalid: Object.assign(Object.assign({}, a.invalid), b.invalid),
+        complete: Object.assign(Object.assign({}, a.complete), b.complete),
+        placeholder: Object.assign(Object.assign({}, a.placeholder), b.placeholder),
+    };
+}
+/**
+ * Resolves an `Appearance` config into a flat `ElementStyleConfig`.
+ * 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;
+    if (!appearance)
+        return undefined;
+    const theme = (_b = THEMES[(_a = appearance.theme) !== null && _a !== void 0 ? _a : 'default']) !== null && _b !== void 0 ? _b : THEMES.default;
+    if (!appearance.variables)
+        return theme;
+    const varStyles = variablesToStyle(appearance.variables);
+    return mergeStyleConfigs(theme, varStyles);
+}
+/**
+ * Merges a resolved appearance with per-element style overrides.
+ * Element styles always win over appearance styles.
+ */
+function mergeAppearanceWithElementStyle(appearance, elementStyle) {
+    if (!appearance && !elementStyle)
+        return undefined;
+    if (!appearance)
+        return elementStyle;
+    if (!elementStyle)
+        return appearance;
+    return mergeStyleConfigs(appearance, elementStyle);
+}
+
+/**
+ * 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') || /\b5\d{2}\b/.test(msg)) {
+        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 funds')) {
+        return 'Your card has insufficient funds. Please use a different card.';
+    }
+    if (msg.includes('declined') || msg.includes('do not honor')) {
+        return 'Your card was declined. Please try a different card or contact your bank.';
+    }
+    const common = normalizeCommonVaultError(msg);
+    if (common)
+        return common;
+    return raw;
+}
+/**
+ * Maps a raw vault /tokenize error string to a user-facing message for bank (ACH) flows.
+ * Uses bank-specific pattern matching so card-specific messages are never shown for
+ * bank errors. Falls back to the original string if no pattern matches.
+ */
+function normalizeBankVaultError(raw) {
+    const msg = raw.toLowerCase();
+    if (msg.includes('account number') || msg.includes('account_number') || msg.includes('invalid account')) {
+        return 'The bank account number is invalid. Please check and try again.';
+    }
+    if (msg.includes('routing number') || msg.includes('routing_number') || msg.includes('invalid routing') || /\baba\b/.test(msg)) {
+        return 'The routing number is invalid. Please check and try again.';
+    }
+    const common = normalizeCommonVaultError(msg);
+    if (common)
+        return common;
+    return raw;
+}
+
+/**
+ * Generates a RFC 4122 v4 UUID.
+ *
+ * Uses `crypto.randomUUID()` when available (Chrome 92+, Firefox 95+,
+ * Safari 15.4+, Node 14.17+) and falls back to `crypto.getRandomValues()`
+ * for older environments (Safari 14, some embedded WebViews, older Node).
+ *
+ * Both paths use the same CSPRNG — the difference is only in API surface.
+ *
+ * @internal
+ */
+function uuid() {
+    if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
+        return crypto.randomUUID();
+    }
+    // Fallback: build UUID v4 from random bytes
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    bytes[6] = (bytes[6] & 0x0f) | 0x40; // version 4
+    bytes[8] = (bytes[8] & 0x3f) | 0x80; // variant RFC 4122
+    const hex = Array.from(bytes, b => b.toString(16).padStart(2, '0')).join('');
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+const BLOCKED_CSS_PATTERNS = /url\s*\(|expression\s*\(|javascript\s*:|vbscript\s*:|@import|behavior\s*:|binding\s*:|-moz-binding|-webkit-binding|<\s*script|<\s*style|\\[0-9a-fA-F]|var\s*\(/i;
+const CSS_BREAKOUT = /[{};<>]/;
+const MAX_CSS_VALUE_LEN = 200;
+function sanitizeStyleObj(obj) {
+    if (!obj)
+        return obj;
+    const clean = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (v === undefined) {
+            clean[k] = v;
+            continue;
+        }
+        if (typeof v !== 'string' || v.length > MAX_CSS_VALUE_LEN || BLOCKED_CSS_PATTERNS.test(v) || CSS_BREAKOUT.test(v))
+            continue;
+        clean[k] = v;
+    }
+    return clean;
+}
+function sanitizeStyles(style) {
+    if (!style)
+        return style;
+    return {
+        base: sanitizeStyleObj(style.base),
+        focus: sanitizeStyleObj(style.focus),
+        invalid: sanitizeStyleObj(style.invalid),
+        complete: sanitizeStyleObj(style.complete),
+        placeholder: sanitizeStyleObj(style.placeholder),
+    };
+}
+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) {
+        result.style = sanitizeStyles(options.style);
+    }
+    return result;
+}
+/**
+ * A proxy for one Ozura iframe element. Merchants interact with this object;
+ * it never holds raw card data — all sensitive values live in the iframe.
+ */
+class OzElement {
+    constructor(elementType, options, vaultId, frameBaseUrl, fonts = [], appearanceStyle, onDestroy, debug = false) {
+        this.iframe = null;
+        this._frameWindow = null;
+        this._ready = false;
+        this._destroyed = false;
+        this._loadTimer = null;
+        this.pendingMessages = [];
+        this.handlers = new Map();
+        this.debug = false;
+        this.elementType = elementType;
+        this.options = sanitizeOptions(options);
+        this.vaultId = vaultId;
+        this.frameBaseUrl = frameBaseUrl;
+        this.frameOrigin = new URL(frameBaseUrl).origin;
+        this.fonts = fonts;
+        this.appearanceStyle = appearanceStyle;
+        this.frameId = `oz-${elementType}-${uuid()}`;
+        this._onDestroy = onDestroy;
+        this.debug = debug;
+    }
+    /** The element type this proxy represents. */
+    get type() {
+        return this.elementType;
+    }
+    /** True once the element iframe has loaded and signalled ready. */
+    get isReady() {
+        return this._ready;
+    }
+    /**
+     * Mounts the element iframe into a container.
+     * Accepts either a CSS selector string or a direct HTMLElement reference
+     * (useful when integrating with React refs).
+     */
+    mount(target) {
+        var _a, _b;
+        if (this._destroyed)
+            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 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 ${(_a = {
+            cardNumber: 'card number',
+            expirationDate: 'expiration date',
+            cvv: 'CVV',
+            accountNumber: 'account number',
+            routingNumber: 'routing number',
+        }[this.elementType]) !== null && _a !== void 0 ? _a : this.elementType} input`;
+        // sandbox="allow-scripts" gives correct iframe isolation:
+        // - Scripts run (allow-scripts), so the field JS executes normally.
+        // - NO allow-same-origin: the frame cannot access window.parent's DOM,
+        //   localStorage, or cookies — prevents sandbox escape even if served
+        //   from the same origin.
+        // - NO allow-top-navigation: a rogue/compromised element frame cannot
+        //   navigate window.top (clickjacking prevention).
+        // - NO allow-forms / allow-popups: reduces attack surface.
+        // Field values are delivered via postMessage, so no parent access is
+        // needed — allow-scripts alone is sufficient.
+        iframe.setAttribute('sandbox', 'allow-scripts');
+        // 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 : '';
+        const src = `${this.frameBaseUrl}/frame/element-frame.html#type=${this.elementType}&vaultId=${encodeURIComponent(this.vaultId)}&frameId=${encodeURIComponent(this.frameId)}${parentOrigin ? `&parentOrigin=${encodeURIComponent(parentOrigin)}` : ''}`;
+        iframe.src = src;
+        container.appendChild(iframe);
+        this.iframe = iframe;
+        this._frameWindow = iframe.contentWindow;
+        const timeout = (_b = this.options.loadTimeoutMs) !== null && _b !== void 0 ? _b : 10000;
+        this._loadTimer = setTimeout(() => {
+            if (!this._ready && !this._destroyed) {
+                this.emit('loaderror', { elementType: this.elementType, error: `${this.elementType} iframe failed to load within ${timeout}ms` });
+            }
+        }, 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;
+        if (!this.handlers.has(event))
+            this.handlers.set(event, []);
+        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) {
+            const idx = list.indexOf(callback);
+            if (idx !== -1)
+                list.splice(idx, 1);
+        }
+        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);
+            callback(payload);
+        };
+        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;
+        this.post({ type: 'OZ_CLEAR' });
+    }
+    /**
+     * Removes the iframe from the DOM and resets internal state.
+     * Called automatically by `OzVault.destroy()`. Safe to call manually
+     * for partial teardown (e.g. swapping payment method in a SPA).
+     */
+    unmount() {
+        var _a;
+        if (this._destroyed)
+            return;
+        if (this._loadTimer) {
+            clearTimeout(this._loadTimer);
+            this._loadTimer = null;
+        }
+        (_a = this.iframe) === null || _a === void 0 ? void 0 : _a.remove();
+        this.iframe = null;
+        this._frameWindow = null;
+        this._ready = false;
+        this.pendingMessages = [];
+    }
+    /** Programmatically focus this element's input. Used internally for auto-advance. */
+    focus() {
+        if (this._destroyed)
+            return;
+        this.post({ type: 'OZ_FOCUS_REQUEST' });
+    }
+    /** Programmatically blur this element's input. */
+    blur() {
+        if (this._destroyed)
+            return;
+        this.post({ type: 'OZ_BLUR_REQUEST' });
+    }
+    /**
+     * Permanently destroys this element: unmounts it, clears all event handlers,
+     * and prevents future use. Distinct from `unmount()` which allows re-mounting.
+     */
+    destroy() {
+        var _a;
+        this.unmount();
+        this.handlers.clear();
+        this._destroyed = true;
+        // Notify OzVault so it can prune the stale frameId entry from its elements
+        // and completionState maps. Without this, manually calling el.destroy() leaks
+        // map entries that grow unboundedly in SPA scenarios with repeated mount/unmount.
+        (_a = this._onDestroy) === null || _a === void 0 ? void 0 : _a.call(this);
+    }
+    // ─── Called by OzVault ───────────────────────────────────────────────────
+    /**
+     * 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.
+     * @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;
+                if (this._loadTimer) {
+                    clearTimeout(this._loadTimer);
+                    this._loadTimer = null;
+                }
+                this._frameWindow = (_b = (_a = this.iframe) === null || _a === void 0 ? void 0 : _a.contentWindow) !== null && _b !== void 0 ? _b : null;
+                const mergedOptions = Object.assign(Object.assign({}, this.options), { style: mergeAppearanceWithElementStyle(this.appearanceStyle, this.options.style) });
+                this.post(Object.assign({ type: 'OZ_INIT', elementType: this.elementType, options: sanitizeOptions(mergedOptions), frameId: this.frameId, debug: this.debug }, (this.fonts.length > 0 ? { fonts: this.fonts } : {})));
+                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':
+                this.emit('change', {
+                    empty: msg.empty,
+                    complete: msg.complete,
+                    valid: msg.valid,
+                    cardBrand: msg.cardBrand,
+                    month: msg.month,
+                    year: msg.year,
+                    error: msg.error,
+                });
+                break;
+            case 'OZ_FOCUS':
+                this.emit('focus', undefined);
+                break;
+            case 'OZ_BLUR':
+                this.emit('blur', {
+                    empty: msg.empty,
+                    complete: msg.complete,
+                    valid: msg.valid,
+                    error: msg.error,
+                });
+                break;
+            case 'OZ_RESIZE':
+                if (this.iframe) {
+                    // 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;
+        }
+    }
+    // ─── Internal ────────────────────────────────────────────────────────────
+    emit(event, payload) {
+        const list = this.handlers.get(event);
+        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);
+        if (!this._ready) {
+            this.pendingMessages.push(msg);
+        }
+        else {
+            this.send(msg);
+        }
+    }
+    send(msg) {
+        var _a;
+        (_a = this._frameWindow) === null || _a === void 0 ? void 0 : _a.postMessage(msg, this.frameOrigin);
+    }
+    /** 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);
+    }
+}
+
+/**
+ * billingUtils.ts — billing detail validation and normalization.
+ *
+ * Mirrors the validation in checkout/page.tsx (pre-flight checks before cardSale)
+ * so that billing data passed to createToken() is guaranteed schema-compliant and
+ * ready to forward directly to the Ozura Pay API cardSale endpoint.
+ *
+ * All string fields enforced to 1–50 characters (cardSale schema constraint).
+ * State is normalized to 2-letter abbreviation for US and CA.
+ * Phone must be E.164 format (matches checkout's formatPhoneForAPI output).
+ */
+// ─── Email ────────────────────────────────────────────────────────────────────
+const EMAIL_RE = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+/** Returns true when the email is syntactically valid and ≤50 characters. */
+function validateEmail(email) {
+    return EMAIL_RE.test(email) && email.length <= 50;
+}
+// ─── Phone ───────────────────────────────────────────────────────────────────
+/**
+ * Validates E.164 phone format: starts with +, 1–3 digit country code,
+ * followed by 7–12 digits, max 15 digits total (E.164 spec cap = 16 chars
+ * including the leading +).
+ *
+ * Matches the output of checkout's formatPhoneForAPI() function.
+ * Examples: "+15551234567", "+447911123456", "+61412345678"
+ */
+function validateE164Phone(phone) {
+    return /^\+[1-9]\d{6,14}$/.test(phone);
+}
+// ─── Field length ─────────────────────────────────────────────────────────────
+/** Returns true when the string is non-empty and ≤50 characters (cardSale schema). */
+function isValidBillingField(value) {
+    return value.length > 0 && value.length <= 50;
+}
+// ─── US state normalization ───────────────────────────────────────────────────
+// Mirrors checkout's convertStateToAbbreviation() so the same input variants work.
+const US_STATES = {
+    alabama: 'AL', alaska: 'AK', arizona: 'AZ', arkansas: 'AR',
+    california: 'CA', colorado: 'CO', connecticut: 'CT', delaware: 'DE',
+    'district of columbia': 'DC', florida: 'FL', georgia: 'GA', hawaii: 'HI',
+    idaho: 'ID', illinois: 'IL', indiana: 'IN', iowa: 'IA', kansas: 'KS',
+    kentucky: 'KY', louisiana: 'LA', maine: 'ME', maryland: 'MD',
+    massachusetts: 'MA', michigan: 'MI', minnesota: 'MN', mississippi: 'MS',
+    missouri: 'MO', montana: 'MT', nebraska: 'NE', nevada: 'NV',
+    'new hampshire': 'NH', 'new jersey': 'NJ', 'new mexico': 'NM', 'new york': 'NY',
+    'north carolina': 'NC', 'north dakota': 'ND', ohio: 'OH', oklahoma: 'OK',
+    oregon: 'OR', pennsylvania: 'PA', 'rhode island': 'RI', 'south carolina': 'SC',
+    '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 = {
+    alberta: 'AB', 'british columbia': 'BC', manitoba: 'MB', 'new brunswick': 'NB',
+    'newfoundland and labrador': 'NL', 'nova scotia': 'NS', ontario: 'ON',
+    'prince edward island': 'PE', quebec: 'QC', saskatchewan: 'SK',
+    'northwest territories': 'NT', nunavut: 'NU', yukon: 'YT',
+};
+const CA_ABBREVS = new Set(Object.values(CA_PROVINCES));
+/**
+ * Converts a full US state or Canadian province name to its 2-letter abbreviation.
+ * If already a valid abbreviation (case-insensitive), returns it uppercased.
+ * For non-US/CA countries, returns the input uppercased unchanged.
+ *
+ * Matches checkout's convertStateToAbbreviation() behaviour exactly.
+ */
+function normalizeState(state, country) {
+    var _a, _b;
+    const upper = state.trim().toUpperCase();
+    const lower = state.trim().toLowerCase();
+    if (country === 'US') {
+        if (US_ABBREVS.has(upper))
+            return upper;
+        return (_a = US_STATES[lower]) !== null && _a !== void 0 ? _a : upper;
+    }
+    if (country === 'CA') {
+        if (CA_ABBREVS.has(upper))
+            return upper;
+        return (_b = CA_PROVINCES[lower]) !== null && _b !== void 0 ? _b : upper;
+    }
+    return upper;
+}
+// ─── Postal code validation ───────────────────────────────────────────────────
+const POSTAL_PATTERNS = {
+    US: /^\d{5}(-?\d{4})?$/, // 5-digit or ZIP+4 (with or without hyphen)
+    CA: /^[A-Za-z]\d[A-Za-z]\s?\d[A-Za-z]\d$/, // A1A 1A1
+    GB: /^[A-Za-z]{1,2}\d[A-Za-z\d]?\s?\d[A-Za-z]{2}$/,
+    DE: /^\d{5}$/,
+    FR: /^\d{5}$/,
+    ES: /^\d{5}$/,
+    IT: /^\d{5}$/,
+    AU: /^\d{4}$/,
+    NL: /^\d{4}\s?[A-Za-z]{2}$/,
+    BR: /^\d{5}-?\d{3}$/,
+    JP: /^\d{3}-?\d{4}$/,
+    IN: /^\d{6}$/,
+};
+/**
+ * Validates a postal/ZIP code against country-specific format rules.
+ * For countries without a specific pattern, falls back to generic 1–50 char check.
+ */
+function validatePostalCode(zip, country) {
+    if (!zip || zip.length === 0)
+        return { valid: false, error: 'Postal code is required' };
+    if (zip.length > 50)
+        return { valid: false, error: 'Postal code must be 50 characters or fewer' };
+    const pattern = POSTAL_PATTERNS[country.toUpperCase()];
+    if (pattern && !pattern.test(zip)) {
+        return { valid: false, error: `Invalid postal code format for ${country.toUpperCase()}` };
+    }
+    return { valid: true };
+}
+/**
+ * Validates and normalizes billing details against the Ozura cardSale API schema.
+ *
+ * Rules applied (same as checkout's pre-flight validation in page.tsx):
+ * - firstName, lastName: required, 1–50 chars
+ * - email: optional; if provided, must be valid format and ≤50 chars
+ * - phone: optional; if provided, must be E.164 and ≤50 chars
+ * - address fields: if address is provided, line1/city/state/zip/country are
+ *   required (1–50 chars each); line2 is optional and omitted from normalized
+ *   output if blank (cardSale schema: minLength 1 if present)
+ * - state: normalized to 2-letter abbreviation for US and CA
+ */
+function validateBilling(billing) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v;
+    const errors = [];
+    const firstName = (_b = (_a = billing.firstName) === null || _a === void 0 ? void 0 : _a.trim()) !== null && _b !== void 0 ? _b : '';
+    const lastName = (_d = (_c = billing.lastName) === null || _c === void 0 ? void 0 : _c.trim()) !== null && _d !== void 0 ? _d : '';
+    const email = (_f = (_e = billing.email) === null || _e === void 0 ? void 0 : _e.trim()) !== null && _f !== void 0 ? _f : '';
+    const phone = (_h = (_g = billing.phone) === null || _g === void 0 ? void 0 : _g.trim()) !== null && _h !== void 0 ? _h : '';
+    if (!isValidBillingField(firstName)) {
+        errors.push('billing.firstName must be 1–50 characters');
+    }
+    if (!isValidBillingField(lastName)) {
+        errors.push('billing.lastName must be 1–50 characters');
+    }
+    if (email && !validateEmail(email)) {
+        errors.push('billing.email must be a valid address (max 50 characters)');
+    }
+    if (phone && !validateE164Phone(phone)) {
+        errors.push('billing.phone must be E.164 format, e.g. "+15551234567" (max 50 characters)');
+    }
+    let normalizedAddress;
+    if (billing.address) {
+        const a = billing.address;
+        const country = (_k = (_j = a.country) === null || _j === void 0 ? void 0 : _j.trim().toUpperCase()) !== null && _k !== void 0 ? _k : '';
+        const line1 = (_m = (_l = a.line1) === null || _l === void 0 ? void 0 : _l.trim()) !== null && _m !== void 0 ? _m : '';
+        const line2 = (_p = (_o = a.line2) === null || _o === void 0 ? void 0 : _o.trim()) !== null && _p !== void 0 ? _p : '';
+        const city = (_r = (_q = a.city) === null || _q === void 0 ? void 0 : _q.trim()) !== null && _r !== void 0 ? _r : '';
+        const zip = (_t = (_s = a.zip) === null || _s === void 0 ? void 0 : _s.trim()) !== null && _t !== void 0 ? _t : '';
+        const state = normalizeState((_v = (_u = a.state) === null || _u === void 0 ? void 0 : _u.trim()) !== null && _v !== void 0 ? _v : '', country);
+        if (!isValidBillingField(line1))
+            errors.push('billing.address.line1 must be 1–50 characters');
+        if (line2 && !isValidBillingField(line2))
+            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)) {
+            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")');
+        }
+        if (!isValidBillingField(zip)) {
+            errors.push('billing.address.zip must be 1–50 characters');
+        }
+        else if (/^[A-Z]{2}$/.test(country)) {
+            const postalResult = validatePostalCode(zip, country);
+            if (!postalResult.valid) {
+                errors.push(`billing.address.zip: ${postalResult.error}`);
+            }
+        }
+        normalizedAddress = Object.assign(Object.assign({ line1 }, (line2 ? { line2 } : {})), { city,
+            state,
+            zip,
+            country });
+    }
+    const normalized = Object.assign(Object.assign(Object.assign({ firstName,
+        lastName }, (email ? { email } : {})), (phone ? { phone } : {})), (normalizedAddress ? { address: normalizedAddress } : {}));
+    return { valid: errors.length === 0, errors, normalized };
+}
+
+/**
+ * Shared postMessage protocol constants.
+ *
+ * PROTOCOL_VERSION must be incremented any time a breaking change is made to
+ * the postMessage message shape (new required fields, renamed types, removed
+ * fields, changed semantics). The SDK reads this value from OZ_FRAME_READY
+ * messages and warns when the frame and SDK are out of sync.
+ *
+ * Non-breaking additions (new optional fields, new message types that old
+ * frames can safely ignore) do NOT require a version bump.
+ */
+const PROTOCOL_VERSION = 1;
+
+/**
+ * Creates a `getSessionKey` callback for `OzVault.create()` and `<OzElements>`.
+ *
+ * This is the recommended way to wire the SDK to your backend session endpoint.
+ * If you don't need custom headers or auth logic, pass `sessionUrl` directly to
+ * `OzVault.create()` or `<OzElements>` — it calls this helper internally.
+ *
+ * The callback POSTs `{ sessionId }` to `url` and reads `sessionKey` (or the
+ * legacy `waxKey`) from the JSON response, so it is compatible with both the
+ * new `createSessionMiddleware` and the old `createMintWaxMiddleware` backends.
+ *
+ * Each call enforces a **10-second timeout**. On pure network failures
+ * (offline, DNS, connection refused) the request is retried **once after 750ms**.
+ * HTTP 4xx/5xx errors are never retried — they indicate misconfiguration.
+ *
+ * @param url - Absolute or relative URL of your session endpoint, e.g. `'/api/oz-session'`.
+ *
+ * @example
+ * // Simplest — just pass sessionUrl, no need to call this directly
+ * const vault = await OzVault.create({ pubKey: 'pk_prod_...', sessionUrl: '/api/oz-session' });
+ *
+ * @example
+ * // Manual — use when you need custom headers
+ * const vault = await OzVault.create({
+ *   pubKey: 'pk_prod_...',
+ *   getSessionKey: createSessionFetcher('/api/oz-session'),
+ * });
+ */
+function createSessionFetcher(url) {
+    const TIMEOUT_MS = 10000;
+    // Each attempt gets its own AbortController so a timeout on attempt 1 does
+    // not bleed into the retry.
+    const attemptFetch = (sessionId) => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), TIMEOUT_MS);
+        return fetch(url, {
+            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) {
+            // Timeout/abort — don't retry, we already waited the full duration.
+            if (firstErr instanceof Error && (firstErr.name === 'AbortError' || firstErr.name === 'TimeoutError')) {
+                throw new OzError(`Session endpoint timed out after ${TIMEOUT_MS / 1000}s (${url})`, undefined, 'timeout');
+            }
+            // Pure network error — retry once after a short pause.
+            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 session endpoint (${url}): ${msg}`, undefined, 'network');
+            }
+        }
+        // Parse JSON separately from the ok-check so that a non-JSON error body
+        // (HTML error page, WAF block, CDN 503) produces the right error code.
+        // Previously res.json() was attempted before res.ok was checked; a parse
+        // failure on a 5xx HTML body would fall through as {} and produce a
+        // misleading 'validation' code when the real cause is a server/network issue.
+        let data = {};
+        try {
+            data = await res.json();
+        }
+        catch (_a) {
+            if (!res.ok) {
+                throw new OzError(`Session endpoint returned HTTP ${res.status} with a non-JSON body`, undefined, res.status >= 500 ? 'server' : res.status === 401 || res.status === 403 ? 'auth' : 'validation');
+            }
+            // HTTP 200 but body isn't JSON — this is a misconfigured session endpoint.
+            throw new OzError('Session endpoint returned HTTP 200 but the response body is not valid JSON. Check your /api/oz-session implementation.', undefined, 'validation');
+        }
+        if (!res.ok) {
+            throw new OzError(typeof data.error === 'string' && data.error
+                ? data.error
+                : `Session endpoint returned HTTP ${res.status}`, undefined, res.status >= 500 ? 'server' : res.status === 401 || res.status === 403 ? 'auth' : 'validation');
+        }
+        // Accept both new `sessionKey` and legacy `waxKey` for backward compatibility
+        // with backends that haven't migrated to createSessionMiddleware yet.
+        const key = (typeof data.sessionKey === 'string' ? data.sessionKey : '') ||
+            (typeof data.waxKey === 'string' ? data.waxKey : '');
+        if (!key.trim()) {
+            throw new OzError('Session endpoint response is missing sessionKey. Check your /api/oz-session implementation.', undefined, 'validation');
+        }
+        return key;
+    };
+}
+
+function isCardMetadata(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const r = v;
+    return (typeof r.last4 === 'string' &&
+        typeof r.brand === 'string' &&
+        typeof r.expMonth === 'string' &&
+        typeof r.expYear === 'string');
+}
+function isBankAccountMetadata(v) {
+    if (!v || typeof v !== 'object')
+        return false;
+    const r = v;
+    return typeof r.last4 === 'string' && typeof r.routingNumberLast4 === '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
+ * // Recommended — pass sessionUrl and let the SDK call your backend automatically
+ * const vault = await OzVault.create({
+ *   pubKey: 'pk_prod_...',  // or 'pk_test_...' for test mode
+ *   sessionUrl: '/api/oz-session',  // backend endpoint that calls ozura.createSession()
+ * });
+ * const cardNum = vault.createElement('cardNumber');
+ * cardNum.mount('#card-number');
+ * const { token, cvcSession } = await vault.createToken({
+ *   billing: { firstName: 'Jane', lastName: 'Doe' },
+ * });
+ */
+class OzVault {
+    /**
+     * 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, _d, _e;
+        this.elements = new Map();
+        this.elementsByType = new Map();
+        this.bankElementsByType = new Map();
+        this.tokenizeResolvers = new Map();
+        this.bankTokenizeResolvers = new Map();
+        // Track completion state per element for auto-advance (only fire on transition)
+        this.completionState = new Map();
+        this.tokenizerFrame = null;
+        this.tokenizerWindow = null;
+        this.tokenizerReady = false;
+        this._tokenizing = null;
+        this._destroyed = false;
+        // Incremented every time reset() cancels an active tokenization so that
+        // any in-flight wax-key refresh retry can detect it was superseded.
+        this._resetCount = 0;
+        // 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;
+        // 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;
+        // Validate immediately after assignment
+        if (!this.frameBaseUrl.startsWith('https://') &&
+            !this.frameBaseUrl.startsWith('http://localhost')) {
+            throw new OzError('frameBaseUrl must use HTTPS (http://localhost is allowed for local development)', undefined, 'config');
+        }
+        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-${uuid()}`;
+        // sessionLimit takes precedence over legacy maxTokenizeCalls.
+        // null means unlimited — use Infinity so the ">=" check never triggers.
+        const rawLimit = options.sessionLimit !== undefined
+            ? options.sessionLimit
+            : ((_b = options.maxTokenizeCalls) !== null && _b !== void 0 ? _b : 3);
+        this._maxTokenizeCalls = rawLimit === null ? Infinity : rawLimit;
+        this._debug = (_c = options.debug) !== null && _c !== void 0 ? _c : false;
+        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 = (_d = options.loadTimeoutMs) !== null && _d !== void 0 ? _d : 10000;
+            this.loadErrorTimeoutId = setTimeout(() => {
+                this.loadErrorTimeoutId = null;
+                if (!this._destroyed && !this.tokenizerReady) {
+                    options.onLoadError();
+                }
+            }, timeout);
+        }
+        // onSessionRefresh takes precedence over legacy onWaxRefresh
+        this._onWaxRefresh = (_e = options.onSessionRefresh) !== null && _e !== void 0 ? _e : options.onWaxRefresh;
+        this._onReady = options.onReady;
+        this.log('vault created', { vaultId: this.vaultId, frameBaseUrl: this.frameBaseUrl, maxTokenizeCalls: this._maxTokenizeCalls });
+    }
+    /**
+     * Creates and returns a ready `OzVault` instance.
+     *
+     * Internally this:
+     * 1. Generates a session UUID.
+     * 2. Starts loading the hidden tokenizer iframe immediately.
+     * 3. Fetches a session key from your backend concurrently — either via
+     *    `sessionUrl` (simplest), `getSessionKey` (custom headers/auth), or the
+     *    deprecated `fetchWaxKey` callback.
+     * 4. Resolves with the vault instance once the session 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 the session fetch fails, times out, or returns an empty 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.');
+        }
+        // Normalize the session callback. Priority: sessionUrl > getSessionKey > fetchWaxKey (deprecated).
+        // This allows merchants to use the clean new API without touching legacy code.
+        let resolvedFetchKey;
+        if (options.sessionUrl) {
+            resolvedFetchKey = createSessionFetcher(options.sessionUrl);
+        }
+        else if (typeof options.getSessionKey === 'function') {
+            resolvedFetchKey = options.getSessionKey;
+        }
+        else if (typeof options.fetchWaxKey === 'function') {
+            resolvedFetchKey = options.fetchWaxKey;
+        }
+        else {
+            throw new OzError('A session URL or callback is required. Pass sessionUrl, getSessionKey, or fetchWaxKey to OzVault.create().');
+        }
+        const tokenizationSessionId = uuid();
+        // Construct the vault immediately — this mounts the tokenizer iframe so it
+        // starts loading while the session fetch is in flight.
+        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 the session fetch
+        // 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 resolvedFetchKey(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 createSessionFetcher)
+            // 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(`Session fetch 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('Session fetch returned an empty key. Check your session endpoint response — it must return { sessionKey: "..." }.');
+        }
+        // Static methods can access private fields of instances of the same class.
+        vault.waxKey = waxKey;
+        vault._storedFetchWaxKey = resolvedFetchKey;
+        // 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, debug: vault._debug });
+        }
+        vault.log('wax key received — vault ready');
+        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.
+     */
+    createElement(type, options = {}) {
+        return this.createElementInto(this.elementsByType, type, options);
+    }
+    /** Returns the existing element of the given type, or null if none has been created. */
+    getElement(type) {
+        var _a;
+        return (_a = this.elementsByType.get(type)) !== null && _a !== void 0 ? _a : null;
+    }
+    /**
+     * Creates a bank account input element (accountNumber or routingNumber).
+     * Call `.mount(selector)` on the returned element to attach it to the DOM.
+     *
+     * @example
+     * const accountEl = vault.createBankElement('accountNumber');
+     * const routingEl = vault.createBankElement('routingNumber');
+     * accountEl.mount('#account-number');
+     * routingEl.mount('#routing-number');
+     */
+    createBankElement(type, options = {}) {
+        return this.createElementInto(this.bankElementsByType, type, options);
+    }
+    /** Returns the existing bank element of the given type, or null if none has been created. */
+    getBankElement(type) {
+        var _a;
+        return (_a = this.bankElementsByType.get(type)) !== null && _a !== void 0 ? _a : null;
+    }
+    createElementInto(typeMap, type, options) {
+        if (this._destroyed) {
+            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) {
+            this.elements.delete(existing.frameId);
+            this.completionState.delete(existing.frameId);
+            existing.destroy();
+        }
+        const el = new OzElement(type, options, this.vaultId, this.frameBaseUrl, this.fonts, this.resolvedAppearance, () => {
+            // Prune vault-level maps when the element is manually destroyed so they
+            // don't grow unboundedly in SPA scenarios with repeated mount/unmount cycles.
+            this.elements.delete(el.frameId);
+            this.completionState.delete(el.frameId);
+        }, this._debug);
+        this.elements.set(el.frameId, el);
+        typeMap.set(type, el);
+        return el;
+    }
+    /**
+     * Tokenizes mounted bank account elements. Raw account and routing numbers
+     * never leave the Ozura-origin iframes — the tokenizer iframe POSTs directly
+     * to the vault API.
+     *
+     * Returns a token that can be used with any ACH-capable payment processor.
+     *
+     * **Note:** OzuraPay does not currently support bank account payments.
+     * Use this token with your own ACH processor backend.
+     *
+     * @example
+     * const { token, bank } = await vault.createBankToken({
+     *   firstName: 'Jane',
+     *   lastName: 'Smith',
+     * });
+     */
+    async createBankToken(options) {
+        var _a, _b;
+        if (this._destroyed) {
+            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.');
+        }
+        if (this._tokenizing) {
+            throw new OzError(this._tokenizing === 'card'
+                ? 'A card tokenization is already in progress. Wait for it to complete before calling createBankToken().'
+                : 'A bank tokenization is already in progress. Wait for it to complete before calling createBankToken() again.');
+        }
+        if (!((_a = options.firstName) === null || _a === void 0 ? void 0 : _a.trim())) {
+            throw new OzError('firstName is required for bank account tokenization.');
+        }
+        if (!((_b = options.lastName) === null || _b === void 0 ? void 0 : _b.trim())) {
+            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.');
+        }
+        if (options.lastName.trim().length > 50) {
+            throw new OzError('lastName must be 50 characters or fewer.');
+        }
+        const accountEl = this.bankElementsByType.get('accountNumber');
+        const routingEl = this.bankElementsByType.get('routingNumber');
+        const accountReady = !!accountEl && this.elements.has(accountEl.frameId) && accountEl.isReady;
+        const routingReady = !!routingEl && this.elements.has(routingEl.frameId) && routingEl.isReady;
+        if (!accountReady && !routingReady) {
+            throw new OzError('No bank elements are mounted and ready. Mount accountNumber and routingNumber elements before calling createBankToken.');
+        }
+        if (!accountReady) {
+            throw new OzError('accountNumber element is not mounted or not ready. Mount both accountNumber and routingNumber elements before calling createBankToken.');
+        }
+        if (!routingReady) {
+            throw new OzError('routingNumber element is not mounted or not ready. Mount both accountNumber and routingNumber elements before calling createBankToken.');
+        }
+        const readyBankElements = [accountEl, routingEl];
+        this._tokenizing = 'bank';
+        const requestId = `req-${uuid()}`;
+        this.log('createBankToken() called');
+        return new Promise((resolve, reject) => {
+            const resetCountAtStart = this._resetCount;
+            const cleanup = () => {
+                if (this._resetCount === resetCountAtStart)
+                    this._tokenizing = null;
+            };
+            this.bankTokenizeResolvers.set(requestId, {
+                resolve: (v) => { cleanup(); resolve(v); },
+                reject: (e) => { cleanup(); reject(e); },
+                firstName: options.firstName.trim(),
+                lastName: options.lastName.trim(),
+                readyElements: readyBankElements,
+                fieldCount: readyBankElements.length,
+            });
+            try {
+                const bankChannels = readyBankElements.map(() => new MessageChannel());
+                const bankTokenizeStartMs = Date.now();
+                this.sendToTokenizer({
+                    type: 'OZ_BANK_TOKENIZE',
+                    requestId,
+                    tokenizationSessionId: this.tokenizationSessionId,
+                    pubKey: this.pubKey,
+                    firstName: options.firstName.trim(),
+                    lastName: options.lastName.trim(),
+                    fieldCount: readyBankElements.length,
+                }, bankChannels.map(ch => ch.port1));
+                this.log('OZ_BANK_TOKENIZE sent', { requestIdPrefix: `${requestId.slice(0, 12)}...`, fieldCount: readyBankElements.length });
+                readyBankElements.forEach((el, i) => {
+                    this.log('OZ_BEGIN_COLLECT dispatched', { type: el.type, requestIdPrefix: `${requestId.slice(0, 12)}...` });
+                    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;
+                    bankPendingEntry.tokenizeStartMs = bankTokenizeStartMs;
+                }
+            }
+            catch (err) {
+                this.bankTokenizeResolvers.delete(requestId);
+                cleanup();
+                reject(err instanceof OzError ? err : new OzError('Bank tokenization failed to start'));
+            }
+        });
+    }
+    /**
+     * Tokenizes all mounted elements. Raw card data never leaves the Ozura-origin
+     * iframes — the tokenizer iframe POSTs directly to the vault API.
+     *
+     * Returns a token and cvcSession that can be passed to the Ozura Pay API.
+     */
+    async createToken(options = {}) {
+        var _a, _b;
+        if (this._destroyed) {
+            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.');
+        }
+        if (this._tokenizing) {
+            throw new OzError(this._tokenizing === 'bank'
+                ? '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.');
+        }
+        // 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 : '').trim();
+        let lastName = ((_b = options.lastName) !== null && _b !== void 0 ? _b : '').trim();
+        if (options.billing) {
+            const result = validateBilling(options.billing);
+            if (!result.valid) {
+                throw new OzError(`Invalid billing details: ${result.errors.join('; ')}`);
+            }
+            normalizedBilling = result.normalized;
+            firstName = normalizedBilling.firstName;
+            lastName = normalizedBilling.lastName;
+        }
+        else {
+            if (firstName.length > 50) {
+                throw new OzError('firstName must be 50 characters or fewer.');
+            }
+            if (lastName.length > 50) {
+                throw new OzError('lastName must be 50 characters or fewer.');
+            }
+        }
+        this._tokenizing = 'card';
+        const requestId = `req-${uuid()}`;
+        this.log('createToken() called', {
+            requestIdPrefix: requestId.slice(0, 12),
+            fields: readyElements.map(el => el.type),
+            billingPresent: Boolean(options.billing),
+        });
+        return new Promise((resolve, reject) => {
+            // Capture the reset generation so cleanup() only zeros _tokenizing when it
+            // still belongs to this invocation — not a newer one that started after a reset.
+            const resetCountAtStart = this._resetCount;
+            const cleanup = () => {
+                if (this._resetCount === resetCountAtStart)
+                    this._tokenizing = null;
+            };
+            this.tokenizeResolvers.set(requestId, {
+                resolve: (v) => { cleanup(); resolve(v); },
+                reject: (e) => { cleanup(); reject(e); },
+                billing: normalizedBilling,
+                firstName,
+                lastName,
+                readyElements,
+                fieldCount: readyElements.length,
+            });
+            try {
+                // Tell tokenizer frame to expect N field values, then tokenize
+                const cardChannels = readyElements.map(() => new MessageChannel());
+                const tokenizeStartMs = Date.now();
+                this.sendToTokenizer({
+                    type: 'OZ_TOKENIZE',
+                    requestId,
+                    tokenizationSessionId: this.tokenizationSessionId,
+                    pubKey: this.pubKey,
+                    firstName,
+                    lastName,
+                    fieldCount: readyElements.length,
+                }, cardChannels.map(ch => ch.port1));
+                this.log('OZ_TOKENIZE sent', { requestIdPrefix: `${requestId.slice(0, 12)}...`, fieldCount: readyElements.length });
+                // Store start time for elapsed-ms logging on result
+                const cardEntry = this.tokenizeResolvers.get(requestId);
+                if (cardEntry)
+                    cardEntry.tokenizeStartMs = tokenizeStartMs;
+                // Tell each ready element frame to send its raw value to the tokenizer
+                readyElements.forEach((el, i) => {
+                    this.log('OZ_BEGIN_COLLECT dispatched', { type: el.type, requestIdPrefix: `${requestId.slice(0, 12)}...` });
+                    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'));
+            }
+        });
+    }
+    /**
+     * Clears all mounted element fields without tearing down the vault.
+     *
+     * Call this after a failed payment (e.g. card declined) to let the customer
+     * re-enter their details. The vault instance, tokenizer iframe, wax key, and
+     * tokenization budget counter are all preserved — no network calls are made.
+     *
+     * **Wax key session model:** by design, one wax key covers the full checkout
+     * session. The default `max_tokenize_calls: 3` supports two declined attempts
+     * and one final attempt on the same key. Do not call `vault.destroy()` and
+     * recreate the vault between declines — that unnecessarily re-mints the key
+     * and discards the remaining budget.
+     *
+     * @example
+     * try {
+     *   const { token, cvcSession } = await vault.createToken({ billing });
+     *   await chargeCard(token, cvcSession);
+     * } catch (err) {
+     *   vault.reset();       // clear fields; let customer re-enter
+     *   showError(err.message);
+     * }
+     */
+    reset() {
+        if (this._destroyed)
+            return;
+        const cancelling = Boolean(this._tokenizing);
+        this.log('reset() called', { tokenizing: this._tokenizing, cancelling });
+        if (this._tokenizing) {
+            this._tokenizing = null;
+            this._resetCount++;
+            this.tokenizeResolvers.forEach(({ reject, timeoutId }, requestId) => {
+                if (timeoutId != null)
+                    clearTimeout(timeoutId);
+                this.log('OZ_TOKENIZE_CANCEL sent (reset)', { requestIdPrefix: `${requestId.slice(0, 12)}...` });
+                this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId });
+                reject(new OzError('Vault was reset while tokenization was in progress.'));
+            });
+            this.tokenizeResolvers.clear();
+            this.bankTokenizeResolvers.forEach(({ reject, timeoutId }, requestId) => {
+                if (timeoutId != null)
+                    clearTimeout(timeoutId);
+                this.log('OZ_TOKENIZE_CANCEL sent (reset, bank)', { requestIdPrefix: `${requestId.slice(0, 12)}...` });
+                this.sendToTokenizer({ type: 'OZ_TOKENIZE_CANCEL', requestId });
+                reject(new OzError('Vault was reset while tokenization was in progress.'));
+            });
+            this.bankTokenizeResolvers.clear();
+        }
+        // Clear field values in all mounted element iframes
+        this.elementsByType.forEach(el => el.clear());
+        this.bankElementsByType.forEach(el => el.clear());
+        // Reset per-element completion state so auto-advance starts fresh on re-entry
+        for (const frameId of this.completionState.keys()) {
+            this.completionState.set(frameId, false);
+        }
+        // NOTE: _tokenizeSuccessCount is intentionally NOT reset.
+        // It reflects real server-side wax key budget consumption. Zeroing it
+        // would desync the proactive refresh logic from the vault's state and
+        // risk triggering a mid-session re-mint on what should be a clean retry.
+    }
+    /**
+     * Tears down the vault: removes all element iframes, the tokenizer iframe,
+     * and the global message listener. Call this when the checkout component
+     * unmounts (e.g. in React's useEffect cleanup or a SPA route change).
+     */
+    destroy() {
+        var _a;
+        if (this._destroyed)
+            return;
+        this._destroyed = true;
+        this.log('destroy() called');
+        window.removeEventListener('message', this.boundHandleMessage);
+        document.removeEventListener('visibilitychange', this.boundHandleVisibility);
+        if (this._pendingMount) {
+            document.removeEventListener('DOMContentLoaded', this._pendingMount);
+            this._pendingMount = null;
+        }
+        if (this.loadErrorTimeoutId != null) {
+            clearTimeout(this.loadErrorTimeoutId);
+            this.loadErrorTimeoutId = null;
+        }
+        // Reject any pending tokenize promises so callers aren't left hanging
+        this._tokenizing = null;
+        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, 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();
+        this.elements.forEach(el => el.destroy());
+        this.elements.clear();
+        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();
+            this.log('tab hidden');
+        }
+        else {
+            const hiddenMs = this._hiddenAt !== null ? Date.now() - this._hiddenAt : 0;
+            const willRefresh = (this._hiddenAt !== null &&
+                hiddenMs >= REFRESH_THRESHOLD_MS &&
+                Boolean(this._storedFetchWaxKey) &&
+                !this._tokenizing &&
+                !this._waxRefreshing);
+            this.log('tab visible', { hiddenMs, willRefresh });
+            if (willRefresh) {
+                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;
+        }
+    }
+    // ─── Debug ───────────────────────────────────────────────────────────────
+    /**
+     * Emits a `[OzVault]`-prefixed entry to `console.log`. No-op when `debug` is
+     * not set. Never called with sensitive values — callers use presence flags only.
+     */
+    log(message, data) {
+        if (!this._debug)
+            return;
+        if (data !== undefined) {
+            console.log(`[OzVault] ${message}`, data);
+        }
+        else {
+            console.log(`[OzVault] ${message}`);
+        }
+    }
+    /**
+     * Returns a plain-object snapshot of the vault's current internal state.
+     * Safe to attach to bug reports — no wax keys, tokens, or billing data included.
+     *
+     * Available on all vault instances regardless of whether `debug` was enabled.
+     *
+     * @example
+     * console.log(vault.debugState());
+     * // {
+     * //   vaultId: 'vault-abc123',
+     * //   isReady: true,
+     * //   tokenizing: null,
+     * //   destroyed: false,
+     * //   waxKeyPresent: true,
+     * //   elements: ['cardNumber', 'expirationDate', 'cvv'],
+     * //   ...
+     * // }
+     */
+    debugState() {
+        return {
+            vaultId: this.vaultId,
+            isReady: this.tokenizerReady,
+            tokenizing: this._tokenizing,
+            destroyed: this._destroyed,
+            waxKeyPresent: Boolean(this.waxKey),
+            tokenizeSuccessCount: this._tokenizeSuccessCount,
+            maxTokenizeCalls: this._maxTokenizeCalls,
+            resetCount: this._resetCount,
+            elements: [...this.elementsByType.keys()],
+            bankElements: [...this.bankElementsByType.keys()],
+            completionState: Object.fromEntries([...this.completionState.entries()].map(([id, v]) => [id.slice(0, 8), v])),
+            pendingTokenizations: this.tokenizeResolvers.size,
+            pendingBankTokenizations: this.bankTokenizeResolvers.size,
+        };
+    }
+    mountTokenizerFrame() {
+        const mount = () => {
+            this._pendingMount = null;
+            const iframe = document.createElement('iframe');
+            iframe.style.cssText = 'position:absolute;top:-9999px;left:-9999px;width:1px;height:1px;';
+            iframe.setAttribute('aria-hidden', 'true');
+            iframe.tabIndex = -1;
+            const parentOrigin = typeof window !== 'undefined' ? window.location.origin : '';
+            iframe.src = `${this.frameBaseUrl}/frame/tokenizer-frame.html#vaultId=${encodeURIComponent(this.vaultId)}${parentOrigin ? `&parentOrigin=${encodeURIComponent(parentOrigin)}` : ''}`;
+            document.body.appendChild(iframe);
+            this.tokenizerFrame = iframe;
+            this.log('mounting tokenizer iframe');
+        };
+        if (document.readyState === 'loading') {
+            this._pendingMount = mount;
+            document.addEventListener('DOMContentLoaded', mount);
+        }
+        else {
+            mount();
+        }
+    }
+    handleMessage(event) {
+        var _a, _b;
+        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)
+            return;
+        const msg = event.data;
+        if (!msg || msg.__oz !== true || msg.vaultId !== this.vaultId)
+            return;
+        // Route tokenizer messages
+        if (event.source === ((_a = this.tokenizerFrame) === null || _a === void 0 ? void 0 : _a.contentWindow)) {
+            this.handleTokenizerMessage(msg);
+            return;
+        }
+        // OZ_TOKEN_ERROR can arrive from element frames when the MessagePort
+        // transferred in OZ_BEGIN_COLLECT was dropped by the browser (e.g. the
+        // frame navigated). These carry a requestId but no frameId — route them
+        // through handleTokenizerMessage so the pending promise is rejected
+        // immediately rather than waiting for the 30 s collect timeout.
+        if (msg.type === 'OZ_TOKEN_ERROR') {
+            this.handleTokenizerMessage(msg);
+            return;
+        }
+        // Route to the matching element
+        const frameId = msg.frameId;
+        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);
+                    if (msg.__ozVersion !== PROTOCOL_VERSION) {
+                        console.warn(`[OzVault] Protocol version mismatch on element frame "${frameId}" — ` +
+                            `SDK expects v${PROTOCOL_VERSION}, frame reported v${typeof msg.__ozVersion === 'number' ? msg.__ozVersion : '(none)'}. ` +
+                            'Deploy the matching frame assets to elements.ozura.com and purge the Azure CDN cache.');
+                    }
+                    this.log('element iframe ready', { type: el.type, frameIdPrefix: frameId.slice(0, 8) });
+                }
+                // Relay debug/warning messages from element iframes into the parent
+                // DevTools console. Element frames run in cross-origin iframes whose
+                // console context is invisible to developers without a frame selector switch.
+                // Errors are always surfaced (genuine failures). Warnings are only emitted
+                // when debug mode is on — CSS var() and font-host warnings fire on every
+                // style update and would pollute production consoles otherwise.
+                if (msg.type === 'OZ_DEBUG_LOG') {
+                    const level = typeof msg.level === 'string' ? msg.level : 'warn';
+                    const message = typeof msg.message === 'string' ? msg.message : String((_b = msg.message) !== null && _b !== void 0 ? _b : '');
+                    if (level === 'error') {
+                        console.error(`[OzVault:${el.type}] ${message}`);
+                    }
+                    else if (this._debug) {
+                        console.warn(`[OzVault:${el.type}] ${message}`);
+                    }
+                    return;
+                }
+                // Intercept OZ_CHANGE before forwarding — handle auto-advance and CVV sync
+                if (msg.type === 'OZ_CHANGE') {
+                    this.handleElementChange(msg, el);
+                }
+                el.handleMessage(msg);
+            }
+        }
+    }
+    /**
+     * Handles side-effects that the SDK manages internally when a field changes:
+     * - CVV length sync when card brand changes
+     * - Auto-advance focus when a field completes
+     */
+    handleElementChange(msg, el) {
+        var _a, _b, _c;
+        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 && 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;
+        this.log('field changed', { type: el.type, complete, valid, justCompleted });
+        // Sync CVV length when card brand changes
+        if (el.type === 'cardNumber') {
+            const brand = msg.cardBrand;
+            const cvvEl = this.elementsByType.get('cvv');
+            if (cvvEl && brand) {
+                cvvEl.setCvvLength(brand === 'amex' ? 4 : 3);
+            }
+        }
+        // Auto-advance focus on completion
+        if (justCompleted) {
+            if (el.type === 'cardNumber') {
+                this.log('auto-advance', { from: 'cardNumber', to: 'expirationDate' });
+                (_b = this.elementsByType.get('expirationDate')) === null || _b === void 0 ? void 0 : _b.focus();
+            }
+            else if (el.type === 'expirationDate') {
+                this.log('auto-advance', { from: 'expirationDate', to: 'cvv' });
+                (_c = this.elementsByType.get('cvv')) === null || _c === void 0 ? void 0 : _c.focus();
+            }
+        }
+    }
+    handleTokenizerMessage(msg) {
+        var _a, _b, _c, _d, _e;
+        switch (msg.type) {
+            case 'OZ_FRAME_READY':
+                if (msg.__ozVersion !== PROTOCOL_VERSION) {
+                    console.warn(`[OzVault] Protocol version mismatch — SDK expects v${PROTOCOL_VERSION}, ` +
+                        `tokenizer frame reported v${typeof msg.__ozVersion === 'number' ? msg.__ozVersion : '(none)'}. ` +
+                        'This usually means the deployed frame files are stale. ' +
+                        'Deploy the matching frame assets to elements.ozura.com and purge the Azure CDN cache.');
+                }
+                this.tokenizerReady = true;
+                if (this.loadErrorTimeoutId != null) {
+                    clearTimeout(this.loadErrorTimeoutId);
+                    this.loadErrorTimeoutId = null;
+                }
+                this.tokenizerWindow = (_b = (_a = this.tokenizerFrame) === null || _a === void 0 ? void 0 : _a.contentWindow) !== null && _b !== void 0 ? _b : null;
+                // 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(Object.assign({ type: 'OZ_INIT', frameId: '__tokenizer__' }, (this.waxKey ? { waxKey: this.waxKey } : {})), { debug: this._debug }));
+                (_c = this._onReady) === null || _c === void 0 ? void 0 : _c.call(this);
+                this.log('tokenizer iframe ready', { protocolVersion: (_d = msg.__ozVersion) !== null && _d !== void 0 ? _d : null });
+                this.log('vault state', this.debugState());
+                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);
+                    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;
+                    const cvcSession = typeof msg.cvcSession === 'string' && msg.cvcSession ? msg.cvcSession : undefined;
+                    if (!cvcSession) {
+                        pending.reject(new OzError('Vault returned a token result without a cvcSession — possible vault misconfiguration or API change.', undefined, 'server'));
+                        break;
+                    }
+                    pending.resolve(Object.assign(Object.assign({ token,
+                        cvcSession }, (card ? { card } : {})), (pending.billing ? { billing: pending.billing } : {})));
+                    this.log('token received', {
+                        requestIdPrefix: msg.requestId.slice(0, 12),
+                        elapsedMs: pending.tokenizeStartMs != null ? Date.now() - pending.tokenizeStartMs : null,
+                        tokenPresent: true,
+                        cvcSessionPresent: true,
+                        cardMetadataPresent: Boolean(card),
+                    });
+                    // 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.log('proactive session key refresh triggered', { tokenizeSuccessCount: this._tokenizeSuccessCount, maxTokenizeCalls: this._maxTokenizeCalls });
+                        this.refreshWaxKey().catch((err) => {
+                            console.warn('[OzVault] Post-budget session 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);
+                    if (pending.timeoutId != null)
+                        clearTimeout(pending.timeoutId);
+                    const willRefresh = this.isRefreshableAuthError(errorCode, raw) && !pending.retried && Boolean(this._storedFetchWaxKey);
+                    this.log('token error', { requestIdPrefix: msg.requestId.slice(0, 12), errorCode, willRefresh });
+                    // 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 (willRefresh) {
+                        const resetCountAtRetry = this._resetCount;
+                        this.refreshWaxKey().then(() => {
+                            if (this._destroyed) {
+                                pending.reject(new OzError('Vault destroyed during wax key refresh.'));
+                                return;
+                            }
+                            if (this._resetCount !== resetCountAtRetry) {
+                                // reset() was called while the wax key was refreshing — the fields
+                                // have been cleared and _tokenizing was zeroed. Reject the original
+                                // promise so it doesn't stay pending, and bail out without starting
+                                // a new retry (which would tokenize against empty fields).
+                                pending.reject(new OzError('Vault was reset while tokenization was in progress.'));
+                                return;
+                            }
+                            // Verify all elements from the original call are still mounted and
+                            // ready. If any were destroyed (e.g. the merchant called
+                            // createElement() or destroy() during the async refresh), the
+                            // beginCollect() calls below would silently no-op — the tokenizer
+                            // would wait forever for field values that never arrive. Reject
+                            // immediately with a clear message instead of hanging 30 seconds.
+                            const allCardElementsStillReady = pending.readyElements.every(el => this.elements.has(el.frameId) && el.isReady);
+                            if (!allCardElementsStillReady) {
+                                pending.reject(new OzError('Card fields changed during session refresh. Please re-enter your card details.'));
+                                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,
+                                    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) => {
+                                    this.log('OZ_BEGIN_COLLECT dispatched (retry)', { type: el.type, requestIdPrefix: `${newRequestId.slice(0, 12)}...` });
+                                    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 errMsg = refreshErr instanceof Error ? refreshErr.message : 'Wax key refresh failed';
+                            pending.reject(new OzError(errMsg, undefined, 'auth'));
+                        });
+                        break;
+                    }
+                    pending.reject(new OzError(normalizeVaultError(raw), raw, errorCode));
+                }
+                else {
+                    // Also check bank resolvers — both card and bank errors use OZ_TOKEN_ERROR.
+                    // Use else-if rather than sequential checks so a UUID collision (however
+                    // improbable) can never trigger double-rejection of two unrelated resolvers.
+                    const bankPending = this.bankTokenizeResolvers.get(msg.requestId);
+                    if (bankPending) {
+                        this.bankTokenizeResolvers.delete(msg.requestId);
+                        if (bankPending.timeoutId != null)
+                            clearTimeout(bankPending.timeoutId);
+                        if (this.isRefreshableAuthError(errorCode, raw) && !bankPending.retried && this._storedFetchWaxKey) {
+                            const resetCountAtRetry = this._resetCount;
+                            this.refreshWaxKey().then(() => {
+                                if (this._destroyed) {
+                                    bankPending.reject(new OzError('Vault destroyed during wax key refresh.'));
+                                    return;
+                                }
+                                if (this._resetCount !== resetCountAtRetry) {
+                                    bankPending.reject(new OzError('Vault was reset while tokenization was in progress.'));
+                                    return;
+                                }
+                                // Same stale-element guard as the card retry path above.
+                                const allBankElementsStillReady = bankPending.readyElements.every(el => this.elements.has(el.frameId) && el.isReady);
+                                if (!allBankElementsStillReady) {
+                                    bankPending.reject(new OzError('Bank fields changed during session refresh. Please re-enter your account details.'));
+                                    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,
+                                        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) => {
+                                        this.log('OZ_BEGIN_COLLECT dispatched (retry)', { type: el.type, requestIdPrefix: `${newRequestId.slice(0, 12)}...` });
+                                        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 errMsg = refreshErr instanceof Error ? refreshErr.message : 'Wax key refresh failed';
+                                bankPending.reject(new OzError(errMsg, undefined, 'auth'));
+                            });
+                            break;
+                        }
+                        bankPending.reject(new OzError(normalizeBankVaultError(raw), raw, errorCode));
+                    }
+                } // end else (bank path)
+                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);
+                    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 } : {})));
+                    this.log('bank token received', {
+                        elapsedMs: pending.tokenizeStartMs != null ? Date.now() - pending.tokenizeStartMs : null,
+                        tokenPresent: true,
+                        bankMetadataPresent: Boolean(bank),
+                    });
+                    // Same proactive refresh logic as card tokenization.
+                    this._tokenizeSuccessCount++;
+                    if (this._tokenizeSuccessCount >= this._maxTokenizeCalls) {
+                        this.log('proactive session key refresh triggered', { tokenizeSuccessCount: this._tokenizeSuccessCount, maxTokenizeCalls: this._maxTokenizeCalls });
+                        this.refreshWaxKey().catch((err) => {
+                            console.warn('[OzVault] Post-budget session key refresh failed:', err instanceof Error ? err.message : err);
+                        });
+                    }
+                }
+                break;
+            }
+            case 'OZ_DEBUG_LOG': {
+                // Relay warnings/errors from the tokenizer iframe into the parent page's
+                // DevTools console. The tokenizer runs in a cross-origin iframe whose
+                // console context is invisible to most developers unless they manually
+                // switch the DevTools frame selector.
+                // Errors are always surfaced; warnings only in debug mode to avoid
+                // polluting production consoles.
+                const level = typeof msg.level === 'string' ? msg.level : 'warn';
+                const message = typeof msg.message === 'string' ? msg.message : String((_e = msg.message) !== null && _e !== void 0 ? _e : '');
+                if (level === 'error') {
+                    console.error(`[OzVault:tokenizer] ${message}`);
+                }
+                else if (this._debug) {
+                    console.warn(`[OzVault:tokenizer] ${message}`);
+                }
+                break;
+            }
+        }
+    }
+    /**
+     * 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);
+        const refreshStartMs = Date.now();
+        this.log('wax key refresh started');
+        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, debug: this._debug });
+            }
+            this.log('wax key refresh succeeded', { durationMs: Date.now() - refreshStartMs });
+        })
+            .catch((err) => {
+            this.log('wax key refresh failed', { error: err instanceof Error ? err.message : String(err), durationMs: Date.now() - refreshStartMs });
+            throw err;
+        })
+            .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, transfer !== null && transfer !== void 0 ? transfer : []);
+    }
+}
+
+/**
+ * @ozura/elements/vue — Vue 3 wrapper for OzElements.
+ *
+ * Provides a context-based provider that creates and manages an OzVault instance,
+ * five individual field components, and a composable to access createToken +
+ * readiness state from anywhere inside the provider tree.
+ *
+ * Quick start:
+ * @example
+ * ```vue
+ * <script setup lang="ts">
+ * import { OzElements, OzCardNumber, OzExpiry, OzCvv, useOzElements } from '@ozura/elements/vue';
+ * const { createToken, ready } = useOzElements();
+ * </script>
+ *
+ * <template>
+ *   <OzElements pub-key="pk_live_..." session-url="/api/oz-session">
+ *     <OzCardNumber />
+ *     <OzExpiry />
+ *     <OzCvv />
+ *     <button :disabled="!ready" @click="createToken()">Pay</button>
+ *   </OzElements>
+ * </template>
+ * ```
+ */
+const OZ_KEY = Symbol('oz-elements');
+// ─── Provider ─────────────────────────────────────────────────────────────────
+/**
+ * Creates and owns an OzVault instance for the lifetime of this component.
+ * All field components must be rendered inside this provider.
+ */
+const OzElements = defineComponent({
+    name: 'OzElements',
+    props: {
+        pubKey: { type: String, required: true },
+        sessionUrl: { type: String, default: undefined },
+        getSessionKey: { type: Function, default: undefined },
+        frameBaseUrl: { type: String, default: undefined },
+        fonts: { type: Array, default: undefined },
+        appearance: { type: Object, default: undefined },
+        loadTimeoutMs: { type: Number, default: undefined },
+        debug: { type: Boolean, default: undefined },
+    },
+    emits: ['ready'],
+    setup(props, { slots, emit }) {
+        const vault = shallowRef(null);
+        const initError = ref(null);
+        const mountedCount = ref(0);
+        const readyCount = ref(0);
+        const tokenizeCount = ref(0);
+        const notifyMount = () => { mountedCount.value++; };
+        let readyEmitted = false;
+        const notifyReady = () => {
+            readyCount.value++;
+            if (!readyEmitted && mountedCount.value > 0 && readyCount.value >= mountedCount.value) {
+                readyEmitted = true;
+                emit('ready');
+            }
+        };
+        const notifyUnmount = () => {
+            mountedCount.value = Math.max(0, mountedCount.value - 1);
+            readyCount.value = Math.max(0, readyCount.value - 1);
+        };
+        const notifyTokenize = () => { tokenizeCount.value++; };
+        provide(OZ_KEY, {
+            vault,
+            initError,
+            mountedCount,
+            readyCount,
+            tokenizeCount,
+            notifyMount,
+            notifyReady,
+            notifyUnmount,
+            notifyTokenize,
+        });
+        let createdVault = null;
+        let abortController = null;
+        onMounted(() => {
+            const ac = new AbortController();
+            abortController = ac;
+            OzVault.create(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign(Object.assign({ pubKey: props.pubKey }, (props.sessionUrl ? { sessionUrl: props.sessionUrl } : {})), (props.getSessionKey ? { getSessionKey: props.getSessionKey } : {})), (props.frameBaseUrl ? { frameBaseUrl: props.frameBaseUrl } : {})), (props.fonts ? { fonts: props.fonts } : {})), (props.appearance ? { appearance: props.appearance } : {})), (props.loadTimeoutMs !== undefined ? { loadTimeoutMs: props.loadTimeoutMs } : {})), (props.debug ? { debug: props.debug } : {})), ac.signal).then(v => {
+                if (ac.signal.aborted) {
+                    v.destroy();
+                    return;
+                }
+                createdVault = v;
+                vault.value = v;
+                initError.value = null;
+            }).catch((err) => {
+                if (ac.signal.aborted)
+                    return;
+                initError.value = err instanceof Error ? err : new Error('OzVault.create() failed.');
+            });
+        });
+        onUnmounted(() => {
+            abortController === null || abortController === void 0 ? void 0 : abortController.abort();
+            createdVault === null || createdVault === void 0 ? void 0 : createdVault.destroy();
+            vault.value = null;
+        });
+        return () => { var _a; return (_a = slots.default) === null || _a === void 0 ? void 0 : _a.call(slots); };
+    },
+});
+/**
+ * Returns createToken, createBankToken, ready, initError, tokenizeCount, and reset.
+ * Must be called from inside an <OzElements> provider tree.
+ *
+ * @throws {Error} if called outside an <OzElements> provider
+ */
+function useOzElements() {
+    const ctx = inject(OZ_KEY);
+    if (!ctx) {
+        throw new Error('[OzVault] useOzElements() must be called inside <OzElements>');
+    }
+    const { vault, initError, mountedCount, readyCount, tokenizeCount, notifyTokenize } = ctx;
+    const ready = computed(() => vault.value !== null &&
+        vault.value.isReady &&
+        mountedCount.value > 0 &&
+        readyCount.value >= mountedCount.value);
+    const createToken = async (options) => {
+        if (!vault.value) {
+            throw new Error('[OzVault] vault is not ready — wait for ready before calling createToken()');
+        }
+        const result = await vault.value.createToken(options);
+        notifyTokenize();
+        return result;
+    };
+    const createBankToken = async (options) => {
+        if (!vault.value) {
+            throw new Error('[OzVault] vault is not ready — wait for ready before calling createBankToken()');
+        }
+        const result = await vault.value.createBankToken(options);
+        notifyTokenize();
+        return result;
+    };
+    const reset = () => { var _a; (_a = vault.value) === null || _a === void 0 ? void 0 : _a.reset(); };
+    return { createToken, createBankToken, ready, initError, tokenizeCount, reset };
+}
+function createFieldComponent(displayName, mountElement) {
+    return defineComponent({
+        name: displayName,
+        props: {
+            placeholder: { type: String, default: undefined },
+            disabled: { type: Boolean, default: undefined },
+            style: { type: Object, default: undefined },
+        },
+        emits: ['change', 'focus', 'blur'],
+        setup(props, { emit }) {
+            const ctx = inject(OZ_KEY);
+            if (!ctx) {
+                throw new Error('[OzVault] useOzElements() must be called inside <OzElements>');
+            }
+            const { vault, notifyMount, notifyReady, notifyUnmount } = ctx;
+            const containerRef = ref(null);
+            let element = null;
+            let notifyMountCalled = false;
+            watch(vault, (v) => {
+                if (!v || !containerRef.value || element)
+                    return;
+                element = mountElement(v, {
+                    style: props.style,
+                    placeholder: props.placeholder,
+                    disabled: props.disabled,
+                });
+                notifyMountCalled = true;
+                notifyMount();
+                element.on('ready', () => notifyReady());
+                element.on('change', (e) => emit('change', e));
+                element.on('focus', () => emit('focus'));
+                element.on('blur', () => emit('blur'));
+                element.mount(containerRef.value);
+            }, { immediate: true });
+            onUnmounted(() => {
+                element === null || element === void 0 ? void 0 : element.destroy();
+                element = null;
+                if (notifyMountCalled)
+                    notifyUnmount();
+            });
+            watch(() => ({
+                style: props.style,
+                placeholder: props.placeholder,
+                disabled: props.disabled,
+            }), (opts) => { element === null || element === void 0 ? void 0 : element.update(opts); }, { deep: true });
+            return () => h('div', { ref: containerRef });
+        },
+    });
+}
+/** Card number field. Emits `change` (ElementChangeEvent), `focus`, `blur`. */
+const OzCardNumber = createFieldComponent('OzCardNumber', (v, opts) => v.createElement('cardNumber', opts));
+/** Expiry date field. Emits `change` (ElementChangeEvent), `focus`, `blur`. */
+const OzExpiry = createFieldComponent('OzExpiry', (v, opts) => v.createElement('expirationDate', opts));
+/** CVV / CVC field. Emits `change` (ElementChangeEvent), `focus`, `blur`. */
+const OzCvv = createFieldComponent('OzCvv', (v, opts) => v.createElement('cvv', opts));
+/** Bank account number field. Emits `change` (ElementChangeEvent), `focus`, `blur`. */
+const OzBankAccountNumber = createFieldComponent('OzBankAccountNumber', (v, opts) => v.createBankElement('accountNumber', opts));
+/** Bank routing number field. Emits `change` (ElementChangeEvent), `focus`, `blur`. */
+const OzBankRoutingNumber = createFieldComponent('OzBankRoutingNumber', (v, opts) => v.createBankElement('routingNumber', opts));
+
+export { OzBankAccountNumber, OzBankRoutingNumber, OzCardNumber, OzCvv, OzElements, OzExpiry, useOzElements };
+//# sourceMappingURL=index.esm.js.map