facebetter 1.5.1 → 2.0.0

package/dist/facebetter.esm.js

@@ -1,235 +1,309 @@
-/**
- * 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$1 = {
-  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$1,
+  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
 });
 
 /**
@@ -266,17 +340,28 @@ function logWarn(message) {
   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
@@ -291,9 +376,8 @@ class BeautyEffectEngine {
    * @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) {
@@ -319,9 +403,9 @@ class BeautyEffectEngine {
     }
 
     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;
@@ -339,18 +423,18 @@ class BeautyEffectEngine {
     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
@@ -447,6 +531,10 @@ class BeautyEffectEngine {
         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',
@@ -462,48 +550,97 @@ class BeautyEffectEngine {
           };
         }
 
-        // 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(
@@ -551,7 +688,10 @@ class BeautyEffectEngine {
       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;
@@ -563,15 +703,15 @@ class BeautyEffectEngine {
       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
@@ -584,406 +724,415 @@ class BeautyEffectEngine {
     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();
@@ -998,15 +1147,25 @@ class BeautyEffectEngine {
   }
 
   /**
-   * 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 = [];
@@ -1022,9 +1181,9 @@ class BeautyEffectEngine {
       
       // 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);
       
@@ -1041,7 +1200,7 @@ class BeautyEffectEngine {
           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;
@@ -1057,7 +1216,6 @@ class BeautyEffectEngine {
             
             // 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++];
@@ -1083,7 +1241,6 @@ class BeautyEffectEngine {
               key_points: keyPoints,
               visibility,
               face_id: faceId,
-              face_action: faceAction,
               score,
               pitch,
               roll,
@@ -1102,7 +1259,7 @@ class BeautyEffectEngine {
     
     // Call C API
     const result = Module.ccall(
-      'SetCallbacks',
+      'fb_engine_set_wasm_callbacks',
       'number',
       ['number', 'number', 'number', 'number'],
       [
@@ -1131,55 +1288,81 @@ class BeautyEffectEngine {
   }
 
   /**
-   * 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');
   }
 
   /**
@@ -1187,12 +1370,12 @@ class BeautyEffectEngine {
    * 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]
@@ -1201,6 +1384,35 @@ class BeautyEffectEngine {
     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
@@ -1254,7 +1466,7 @@ class BeautyEffectEngine {
       srcView.set(imageData.data);
 
       const result = Module.ccall(
-        'ProcessImageRGBA',
+        'fb_process_rgba',
         'number',
         ['number', 'number', 'number', 'number', 'number', 'number', 'number', 'number'],
         [
@@ -1315,7 +1527,7 @@ class BeautyEffectEngine {
 
     try {
       const result = Module.ccall(
-        'ProcessImageTexture',
+        'fb_process_texture',
         'number',
         ['number', 'number', 'number', 'number', 'number', 'number', 'number'],
         [
@@ -1355,37 +1567,37 @@ class BeautyEffectEngine {
   }
 
   /**
-   * 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;
     }
   }
 
@@ -1414,6 +1626,102 @@ class BeautyEffectEngine {
 
 }
 
+/** 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 Image Utilities
  * Uses DOM APIs (canvas, ImageData, etc.)
@@ -1576,15 +1884,15 @@ function getWasmBuffer() {
 }
 
 // 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;
@@ -1594,7 +1902,7 @@ function ensureGPUPixelCanvas() {
   }
 }
 
-function cleanupGPUPixelCanvas() {
+function cleanupFacebetterCanvas() {
   // Cleanup is handled by engine instance
 }
 
@@ -1604,8 +1912,8 @@ const platformAPI = {
   getWasmModule,
   getWasmBuffer,
   toImageData: toImageData,
-  ensureGPUPixelCanvas,
-  cleanupGPUPixelCanvas
+  ensureFacebetterCanvas,
+  cleanupFacebetterCanvas
 };
 
 // Export factory function
@@ -1623,26 +1931,38 @@ class ESMBeautyEffectEngine extends BeautyEffectEngine {
 }
 
 // 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 ChromaKeyParam = ChromaKeyParam$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: ESMBeautyEffectEngine,
   EngineConfig,
   FacebetterError,
+  FACEBETTER_AUTH_URL,
+  createDirectAuthFetcher,
+  requestFacebetterAuth,
   ...constants,
   loadWasmModule
 };
 
-export { BackgroundMode, BasicParam, ESMBeautyEffectEngine as BeautyEffectEngine, BeautyType, BlushStyle, ChromaKeyParam, EngineConfig, FacebetterError, FrameType, LipstickStyle, MakeupParam, MirrorMode, ReshapeParam, VirtualBackgroundOptions, createBeautyEffectEngine, index as default, getWasmBuffer, getWasmModule, loadWasmModule };
+export { ESMBeautyEffectEngine as BeautyEffectEngine, BlushColor, BlushStyle, ChromaKeyColor, ContourStyle, EngineConfig, EngineEventCode, EyeLinerColor, EyeLinerStyle, EyeShadowColor, EyeShadowStyle, EyebrowColor, EyebrowStyle, EyelashColor, EyelashStyle, FACEBETTER_AUTH_URL, FacebetterError, FrameType, LipstickColor, MirrorMode, PupilColor, Reshape, SmoothingStyle, WhiteningStyle, createBeautyEffectEngine, createDirectAuthFetcher, index as default, getWasmBuffer, getWasmModule, loadWasmModule, requestFacebetterAuth };
 //# sourceMappingURL=facebetter.esm.js.map