@alipay/ams-checkout 0.0.1788166152-dev.0 → 0.0.1788166152-dev.2

package/types.d.ts

@@ -215,30 +215,51 @@ export declare type AntomPreloadElement = 'payment' | 'express' | 'vaulting' | '
  */
 export declare class AntomSDK extends BaseElementsFactory {
     static version: string;
+    private stopModalMessageMonitor;
+    private readonly apiTracker;
     constructor(config?: AntomSDKConfig);
     protected canUseElements(): Array<ElementListItemType>;
+    init(): Promise<this>;
     /**
      * @description 更新配置
      */
     updateConfig(config: Partial<BaseFactoryConfig>): void;
+    destroy(): void;
     /* Excluded from this release type: redirect */
     /* Excluded from this release type: openModal */
     elements(): Elements;
     createElement(elementType: 'payment', options?: PaymentAppConfig): PaymentElement;
     createElement(elementType: 'vaulting', options?: VaultingAppConfig): VaultingElement;
-    createElement(elementType: 'CVV', options?: CVVAppConfig): CVVElement;
+    createElement(elementType: 'CVV', options: CVVAppConfig): CVVElement;
     createElement(elementType: 'express', options?: ExpressAppConfig): ExpressElement;
+    createElement(elementType: 'expressVaulting', options?: ExpressVaultingAppConfig): ExpressVaultingElement;
     getElement(elementType: 'payment', options?: PaymentAppConfig): PaymentElement;
     getElement(elementType: 'vaulting', options?: VaultingAppConfig): VaultingElement;
     getElement(elementType: 'CVV', options?: CVVAppConfig): CVVElement;
     getElement(elementType: 'express', options?: ExpressAppConfig): ExpressElement;
+    getElement(elementType: 'expressVaulting', options?: ExpressVaultingAppConfig): ExpressVaultingElement;
     /**
      * 从 elements 容器或直接传入的 MainElement 中提取指定类型的主元素
      * @throws {AntomSDKError} 当无法找到有效的主元素时抛出错误
      */
     private extractMainElement;
     confirmCardSetup(options: ConfirmCardSetupOptions): Promise<SubmitResult>;
+    private runConfirmCardSetup;
     confirmPayment(options: ConfirmPaymentOptions): Promise<SubmitResult>;
+    private runConfirmPayment;
+    /**
+     * 触发 Express Vaulting element 的 PayPal 绑卡提交流程。
+     *
+     * iframe 收到 OPENSDK@CONFIRM_VAULTING 后执行 submitPay + 单次 inquiry 兜底，
+     * 完成后通过 OPENSDK@CONFIRM_VAULTING_RESULT 回包，Promise resolve。
+     *
+     * @param options.elements 已挂载的 ExpressVaultingElement 或包含它的 Elements 实例
+     * @param options.redirect 跳转策略，默认 'always'，透传给 iframe
+     */
+    confirmVaulting(options: {
+        elements: BaseMainElement | BaseElements;
+        redirect?: 'always' | 'if_required';
+    }): Promise<ExpressVaultingResult>;
 }
 
 /**
@@ -298,9 +319,29 @@ export declare const AntomSDKErrorCodes: {
      */
     readonly AMOUNT_VALUE_EMPTY: "AMOUNT_VALUE_EMPTY";
     /**
-     * @description 金额格式非法（仅允许整数和小数）
+     * @description 金额格式非法（仅允许 ASCII 数字字符串）
      */
     readonly AMOUNT_VALUE_INVALID: "AMOUNT_VALUE_INVALID";
+    /**
+     * @description Amount currency does not match the payment session currency
+     */
+    readonly AMOUNT_CURRENCY_MISMATCH: "AMOUNT_CURRENCY_MISMATCH";
+    /**
+     * @description Amount currency is not supported
+     */
+    readonly AMOUNT_CURRENCY_UNSUPPORTED: "AMOUNT_CURRENCY_UNSUPPORTED";
+    /**
+     * @description Amount currency precision is not supported
+     */
+    readonly AMOUNT_PRECISION_UNSUPPORTED: "AMOUNT_PRECISION_UNSUPPORTED";
+    /**
+     * @description Amount conversion timed out
+     */
+    readonly AMOUNT_RESOLVE_TIMEOUT: "AMOUNT_RESOLVE_TIMEOUT";
+    /**
+     * @description Amount conversion failed
+     */
+    readonly AMOUNT_RESOLVE_FAILED: "AMOUNT_RESOLVE_FAILED";
     readonly GENERATE_ELEMENT_KEY_FAILED: "GENERATE_ELEMENT_KEY_FAILED";
     readonly ELEMENT_INIT_FAILED: "ELEMENT_INIT_FAILED";
     readonly MOUNT_TIMEOUT: "MOUNT_TIMEOUT";
