facebetter 1.5.0 → 2.0.0

package/dist/facebetter.js

@@ -4,238 +4,312 @@
   (global = typeof globalThis !== 'undefined' ? globalThis : global || self, factory(global.Facebetter = {}));
 })(this, (function (exports) { 'use strict';
 
-  /**
-   * Facebetter Error Classes
-   * Platform-agnostic error handling
-   */
-
-  /**
-   * Facebetter error class
-   */
-  class FacebetterError extends Error {
-    constructor(message, code = -1) {
-      super(message);
-      this.name = 'FacebetterError';
-      this.code = code;
-    }
-  }
-
-  /**
-   * Checks if a result code indicates success
-   * @param {number} result - Result code from WASM function
-   * @throws {FacebetterError} If result indicates failure
-   */
-  function checkResult(result, errorMessage = 'Operation failed') {
-    if (result !== 0) {
-      throw new FacebetterError(`${errorMessage} (error code: ${result})`, result);
-    }
-  }
-
   /**
    * Engine Configuration
    * Platform-agnostic configuration class
    */
 
-
   /**
    * Engine configuration class
-   * Similar to EngineConfig struct in C++/Java/OC
+   * Analogous to EngineConfig in C++ / Java / Objective-C, with Web-only auth fields.
    */
   class EngineConfig {
     /**
-     * Creates a new EngineConfig instance
-     * @param {Object} config - Configuration object
-     * @param {string} [config.appId] - Application ID (required if licenseJson is not provided)
-     * @param {string} [config.appKey] - Application key (required if licenseJson is not provided)
-     * @param {string} [config.licenseJson] - License JSON string (optional, if provided, appId and appKey are not required)
+     * @param {Object} config
+     * @param {string} [config.licenseToken] Compact JWS, or the raw `{success, token}`
+     *   HTTP response body from your auth server.
+     * @param {string} [config.authProxyUrl] Production: forward the WASM auth
+     *   challenge to your server, which holds app_id/app_key and calls Cloudflare.
+     * @param {Function} [config.fetchAuthResponse] Custom auth hook with signature
+     *   `async (challenge) => string|object`. For local debugging you can use
+     *   `createDirectAuthFetcher` to hit Cloudflare directly — never ship keys in
+     *   a production frontend bundle.
+     * @param {boolean} [config.externalContext] Kept for cross-platform alignment;
+     *   unused on Web/WASM today.
      */
     constructor(config = {}) {
-      this.appId = config.appId || null;
-      this.appKey = config.appKey || null;
-      this.licenseJson = config.licenseJson || null;
+      this.licenseToken = config.licenseToken || null;
+      this.authProxyUrl = config.authProxyUrl || null;
+      this.fetchAuthResponse = config.fetchAuthResponse || null;
       this.resourcePath = '/resource.fbd';
       /**
        * Whether to use an external GL context (native platforms only).
-       * In Web/WASM environments, this field is kept for configuration structure alignment,
-       * but it does not take effect in the current implementation.
+       * On Web/WASM this field is kept for config-shape alignment and has no effect.
        */
       this.externalContext = !!config.externalContext;
     }
 
-    /**
-     * Validates the configuration
-     * @returns {boolean} True if valid
-     */
     isValid() {
-      // If licenseJson is provided, use it for validation
-      if (this.licenseJson) {
-        return typeof this.licenseJson === 'string' && this.licenseJson.trim() !== '';
+      if (this.licenseToken && typeof this.licenseToken === 'string' &&
+          this.licenseToken.trim() !== '') {
+        return true;
       }
-      // Otherwise appId and appKey are required
-      return this.appId && typeof this.appId === 'string' && this.appId.trim() !== '' &&
-             this.appKey && typeof this.appKey === 'string' && this.appKey.trim() !== '';
+      if (typeof this.fetchAuthResponse === 'function') {
+        return true;
+      }
+      if (this.authProxyUrl && typeof this.authProxyUrl === 'string' &&
+          this.authProxyUrl.trim() !== '') {
+        return true;
+      }
+      return false;
     }
 
-    /**
-     * Returns a string representation of the config
-     * @returns {string} String representation
-     */
     toString() {
-      return `EngineConfig{appId='${this.appId ? this.appId.substring(0, Math.min(this.appId.length, 8)) + '...' : 'null'}', appKey='${this.appKey ? '***' : 'null'}', licenseJson=${this.licenseJson ? 'provided' : 'null'}}`;
+      const mode = this.licenseToken
+        ? 'licenseToken'
+        : this.fetchAuthResponse
+          ? 'fetchAuthResponse'
+          : this.authProxyUrl
+            ? 'authProxyUrl'
+            : 'invalid';
+      return `EngineConfig{mode='${mode}'}`;
     }
   }
 
   /**
-   * Facebetter Constants and Enums
-   * Platform-agnostic constants
+   * Facebetter Error Classes
+   * Platform-agnostic error handling
    */
 
   /**
-   * Beauty type enumeration
+   * Facebetter error class
    */
-  const BeautyType$1 = {
-    Basic: 0,             // Basic beauty (smoothing, whitening, etc.)
-    Reshape: 1,           // Face reshaping (face thinning, big eyes, etc.)
-    Makeup: 2,            // Makeup effects (lipstick, blush, etc.)
-    VirtualBackground: 3,  // Virtual background (blur, image replacement)
-    ChromaKey: 4,          // Chroma key (green screen removal)
-    Filter: 5,             // LUT based filter
-    Sticker: 6             // 2D/3D sticker
-  };
+  class FacebetterError extends Error {
+    constructor(message, code = -1) {
+      super(message);
+      this.name = 'FacebetterError';
+      this.code = code;
+    }
+  }
 
   /**
-   * Basic beauty parameter enumeration
-   * All values should be in range [0.0, 1.0]
+   * Checks if a result code indicates success
+   * @param {number} result - Result code from WASM function
+   * @throws {FacebetterError} If result indicates failure
    */
-  const BasicParam$1 = {
-    Smoothing: 0,   // Skin smoothing (0.0: none, 1.0: maximum)
-    Sharpening: 1,  // Image sharpening (0.0: none, 1.0: maximum)
-    Whitening: 2,   // Skin whitening (0.0: none, 1.0: maximum)
-    Rosiness: 3     // Skin rosiness (0.0: none, 1.0: maximum)
-  };
+  function checkResult(result, errorMessage = 'Operation failed') {
+    if (result !== 0) {
+      throw new FacebetterError(`${errorMessage} (error code: ${result})`, result);
+    }
+  }
 
   /**
-   * Face reshape parameter enumeration
-   * All values should be in range [0.0, 1.0]
+   * Facebetter Constants and Enums
+   * Platform-agnostic constants. Ordinals match facebetter::beauty_params.
    */
-  const ReshapeParam$1 = {
-    FaceThinning: 0,  // Face thinning (0.0: none, 1.0: maximum)
-    FaceVShape: 1,    // V-shape face (0.0: none, 1.0: maximum)
-    FaceNarrowing: 2, // Face narrowing (0.0: none, 1.0: maximum)
-    FaceShortening: 3,// Face shortening (0.0: none, 1.0: maximum)
-    Cheekbone: 4,     // Cheekbone slimming (0.0: none, 1.0: maximum)
-    Jawbone: 5,       // Jawbone slimming (0.0: none, 1.0: maximum)
-    Chin: 6,          // Chin length adjustment (0.0: none, 1.0: maximum)
-    NoseSlimming: 7,  // Nose slimming (0.0: none, 1.0: maximum)
-    EyeSize: 8,       // Eye size (0.0: normal, 1.0: maximum)
-    EyeDistance: 9    // Eye distance (0.0: normal, 1.0: maximum)
+
+  const WhiteningStyle$1 = {
+    ColdWhite: 0,  // Cool white
+    PinkWhite: 1,  // Pink white
+    WarmWhite: 2,  // Warm white
+    Wheat: 3,      // Light wheat / olive
+    Tan: 4         // Tan / bronzed
   };
 
-  /**
-   * Makeup parameter enumeration
-   * All values should be in range [0.0, 1.0]
-   */
-  const MakeupParam$1 = {
-    Lipstick: 0,    // Lipstick intensity (0.0: none, 1.0: maximum)
-    Blush: 1        // Blush intensity (0.0: none, 1.0: maximum)
+  const SmoothingStyle$1 = {
+    Natural: 0,  // Natural: keeps pores
+    Texture: 1,  // Cleaner skin while retaining texture
+    Smooth: 2    // Creamy / porcelain finish
   };
 
   /**
-   * Lipstick style types
+   * Face reshape parameters.
+   * Values match facebetter::beauty_params::Reshape.
+   * Intensity range is [-1.0, 1.0]; 0 is off. Comments list + / - directions.
    */
-  const LipstickStyle$1 = {
-    Rouge: 0,  // Rose red
-    Coral: 1,  // Coral
-    Pink: 2    // Pink
+  const Reshape$1 = {
+    FaceThin: 0,        // +slim face / -fuller cheeks
+    FaceVShape: 1,      // +V-shape jaw / -square jaw
+    FaceNarrow: 2,      // +narrow face / -wider face
+    FaceShort: 3,       // +shorter face / -longer face
+    Cheekbone: 4,       // +slim cheekbones / -wider cheekbones
+    Jawbone: 5,         // +slim jaw / -wider jaw
+    Chin: 6,            // +longer chin / -shorter chin
+    NoseSlim: 7,        // +slimmer nose / -wider nose
+    EyeSize: 8,         // +larger eyes / -smaller eyes
+    EyeDistance: 9,     // +wider eye spacing / -closer eyes
+    FaceSmall: 10,      // +smaller face / -larger face
+    Forehead: 11,       // +fuller forehead / -lower forehead
+    NoseLong: 12,       // +longer nose / -shorter nose
+    Philtrum: 13,       // +shorter philtrum / -longer philtrum
+    MouthSize: 14,      // +larger mouth / -smaller mouth
+    MouthPosition: 15,  // +mouth lower / -mouth higher
+    MouthSmile: 16,     // +smile lift / -droop corners
+    LipThickness: 17,   // +thicker lips / -thinner lips
+    EyeRound: 18,       // +rounder eyes / -narrower eyes
+    EyePosition: 19,    // +eyes lower / -eyes higher
+    EyeAngle: 20,       // +outer corner up / -outer corner down
+    EyeCornerOpen: 21,  // +open eye corners / -close eye corners
+    LowerEyelid: 22,    // +lower eyelid down / -lift lower eyelid
+    BrowPosition: 23,   // +brows higher / -brows lower
+    BrowDistance: 24,   // +wider brow spacing / -closer brows
+    BrowThickness: 25   // +thicker brows / -thinner brows
+  };
+
+  const EngineEventCode$1 = {
+    LicenseValidationSuccess: 0,
+    LicenseValidationFailed: 1,
+    InitializationComplete: 100,
+    InitializationFailed: 101
+  };
+
+  const LipstickColor$1 = {
+    Rouge: 0,           // Classic rose
+    RetroRed: 1,        // Retro red
+    Peach: 2,           // Peach
+    CoralOrange: 3,     // Coral orange
+    GentlePink: 4,      // Soft pink
+    VitalityOrange: 5   // Bright orange
   };
 
-  /**
-   * Blush style types
-   */
   const BlushStyle$1 = {
-    Classic: 0,  // Classic
-    Peach: 1,    // Peach
-    Rose: 2      // Rose
+    SunKissed: 0,  // Sun-kissed sweep across cheekbones and bridge
+    Igari: 1,      // Flushed band across the nose bridge
+    Soft: 2,       // Soft dual cheeks
+    Apple: 3,      // Round apple cheeks
+    Classic: 4,    // Classic two spots
+    Doll: 5,       // Cheeks + nose tip
+    Rose: 6        // Rose dual cheeks
   };
 
-  /**
-   * Chroma Key parameter enumeration
-   */
-  const ChromaKeyParam = {
-    KeyColor: 0,      // Key color (0.0: Green, 1.0: Blue, 2.0: Red)
-    Similarity: 1,    // Color similarity (0.0 - 1.0)
-    Smoothness: 2,    // Edge smoothness (0.0 - 1.0)
-    Desaturation: 3   // Spill desaturation (0.0 - 1.0)
+  const BlushColor$1 = {
+    CoralPink: 0,     // Coral pink
+    DustyRose: 1,     // Dusty rose
+    VividRed: 2,      // Vivid red
+    Berry: 3,         // Berry
+    SunsetOrange: 4   // Sunset orange
   };
 
-  /**
-   * Background mode enumeration
-   */
-  const BackgroundMode$1 = {
-    None: 0,        // No background processing
-    Blur: 1,        // Blurred background
-    Image: 2        // Background image replacement
+  const ContourStyle$1 = {
+    Natural: 0,  // Soft everyday contour
+    Sculpt: 1,   // Deeper sculpted contour
+    Glow: 2,     // Highlight-focused
+    Slim: 3,     // Slim cheekbones
+    Nose: 4,     // Nose bridge lift
+    Glam: 5      // Spot highlights
   };
 
-  /**
-   * Frame type enumeration
-   */
-  const FrameType$1 = {
-    Image: 0,       // Image mode
-    Video: 1        // Video mode
+  const EyeShadowStyle$1 = {
+    Soft: 0,    // Soft wash
+    Crease: 1,  // Crease deepen
+    Smoky: 2,   // Smoky surround
+    Halo: 3,    // Halo around the eye
+    Glow: 4,    // Outer-corner glow
+    Drama: 5,   // Full dramatic cover
+    Warm: 6     // Warm-tone wash
   };
 
-  /**
-   * Mirror mode enumeration (apply to input before processing)
-   */
-  const MirrorMode$1 = {
-    None: 0,        // No mirror
-    Horizontal: 1,  // Mirror horizontally (e.g. front camera selfie)
-    Vertical: 2,    // Mirror vertically
-    Both: 3         // Mirror both axes
+  const EyeShadowColor$1 = {
+    Plum: 0,   // Plum / mauve (default)
+    Brown: 1,  // Warm brown
+    Gold: 2,   // Soft gold
+    Pink: 3    // Dusty pink
   };
 
-  /**
-   * Virtual background options class
-   * Matches the C++/Java/OC API design
-   */
-  let VirtualBackgroundOptions$1 = class VirtualBackgroundOptions {
-    /**
-     * Creates a new VirtualBackgroundOptions instance
-     * @param {Object} [options] - Options object
-     * @param {number} [options.mode] - Background mode (use BackgroundMode enum)
-     * @param {ImageData|HTMLImageElement|HTMLCanvasElement} [options.backgroundImage] - Background image (required when mode is Image)
-     */
-    constructor(options = {}) {
-      this.mode = options.mode !== undefined ? options.mode : BackgroundMode$1.None;
-      this.backgroundImage = options.backgroundImage || null;
-    }
+  const EyeLinerStyle$1 = {
+    Classic: 0,  // Full liner with winged tip
+    Flick: 1,    // Extended outer flick
+    CatEye: 2,   // Short cat-eye lift
+    Natural: 3,  // Thin soft natural line
+    Bold: 4,     // Bold cover
+    Soft: 5      // Soft feathered wing
+  };
 
-    /**
-     * Validates the options
-     * @returns {boolean} True if valid
-     */
-    isValid() {
-      if (this.mode === BackgroundMode$1.Image) {
-        return this.backgroundImage !== null;
-      }
-      return true;
-    }
+  const EyeLinerColor$1 = {
+    Burgundy: 0,   // Burgundy brown
+    Plum: 1,       // Deep plum
+    Chocolate: 2,  // Chocolate brown
+    Coffee: 3,     // Near-black coffee
+    Mauve: 4       // Mauve grey
+  };
+
+  const EyebrowStyle$1 = {
+    Natural: 0,    // Natural arch with hair strokes
+    Soft: 1,       // Soft powdery thick brow
+    Feathered: 2,  // Feathered hair strokes
+    Mist: 3,       // Light powder mist
+    Arched: 4,     // Classic high arch
+    Powder: 5,     // Dense powder fill
+    Wild: 6,       // Wispy upper edge
+    Full: 7,       // Full balanced brow
+    Straight: 8    // Straight low arch
+  };
+
+  const EyebrowColor$1 = {
+    DarkBrown: 0,  // Dark brown (default)
+    Black: 1,      // Black
+    SoftBrown: 2   // Soft brown
+  };
+
+  const EyelashStyle$1 = {
+    Classic: 0,    // Balanced clusters + lower lashes
+    Manga: 1,      // Bold spiked clusters
+    Winged: 2,     // Extended outer corner
+    Wispy: 3,      // Fluffy lifted tips
+    Clustered: 4,  // Distinct clusters
+    Doll: 5        // Short doll lashes
+  };
+
+  const EyelashColor$1 = {
+    Black: 0,      // Near-black (default)
+    Brown: 1,      // Soft brown
+    SoftBlack: 2   // Slightly softer black
+  };
+
+  const PupilColor$1 = {
+    Hazel: 0,  // Amber / honey brown
+    Ice: 1,    // Icy blue
+    Mocha: 2,  // Dark brown with sparkle
+    Olive: 3,  // Forest green
+    Gloss: 4,  // Glossy dark brown
+    Moss: 5,   // Muted olive
+    Sand: 6,   // Sandy beige brown
+    Glow: 7,   // Lower-iris crescent highlight
+    Slate: 8   // Cool blue-grey
+  };
+
+  const ChromaKeyColor$1 = {
+    Green: 0,
+    Blue: 1,
+    Red: 2
+  };
+
+  /** Frame type for processing (affects temporal smoothing / tracking). */
+  const FrameType$1 = {
+    Image: 0,  // Still image
+    Video: 1   // Continuous video stream
+  };
+
+  /** Mirror mode applied to the input before processing. */
+  const MirrorMode$1 = {
+    None: 0,        // No mirror
+    Horizontal: 1,  // Horizontal (e.g. front-camera selfie)
+    Vertical: 2,    // Vertical
+    Both: 3         // Both axes
   };
 
   var constants = /*#__PURE__*/Object.freeze({
     __proto__: null,
-    BackgroundMode: BackgroundMode$1,
-    BasicParam: BasicParam$1,
-    BeautyType: BeautyType$1,
+    BlushColor: BlushColor$1,
     BlushStyle: BlushStyle$1,
-    ChromaKeyParam: ChromaKeyParam,
+    ChromaKeyColor: ChromaKeyColor$1,
+    ContourStyle: ContourStyle$1,
+    EngineEventCode: EngineEventCode$1,
+    EyeLinerColor: EyeLinerColor$1,
+    EyeLinerStyle: EyeLinerStyle$1,
+    EyeShadowColor: EyeShadowColor$1,
+    EyeShadowStyle: EyeShadowStyle$1,
+    EyebrowColor: EyebrowColor$1,
+    EyebrowStyle: EyebrowStyle$1,
+    EyelashColor: EyelashColor$1,
+    EyelashStyle: EyelashStyle$1,
     FrameType: FrameType$1,
-    LipstickStyle: LipstickStyle$1,
-    MakeupParam: MakeupParam$1,
+    LipstickColor: LipstickColor$1,
     MirrorMode: MirrorMode$1,
-    ReshapeParam: ReshapeParam$1,
-    VirtualBackgroundOptions: VirtualBackgroundOptions$1
+    PupilColor: PupilColor$1,
+    Reshape: Reshape$1,
+    SmoothingStyle: SmoothingStyle$1,
+    WhiteningStyle: WhiteningStyle$1
   });
 
   /**
@@ -272,17 +346,28 @@
     console.warn(formatLogLine('warning', message));
   }
 
-  /** @param {string} message */
-  function logError(message) {
-    console.error(formatLogLine('error', message));
-  }
-
   /**
    * Beauty Effect Engine Core
    * Platform-agnostic engine implementation with dependency injection
    */
 
 
+  /** Byte layouts of fb_engine_config_t / fb_log_config_t on wasm32. */
+  const FB_ENGINE_CONFIG_SIZE = 28;
+  const FB_LOG_CONFIG_SIZE = 16;
+
+  function allocUtf8(Module, text) {
+    const value = text || '';
+    const len = Module.lengthBytesUTF8(value) + 1;
+    const ptr = Module._malloc(len);
+    Module.stringToUTF8(value, ptr, len);
+    return ptr;
+  }
+
+  function writeI32(Module, ptr, index, value) {
+    Module.HEAP32[(ptr >> 2) + index] = value;
+  }
+
   /**
    * Beauty effect engine class
    * Provides high-level API for face beauty effects processing
@@ -297,9 +382,8 @@
      * @param {Function} platformAPI.getWasmModule - Get WASM module instance
      * @param {Function} platformAPI.getWasmBuffer - Get WASM memory buffer
      * @param {Function} platformAPI.toImageData - Convert to ImageData
-     * @param {Function} platformAPI.verifyAppKeyOnline - Verify app key online
-     * @param {Function} [platformAPI.ensureGPUPixelCanvas] - Ensure GPU canvas exists (browser only)
-     * @param {Function} [platformAPI.cleanupGPUPixelCanvas] - Cleanup GPU canvas (browser only)
+     * @param {Function} [platformAPI.ensureFacebetterCanvas] - Ensure GPU canvas exists (browser only)
+     * @param {Function} [platformAPI.cleanupFacebetterCanvas] - Cleanup GPU canvas (browser only)
      */
     constructor(config, platformAPI) {
       if (!config) {
@@ -325,9 +409,9 @@
       }
 
       this.config = engineConfig;
-      this.appId = engineConfig.appId;
-      this.appKey = engineConfig.appKey;
-      this.licenseJson = engineConfig.licenseJson;
+      this.licenseToken = engineConfig.licenseToken;
+      this.authProxyUrl = engineConfig.authProxyUrl;
+      this.fetchAuthResponse = engineConfig.fetchAuthResponse;
       this.resourcePath = '/resource.fbd';
       this.enginePtr = null;
       this.initialized = false;
@@ -345,18 +429,18 @@
       this._getWasmModule = platformAPI.getWasmModule;
       this._getWasmBuffer = platformAPI.getWasmBuffer;
       this._toImageData = platformAPI.toImageData;
-      this._ensureGPUPixelCanvas = platformAPI.ensureGPUPixelCanvas;
-      this._cleanupGPUPixelCanvas = platformAPI.cleanupGPUPixelCanvas;
+      this._ensureFacebetterCanvas = platformAPI.ensureFacebetterCanvas;
+      this._cleanupFacebetterCanvas = platformAPI.cleanupFacebetterCanvas;
       
       // Browser-specific state
-      this._gpupixelCanvas = null;
-      this._createdGPUPixelCanvas = false;
+      this._facebetterCanvas = null;
+      this._createdFacebetterCanvas = false;
       this._offscreenCanvas = null;
       this._offscreenCtx = null;
       
-      // Automatically create gpupixel_canvas if it doesn't exist (browser only)
-      if (this._ensureGPUPixelCanvas) {
-        this._ensureGPUPixelCanvas();
+      // Automatically create facebetter_canvas if it doesn't exist (browser only)
+      if (this._ensureFacebetterCanvas) {
+        this._ensureFacebetterCanvas();
       }
       
       // Start loading WASM module immediately in constructor
@@ -453,6 +537,10 @@
           if (!Module.onReportUsage) {
             Module.onReportUsage = async (payloadJson) => {
               try {
+                const payload = JSON.parse(payloadJson);
+                if (!payload.app_id || !payload.hmac_signature) {
+                  return true;
+                }
                 const url = 'https://facebetter.pixpark.net/facebetter/v1/report';
                 const response = await fetch(url, {
                   method: 'POST',
@@ -468,48 +556,97 @@
             };
           }
 
-          // Setup online auth proxy for WASM（纯在线，失败不回退本地缓存）。
-          if (!Module.onOnlineAuth) {
-            Module.onOnlineAuth = async (payloadJson) => {
-              const authUrl = 'https://facebetter.pixpark.net/facebetter/v1/auth';
-              logInfo('Online license: requesting auth server');
-              try {
-                const response = await fetch(authUrl, {
-                  method: 'POST',
-                  headers: {
-                    'Content-Type': 'application/json',
-                  },
-                  body: payloadJson,
-                });
-                if (!response.ok) {
-                  logWarn(`Online license: HTTP ${response.status}`);
+          // Web v2 auth: never accept appId/appKey in the browser.
+          // - licenseToken: pre-fetched JWS or `{success, token}` body
+          // - authProxyUrl: production — forward the challenge to your server
+          // - fetchAuthResponse: custom hook; locally use createDirectAuthFetcher
+          if (!this.licenseToken) {
+            if (typeof this.fetchAuthResponse === 'function') {
+              Module.onOnlineAuth = async (payloadJson) => {
+                try {
+                  const challenge = JSON.parse(payloadJson);
+                  const result = await this.fetchAuthResponse(challenge);
+                  if (result && typeof result === 'object' && typeof result.response === 'string') {
+                    return { response: result.response };
+                  }
+                  if (typeof result === 'string') {
+                    return result;
+                  }
+                  if (result && typeof result === 'object') {
+                    return JSON.stringify(result);
+                  }
                   return '';
+                } catch (err) {
+                  logWarn(
+                    `Online license: fetchAuthResponse error${err?.message ? `: ${err.message}` : ''}`
+                  );
+                  return JSON.stringify({
+                    success: false,
+                    error: 'auth_fetch_failed',
+                    message: err?.message || 'auth fetch failed',
+                  });
                 }
-                const text = await response.text();
-                logInfo('Online license: server response ok');
-                return text;
-              } catch (err) {
-                logWarn(
-                  `Online license: network error${err?.message ? `: ${err.message}` : ''}`
-                );
-                return '';
-              }
-            };
+              };
+            } else if (this.authProxyUrl) {
+              Module.onOnlineAuth = async (payloadJson) => {
+                logInfo('Online license: proxying auth challenge');
+                try {
+                  const response = await fetch(this.authProxyUrl, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/json' },
+                    body: payloadJson,
+                  });
+                  if (!response.ok) {
+                    logWarn(`Online license: proxy HTTP ${response.status}`);
+                    return '';
+                  }
+                  const text = await response.text();
+                  logInfo('Online license: proxy response ok');
+                  return text;
+                } catch (err) {
+                  logWarn(
+                    `Online license: proxy error${err?.message ? `: ${err.message}` : ''}`
+                  );
+                  return '';
+                }
+              };
+            } else {
+              throw new FacebetterError(
+                'Web auth requires licenseToken, authProxyUrl, or fetchAuthResponse.',
+                'LICENSE_ERROR'
+              );
+            }
           }
 
-          // Create engine instance, auth (online/offline) is handled by WASM layer via onOnlineAuth
-          const enginePtr = Module.ccall(
-            'CreateBeautyEffectEngineEx',
-            'number',
-            ['string', 'string', 'string', 'string', 'number'],
-            [
-              this.resourcePath,
-              this.licenseJson || '',
-              this.appId || '',
-              this.appKey || '',
-              this.config.externalContext ? 1 : 0
-            ]
-          );
+          // C ABI still has app_id/app_key slots; leave them empty on Web.
+          const appIdPtr = allocUtf8(Module, '');
+          const appKeyPtr = allocUtf8(Module, '');
+          const licensePtr = allocUtf8(Module, this.licenseToken);
+          const resourcePtr = allocUtf8(Module, this.resourcePath);
+          const configPtr = Module._malloc(FB_ENGINE_CONFIG_SIZE);
+          writeI32(Module, configPtr, 0, appIdPtr);
+          writeI32(Module, configPtr, 1, appKeyPtr);
+          writeI32(Module, configPtr, 2, licensePtr);
+          writeI32(Module, configPtr, 3, resourcePtr);
+          writeI32(Module, configPtr, 4, 0);
+          writeI32(Module, configPtr, 5, this.config.externalContext ? 1 : 0);
+          writeI32(Module, configPtr, 6, 0);
+
+          let enginePtr = 0;
+          try {
+            enginePtr = Module.ccall(
+              'fb_engine_create',
+              'number',
+              ['number'],
+              [configPtr]
+            );
+          } finally {
+            Module._free(configPtr);
+            Module._free(appIdPtr);
+            Module._free(appKeyPtr);
+            Module._free(licensePtr);
+            Module._free(resourcePtr);
+          }
 
           if (!enginePtr) {
             throw new FacebetterError(
@@ -557,7 +694,10 @@
         this._callbackSharedBufferSize = 0;
       }
 
-      Module.ccall('DestroyBeautyEffectEngine', null, ['number'], [this.enginePtr]);
+      Module.ccall('fb_engine_destroy', null, ['number'], [this.enginePtr]);
+      if (Module._engine_event_callbacks) {
+        delete Module._engine_event_callbacks[this.enginePtr];
+      }
       this.enginePtr = null;
       this.initialized = false;
       this.bufferSize = 0;
@@ -569,15 +709,15 @@
         this._offscreenCtx = null;
       }
       
-      // Clean up gpupixel_canvas if we created it
-      if (this._cleanupGPUPixelCanvas) {
-        this._cleanupGPUPixelCanvas();
+      // Clean up facebetter_canvas if we created it
+      if (this._cleanupFacebetterCanvas) {
+        this._cleanupFacebetterCanvas();
       }
     }
 
     /**
      * Sets log configuration
-     * Can be called before init() since SetLogConfig is a global function
+     * Can be called before init() since fb_set_log_config is a global function
      * @param {Object} config - Log configuration
      * @param {boolean} config.consoleEnabled - Enable console logging
      * @param {boolean} config.fileEnabled - Enable file logging
@@ -590,406 +730,415 @@
       await this._wasmLoadPromise;
       const Module = this._getWasmModule();
 
-      const result = Module.ccall(
-        'SetLogConfig',
-        'number',
-        ['bool', 'bool', 'number', 'string'],
-        [
-          config.consoleEnabled || false,
-          config.fileEnabled || false,
-          config.level || 0,
-          config.fileName || ''
-        ]
-      );
+      const fileNamePtr = allocUtf8(Module, config.fileName);
+      const configPtr = Module._malloc(FB_LOG_CONFIG_SIZE);
+      writeI32(Module, configPtr, 0, config.consoleEnabled ? 1 : 0);
+      writeI32(Module, configPtr, 1, config.fileEnabled ? 1 : 0);
+      writeI32(Module, configPtr, 2, config.level || 0);
+      writeI32(Module, configPtr, 3, fileNamePtr);
+
+      let result;
+      try {
+        result = Module.ccall(
+          'fb_set_log_config',
+          'number',
+          ['number'],
+          [configPtr]
+        );
+      } finally {
+        Module._free(configPtr);
+        Module._free(fileNamePtr);
+      }
 
       checkResult(result, 'Failed to set log config');
     }
 
     /**
-     * [Deprecated] No-op in parameter-driven mode. Use:
-     * - setBasicParam/setReshapeParam/setMakeupParam
-     * - setVirtualBackground
-     * - setFilter/setSticker
-     * Kept for compatibility and may be removed in a future release.
-     * @deprecated
-     * @param {number} beautyType - Beauty type (use BeautyType enum)
-     * @param {boolean} enabled - Enable or disable
+     * Sets skin smoothing intensity
+     * @param {number} value - Parameter value (0.0 - 1.0)
      */
-    setBeautyTypeEnabled(beautyType, enabled) {
+    setSmoothing(value) {
       this._ensureInitialized();
-      const Module = this._getWasmModule();
-
-      const result = Module.ccall(
-        'SetBeautyTypeEnabled',
-        'number',
-        ['number', 'number', 'number'],
-        [this.enginePtr, beautyType, enabled ? 1 : 0]
-      );
+      this._setIntensity('fb_set_smoothing', value);
+    }
 
-      checkResult(result, `Failed to ${enabled ? 'enable' : 'disable'} beauty type`);
+    /**
+     * Sets skin smoothing style
+     * @param {number} style - Style (use SmoothingStyle enum, e.g., SmoothingStyle.Natural)
+     */
+    setSmoothingStyle(style) {
+      this._setMakeupStyle('fb_set_smoothing_style', style, 'Failed to set smoothing style');
     }
 
     /**
-     * [Deprecated] Always returns false in parameter-driven mode.
-     * Query your own UI state or parameters instead.
-     * Kept for compatibility and may be removed in a future release.
-     * @deprecated
-     * @param {number} beautyType - Beauty type (use BeautyType enum)
-     * @returns {boolean} True if enabled
+     * Sets skin whitening intensity
+     * @param {number} value - Parameter value (0.0 - 1.0)
      */
-    isBeautyTypeEnabled(beautyType) {
+    setWhitening(value) {
       this._ensureInitialized();
-      const Module = this._getWasmModule();
-
-      const result = Module.ccall(
-        'IsBeautyTypeEnabled',
-        'number',
-        ['number', 'number'],
-        [this.enginePtr, beautyType]
-      );
-
-      if (result === -1) {
-        throw new FacebetterError('Failed to check beauty type status');
-      }
+      this._setIntensity('fb_set_whitening', value);
+    }
 
-      return result === 1;
+    /**
+     * Sets whitening style by swapping the custom LUT
+     * @param {number} style - Style (use WhiteningStyle enum, e.g., WhiteningStyle.ColdWhite)
+     */
+    setWhiteningStyle(style) {
+      this._setMakeupStyle('fb_set_whitening_style', style, 'Failed to set whitening style');
     }
 
     /**
-     * [Deprecated] No-op that returns success. To reset, explicitly zero parameters
-     * and clear effects via parameter-driven APIs. Kept for compatibility and may
-     * be removed in a future release.
-     * @deprecated
+     * Sets image sharpening intensity
+     * @param {number} value - Parameter value (0.0 - 1.0)
      */
-    disableAllBeautyTypes() {
+    setSharpening(value) {
       this._ensureInitialized();
-      const Module = this._getWasmModule();
-
-      const result = Module.ccall(
-        'DisableAllBeautyTypes',
-        'number',
-        ['number'],
-        [this.enginePtr]
-      );
-
-      checkResult(result, 'Failed to disable all beauty types');
+      this._setIntensity('fb_set_sharpening', value);
     }
 
     /**
-     * Sets a basic beauty parameter
-     * @param {number} param - Parameter (use BasicParam enum, e.g., BasicParam.Smoothing)
+     * Sets skin rosiness intensity
      * @param {number} value - Parameter value (0.0 - 1.0)
      */
-    setBasicParam(param, value) {
+    setRosiness(value) {
       this._ensureInitialized();
-      this._setBeautyParam('SetBeautyParamBasic', param, value);
+      this._setIntensity('fb_set_rosiness', value);
     }
 
     /**
      * Sets a reshape parameter
-     * @param {number} param - Parameter (use ReshapeParam enum, e.g., ReshapeParam.FaceThinning)
-     * @param {number} value - Parameter value (0.0 - 1.0)
+     * @param {number} param - Parameter (use Reshape enum, e.g., Reshape.FaceThin)
+     * @param {number} value - Parameter value in [-1.0, 1.0]. 0 is off.
      */
-    setReshapeParam(param, value) {
+    setReshape(param, value) {
       this._ensureInitialized();
-      this._setBeautyParam('SetBeautyParamReshape', param, value);
+      this._setBeautyParam('fb_set_reshape', param, value);
     }
 
     /**
-     * Sets a makeup parameter
-     * @param {number} param - Parameter (use MakeupParam enum, e.g., MakeupParam.Lipstick)
+     * Sets lipstick intensity
      * @param {number} value - Parameter value (0.0 - 1.0)
      */
-    setMakeupParam(param, value) {
+    setLipstick(value) {
       this._ensureInitialized();
-      this._setBeautyParam('SetBeautyParamMakeup', param, value);
+      this._setIntensity('fb_set_lipstick', value);
     }
 
     /**
-     * Sets lipstick style/texture
-     * @param {number} style - Style (use LipstickStyle enum, e.g., LipstickStyle.Rouge)
+     * Sets lipstick colour preset
+     * @param {number} style - Style (use LipstickColor enum, e.g., LipstickColor.Rouge)
      */
-    setLipstickStyle(style) {
-      this._ensureInitialized();
-      const Module = this._getWasmModule();
-      const result = Module.ccall(
-        'SetLipstickStyle',
-        'number',
-        ['number', 'number'],
-        [this.enginePtr, style]
-      );
-      checkResult(result, 'Failed to set lipstick style');
+    setLipstickColor(style) {
+      this._setMakeupStyle('fb_set_lipstick_color', style, 'Failed to set lipstick style');
     }
 
     /**
-     * Sets blush style/texture
-     * @param {number} style - Style (use BlushStyle enum, e.g., BlushStyle.Classic)
+     * Sets blush intensity
+     * @param {number} value - Parameter value (0.0 - 1.0)
      */
+    setBlush(value) {
+      this._ensureInitialized();
+      this._setIntensity('fb_set_blush', value);
+    }
+
     setBlushStyle(style) {
+      this._setMakeupStyle('fb_set_blush_style', style, 'Failed to set blush style');
+    }
+
+    setBlushColor(color) {
+      this._setMakeupStyle('fb_set_blush_color', color, 'Failed to set blush color');
+    }
+
+    setContour(value) {
       this._ensureInitialized();
-      const Module = this._getWasmModule();
-      const result = Module.ccall(
-        'SetBlushStyle',
-        'number',
-        ['number', 'number'],
-        [this.enginePtr, style]
-      );
-      checkResult(result, 'Failed to set blush style');
+      this._setIntensity('fb_set_contour', value);
     }
 
-    /**
-     * Sets chroma key parameter
-     * @param {number} param - Parameter (use ChromaKeyParam enum, e.g., ChromaKeyParam.Similarity)
-     * @param {number} value - Parameter value (KeyColor: 0.0=Green, 1.0=Blue, 2.0=Red; others 0.0-1.0)
-     */
-    setChromaKeyParam(param, value) {
+    setContourStyle(style) {
+      this._setMakeupStyle('fb_set_contour_style', style, 'Failed to set contour style');
+    }
+
+    setEyeShadow(value) {
       this._ensureInitialized();
-      // For KeyColor, values are 0, 1, 2, not 0.0-1.0
-      if (param === 0) { // ChromaKeyParam.KeyColor
-          const Module = this._getWasmModule();
-          const result = Module.ccall(
-            'SetBeautyParamChromaKey',
-            'number',
-            ['number', 'number', 'number'],
-            [this.enginePtr, param, value]
-          );
-          checkResult(result, `Failed to set chroma key parameter`);
-          return;
-      }
-      this._setBeautyParam('SetBeautyParamChromaKey', param, value);
+      this._setIntensity('fb_set_eye_shadow', value);
+    }
+
+    setEyeShadowStyle(style) {
+      this._setMakeupStyle('fb_set_eye_shadow_style', style, 'Failed to set eyeshadow style');
+    }
+
+    setEyeShadowColor(style) {
+      this._setMakeupStyle('fb_set_eye_shadow_color', style, 'Failed to set eyeshadow style');
+    }
+
+    setEyeLiner(value) {
+      this._ensureInitialized();
+      this._setIntensity('fb_set_eye_liner', value);
+    }
+
+    setEyeLinerStyle(style) {
+      this._setMakeupStyle('fb_set_eye_liner_style', style, 'Failed to set eyeliner style');
+    }
+
+    setEyeLinerColor(style) {
+      this._setMakeupStyle('fb_set_eye_liner_color', style, 'Failed to set eyeliner style');
+    }
+
+    setEyebrow(value) {
+      this._ensureInitialized();
+      this._setIntensity('fb_set_eyebrow', value);
+    }
+
+    setEyebrowStyle(style) {
+      this._setMakeupStyle('fb_set_eyebrow_style', style, 'Failed to set eyebrow style');
+    }
+
+    setEyebrowColor(style) {
+      this._setMakeupStyle('fb_set_eyebrow_color', style, 'Failed to set eyebrow style');
+    }
+
+    setEyelash(value) {
+      this._ensureInitialized();
+      this._setIntensity('fb_set_eyelash', value);
+    }
+
+    setEyelashStyle(style) {
+      this._setMakeupStyle('fb_set_eyelash_style', style, 'Failed to set eyelash style');
+    }
+
+    setEyelashColor(style) {
+      this._setMakeupStyle('fb_set_eyelash_color', style, 'Failed to set eyelash style');
+    }
+
+    setPupil(value) {
+      this._ensureInitialized();
+      this._setIntensity('fb_set_pupil', value);
+    }
+
+    setPupilColor(style) {
+      this._setMakeupStyle('fb_set_pupil_color', style, 'Failed to set pupil style');
     }
 
     /**
-     * Sets a LUT-based filter
-     * @param {string} filterId - Unique identifier of the filter (e.g., "chuxin"). Pass "" to clear.
+     * Uses chroma keying as the virtual-background mask.
+     * Fill is still controlled by setVirtualBackgroundBlur / setVirtualBackground.
+     * @param {number} color - Key colour (use ChromaKeyColor enum)
      */
-    setFilter(filterId) {
-      this._ensureInitialized();
-      const Module = this._getWasmModule();
-      const result = Module.ccall(
-        'SetFilter',
-        'number',
-        ['number', 'string'],
-        [this.enginePtr, filterId || '']
-      );
-      checkResult(result, 'Failed to set filter');
+    setChromaKey(color) {
+      this._setMakeupStyle('fb_set_chroma_key', color, 'Failed to set chroma key');
     }
 
     /**
-     * Sets the intensity of the current filter
-     * @param {number} intensity - Filter intensity (0.0 - 1.0)
+     * Turns off chroma keying and restores portrait-segmentation as the mask.
      */
-    setFilterIntensity(intensity) {
+    clearChromaKey() {
       this._ensureInitialized();
       const Module = this._getWasmModule();
       const result = Module.ccall(
-        'SetFilterIntensity',
+        'fb_clear_chroma_key',
         'number',
-        ['number', 'number'],
-        [this.enginePtr, intensity]
+        ['number'],
+        [this.enginePtr]
       );
-      checkResult(result, 'Failed to set filter intensity');
+      checkResult(result, 'Failed to clear chroma key');
     }
 
-    /**
-     * Sets a 2D sticker
-     * @param {string} stickerId - Unique identifier of the sticker (e.g., "樱花"). Pass "" to clear.
-     */
-    setSticker(stickerId) {
+    /** How close a pixel must be to the key colour to be keyed out. [0.0, 1.0]. */
+    setChromaKeySimilarity(value) {
+      this._setChromaKeyFloat('fb_set_chroma_key_similarity', value);
+    }
+
+    /** Edge feather around the key. [0.0, 1.0]. */
+    setChromaKeySmoothness(value) {
+      this._setChromaKeyFloat('fb_set_chroma_key_smoothness', value);
+    }
+
+    /** Spill suppression on semi-transparent edges. [0.0, 1.0]. */
+    setChromaKeyDesaturation(value) {
+      this._setChromaKeyFloat('fb_set_chroma_key_desaturation', value);
+    }
+
+    _setChromaKeyFloat(cFuncName, value) {
       this._ensureInitialized();
       const Module = this._getWasmModule();
       const result = Module.ccall(
-        'SetSticker',
+        cFuncName,
         'number',
-        ['number', 'string'],
-        [this.enginePtr, stickerId || '']
+        ['number', 'number'],
+        [this.enginePtr, value]
       );
-      checkResult(result, 'Failed to set sticker');
+      checkResult(result, `Failed to call ${cFuncName}`);
     }
 
     /**
-     * Registers a filter from a file path or data
-     * @param {string} filterId - Unique identifier for the filter
-     * @param {string|Uint8Array} resource - Path to .fbd file or Uint8Array data
+     * Applies a LUT filter from a file path or in-memory .fbd data.
+     * @param {string|Uint8Array} resource - Path to .fbd file or Uint8Array data.
      */
-    registerFilter(filterId, resource) {
+    setFilter(resource) {
       this._ensureInitialized();
       const Module = this._getWasmModule();
 
       if (typeof resource === 'string') {
+        if (!resource) {
+          throw new FacebetterError('Filter path must not be empty; use clearFilter()');
+        }
         const result = Module.ccall(
-          'RegisterFilterPath',
+          'fb_set_filter',
           'number',
-          ['number', 'string', 'string'],
-          [this.enginePtr, filterId, resource]
+          ['number', 'string'],
+          [this.enginePtr, resource]
         );
-        checkResult(result, `Failed to register filter path: ${filterId}`);
-      } else if (resource instanceof Uint8Array) {
+        checkResult(result, 'Failed to set filter from path');
+        return;
+      }
+
+      if (resource instanceof Uint8Array) {
         const dataPtr = Module._malloc(resource.length);
         Module.HEAPU8.set(resource, dataPtr);
         try {
           const result = Module.ccall(
-            'RegisterFilterData',
+            'fb_set_filter_data',
             'number',
-            ['number', 'string', 'number', 'number'],
-            [this.enginePtr, filterId, dataPtr, resource.length]
+            ['number', 'number', 'number'],
+            [this.enginePtr, dataPtr, resource.length]
           );
-          checkResult(result, `Failed to register filter data: ${filterId}`);
+          checkResult(result, 'Failed to set filter from data');
         } finally {
           Module._free(dataPtr);
         }
-      } else {
-        throw new FacebetterError('Resource must be a string path or Uint8Array data');
+        return;
       }
+
+      throw new FacebetterError('Filter resource must be a string path or Uint8Array');
+    }
+
+    /**
+     * Clears the current LUT filter.
+     */
+    clearFilter() {
+      this._ensureInitialized();
+      const Module = this._getWasmModule();
+      const result = Module.ccall(
+        'fb_clear_filter',
+        'number',
+        ['number'],
+        [this.enginePtr]
+      );
+      checkResult(result, 'Failed to clear filter');
+    }
+
+    /**
+     * Sets the intensity of the current filter
+     * @param {number} intensity - Filter intensity (0.0 - 1.0)
+     */
+    setFilterIntensity(intensity) {
+      this._ensureInitialized();
+      const Module = this._getWasmModule();
+      const result = Module.ccall(
+        'fb_set_filter_intensity',
+        'number',
+        ['number', 'number'],
+        [this.enginePtr, intensity]
+      );
+      checkResult(result, 'Failed to set filter intensity');
     }
 
     /**
-     * Registers a sticker from a file path or data
-     * @param {string} stickerId - Unique identifier for the sticker
-     * @param {string|Uint8Array} resource - Path to .fbd file or Uint8Array data
+     * Applies a 2D sticker from a file path or in-memory .fbd data.
+     * @param {string|Uint8Array} resource - Path to .fbd file or Uint8Array data.
      */
-    registerSticker(stickerId, resource) {
+    setSticker(resource) {
       this._ensureInitialized();
       const Module = this._getWasmModule();
 
       if (typeof resource === 'string') {
+        if (!resource) {
+          throw new FacebetterError('Sticker path must not be empty; use clearSticker()');
+        }
         const result = Module.ccall(
-          'RegisterStickerPath',
+          'fb_set_sticker',
           'number',
-          ['number', 'string', 'string'],
-          [this.enginePtr, stickerId, resource]
+          ['number', 'string'],
+          [this.enginePtr, resource]
         );
-        checkResult(result, `Failed to register sticker path: ${stickerId}`);
-      } else if (resource instanceof Uint8Array) {
+        checkResult(result, 'Failed to set sticker from path');
+        return;
+      }
+
+      if (resource instanceof Uint8Array) {
         const dataPtr = Module._malloc(resource.length);
         Module.HEAPU8.set(resource, dataPtr);
         try {
           const result = Module.ccall(
-            'RegisterStickerData',
+            'fb_set_sticker_data',
             'number',
-            ['number', 'string', 'number', 'number'],
-            [this.enginePtr, stickerId, dataPtr, resource.length]
+            ['number', 'number', 'number'],
+            [this.enginePtr, dataPtr, resource.length]
           );
-          checkResult(result, `Failed to register sticker data: ${stickerId}`);
+          checkResult(result, 'Failed to set sticker from data');
         } finally {
           Module._free(dataPtr);
         }
-      } else {
-        throw new FacebetterError('Resource must be a string path or Uint8Array data');
+        return;
       }
+
+      throw new FacebetterError('Sticker resource must be a string path or Uint8Array');
     }
 
     /**
-     * Unregisters a specific filter
-     * @param {string} filterId - Filter ID to unregister
+     * Clears the current 2D sticker.
      */
-    unregisterFilter(filterId) {
+    clearSticker() {
       this._ensureInitialized();
       const Module = this._getWasmModule();
       const result = Module.ccall(
-        'UnregisterFilter',
+        'fb_clear_sticker',
         'number',
-        ['number', 'string'],
-        [this.enginePtr, filterId]
+        ['number'],
+        [this.enginePtr]
       );
-      checkResult(result, `Failed to unregister filter: ${filterId}`);
+      checkResult(result, 'Failed to clear sticker');
     }
 
     /**
-     * Unregisters all filters
+     * Internal method to set a single intensity parameter
+     * @private
      */
-    unregisterAllFilters() {
-      this._ensureInitialized();
+    _setIntensity(functionName, value) {
+      if (value < 0 || value > 1) {
+        throw new FacebetterError('Parameter value must be between 0.0 and 1.0');
+      }
+
       const Module = this._getWasmModule();
       const result = Module.ccall(
-        'UnregisterAllFilters',
+        functionName,
         'number',
-        ['number'],
-        [this.enginePtr]
+        ['number', 'number'],
+        [this.enginePtr, value]
       );
-      checkResult(result, 'Failed to unregister all filters');
+
+      checkResult(result, `Failed to set beauty parameter`);
     }
 
-    /**
-     * Unregisters a specific sticker
-     * @param {string} stickerId - Sticker ID to unregister
-     */
-    unregisterSticker(stickerId) {
+    _setMakeupStyle(cFuncName, value, errorMessage) {
       this._ensureInitialized();
       const Module = this._getWasmModule();
       const result = Module.ccall(
-        'UnregisterSticker',
+        cFuncName,
         'number',
-        ['number', 'string'],
-        [this.enginePtr, stickerId]
+        ['number', 'number'],
+        [this.enginePtr, value]
       );
-      checkResult(result, `Failed to unregister sticker: ${stickerId}`);
+      checkResult(result, errorMessage);
     }
 
     /**
-     * Unregisters all stickers
-     */
-    unregisterAllStickers() {
-       this._ensureInitialized();
-       const Module = this._getWasmModule();
-       const result = Module.ccall(
-         'UnregisterAllStickers',
-         'number',
-         ['number'],
-         [this.enginePtr]
-       );
-       checkResult(result, 'Failed to unregister all stickers');
-     }
-   
-     /**
-      * Gets the list of registered filter IDs
-      * @returns {string[]} Array of registered filter IDs
-      */
-     getRegisteredFilters() {
-       this._ensureInitialized();
-       const Module = this._getWasmModule();
-       const jsonStr = Module.ccall(
-         'GetRegisteredFilters',
-         'string',
-         ['number'],
-         [this.enginePtr]
-       );
-       try {
-         return JSON.parse(jsonStr || '[]');
-       } catch (e) {
-         logError(`Failed to parse registered filters JSON: ${e}`);
-         return [];
-       }
-     }
-   
-     /**
-      * Gets the list of registered sticker IDs
-      * @returns {string[]} Array of registered sticker IDs
-      */
-     getRegisteredStickers() {
-       this._ensureInitialized();
-       const Module = this._getWasmModule();
-       const jsonStr = Module.ccall(
-         'GetRegisteredStickers',
-         'string',
-         ['number'],
-         [this.enginePtr]
-       );
-       try {
-         return JSON.parse(jsonStr || '[]');
-       } catch (e) {
-         logError(`Failed to parse registered stickers JSON: ${e}`);
-         return [];
-       }
-     }
-   
-     /**
-      * Internal method to set beauty parameters
+     * Internal method to set beauty parameters
      * @private
      */
     _setBeautyParam(functionName, param, value) {
-      if (value < 0 || value > 1) {
-        throw new FacebetterError('Parameter value must be between 0.0 and 1.0');
+      if (value < -1 || value > 1) {
+        throw new FacebetterError('Parameter value must be between -1.0 and 1.0');
       }
 
       const Module = this._getWasmModule();
@@ -1004,15 +1153,25 @@
     }
 
     /**
-     * Sets engine callbacks (face landmarks detection)
+     * Sets engine callbacks (face landmarks and engine events)
      * @param {Object} callbacks - Callback functions
-     * @param {Function} callbacks.onFaceLandmarks - Callback for face landmarks detection
+     * @param {Function} [callbacks.onFaceLandmarks] - Callback for face landmarks detection
+     * @param {Function} [callbacks.onEngineEvent] - Callback for license / init events (code, message)
      * @param {number} [callbacks.maxFaces=10] - Maximum number of faces to support (affects shared buffer size)
      */
     setCallbacks(callbacks) {
       this._ensureInitialized();
       const Module = this._getWasmModule();
-      
+
+      if (!Module._engine_event_callbacks) {
+        Module._engine_event_callbacks = {};
+      }
+      if (callbacks && typeof callbacks.onEngineEvent === 'function') {
+        Module._engine_event_callbacks[this.enginePtr] = callbacks.onEngineEvent;
+      } else {
+        delete Module._engine_event_callbacks[this.enginePtr];
+      }
+
       // Initialize callback storage (if it doesn't exist)
       if (!Module._face_landmarks_callbacks) {
         Module._face_landmarks_callbacks = [];
@@ -1028,9 +1187,9 @@
         
         // Pre-allocate shared memory
         // Metadata: 2 ints (frame_number, face_count) = 8 bytes
-        // Face data: maxFaces * 343 floats * 4 bytes = maxFaces * 1372 bytes
+        // Face data: maxFaces * 342 floats * 4 bytes = maxFaces * 1368 bytes
         const metadataSize = 2 * 4;  // 2 ints
-        const faceDataSize = maxFaces * 343 * 4;  // 343 floats per face
+        const faceDataSize = maxFaces * 342 * 4;  // 342 floats per face
         sharedBufferSize = metadataSize + faceDataSize;
         sharedBufferPtr = Module._malloc(sharedBufferSize);
         
@@ -1047,7 +1206,7 @@
             const dataOffset = dataPtr / 4;  // float is 4 bytes
             
             const results = [];
-            const FLOATS_PER_FACE = 343;
+            const FLOATS_PER_FACE = 342;
             
             for (let i = 0; i < faceCount; i++) {
               const faceOffset = dataOffset + i * FLOATS_PER_FACE;
@@ -1063,7 +1222,6 @@
               
               // Read basic fields
               const faceId = Math.round(heap[offset++]);
-              const faceAction = Math.round(heap[offset++]);
               const score = heap[offset++];
               const pitch = heap[offset++];
               const roll = heap[offset++];
@@ -1089,7 +1247,6 @@
                 key_points: keyPoints,
                 visibility,
                 face_id: faceId,
-                face_action: faceAction,
                 score,
                 pitch,
                 roll,
@@ -1108,7 +1265,7 @@
       
       // Call C API
       const result = Module.ccall(
-        'SetCallbacks',
+        'fb_engine_set_wasm_callbacks',
         'number',
         ['number', 'number', 'number', 'number'],
         [
@@ -1137,55 +1294,81 @@
     }
 
     /**
-     * Sets virtual background options (unified API, matches C++/Java/OC)
-     * @param {VirtualBackgroundOptions|Object} options - Virtual background options
-     * @param {number} [options.mode] - Background mode (use BackgroundMode enum)
-     * @param {ImageData|HTMLImageElement|HTMLCanvasElement} [options.backgroundImage] - Background image (required when mode is Image)
+     * Enables virtual background blur.
+     * Level is continuous in [0.0, 1.0] (downsample + mix, no shader rebuild).
+     * @param {number} level - Blur strength in [0.0, 1.0]. 0 clears the virtual background.
      */
-    setVirtualBackground(options) {
+    setVirtualBackgroundBlur(level) {
       this._ensureInitialized();
       const Module = this._getWasmModule();
-      
-      // Support both VirtualBackgroundOptions object and plain object
-      const opts = options.mode !== undefined ? options : { mode: BackgroundMode$1.None, backgroundImage: null };
-      
-      let imageData = null;
-      let imageBufferPtr = null;
-      
-      try {
-        // If a background image is provided, convert to ImageData and prepare buffer
-        if (opts.backgroundImage) {
-          imageData = this._toImageData(opts.backgroundImage);
-          const bufferSize = imageData.width * imageData.height * 4;
-          imageBufferPtr = Module._malloc(bufferSize);
-          
-          const buffer = this._getWasmBuffer();
-          const view = new Uint8Array(buffer, imageBufferPtr, bufferSize);
-          view.set(imageData.data);
+      const result = Module.ccall(
+        'fb_set_virtual_background_blur',
+        'number',
+        ['number', 'number'],
+        [this.enginePtr, level]
+      );
+      checkResult(result, 'Failed to set virtual background blur');
+    }
+
+    /**
+     * Replaces the background with an image file path or encoded png/jpg bytes.
+     * @param {string|Uint8Array} resource - Image path or Uint8Array data.
+     */
+    setVirtualBackground(resource) {
+      this._ensureInitialized();
+      const Module = this._getWasmModule();
+
+      if (typeof resource === 'string') {
+        if (!resource) {
+          throw new FacebetterError(
+            'Virtual background path must not be empty; use clearVirtualBackground()'
+          );
         }
-        
-        // Use unified SetVirtualBackground C interface (consistent with other platforms)
         const result = Module.ccall(
-          'SetVirtualBackground',
+          'fb_set_virtual_background',
           'number',
-          ['number', 'number', 'number', 'number', 'number', 'number'],
-          [
-            this.enginePtr,
-            opts.mode,
-            imageBufferPtr || 0,  // If null, pass 0
-            imageData ? imageData.width : 0,
-            imageData ? imageData.height : 0,
-            imageData ? imageData.width * 4 : 0
-          ]
+          ['number', 'string'],
+          [this.enginePtr, resource]
         );
-        
-        checkResult(result, 'Failed to set virtual background');
-      } finally {
-        // Free memory
-        if (imageBufferPtr) {
-          Module._free(imageBufferPtr);
+        checkResult(result, 'Failed to set virtual background from path');
+        return;
+      }
+
+      if (resource instanceof Uint8Array) {
+        const dataPtr = Module._malloc(resource.length);
+        Module.HEAPU8.set(resource, dataPtr);
+        try {
+          const result = Module.ccall(
+            'fb_set_virtual_background_data',
+            'number',
+            ['number', 'number', 'number'],
+            [this.enginePtr, dataPtr, resource.length]
+          );
+          checkResult(result, 'Failed to set virtual background from data');
+        } finally {
+          Module._free(dataPtr);
         }
+        return;
       }
+
+      throw new FacebetterError(
+        'setVirtualBackground expects a file path string or Uint8Array'
+      );
+    }
+
+    /**
+     * Clears virtual background (blur or image replacement).
+     */
+    clearVirtualBackground() {
+      this._ensureInitialized();
+      const Module = this._getWasmModule();
+      const result = Module.ccall(
+        'fb_clear_virtual_background',
+        'number',
+        ['number'],
+        [this.enginePtr]
+      );
+      checkResult(result, 'Failed to clear virtual background');
     }
 
     /**
@@ -1193,12 +1376,12 @@
      * When enabled, beauty effects will only be applied to detected skin areas.
      * @param {boolean} enabled - True to enable skin-only beauty, false to apply to entire image.
      */
-    setSkinOnlyBeauty(enabled) {
+    setBeautySkinOnly(enabled) {
       this._ensureInitialized();
       const Module = this._getWasmModule();
 
       const result = Module.ccall(
-        'SetSkinOnlyBeauty',
+        'fb_set_beauty_skin_only',
         'number',
         ['number', 'number'],
         [this.enginePtr, enabled ? 1 : 0]
@@ -1207,6 +1390,35 @@
       checkResult(result, 'Failed to set skin only beauty');
     }
 
+    /**
+     * Gets engine performance statistics.
+     * @returns {{fps: number, avgProcessTimeMs: number, sessionTimeS: number}}
+     */
+    getStats() {
+      this._ensureInitialized();
+      const Module = this._getWasmModule();
+      const ptr = Module._malloc(24);
+      try {
+        const result = Module.ccall(
+          'fb_engine_get_stats',
+          'number',
+          ['number', 'number'],
+          [this.enginePtr, ptr]
+        );
+        checkResult(result, 'Failed to get stats');
+        if ((ptr & 7) !== 0) {
+          throw new FacebetterError('Unaligned stats buffer');
+        }
+        const base = ptr >> 3;
+        return {
+          fps: Module.HEAPF64[base],
+          avgProcessTimeMs: Module.HEAPF64[base + 1],
+          sessionTimeS: Module.HEAPF64[base + 2]
+        };
+      } finally {
+        Module._free(ptr);
+      }
+    }
 
     /**
      * Ensures buffers are allocated for the given dimensions
@@ -1260,7 +1472,7 @@
         srcView.set(imageData.data);
 
         const result = Module.ccall(
-          'ProcessImageRGBA',
+          'fb_process_rgba',
           'number',
           ['number', 'number', 'number', 'number', 'number', 'number', 'number', 'number'],
           [
@@ -1321,7 +1533,7 @@
 
       try {
         const result = Module.ccall(
-          'ProcessImageTexture',
+          'fb_process_texture',
           'number',
           ['number', 'number', 'number', 'number', 'number', 'number', 'number'],
           [
@@ -1361,37 +1573,37 @@
     }
 
     /**
-     * Ensures gpupixel_canvas exists in the DOM (browser only)
+     * Ensures facebetter_canvas exists in the DOM (browser only)
      * This canvas is required by GPUPixel for WebGL context creation
      * @private
      */
-    _ensureGPUPixelCanvas() {
+    _ensureFacebetterCanvas() {
       if (typeof document === 'undefined') {
         return;
       }
       
-      let canvas = document.getElementById('gpupixel_canvas');
+      let canvas = document.getElementById('facebetter_canvas');
       if (!canvas) {
         canvas = document.createElement('canvas');
-        canvas.id = 'gpupixel_canvas';
+        canvas.id = 'facebetter_canvas';
         canvas.style.display = 'none';
         canvas.width = 1;
         canvas.height = 1;
         document.body.appendChild(canvas);
-        this._createdGPUPixelCanvas = true;
+        this._createdFacebetterCanvas = true;
       }
-      this._gpupixelCanvas = canvas;
+      this._facebetterCanvas = canvas;
     }
 
     /**
-     * Cleans up gpupixel_canvas if it was created by this engine instance (browser only)
+     * Cleans up facebetter_canvas if it was created by this engine instance (browser only)
      * @private
      */
-    _cleanupGPUPixelCanvas() {
-      if (this._createdGPUPixelCanvas && this._gpupixelCanvas) {
-        this._gpupixelCanvas.remove();
-        this._gpupixelCanvas = null;
-        this._createdGPUPixelCanvas = false;
+    _cleanupFacebetterCanvas() {
+      if (this._createdFacebetterCanvas && this._facebetterCanvas) {
+        this._facebetterCanvas.remove();
+        this._facebetterCanvas = null;
+        this._createdFacebetterCanvas = false;
       }
     }
 
@@ -1420,6 +1632,102 @@
 
   }
 
+  /** Cloudflare v2 online auth URL. Proxy through your server in production; never ship keys in the frontend bundle. */
+  const FACEBETTER_AUTH_URL =
+    'https://facebetter.pixpark.net/facebetter/v2/auth';
+
+  function toHex(buffer) {
+    return Array.from(new Uint8Array(buffer), (b) =>
+      b.toString(16).padStart(2, '0')
+    ).join('');
+  }
+
+  async function hmacSha256Hex(key, message) {
+    const encoder = new TextEncoder();
+    const cryptoKey = await crypto.subtle.importKey(
+      'raw',
+      encoder.encode(key),
+      { name: 'HMAC', hash: 'SHA-256' },
+      false,
+      ['sign']
+    );
+    const signature = await crypto.subtle.sign(
+      'HMAC',
+      cryptoKey,
+      encoder.encode(message)
+    );
+    return toHex(signature);
+  }
+
+  /**
+   * Call Cloudflare v2/auth directly with app_id / app_key.
+   * Intended for local debugging, or environments where key leakage is not a risk.
+   *
+   * @param {Object} options
+   * @param {string} options.appId
+   * @param {string} options.appKey
+   * @param {Object} options.challenge WASM challenge `{nonce, timestamp, platform, user_agent}`
+   * @param {string} [options.authUrl]
+   * @returns {Promise<string>} Raw HTTP body (`{success, token}` or an error envelope)
+   */
+  async function requestFacebetterAuth({
+    appId,
+    appKey,
+    challenge,
+    authUrl = FACEBETTER_AUTH_URL,
+  }) {
+    const id = typeof appId === 'string' ? appId.trim() : '';
+    const key = typeof appKey === 'string' ? appKey.trim() : '';
+    if (!id || !key) {
+      throw new FacebetterError(
+        'requestFacebetterAuth requires appId and appKey',
+        'LICENSE_ERROR'
+      );
+    }
+    if (!challenge || typeof challenge !== 'object') {
+      throw new FacebetterError(
+        'requestFacebetterAuth requires a WASM auth challenge',
+        'LICENSE_ERROR'
+      );
+    }
+
+    const nonce = String(challenge.nonce || '');
+    const timestamp = Number(challenge.timestamp);
+    const platform = String(challenge.platform || 'web');
+    const userAgent = String(challenge.user_agent || '');
+    const payload = `v2|${id}|${timestamp}|${nonce}|${platform}`;
+    const hmac = await hmacSha256Hex(key, payload);
+
+    const response = await fetch(authUrl, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        app_id: id,
+        hmac_signature: hmac,
+        timestamp,
+        nonce,
+        platform,
+        user_agent: userAgent,
+      }),
+    });
+    return response.text();
+  }
+
+  /**
+   * Build an `EngineConfig.fetchAuthResponse` that talks to Cloudflare directly
+   * (no customer proxy).
+   *
+   * @param {Object} options
+   * @param {string} options.appId
+   * @param {string} options.appKey
+   * @param {string} [options.authUrl]
+   * @returns {(challenge: Object) => Promise<string>}
+   */
+  function createDirectAuthFetcher({ appId, appKey, authUrl } = {}) {
+    return (challenge) =>
+      requestFacebetterAuth({ appId, appKey, challenge, authUrl });
+  }
+
   /**
    * Browser-specific WASM Module Loader
    * Supports ESM format WASM modules (generated with MODULARIZE and EXPORT_ES6)
@@ -1684,15 +1992,15 @@
 
 
   // Browser-specific GPU canvas management
-  function ensureGPUPixelCanvas() {
+  function ensureFacebetterCanvas() {
     if (typeof document === 'undefined') {
       return;
     }
     
-    let canvas = document.getElementById('gpupixel_canvas');
+    let canvas = document.getElementById('facebetter_canvas');
     if (!canvas) {
       canvas = document.createElement('canvas');
-      canvas.id = 'gpupixel_canvas';
+      canvas.id = 'facebetter_canvas';
       canvas.style.display = 'none';
       canvas.width = 1;
       canvas.height = 1;
@@ -1702,7 +2010,7 @@
     }
   }
 
-  function cleanupGPUPixelCanvas() {
+  function cleanupFacebetterCanvas() {
     // Cleanup is handled by engine instance
   }
 
@@ -1712,8 +2020,8 @@
     getWasmModule: getWasmModule,
     getWasmBuffer: getWasmBuffer,
     toImageData: toImageData,
-    ensureGPUPixelCanvas,
-    cleanupGPUPixelCanvas
+    ensureFacebetterCanvas,
+    cleanupFacebetterCanvas
   };
 
   // Export factory function for UMD
@@ -1731,42 +2039,68 @@
   }
 
   // Export constants with proper names
-  const BeautyType = BeautyType$1;
-  const BasicParam = BasicParam$1;
-  const ReshapeParam = ReshapeParam$1;
-  const MakeupParam = MakeupParam$1;
-  const LipstickStyle = LipstickStyle$1;
+  const WhiteningStyle = WhiteningStyle$1;
+  const SmoothingStyle = SmoothingStyle$1;
+  const Reshape = Reshape$1;
+  const LipstickColor = LipstickColor$1;
   const BlushStyle = BlushStyle$1;
-  const BackgroundMode = BackgroundMode$1;
+  const BlushColor = BlushColor$1;
+  const ContourStyle = ContourStyle$1;
+  const EyeShadowStyle = EyeShadowStyle$1;
+  const EyeShadowColor = EyeShadowColor$1;
+  const EyeLinerStyle = EyeLinerStyle$1;
+  const EyeLinerColor = EyeLinerColor$1;
+  const EyebrowStyle = EyebrowStyle$1;
+  const EyebrowColor = EyebrowColor$1;
+  const EyelashStyle = EyelashStyle$1;
+  const EyelashColor = EyelashColor$1;
+  const PupilColor = PupilColor$1;
+  const ChromaKeyColor = ChromaKeyColor$1;
   const FrameType = FrameType$1;
   const MirrorMode = MirrorMode$1;
-  const VirtualBackgroundOptions = VirtualBackgroundOptions$1;
+  const EngineEventCode = EngineEventCode$1;
 
   // Default export
   var index = {
     BeautyEffectEngine: BrowserBeautyEffectEngine,
     EngineConfig,
     FacebetterError,
+    FACEBETTER_AUTH_URL,
+    createDirectAuthFetcher,
+    requestFacebetterAuth,
     ...constants,
     loadWasmModule: loadWasmModule
   };
 
-  exports.BackgroundMode = BackgroundMode;
-  exports.BasicParam = BasicParam;
   exports.BeautyEffectEngine = BrowserBeautyEffectEngine;
-  exports.BeautyType = BeautyType;
+  exports.BlushColor = BlushColor;
   exports.BlushStyle = BlushStyle;
+  exports.ChromaKeyColor = ChromaKeyColor;
+  exports.ContourStyle = ContourStyle;
   exports.EngineConfig = EngineConfig;
+  exports.EngineEventCode = EngineEventCode;
+  exports.EyeLinerColor = EyeLinerColor;
+  exports.EyeLinerStyle = EyeLinerStyle;
+  exports.EyeShadowColor = EyeShadowColor;
+  exports.EyeShadowStyle = EyeShadowStyle;
+  exports.EyebrowColor = EyebrowColor;
+  exports.EyebrowStyle = EyebrowStyle;
+  exports.EyelashColor = EyelashColor;
+  exports.EyelashStyle = EyelashStyle;
+  exports.FACEBETTER_AUTH_URL = FACEBETTER_AUTH_URL;
   exports.FacebetterError = FacebetterError;
   exports.FrameType = FrameType;
-  exports.LipstickStyle = LipstickStyle;
-  exports.MakeupParam = MakeupParam;
+  exports.LipstickColor = LipstickColor;
   exports.MirrorMode = MirrorMode;
-  exports.ReshapeParam = ReshapeParam;
-  exports.VirtualBackgroundOptions = VirtualBackgroundOptions;
+  exports.PupilColor = PupilColor;
+  exports.Reshape = Reshape;
+  exports.SmoothingStyle = SmoothingStyle;
+  exports.WhiteningStyle = WhiteningStyle;
   exports.createBeautyEffectEngine = createBeautyEffectEngine;
+  exports.createDirectAuthFetcher = createDirectAuthFetcher;
   exports.default = index;
   exports.loadWasmModule = loadWasmModule;
+  exports.requestFacebetterAuth = requestFacebetterAuth;
 
   Object.defineProperty(exports, '__esModule', { value: true });