@@ -314,7 +355,9 @@ export declare const AntomSDKErrorCodes: {
     readonly ELEMENT_ALREADY_REGISTERED: "ELEMENT_ALREADY_REGISTERED";
     readonly CANNOT_CREATE_SAME_ELEMENT_TWICE: "CANNOT_CREATE_SAME_ELEMENT_TWICE";
     readonly GROUPS_ONLY_ONE_MAIN_ELEMENT: "GROUPS_ONLY_ONE_MAIN_ELEMENT";
-    readonly GROUPS_NOT_FOUND_MAIN_ELEMENT: "GROUPS_NOT_FOUND_MAIN_ELEMENT";
+    readonly GROUPS_NOT_FOUND_MAIN_ELEMENT: "GROUPS_NOT_FOUND_MAIN_ELEMENT"; /**
+    * @description 环境配置，默认为prod
+    */
     readonly NOT_SUPPORT_ELEMENT: "NOT_SUPPORT_ELEMENT";
     readonly NOT_SUPPORT_SUBMIT: "NOT_SUPPORT_SUBMIT";
     readonly UPDATE_CONFIG_TIMEOUT: "UPDATE_CONFIG_TIMEOUT";
@@ -336,28 +379,100 @@ export declare type AntomSDKErrorCodes = (typeof AntomSDKErrorCodes)[keyof typeo
 
 export declare type AntomTheme = 'default' | 'agateGreen' | 'night' | 'nostalgicGray' | 'gamingPurple' | 'cherryBlossomPink' | 'light';
 
-export declare type AntomVariables = 'content-primary' | 'content-secondary' | 'content-tertiary' | 'content-quaternary' | 'background-primary' | 'background-secondary' | 'background-disable' | 'background-transparency' | 'border-primary' | 'border-secondary' | 'border-disable' | 'action-normal' | 'action-hover' | 'action-disable' | 'action-secondary' | 'state-failure' | 'state-warning' | 'state-success' | 'state-info' | 'state-marketing' | 'state-conventional' | 'radius-backup' | 'radius-module' | 'radius-component' | 'radius-button' | 'wrapper-padding' | 'stroke-default' | 'stroke-active' | 'fontFamily';
+/**
+ * @deprecated Use {@link AppearanceVariables} (Token 2.0) instead.
+ * 保留仅为向后兼容，将在下一个 major 版本中删除。
+ */
+export declare type AntomVariables = LegacyAppearanceVariables;
 
 /**
  * @description SDK UI组件的外观配置。
  * 控制主题、CSS变量、布局规则及显示设置。
  * @template Props - 自定义外观属性类型，默认为 DefaultAppearanceProps。
  */
-declare interface Appearance<Props extends Partial<DefaultAppearanceProps> = DefaultAppearanceProps> {
+declare interface Appearance<Props extends Partial<DefaultAppearanceProps> = DefaultAppearanceProps, Rules extends CSS_2.Properties<string, number> = CSS_2.Properties<string, number>> {
     theme?: Props['theme'];
     variables?: PartialSpeKey<Props['variables'], string>;
-    rules?: PartialSpeKey<Props['rules'], CSS_2.Properties<string, number>>;
+    rules?: PartialSpeKey<Props['rules'], Rules>;
     displaySetting?: PartialSpeKey<Props['displaySetting'], boolean>;
     layout?: Props['layout'];
     fonts?: FontSource[];
 }
 
-export declare type AppearanceSetting = {
-    displaySetting: Record<'showCardBrandIcon', boolean>;
-    theme: 'light' | 'dark';
-    layout: 'accordion' | 'tabs';
+/** Target-level layout declarations admitted before runtime capability intersection. */
+export declare type AppearanceLayoutDeclarations = {
+    [Property in Exclude<AppearanceLayoutProperty, 'height'>]?: AppearanceSpacingValue;
+} & {
+    /** Exact integer-pixel enum allocated by the target contract. */
+    readonly height?: `${number}px`;
 };
 
+/** Controlled layout longhands intersected with the concrete Part at runtime. */
+export declare type AppearanceLayoutProperty = 'marginTop' | 'marginRight' | 'marginBottom' | 'marginLeft' | 'paddingTop' | 'paddingRight' | 'paddingBottom' | 'paddingLeft' | 'height';
+
+/** Paint declarations accepted before WebApp and Components runtime validation. */
+declare type AppearancePaintDeclarations = Partial<Record<Exclude<AppearancePaintProperty, 'fillOpacity' | 'strokeOpacity' | 'strokeWidth' | 'textDecorationStyle' | 'outlineStyle'>, string> & Record<'fillOpacity' | 'strokeOpacity' | 'strokeWidth', string | number> & {
+    textDecorationStyle: '-moz-initial' | 'inherit' | 'initial' | 'revert' | 'revert-layer' | 'unset' | 'dashed' | 'dotted' | 'double' | 'solid' | 'wavy';
+    outlineStyle: '-moz-initial' | 'inherit' | 'initial' | 'revert' | 'revert-layer' | 'unset' | 'auto' | 'dashed' | 'dotted' | 'double' | 'groove' | 'inset' | 'none' | 'outset' | 'ridge' | 'solid';
+}>;
+
+/** Paint-only property names exposed by the SDK contract. */
+export declare type AppearancePaintProperty = 'color' | 'WebkitTextFillColor' | 'textDecorationColor' | 'textDecorationLine' | 'textDecorationStyle' | 'textShadow' | 'backgroundColor' | 'borderColor' | 'borderTopColor' | 'borderRightColor' | 'borderBottomColor' | 'borderLeftColor' | 'borderRadius' | 'borderTopLeftRadius' | 'borderTopRightRadius' | 'borderBottomRightRadius' | 'borderBottomLeftRadius' | 'borderStyle' | 'boxShadow' | 'fill' | 'stroke' | 'fillOpacity' | 'strokeOpacity' | 'strokeWidth' | 'outlineColor' | 'outlineStyle' | 'outlineWidth' | 'outlineOffset' | 'caretColor' | 'accentColor';
+
+/** Paint declarations plus controlled typography and target-level layout fields. */
+declare type AppearanceRuleDeclarations = AppearancePaintDeclarations & AppearanceLayoutDeclarations & {
+    /** Single font family identifier admitted only for authorized targets at runtime. */
+    readonly fontFamily?: string;
+    /** Integer pixel size admitted only for authorized text targets at runtime. */
+    readonly fontSize?: `${number}px`;
+    /** Controlled font weight admitted only for authorized text targets at runtime. */
+    readonly fontWeight?: 400 | 500 | 600 | 700;
+    /** Controlled font style admitted only for authorized text targets at runtime. */
+    readonly fontStyle?: 'normal' | 'italic';
+};
+
+/** Controlled pseudo-class accepted by the merchant selector grammar. */
+declare type AppearanceRulePseudoClass = 'autofill';
+
+/** Controlled pseudo-element accepted by the merchant selector grammar. */
+declare type AppearanceRulePseudoElement = 'placeholder' | 'selection';
+
+/**
+ * Optional state or controlled pseudo suffix on one alias.
+ */
+export declare type AppearanceRuleScopeSuffix = '' | `:${AppearanceRuleState | AppearanceRulePseudoClass}` | `::${AppearanceRulePseudoElement}`;
+
+/** One merchant alias with an optional semantic suffix. */
+export declare type AppearanceRuleSelector<RuleAlias extends string> = `${RuleAlias}${AppearanceRuleScopeSuffix}`;
+
+/** Semantic states accepted by the merchant selector grammar. */
+declare type AppearanceRuleState = 'hover' | 'focus' | 'focus-visible' | 'active' | 'disabled' | 'loading' | 'selected' | 'checked' | 'expanded' | 'invalid' | 'success' | 'error';
+
+/** Backward-compatible name for the Express appearance configuration. */
+export declare type AppearanceSetting = ExpressAppearance;
+
+/** Exact official spacing Token accepted by controlled margin and padding. */
+export declare type AppearanceSpacingToken = `var(--spacing-${'base' | 'none' | '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | '3xl'})`;
+
+/** Runtime-constrained non-negative integer pixel value for spacing longhands. */
+export declare type AppearanceSpacingValue = '0' | `${number}px` | AppearanceSpacingToken;
+
+/**
+ * 对客公开 appearance variables 类型（Token 2.x，figma-v4「3 层 + 状态」命名）。
+ * 字段名为新 CSS 变量名去掉 '--' 前缀（如 color-text-primary）。
+ *
+ * 权威源：`antom-web-checkout-v2/packages/elements2/src/utils/themeConfig.ts` 的 `PUBLIC_TOKENS`
+ * （54 color + 4 radius + 10 spacing = 68 项）。本 union 是该清单的手工镜像，
+ * 增删 token 时必须两侧同步，否则商户会遇到「类型报错但运行时可用」的错位。
+ *
+ * 命名规则：`--color-<scene>-<level>[-<state>]`；brand 场景并入 scene 段的 camelCase
+ * （如 `color-backgroundBrand-primary-hover`），CSS 变量大小写敏感，不可改写为 kebab。
+ *
+ * @example
+ *   variables: { 'color-text-primary': '#2a3a52', 'radius-sm': '4px' }
+ */
+export declare type AppearanceVariables = 'color-background-primary' | 'color-background-primary-hover' | 'color-background-primary-active' | 'color-background-secondary' | 'color-background-secondary-hover' | 'color-background-secondary-active' | 'color-background-layout' | 'color-background-inverse' | 'color-background-disabled' | 'color-background-transparency' | 'color-background-mask' | 'color-background-success' | 'color-background-warning' | 'color-background-danger' | 'color-background-info' | 'color-background-neutral' | 'color-background-promotional' | 'color-backgroundBrand-primary' | 'color-backgroundBrand-primary-hover' | 'color-backgroundBrand-secondary' | 'color-backgroundBrand-secondary-hover' | 'color-backgroundBrand-tertiary' | 'color-backgroundBrand-disabled' | 'color-text-primary' | 'color-text-secondary' | 'color-text-tertiary' | 'color-text-inverse' | 'color-text-active' | 'color-text-disabled' | 'color-text-success' | 'color-text-warning' | 'color-text-danger' | 'color-text-info' | 'color-text-neutral' | 'color-text-promotional' | 'color-textBrand-primary' | 'color-textBrand-secondary' | 'color-textBrand-secondary-hover' | 'color-textBrand-disabled' | 'color-border-primary' | 'color-border-secondary' | 'color-border-inverse' | 'color-border-active' | 'color-border-subtle' | 'color-border-disabled' | 'color-border-success' | 'color-border-warning' | 'color-border-danger' | 'color-border-info' | 'color-border-neutral' | 'color-border-promotional' | 'color-borderBrand-primary' | 'color-borderBrand-primary-hover' | 'color-borderBrand-disabled' | 'radius-sm' | 'radius-md' | 'radius-lg' | 'radius-xl' | 'spacing-base' | 'spacing-none' | 'spacing-2xs' | 'spacing-xs' | 'spacing-sm' | 'spacing-md' | 'spacing-lg' | 'spacing-xl' | 'spacing-2xl' | 'spacing-3xl';
+
 declare interface AppleMerchantInfo {
     /**
      * @description Apple商户ID
@@ -746,10 +861,6 @@ declare interface BankInfo {
     hasSchemaUrl?: boolean;
 }
 
-declare interface BaseAppearance<A extends Partial<Appearance>> {
-    appearance?: A;
-}
-
 /**
  * @description 内置基础的桥接事件映射类型
  */
@@ -2066,18 +2177,22 @@ export declare interface ConfirmCardSetupOptions {
     redirect?: 'always' | 'if_required';
 }
 
-export declare interface ConfirmPaymentOptions extends Omit<ConfirmCardSetupOptions, 'elements'>, PaymentSubmitParams {
-    sessionData: string;
-    /**
-     * @description 传入已挂载的 CVVElement / PaymentElement / Elements 实例，不传则使用无 UI 自动提交模式
-     */
-    elements?: BaseMainElement | BaseElements;
+export declare type ConfirmPaymentOptions = PaymentSubmitParams & {
     appearance?: CVVAppearance;
     /**
      * @description 集成用户自定义信息（如 cardHolderName）
      */
     params?: Record<string, unknown>;
-}
+} & ({
+    /** 已挂载的 Element；确认时使用其创建时绑定的会话。 */
+    elements: BaseMainElement | BaseElements;
+    /** @deprecated 传入 elements 时无需重复传递，且不会覆盖 Element 的会话。 */
+    sessionData?: string;
+} | {
+    elements?: undefined;
+    /** 无 UI 模式必填，仅用于创建内部 CVVElement。 */
+    sessionData: string;
+});
 
 /**
  * @description Connect流程参数
@@ -2214,11 +2329,13 @@ declare interface CustomFontSource {
  * @public
  * @description CVV element app config type
  */
-export declare interface CVVAppConfig extends BaseAppearance<CVVAppearance>, BaseElementAppConfig {
+export declare interface CVVAppConfig extends BaseElementAppConfig {
+    /** CVV appearance configuration including optional alias-only Rules. */
+    appearance?: CVVAppearance;
     /**
-     * @description sessionData
+     * @description 创建时必填的支付会话；不可通过 updateConfig 或 submit 替换
      */
-    sessionData?: string;
+    sessionData: string;
     /* Excluded from this release type: paymentSessionConfig */
     /* Excluded from this release type: renderData */
     /* Excluded from this release type: sdkVersion */
@@ -2231,12 +2348,13 @@ export declare interface CVVAppConfig extends BaseAppearance<CVVAppearance>, Bas
     /* Excluded from this release type: paymentFlow */
 }
 
-export declare type CVVAppearance = PickAppearance<CVVAppearanceProps>;
+export declare type CVVAppearance = PickAntomAppearance<CVVAppearanceProps>;
 
 export declare type CVVAppearanceProps = {
     theme: AntomTheme;
-    variables: AntomVariables;
+    variables: AppearanceVariables | AntomVariables;
     fonts?: FontSource[];
+    rules: AppearanceRuleSelector<string>;
 };
 
 /**
@@ -2244,9 +2362,18 @@ export declare type CVVAppearanceProps = {
  */
 export declare class CVVElement extends BaseMainElement<CVVElementConfig, CVVElementEvents> {
     static elementType: string;
+    private readonly sessionData;
+    private readonly elementTracker;
+    private _mountInProgress;
+    private _destroyInProgress;
     constructor(name: string, config: CVVElementConfig);
     /* Excluded from this release type: setup */
+    /* Excluded from this release type: updateConfig */
     /* Excluded from this release type: submit */
+    mount(container: HTMLElement): Promise<void>;
+    on<T extends keyof CVVElementEvents>(event: T, handler: (payload: CVVElementEvents[T]) => void): void;
+    unmount(): void;
+    destroy(): void;
     protected focus(): void;
     protected blur(): void;
     protected clear(): void;
@@ -2257,20 +2384,10 @@ export declare class CVVElement extends BaseMainElement<CVVElementConfig, CVVEle
  * @description CVV element config type
  */
 export declare interface CVVElementConfig extends BaseElementConfig<CVVAppConfig> {
+    appConfig: CVVAppConfig;
 }
 
-export declare interface CVVElementEvents extends AntomBridgeEventMap<CVVAppConfig, CVVSubmitParams> {
-    /**
-     * @description Emitted event about form
-     */
-    form: {
-        errors?: Array<{
-            field: string | number;
-            message: string;
-            currentValue: any;
-        }>;
-        message: string;
-    };
+export declare interface CVVElementEvents extends AntomBridgeEventMap<CVVAppConfig, CVVSubmitParams & Pick<CVVAppConfig, 'sessionData'>> {
     /**
      * @description Emitted when the element is destroy
      */
@@ -2314,10 +2431,6 @@ export declare type CVVSubmitErrorCodes = 'NOT_FIND_MAINELEMENT' | 'SESSION_DATA
  * @description CVV 支付提交参数
  */
 export declare interface CVVSubmitParams {
-    /**
-     * 支付会话数据
-     */
-    sessionData?: string;
     /**
      * 重定向策略
      */
@@ -3001,8 +3114,12 @@ declare interface ElementPluginChangeStates {
 declare type ElementPluginNameEnum = 'SET_STATE' | 'PASSIVE_SET_STATE';
 
 declare class Elements extends BaseElements {
+    private readonly apiTracker;
     protected canUseElements(): Array<ElementListItemType>;
     constructor(config: BaseElementsConfig);
+    init(): Promise<this>;
+    updateConfig(config: Partial<BaseElementsConfig>): void;
+    destroy(): void;
     createElement(elementType: 'vaulting', options?: VaultingAppConfig): VaultingElement;
     createElement(elementType: 'express', options?: ExpressAppConfig): ExpressElement;
     getElement(elementType: 'vaulting', options?: VaultingAppConfig): VaultingElement;
@@ -3130,20 +3247,21 @@ declare interface ExpPaymentOptionDetail {
  * @public
  * @description Express element app config type
  */
-export declare interface ExpressAppConfig extends BaseAppearance<AppearanceSetting>, BaseElementAppConfig {
+export declare interface ExpressAppConfig extends BaseElementAppConfig {
+    /** Express appearance configuration. */
+    appearance?: ExpressAppearance;
     /** payment SessionData */
     sessionData?: string;
-    /** Business division (country/region) */
-    businessDivision?: string;
     /**
      * Amount & Currency
      *
-     * Only effective via `updateConfig({ amount })` at runtime.
-     * Passing amount at creation time is ignored; the initial amount
-     * comes from the server-side sdkQuery result (renderData.paymentAmount).
+     * For Apple Pay and Google Pay, `value` is a positive ASCII digit string in
+     * the payment session currency's minor unit; `currency` may be omitted.
+     * For example, USD 10.99 is passed as `{ value: '1099' }`.
+     * PayPal keeps its existing major-unit amount semantics and requires `currency`.
      */
     amount?: {
-        currency: string;
+        currency?: string;
         value: string;
     };
     /** PayPal 配置 */
@@ -3189,6 +3307,17 @@ export declare interface ExpressAppConfig extends BaseAppearance<AppearanceSetti
     /* Excluded from this release type: doMain */
 }
 
+/** Express element appearance configuration. */
+declare type ExpressAppearance = PickAntomAppearance<ExpressAppearanceProps>;
+
+/** Express element appearance properties. */
+export declare type ExpressAppearanceProps = {
+    displaySetting: 'showCardBrandIcon';
+    theme: 'light' | 'dark';
+    layout: 'accordion' | 'tabs';
+    rules: AppearanceRuleSelector<string>;
+};
+
 /** cancel 事件负载 */
 export declare interface ExpressCancelEvent {
     expressPaymentType: string;
@@ -3200,6 +3329,17 @@ export declare interface ExpressClickEvent {
     expressPaymentType: string;
 }
 
+declare type ExpressCompletePaymentResult = {
+    success: boolean;
+    result?: any;
+    error?: {
+        code: string;
+        message: string;
+    };
+    userCanceled3D?: boolean;
+    status?: 'SUCCESS' | 'CANCELLED' | 'FAIL' | 'PROCESSING';
+};
+
 /** confirm 事件负载（统一终态，替代 approve） */
 export declare interface ExpressConfirmData {
     expressPaymentType: string;
@@ -3246,6 +3386,10 @@ export declare interface ExpressConfirmData {
  */
 export declare class ExpressElement extends BaseMainElement<ExpressElementConfig, ExpressElementEvents> {
     static elementType: string;
+    private readonly elementTracker;
+    private _mountInProgress;
+    private _destroyInProgress;
+    private _registeringInternalListeners;
     /**
      * Store all function-type callbacks locally, not involved in postMessage serialization
      */
@@ -3264,7 +3408,23 @@ export declare class ExpressElement extends BaseMainElement<ExpressElementConfig
     private _localHandlers;
     /** 支付流程进行中标志（click → confirm/error/cancel 之间） */
     private _paymentInProgress;
+    /**
+     * confirm 窗口超时标志：iframe 在 20s onTimeout 发 error(MERCHANT_CONFIRM_TIMEOUT) 时置位，
+     * completePayment 入口据此立即返失败（不发 COMPLETE_PAYMENT，不进 5min 兜底）。
+     * 每新一轮 confirm 事件到达时复位（见 on() 重写）。
+     */
+    private _confirmWindowTimedOut;
+    /**
+     * 是否已收到 iframe 业务层 ready 事件（app.tsx sendReady）。
+     * 注意：与 host `status='ready'`（由 HANDSHAKE_ACK 触发，bridge.js:450 同步回发，与 amount 解析无关）不同。
+     * 首屏 amount setupError 时 iframe 不发业务 ready → _readyReceived 保持 false，
+     * 据此判别"首屏失败"以阻断后续 updateConfig。
+     */
+    private _readyReceived;
+    /** 首屏 setupError 致命标志：置位后 updateConfig 被 CHECKOUT_NOT_READY 阻断，只能 destroy 重开。 */
+    private _setupFailed;
     private _paypalOverlay;
+    private _updateQueue;
     constructor(name: string, config: ExpressElementConfig);
     /**
      * 重写 on：对 confirm 事件拦截，在商户回调执行前注入 paymentFailed()
@@ -3275,24 +3435,30 @@ export declare class ExpressElement extends BaseMainElement<ExpressElementConfig
      * 用于 Native WebView 场景下 SDK 需要向商户透传跳转信息等。
      */
     private _emit;
-    updateConfig(newConfig: Pick<ExpressAppConfig, 'amount'>): Promise<ExpressElementEvents['OPENSDK@UPDATE_CONFIG_REPLY']>;
+    updateConfig(newConfig: ExpressAppConfig): Promise<ExpressElementEvents['OPENSDK@UPDATE_CONFIG_REPLY']>;
+    private runUpdateConfig;
+    private updateConfigTransaction;
+    private updateAmountConfigWithSanitizedDebug;
+    private getAmountValidationReason;
+    /** iframe 业务 ready 事件到达：置 _readyReceived，后续运行时 error 不再视为首屏失败。
+     *  ready 是"本次首屏成功"的确实信号（首屏 setupError 时 iframe 不发 ready），
+     *  故同时清掉 _setupFailed——unmount+remount 同实例二次首屏成功后可恢复 updateConfig。
+     */
+    private _handleReady;
+    /** iframe error 事件：若 business ready 未到达，视为首屏 setupError → 置 _setupFailed 阻断后续 updateConfig。 */
+    private _handleError;
     /**
      * 商户在 confirm 回调内调用，触发实际支付提交。
      * iframe 收到 OPENSDK@COMPLETE_PAYMENT 后执行 submitPay / polling 等，
      * 完成后通过 OPENSDK@COMPLETE_PAYMENT_RESULT 回包，Promise resolve。
      */
-    completePayment(redirect?: 'always' | 'if_required'): Promise<{
-        success: boolean;
-        result?: any;
-        error?: {
-            code: string;
-            message: string;
-        };
-        /** 用户是否手动关闭 3D 弹窗（透传 webapp COMPLETE_PAYMENT_RESULT.userCanceled3D） */
-        userCanceled3D?: boolean;
-    }>;
+    completePayment(redirect?: 'always' | 'if_required'): Promise<ExpressCompletePaymentResult>;
+    private runCompletePayment;
     setup(): Promise<Partial<ExpressAppConfig> | undefined>;
     private registerInternalListeners;
+    mount(container: HTMLElement): Promise<void>;
+    unmount(): void;
+    destroy(): void;
     protected focus(): void;
     protected blur(): void;
     protected clear(): void;
@@ -3364,6 +3530,11 @@ export declare interface ExpressElementEvents extends AntomBridgeWithNativeEvent
     'OPENSDK@GET_APPLE_PAY_TOKEN': {
         requestId: string;
         expressPaymentType: string;
+        /** iframe 已转好的 major unit 金额（来自 resolvedAmount）；host 委托 Apple Pay 消费，不再做 minor→major 转换。 */
+        walletAmount?: {
+            value: string;
+            currency: string;
+        };
     };
     /** host 完成 Apple Pay token 获取后回包给 iframe，submit/3DS/polling 均由 webapp 完成 */
     'OPENSDK@GET_APPLE_PAY_TOKEN_REPLY': {
@@ -3396,6 +3567,184 @@ declare type ExpressSetupError = ErrorPayload & {
     mulityLanguageMapping?: boolean;
 };
 
+/**
+ * @public
+ * @description Express Vaulting element app config type
+ */
+export declare interface ExpressVaultingAppConfig extends BaseElementAppConfig {
+    /**
+     * @description payment sessionData，无法通过 updateConfig 更新
+     */
+    sessionData?: string;
+    /**
+     * @description 开通的支付方式列表，本期固定为 ['PAYPAL_DIRECTDEBIT']
+     */
+    paymentMethods?: string[];
+    /** PayPal 按钮配置 */
+    paypal?: ExpressVaultingPayPalConfig;
+    /** PayPal 按钮文案类型 */
+    buttonType?: {
+        paypal?: 'paypal' | 'checkout' | 'buynow' | 'pay';
+    };
+    /** 按钮统一高度（px） */
+    buttonHeight?: number;
+    /** PayPal 按钮主题色 */
+    buttonTheme?: {
+        paypal?: 'gold' | 'blue' | 'silver' | 'white' | 'black';
+    };
+}
+
+/**
+ * @public
+ * @description cancel 事件负载
+ */
+export declare interface ExpressVaultingCancelEvent {
+    paymentMethodType: ExpressVaultingMethod;
+    data?: unknown;
+}
+
+/**
+ * @public
+ * @description click 事件负载
+ */
+export declare interface ExpressVaultingClickEvent {
+    paymentMethodType: ExpressVaultingMethod;
+}
+
+/**
+ * @public
+ * @description confirm 事件负载（PayPal onApprove 成功后触发，商户可在回调中调 confirmVaulting）
+ */
+export declare interface ExpressVaultingConfirmEvent {
+    paymentMethodType: ExpressVaultingMethod;
+    payerInfo?: ExpressVaultingPayerInfo;
+}
+
+/**
+ * @public
+ * @description Express Vaulting element - PayPal 绑卡 Element
+ *
+ * Host 侧只保留 Element 生命周期与 bridge 连接；PayPal 按钮渲染、Braintree SDK
+ * 加载、submit/inquiry 都由 express_vaulting webapp 承接。
+ *
+ * setup 阶段调 sdkActionQuery 拿 paypalClientToken，握手时下发给 iframe（系分
+ * 4.1 节 BR-007：client token 必须来自握手，iframe 不自调 sdkActionQuery）。
+ */
+export declare class ExpressVaultingElement extends BaseMainElement<ExpressVaultingElementConfig, ExpressVaultingElementEvents> {
+    static elementType: string;
+    /**
+     * Host-side fullscreen overlay shown while the PayPal popup is open.
+     *
+     * PayPal Braintree vault flow renders its own popup + backdrop inside the
+     * iframe body, so without a host overlay the backdrop only masks the tiny
+     * button area. Mirrors ExpressElement: show on `click`, hide on
+     * `confirm` / `cancel` / `error`.
+     */
+    private _paypalOverlay;
+    constructor(name: string, config: ExpressVaultingElementConfig);
+    /* Excluded from this release type: setup */
+    /* Excluded from this release type: registerInternalListeners */
+    protected focus(): void;
+    protected blur(): void;
+    protected clear(): void;
+    /* Excluded from this release type: _confirmVaulting */
+}
+
+/**
+ * @public
+ * @description Express Vaulting element config type
+ */
+export declare interface ExpressVaultingElementConfig extends BaseElementConfig<ExpressVaultingAppConfig> {
+}
+
+/**
+ * @public
+ * @description Express Vaulting element 事件类型
+ */
+export declare interface ExpressVaultingElementEvents extends AntomBridgeWithNativeEventMap<ExpressVaultingAppConfig> {
+    ready: ExpressVaultingReadyEvent;
+    click: ExpressVaultingClickEvent;
+    confirm: ExpressVaultingConfirmEvent;
+    cancel: ExpressVaultingCancelEvent;
+    error: ExpressVaultingErrorEvent;
+    'OPENSDK@CONFIRM_VAULTING': {
+        requestId: string;
+        redirect?: 'always' | 'if_required';
+    };
+    'OPENSDK@CONFIRM_VAULTING_RESULT': {
+        requestId: string;
+        result: ExpressVaultingResult;
+    };
+}
+
+/**
+ * @public
+ * @description error 事件负载
+ */
+export declare interface ExpressVaultingErrorEvent extends ErrorPayload<string> {
+    paymentMethodType: ExpressVaultingMethod;
+}
+
+/**
+ * Supported express vaulting payment methods. All bridge event payloads carry
+ * `paymentMethodType` — use this enum instead of硬编码 strings so adding a
+ * new wallet only needs one entry here. Must match the iframe-side enum in
+ * elements2/express_vaulting/interface.ts.
+ */
+declare enum ExpressVaultingMethod {
+    PAYPAL_DIRECTDEBIT = "PAYPAL_DIRECTDEBIT"
+}
+
+/**
+ * @public
+ * @description Braintree tokenizePayment 返回的 payer 信息，随 confirm 事件透传给商户
+ */
+export declare interface ExpressVaultingPayerInfo {
+    payerId?: string;
+    email?: string;
+    firstName?: string;
+    lastName?: string;
+    countryCode?: string;
+    phone?: string;
+}
+
+/**
+ * MERCHANT_CONFIRM_TIMEOUT is owned by the iframe side (mirrors express_element:
+ * iframe starts a 20s timer on the `confirm` event and sends
+ * `error(MERCHANT_CONFIRM_TIMEOUT)` if the merchant never calls confirmVaulting).
+ * See elements2/express_vaulting/app.tsx + tools/error.ts.
+ */
+/**
+ * @public
+ * @description PayPal 按钮配置
+ */
+export declare interface ExpressVaultingPayPalConfig {
+    /** 按钮形状 */
+    buttonShape?: 'pill' | 'rect' | 'sharp';
+}
+
+/**
+ * @public
+ * @description ready 事件负载
+ */
+export declare interface ExpressVaultingReadyEvent {
+    availablePaymentMethods: Partial<Record<ExpressVaultingMethod, boolean>>;
+}
+
+/**
+ * @public
+ * @description confirmVaulting 返回结果
+ */
+export declare interface ExpressVaultingResult {
+    status: 'SUCCESS' | 'PROCESSING' | 'FAIL' | 'CANCELLED';
+    paymentMethodId?: string;
+    payerId?: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+
 declare interface ExpSupportBank {
     /**
      * @description 银行名称
@@ -3474,6 +3823,57 @@ declare interface FrontSupportIppBank {
     logo?: Logo;
 }
 
+/** host 回传 webapp 的 OPENSDK@GET_APPLE_PAY_TOKEN_REPLY 形态(result 对齐老链路 {token,billingContact,shippingContact})。 */
+declare interface GetApplePayTokenReply {
+    success: boolean;
+    result?: {
+        token?: unknown;
+        billingContact?: unknown;
+        shippingContact?: unknown;
+    } | {
+        errorCode: string;
+    };
+}
+
+/** webapp 传来的 OPENSDK@GET_APPLE_PAY_TOKEN payload 形态。 */
+declare interface GetApplePayTokenRequest {
+    paymentMethod?: {
+        paymentMethodDetail?: {
+            applePayProps?: {
+                paymentRequest?: unknown;
+            };
+        };
+    };
+    shipping?: unknown;
+}
+
+/** host 回传 webapp 的 OPENSDK@GET_GOOGLE_PAY_TOKEN_REPLY 形态。 */
+declare interface GetGooglePayTokenReply {
+    success: boolean;
+    result?: unknown;
+    err?: {
+        statusCode?: string;
+        [key: string]: unknown;
+    };
+}
+
+/** webapp 传来的 OPENSDK@GET_GOOGLE_PAY_TOKEN payload 形态。 */
+declare interface GetGooglePayTokenRequest {
+    actionName?: string;
+    data?: {
+        environment?: string;
+        paymentRequest?: unknown;
+        paymentMethod?: unknown;
+        paymentMethodDetail?: {
+            googlePayProps?: {
+                environment?: string;
+                paymentRequest?: unknown;
+            };
+        };
+        [key: string]: unknown;
+    };
+}
+
 declare type GetI18nQueryParam = string | {
     /**
      * 多语言文案的 key
@@ -4324,6 +4724,58 @@ declare interface Language {
     country?: string;
 }
 
+/**
+ * @deprecated Token 1.0 老字段类型 — 请迁移到 {@link AppearanceVariables}。
+ * 所有字段均已废弃，运行时由 WebApp 侧 LEGACY_TO_NEW_TOKEN_MAP 翻译为新 token。
+ *
+ * @deprecated 'content-primary'        → color-text-primary
+ * @deprecated 'content-secondary'      → color-text-secondary
+ * @deprecated 'content-tertiary'       → color-text-tertiary
+ * @deprecated 'content-quaternary'     → color-text-inverse
+ * @deprecated 'background-primary'     → color-background-primary
+ * @deprecated 'background-secondary'   → color-background-secondary
+ * @deprecated 'background-disable'     → color-background-disabled
+ * @deprecated 'background-transparency' → color-background-transparency
+ * @deprecated 'border-primary'         → color-border-primary
+ * @deprecated 'border-secondary'       → color-border-secondary
+ * @deprecated 'border-disable'         → color-border-disabled
+ * @deprecated 'border-active'          → color-border-active
+ * @deprecated 'action-normal'          → 一对多 fan-out（无单值映射；运行时展开为 3 个新 token，老 key 不再注入）：
+ *                                        - background/background-color → color-backgroundBrand-primary
+ *                                        - border/border-color/box-shadow → color-border-active
+ *                                        - color/文本/图标/勾选态 → color-text-active
+ * @deprecated 'action-hover'           → 一对多 fan-out（运行时展开为 2 个新 token，老 key 不再注入）：
+ *                                        - background → color-backgroundBrand-primary-hover
+ *                                        - border     → color-borderBrand-primary-hover
+ *                                        文字色 color-textBrand-secondary-hover 不参与派生
+ *                                        （设计稿中与 bg/border 不同色阶），需要时请显式传入该新 token 键
+ * @deprecated 'action-secondary'       → color-backgroundBrand-secondary
+ * @deprecated 'action-disable'         → 一对多 fan-out（运行时展开为 2 个新 token，老 key 不再注入）：
+ *                                        - background/background-color → color-backgroundBrand-disabled
+ *                                        - border/border-color         → color-borderBrand-disabled
+ *                                        文字色 color-textBrand-disabled 不参与派生
+ *                                        （设计稿中全部主题均与 bg/border 不同色阶），需要时请显式传入该新 token 键
+ * @deprecated 'state-success'          → color-text-success
+ * @deprecated 'state-failure'          → color-text-danger
+ * @deprecated 'state-warning'          → color-text-warning
+ * @deprecated 'state-info'             → color-text-info
+ * @deprecated 'state-conventional'     → color-text-neutral
+ * @deprecated 'state-marketing'        → color-text-promotional（color 上下文；background 上下文由 CSS 层直接迁移）
+ * @deprecated 'radius-backup'          → radius-sm
+ * @deprecated 'radius-component'       → radius-md
+ * @deprecated 'radius-module'          → radius-lg
+ * @deprecated 'radius-button'          → radius-lg（与 radius-module 同档合并）
+ * @deprecated 'wrapper-padding'        → spacing-lg
+ * @deprecated 'stroke-default'         → 由 Rules 机制接管
+ * @deprecated 'stroke-active'          → 由 Rules 机制接管
+ *
+ * 注：fan-out 展开基数以 figma-v4 设计稿的色阶一致性为准，故 action-hover / action-disable
+ * 为 1→2 而非 1→3；三者合计派生 7 项。
+ */
+export declare type LegacyAppearanceVariables = 'content-primary' | 'content-secondary' | 'content-tertiary' | 'content-quaternary' | 'background-primary' | 'background-secondary' | 'background-disable' | 'background-transparency' | 'border-primary' | 'border-secondary' | 'border-disable' | 'action-normal' | 'action-hover' | 'action-disable' | 'action-secondary' | 'state-failure' | 'state-warning' | 'state-success' | 'state-info' | 'state-marketing' | 'state-conventional' | 'radius-backup' | 'radius-module' | 'radius-component' | 'radius-button' | 'wrapper-padding' | 'stroke-default' | 'stroke-active'
+/** 非 Token 体系字段，由 WebApp 侧展开为 design-font-family-* 系列 */
+| 'fontFamily';
+
 declare interface Link {
     /**
      * @description 发起关联的父元素，如国家
@@ -6889,7 +7341,7 @@ declare interface OtpChallengeActionForm {
     resendLeftTimes?: number;
 }
 
-declare type PartialSpeKey<T, V> = Partial<T extends infer K extends string ? Record<K, V> : Record<string, V>>;
+declare type PartialSpeKey<T extends string | undefined, V> = Partial<Record<T extends string ? T : string, V>>;
 
 declare interface PayByLinkInfo {
     /**
@@ -6913,7 +7365,9 @@ declare interface PayByLinkInfo {
 /**
  * @description Payment element app config type
  */
-export declare interface PaymentAppConfig extends BaseAppearance<PaymentAppearance>, BaseElementAppConfig {
+export declare interface PaymentAppConfig extends BaseElementAppConfig {
+    /** Payment appearance configuration including optional alias-only Rules. */
+    appearance?: PaymentAppearance;
     /**
      * @description sessionData，无法通过updateConfig更新
      */
@@ -6943,12 +7397,18 @@ export declare interface PaymentAppConfig extends BaseAppearance<PaymentAppearan
 /**
  * @description Payment element appearance type
  */
-export declare type PaymentAppearance = PickAppearance<{
+export declare type PaymentAppearance = PickAntomAppearance<PaymentAppearanceProps>;
+
+/**
+ * @description Payment element appearance properties
+ */
+export declare type PaymentAppearanceProps = {
     displaySetting: 'showPaymentMethodListWhenSingleOption' | 'showCardBrandIcon' | 'showRadioWhenAccordionLayout' | 'showCardCVV';
     theme: AntomTheme;
-    variables: AntomVariables;
+    variables: AppearanceVariables | AntomVariables;
     layout: AntomLayouts;
-}>;
+    rules: AppearanceRuleSelector<string>;
+};
 
 /**
  * @description Payment element
@@ -6956,13 +7416,23 @@ export declare type PaymentAppearance = PickAppearance<{
 export declare class PaymentElement extends BaseMainElement<PaymentElementConfig, PaymentElementEvents> {
     static elementType: string;
     private _paymentInProgress;
+    private readonly paymentTracker;
+    private _mountStartedAt;
+    private _mountInProgress;
+    private _mountPhase;
+    private _destroyInProgress;
+    private readonly walletLogger;
     constructor(name: string, config: PaymentElementConfig);
     /* Excluded from this release type: setup */
+    mount(container: HTMLElement): Promise<void>;
     /**
-     * @description Update payment element configuration with amount validation
+     * @description Update payment element configuration with amount validation and appearance Rules support
      */
-    updateConfig(newConfig: Pick<PaymentAppConfig, 'amount'>): Promise<PaymentElementEvents['OPENSDK@UPDATE_CONFIG_REPLY']>;
+    updateConfig(newConfig: Partial<PaymentAppConfig>): Promise<PaymentElementEvents['OPENSDK@UPDATE_CONFIG_REPLY']>;
     /* Excluded from this release type: submit */
+    on<T extends keyof PaymentElementEvents>(event: T, handler: (payload: PaymentElementEvents[T]) => void): void;
+    unmount(): void;
+    destroy(): void;
     protected focus(): void;
     protected blur(): void;
     protected clear(): void;
@@ -6978,6 +7448,25 @@ declare interface PaymentElementConfig extends BaseElementConfig<PaymentAppConfi
  * @description Payment element events
  */
 export declare interface PaymentElementEvents extends AntomBridgeWithNativeEventMap<PaymentAppConfig, PaymentSubmitParams, PaymentSubmitResult> {
+    /**
+     * webapp 委托 host(父 frame)拉起 Apple Pay 拿 token。
+     * payload 结构对齐 ModernElementController.GetApplePayTokenRequest(放 paymentMethod/shipping)。
+     */
+    'OPENSDK@GET_APPLE_PAY_TOKEN': GetApplePayTokenRequest;
+    /** host 完成 Apple Pay token 获取后回包给 webapp */
+    'OPENSDK@GET_APPLE_PAY_TOKEN_REPLY': GetApplePayTokenReply;
+    /**
+     * webapp 委托 host(父 frame)拉起 Google Pay 拿 token。
+     * payload 结构对齐 ModernElementController.GetGooglePayTokenRequest(放 data.environment/paymentRequest)。
+     */
+    'OPENSDK@GET_GOOGLE_PAY_TOKEN': GetGooglePayTokenRequest;
+    /** host 完成 Google Pay token 获取后回包给 webapp */
+    'OPENSDK@GET_GOOGLE_PAY_TOKEN_REPLY': GetGooglePayTokenReply;
+    /** WebApp notifies the host when the selected payment method changes. */
+    paymentMethodChanged: {
+        type: string;
+        name?: string;
+    };
 }
 
 declare interface PaymentElementView {
@@ -7669,6 +8158,7 @@ export declare interface PayPalConfig {
     channelMerchantAccountId?: string;
     /** Button style (fine-grained override) */
     style?: PayPalButtonStyle;
+    businessDivision?: string;
     /** Callback to create PayPal order, no params, returns sessionData */
     createOrder?: () => Promise<string>;
     /** Callback when user changes shipping address, data is raw data returned by PayPal */
@@ -7688,12 +8178,15 @@ declare interface PeriodRule {
     periodCount?: number;
 }
 
+/** Builds an Antom appearance type with the restricted Rules declaration contract. */
+declare type PickAntomAppearance<T extends Record<string, any>> = PickAppearance<T, AppearanceRuleDeclarations>;
+
 /**
  * @description 工具类型，仅从 Appearance 中拾取与 Props 类型匹配的属性。
  * 返回受 Props 中存在的键约束的部分外观对象。
  * @template Props - 要从 Appearance 中拾取的自定义外观属性类型。
  */
-declare type PickAppearance<Props extends Partial<DefaultAppearanceProps>> = Partial<Pick<Appearance<Props>, keyof Props extends infer k extends keyof Partial<Appearance> ? k : keyof Partial<Appearance>>>;
+declare type PickAppearance<Props extends Partial<DefaultAppearanceProps>, Rules extends CSS_2.Properties<string, number> = CSS_2.Properties<string, number>> = Partial<Pick<Appearance<Props, Rules>, keyof Props extends infer k extends keyof Partial<Appearance> ? k : keyof Partial<Appearance>>>;
 
 /**
  * @description 政策信息，例如隐私链接，免责声明等
@@ -24393,7 +24886,9 @@ declare interface UserName {
  * @public
  * @description Vaulting element app config type
  */
-export declare interface VaultingAppConfig extends BaseAppearance<VaultingAppearance>, BaseElementAppConfig {
+export declare interface VaultingAppConfig extends BaseElementAppConfig {
+    /** Vaulting appearance configuration including optional alias-only Rules. */
+    appearance?: VaultingAppearance;
     /**
      * @description sessionData，无法通过updateConfig更新
      */
@@ -24406,13 +24901,14 @@ export declare interface VaultingAppConfig extends BaseAppearance<VaultingAppear
     /* Excluded from this release type: preloadTelemetryContext */
 }
 
-export declare type VaultingAppearance = PickAppearance<VaultingAppearanceProps>;
+export declare type VaultingAppearance = PickAntomAppearance<VaultingAppearanceProps>;
 
 export declare type VaultingAppearanceProps = {
     displaySetting: 'showCardBrandIcon';
     theme: AntomTheme;
-    variables: AntomVariables;
+    variables: AppearanceVariables | AntomVariables;
     fonts?: FontSource[];
+    rules: AppearanceRuleSelector<string>;
 };
 
 /**
@@ -24420,9 +24916,22 @@ export declare type VaultingAppearanceProps = {
  */
 export declare class VaultingElement extends BaseMainElement<VaultingElementConfig, VaultingElementEvents> {
     static elementType: string;
+    private readonly elementTracker;
+    private _mountInProgress;
+    private _destroyInProgress;
     constructor(name: string, config: VaultingElementConfig);
     /* Excluded from this release type: setup */
+    /**
+     * Updates Vaulting configuration while preserving the public Rules clear semantics.
+     * @param newConfig Partial Vaulting configuration patch.
+     * @returns The WebApp update acknowledgement.
+     */
+    updateConfig(newConfig: Partial<VaultingAppConfig>): Promise<VaultingElementEvents['OPENSDK@UPDATE_CONFIG_REPLY']>;
     /* Excluded from this release type: submit */
+    mount(container: HTMLElement): Promise<void>;
+    on<T extends keyof VaultingElementEvents>(event: T, handler: (payload: VaultingElementEvents[T]) => void): void;
+    unmount(): void;
+    destroy(): void;
     protected focus(): void;
     protected blur(): void;
     protected clear(): void;