@envive-ai/react-hooks 0.3.46 → 0.3.48

package/src/hooks/ProductDetails/variantSelection.ts

@@ -0,0 +1,61 @@
+import CommerceApiClient from 'src/application/commerce-api';
+import {
+  ProductDetails,
+  ProductVariant,
+} from 'src/application/models/graphql/queries/getProductOptionsQuery';
+
+/** A dropdown selection state: option name → chosen value. */
+export type VariantSelection = Record<string, string>;
+
+/**
+ * Imperative variant-details fetch for click-driven flows (the mount-driven
+ * useProductDetails hook is a poor fit when the fetch should ride a button's
+ * pending state). Resolves undefined when the product has no options data.
+ *
+ * @throws on network/HTTP failure or GraphQL errors
+ */
+export const fetchProductDetails = (productId: string): Promise<ProductDetails | undefined> =>
+  CommerceApiClient.retrieveProductDetails(productId);
+
+/**
+ * A product needs the variant selector when there is more than one variant to
+ * choose between and at least one option actually offers a choice.
+ */
+export const needsVariantSelection = (
+  details: ProductDetails | undefined,
+): details is ProductDetails =>
+  !!details && details.variants.length > 1 && details.options.some(o => o.values.length > 1);
+
+/** The variantId to add directly when the product has exactly one variant. */
+export const getSingleVariantId = (details: ProductDetails | undefined): string | undefined =>
+  details && details.variants.length === 1 ? details.variants[0].variantId : undefined;
+
+/**
+ * Initial dropdown state: the options of the first available variant, falling
+ * back to the first variant, falling back to the first value of each option —
+ * so the selector opens in an addable state whenever possible.
+ */
+export const getDefaultVariantSelection = (details: ProductDetails): VariantSelection => {
+  const defaultVariant = details.variants.find(v => v.available) ?? details.variants[0];
+  if (defaultVariant) {
+    return Object.fromEntries(defaultVariant.options.map(({ name, value }) => [name, value]));
+  }
+  return Object.fromEntries(
+    details.options.filter(o => o.values.length > 0).map(o => [o.name, o.values[0]]),
+  );
+};
+
+/**
+ * The variant whose options exactly match the selection (every option name in
+ * the variant agrees with the selected value, and counts match), or undefined
+ * when the combination does not exist.
+ */
+export const findVariantForSelection = (
+  details: ProductDetails,
+  selection: VariantSelection,
+): ProductVariant | undefined =>
+  details.variants.find(
+    variant =>
+      variant.options.length === Object.keys(selection).length &&
+      variant.options.every(({ name, value }) => selection[name] === value),
+  );

package/src/hooks/TrackComponentVisibleEvent/useTrackComponentVisibleEvent.ts

@@ -18,6 +18,14 @@ import {
  * @param rootMargin - Root margin for the intersection observer (defaults to 0px).
  * @param enabled - Whether tracking is enabled (defaults to true).
  */
+const safeNow = (): number | undefined => {
+  try {
+    return typeof window !== 'undefined' ? window.performance?.now?.() : undefined;
+  } catch {
+    return undefined;
+  }
+};
+
 export const useTrackComponentVisibleEvent = (
   element: RefObject<HTMLElement>,
   eventProps?: Record<string, unknown>,
@@ -28,6 +36,12 @@ export const useTrackComponentVisibleEvent = (
   const hasTrackedEvent = useRef(false);
   const { trackEvent } = useAmplitude();
   const variantInfo = useAtomValue(pageVariantInfoAtom);
+  // Captured on first render, not when the event fires: Widget Rendered is
+  // emitted at visibility, which for below-the-fold widgets can be long
+  // after the widget actually rendered. performance.now() is relative to
+  // navigation start, so this reads as "ms from initial page load to
+  // widget render".
+  const renderOffsetMs = useRef(safeNow()).current;
 
   useEffect(() => {
     console.debug('[useTrackComponentVisibleEvent] effect ran', {
@@ -63,6 +77,7 @@ export const useTrackComponentVisibleEvent = (
           widget: eventProps?.widget_type,
         },
         context: variantInfo ? extractPageContext(variantInfo as PageVariantInfo) : null,
+        'performance.render_offset_ms': renderOffsetMs,
       },
     });
     hasTrackedEvent.current = true;

package/src/hooks/WidgetInteraction/types.ts

@@ -61,6 +61,8 @@ export enum WidgetInteractionType {
   SUGGESTION_SCROLLED = 'suggestion_scrolled',
   LINK_CLICKED = 'link_clicked',
   PRODUCT_CARD_CLICKED = 'product_card_clicked',
+  ADD_TO_CART_CLICKED = 'add_to_cart_clicked',
+  ADD_TO_CART_FAILED = 'add_to_cart_failed',
   TEXT_LINK_CLICKED = 'text_link_clicked',
   ARTICLE_LINK_CLICKED = 'article_link_clicked',
   REVIEW_CARD_CLICKED = 'review_card_clicked',
@@ -69,6 +71,9 @@ export enum WidgetInteractionType {
   VOICE_TRANSCRIPTION_STARTED = 'voice_transcription_started',
   VOICE_TRANSCRIPTION_COMPLETED = 'voice_transcription_completed',
   OVERLAY_DISMISSED = 'overlay_dismissed',
+  VARIANT_SELECTOR_OPENED = 'variant_selector_opened',
+  VARIANT_OPTION_SELECTED = 'variant_option_selected',
+  VARIANT_SELECTOR_DISMISSED = 'variant_selector_dismissed',
 }
 
 export enum InteractionClass {
@@ -87,6 +92,8 @@ export const INTERACTION_TYPE_CLASS: Record<WidgetInteractionType, InteractionCl
   [WidgetInteractionType.SUGGESTION_SCROLLED]: InteractionClass.PASSIVE,
   [WidgetInteractionType.LINK_CLICKED]: InteractionClass.INTENTIONAL,
   [WidgetInteractionType.PRODUCT_CARD_CLICKED]: InteractionClass.INTENTIONAL,
+  [WidgetInteractionType.ADD_TO_CART_CLICKED]: InteractionClass.INTENTIONAL,
+  [WidgetInteractionType.ADD_TO_CART_FAILED]: InteractionClass.PASSIVE,
   [WidgetInteractionType.TEXT_LINK_CLICKED]: InteractionClass.INTENTIONAL,
   [WidgetInteractionType.ARTICLE_LINK_CLICKED]: InteractionClass.INTENTIONAL,
   [WidgetInteractionType.REVIEW_CARD_CLICKED]: InteractionClass.INTENTIONAL,
@@ -95,6 +102,9 @@ export const INTERACTION_TYPE_CLASS: Record<WidgetInteractionType, InteractionCl
   [WidgetInteractionType.VOICE_TRANSCRIPTION_STARTED]: InteractionClass.INTENTIONAL,
   [WidgetInteractionType.VOICE_TRANSCRIPTION_COMPLETED]: InteractionClass.INTENTIONAL,
   [WidgetInteractionType.OVERLAY_DISMISSED]: InteractionClass.NAVIGATIONAL,
+  [WidgetInteractionType.VARIANT_SELECTOR_OPENED]: InteractionClass.NAVIGATIONAL,
+  [WidgetInteractionType.VARIANT_OPTION_SELECTED]: InteractionClass.INTENTIONAL,
+  [WidgetInteractionType.VARIANT_SELECTOR_DISMISSED]: InteractionClass.NAVIGATIONAL,
 };
 
 export type URL = {
@@ -153,6 +163,14 @@ export type ProductCardClicked = {
   product_card_clicked: Product;
 };
 
+export type AddToCartClicked = {
+  add_to_cart_clicked: Product;
+};
+
+export type AddToCartFailed = {
+  add_to_cart_failed: Product;
+};
+
 export type ReviewCardClicked = {
   review_card_clicked: Review;
 };
@@ -165,6 +183,24 @@ export type VoiceTranscription = {
   transcription: string;
 };
 
+export type SelectedVariantOption = {
+  product_id: string;
+  option_name: string;
+  option_value: string;
+};
+
+export type VariantSelectorOpened = {
+  variant_selector_opened: Product;
+};
+
+export type VariantOptionSelected = {
+  variant_option_selected: SelectedVariantOption;
+};
+
+export type VariantSelectorDismissed = {
+  variant_selector_dismissed: Product;
+};
+
 export type WidgetInteractionData =
   | SuggestionScrolled
   | SuggestionClicked
@@ -174,6 +210,11 @@ export type WidgetInteractionData =
   | TextLinkClicked
   | ArticleLinkClicked
   | ProductCardClicked
+  | AddToCartClicked
+  | AddToCartFailed
   | ReviewCardClicked
   | MessageSubmitted
-  | VoiceTranscription;
+  | VoiceTranscription
+  | VariantSelectorOpened
+  | VariantOptionSelected
+  | VariantSelectorDismissed;

package/src/services/amplitudeService/__tests__/amplitudeService.test.ts

@@ -105,8 +105,8 @@ describe('AmplitudeService', () => {
   };
 
   describe('Initialization', () => {
-    it('should initialize Amplitude client when all required config is provided', () => {
-      createService();
+    it('should initialize Amplitude client when all required config is provided', async () => {
+      await createService().initialized();
 
       expect(mockInit).toHaveBeenCalledWith(
         validApiKey,
@@ -516,9 +516,9 @@ describe('AmplitudeService', () => {
         configurable: true,
       });
 
-      createService({
+      await createService({
         show: true,
-      });
+      }).initialized();
 
       // Simulate a Page Viewed event by calling the enrichment plugin
       // The enrichment is added during initialization
@@ -564,7 +564,7 @@ describe('AmplitudeService', () => {
         configurable: true,
       });
 
-      createService();
+      await createService().initialized();
 
       const enrichmentCall = mockAdd.mock.calls[0];
       const enrichment = enrichmentCall[0];
@@ -580,7 +580,7 @@ describe('AmplitudeService', () => {
     });
 
     it('should not enrich non-specified events', async () => {
-      createService();
+      await createService().initialized();
 
       const enrichmentCall = mockAdd.mock.calls[0];
       const enrichment = enrichmentCall[0];
@@ -659,8 +659,8 @@ describe('AmplitudeService', () => {
   });
 
   describe('Session replay initialization', () => {
-    it('should disable session replay by default', () => {
-      createService();
+    it('should disable session replay by default', async () => {
+      await createService().initialized();
 
       // Session replay is always disabled in the current implementation
       expect(mockInit).toHaveBeenCalledWith(

package/src/services/amplitudeService/amplitudeService.ts

@@ -1,4 +1,3 @@
-import { createInstance } from '@amplitude/analytics-browser';
 import { EventsDispatcher, SpiffyEvent } from 'src/events';
 import { LocalStorageKeys } from 'src/contexts/localStorageContext';
 import Logger from 'src/application/logging/logger';
@@ -8,7 +7,7 @@ import type {
   Event,
   ServerZoneType,
 } from '@amplitude/analytics-types';
-import { FeatureFlagService } from 'src/contexts/featureFlagServiceContext/featureFlagServiceContext';
+import { FeatureFlagService } from 'src/services/featureFlagService';
 import { WidgetTypeV3 } from 'src/contexts/typesV3';
 import { ChatElementDisplayLocationV3 } from 'src/application/models/chatElementDisplayLocationV3';
 import { ExperimentNamespace, OrgConfigExperimentAssignment } from 'src/application/models';
@@ -80,24 +79,36 @@ export class AmplitudeService {
 
   private config: AmplitudeServiceConfig;
 
+  private initPromise: Promise<void>;
+
   constructor(config: AmplitudeServiceConfig) {
     this.config = config;
-    this.initialize();
+    this.initPromise = this.initialize();
   }
 
   get isMockApiKey(): boolean {
     return this.config.amplitudeApiKey === 'mock-amplitude-key';
   }
 
+  // Must not depend on `amplitudeClient`: the SDK now loads via dynamic
+  // import, and AmplitudeProvider unmounts its entire subtree while
+  // isReady is false — gating on the client would block widget rendering
+  // on the analytics chunk download. Events awaited in trackEvent queue
+  // behind `initPromise` instead.
   get isReady(): boolean {
     return Boolean(
       this.config.userId &&
       this.config.featureFlagService &&
       this.config.amplitudeApiKey &&
-      this.amplitudeClient,
+      !this.isMockApiKey,
     );
   }
 
+  /** Resolves once SDK initialization has settled (never rejects). */
+  initialized(): Promise<void> {
+    return this.initPromise;
+  }
+
   private getLocalStorageItem(key: string): string | null {
     if (this.config.getLocalStorageItem) {
       return this.config.getLocalStorageItem(key);
@@ -246,7 +257,7 @@ export class AmplitudeService {
     return enrichment;
   }
 
-  private initialize(): void {
+  private async initialize(): Promise<void> {
     const isReady = Boolean(
       this.config.userId && this.config.featureFlagService && this.config.amplitudeApiKey,
     );
@@ -270,25 +281,32 @@ export class AmplitudeService {
     }
 
     if (!this.amplitudeClient) {
-      const currentAmplitudeInstance: BrowserClient = createInstance();
-
-      currentAmplitudeInstance.add(this.getEventTrackingEnrichment());
-      currentAmplitudeInstance.init(this.config.amplitudeApiKey, this.config.userId, {
-        serverZone: this.config.dataResidency as ServerZoneType,
-        trackingOptions: {
-          ipAddress: true,
-        },
-        autocapture: {
-          attribution: true,
-          pageViews: {
-            trackHistoryChanges: 'pathOnly',
+      try {
+        // Dynamic import keeps the Amplitude SDK out of the eager
+        // injection-bundle chunk; trackEvent queues behind initPromise.
+        const { createInstance } = await import('@amplitude/analytics-browser');
+        const currentAmplitudeInstance: BrowserClient = createInstance();
+
+        currentAmplitudeInstance.add(this.getEventTrackingEnrichment());
+        currentAmplitudeInstance.init(this.config.amplitudeApiKey, this.config.userId, {
+          serverZone: this.config.dataResidency as ServerZoneType,
+          trackingOptions: {
+            ipAddress: true,
           },
-          sessions: false,
-          formInteractions: false,
-          fileDownloads: false,
-        },
-      });
-      this.amplitudeClient = currentAmplitudeInstance;
+          autocapture: {
+            attribution: true,
+            pageViews: {
+              trackHistoryChanges: 'pathOnly',
+            },
+            sessions: false,
+            formInteractions: false,
+            fileDownloads: false,
+          },
+        });
+        this.amplitudeClient = currentAmplitudeInstance;
+      } catch (err) {
+        logger.logError('Failed to load or initialize the Amplitude SDK', err);
+      }
     }
   }
 
@@ -396,6 +414,7 @@ export class AmplitudeService {
     alsoSendToGoogleAnalytics = false,
   }: TrackEventParams): Promise<void> {
     if (this.isMockApiKey) return;
+    await this.initPromise;
     logger.logDebug('Submitting event', eventName);
     try {
       const decoratedEventName = AmplitudeService.decorateEventName(eventName);

package/src/services/enviveConfigService/enviveConfigService.ts

@@ -1,7 +1,7 @@
 import { OrgConfigExperimentAssignment, OrgConfigFeatureGate } from 'src/application/models';
 import { FeatureGates } from 'src/application/models/featureGates';
-import { FeatureFlagService } from 'src/contexts/featureFlagServiceContext';
-import { GraphQlConfigValues } from 'src/contexts/graphqlContext';
+import { FeatureFlagService } from 'src/services/featureFlagService';
+import type { GraphQlConfigValues } from 'src/contexts/graphqlContext';
 import { configVersionOverride } from 'src/types/config-versions';
 import { fetchGraphQLConfig, fetchUnifiedGraphQLConfig } from './fetchGraphQLConfig';
 

package/src/services/enviveConfigService/fetchGraphQLConfig.ts

@@ -7,13 +7,16 @@ import {
 } from 'src/application/models';
 import { FrontendConfigV3 } from 'src/application/models/frontendConfigV3';
 import { ColorMappingV3 } from 'src/application/models/colorsConfigV3';
-import { FloatingButtonLocation } from '@envive-ai/react-toolkit-v3/FloatingButton';
+// Type-only: a value import would pull the FloatingButton component (and
+// React) through the package's component index into the injection bundle's
+// pre-config chunk.
+import type { FloatingButtonLocation } from '@envive-ai/react-toolkit-v3/FloatingButton';
 import { getColorsAndFrontendQuery } from 'src/application/models/graphql/queries/getColorsAndFrontendQuery';
 import { getWidgetConfigQuery } from 'src/application/models/graphql/queries/getWidgetConfigQuery';
 import { mockV3ColorsConfig, mockV3FrontendConfig } from 'src/contexts/graphqlContext/mockV3Config';
 import { WidgetConfigV3 } from 'src/contexts/typesV3';
 import { PageVariantConfig, PageVariantTestType, WidgetMountingConfig } from 'src/contexts/types';
-import { GraphQlConfigValues } from 'src/contexts/graphqlContext';
+import type { GraphQlConfigValues } from 'src/contexts/graphqlContext';
 import { configVersionOverride } from 'src/types/config-versions';
 import { ExperimentConfigResolutionMetadata } from 'src/application/models/api/orgConfigResults';
 
@@ -39,11 +42,19 @@ export const DEFAULT_PAGE_VARIANTS: PageVariantConfig[] = [
   },
 ];
 
+// String-literal values of the FloatingButtonLocation enum; keep in sync
+// with @envive-ai/react-toolkit-v3/FloatingButton/types/types.ts.
+const FLOATING_BUTTON_POSITIONS = [
+  'bottom-left',
+  'middle-left',
+  'middle-right',
+  'bottom-right',
+] as const;
+
 const mapPositionToCamelCase = (position: string): FloatingButtonLocation => {
-  if (position === 'bottom-left') return FloatingButtonLocation.BOTTOM_LEFT;
-  if (position === 'middle-left') return FloatingButtonLocation.MIDDLE_LEFT;
-  if (position === 'middle-right') return FloatingButtonLocation.MIDDLE_RIGHT;
-  if (position === 'bottom-right') return FloatingButtonLocation.BOTTOM_RIGHT;
+  if ((FLOATING_BUTTON_POSITIONS as readonly string[]).includes(position)) {
+    return position as FloatingButtonLocation;
+  }
   throw new Error(`Invalid position: ${position}`);
 };
 

package/src/services/featureFlagService/index.ts

@@ -0,0 +1,176 @@
+import { OrgConfigFeatureGate } from 'src/application/models/api/orgConfigResults';
+import { FeatureGates } from 'src/application/models/featureGates';
+import Logger from 'src/application/logging/logger';
+
+const FEATURE_FLAGS_STORAGE_KEY = 'spiffy-feature-flags';
+
+const logger = new Logger('featureFlagService');
+
+export interface FullFlagValue {
+  resolved: boolean;
+  initial: boolean | undefined;
+  query_param_override: boolean | undefined;
+  window_param_override: boolean | undefined;
+  stored_override: boolean | undefined;
+}
+
+// Kept free of React imports: the injection bundle constructs this service
+// before deciding whether to load the React app, and pulling React into
+// that pre-config code path would put it on the eager critical chunk.
+export class FeatureFlagService {
+  private featureGates: OrgConfigFeatureGate[];
+
+  constructor(featureGates: OrgConfigFeatureGate[]) {
+    this.featureGates = featureGates;
+  }
+
+  static getQueryParamFeatureGateOverrides(featureGate: FeatureGates): boolean | undefined {
+    const url = window.location?.href ?? '';
+    if (url.includes('?')) {
+      const urlObj = new URL(url);
+      const params = new URLSearchParams(urlObj.search);
+      const paramsObj = Object.fromEntries(params.entries());
+      const value = paramsObj[featureGate];
+
+      if (value != null) {
+        return value === 'true';
+      }
+    }
+
+    return undefined;
+  }
+
+  static getWindowFeatureGateOverrides(featureGate: FeatureGates): boolean | undefined {
+    if (typeof window === 'undefined') {
+      return undefined;
+    }
+    const windowOverride = window as Window & {
+      _envive?: { featureOverrides?: Record<string, boolean> };
+      _spiffy?: { featureOverrides?: Record<string, boolean> };
+    };
+    const featureOverrides =
+      windowOverride?._envive?.featureOverrides ?? windowOverride?._spiffy?.featureOverrides;
+    const value = featureOverrides?.[String(featureGate)];
+    if (value != null) {
+      return value;
+    }
+    return undefined;
+  }
+
+  static getStoredFeatureGateOverrides(featureGate: FeatureGates): boolean | undefined {
+    if (typeof window === 'undefined' || typeof window.localStorage === 'undefined') {
+      return undefined;
+    }
+    try {
+      const featureFlags = window.localStorage.getItem(FEATURE_FLAGS_STORAGE_KEY);
+      if (!featureFlags) {
+        return undefined;
+      }
+      const featureFlagsObj = JSON.parse(featureFlags) as Record<string, boolean>;
+      return featureFlagsObj[featureGate];
+    } catch (err) {
+      logger.logError('getStoredFeatureGateOverrides: error parsing feature flags', err);
+      return undefined;
+    }
+  }
+
+  static getFeatureFlagOverride(featureGate: FeatureGates): boolean | undefined {
+    const queryOverride = FeatureFlagService.getQueryParamFeatureGateOverrides(featureGate);
+    if (queryOverride != null) {
+      logger.logDebug(
+        `isFeatureGateEnabled featureGate:${featureGate} overridden by URL param. New value: ${queryOverride}`,
+      );
+      return queryOverride;
+    }
+
+    const windowOverride = FeatureFlagService.getWindowFeatureGateOverrides(featureGate);
+    if (windowOverride != null) {
+      logger.logDebug(
+        `isFeatureGateEnabled featureGate:${featureGate} overridden by window param. New value: ${windowOverride}`,
+      );
+      return windowOverride;
+    }
+
+    const storedOverride = FeatureFlagService.getStoredFeatureGateOverrides(featureGate);
+    if (storedOverride != null) {
+      logger.logDebug(
+        `isFeatureGateEnabled featureGate:${featureGate} overridden by stored value. New value: ${storedOverride}`,
+      );
+      return storedOverride;
+    }
+
+    return undefined;
+  }
+
+  isFeatureGateEnabled = (featureGate: FeatureGates): boolean => {
+    const gateValue = this.featureGates.find(gate => gate.name === featureGate);
+
+    const featureFlagOverride = FeatureFlagService.getFeatureFlagOverride(featureGate);
+    if (featureFlagOverride !== undefined) {
+      return featureFlagOverride;
+    }
+
+    if (gateValue == null || gateValue.value == null) {
+      logger.logDebug(
+        `isFeatureGateEnabled featureGate:${featureGate} value is undefined - returning false`,
+      );
+      return false;
+    }
+    return gateValue.value;
+  };
+
+  // Ensure that standard overrides work as expected
+  isClientSessionEnabled = (): boolean =>
+    this.isFeatureGateEnabled(FeatureGates.IsClientSessionEnabled);
+
+  getFeatureFlags = (): Record<string, boolean> => {
+    return Object.fromEntries(
+      Object.values(FeatureGates).map((featureGate: FeatureGates) => [
+        featureGate,
+        this.isFeatureGateEnabled(featureGate),
+      ]),
+    );
+  };
+
+  getFullFlagValue = (featureGate: FeatureGates): FullFlagValue => {
+    const gateValue = this.featureGates.find(gate => gate.name === featureGate);
+    return {
+      resolved: this.isFeatureGateEnabled(featureGate),
+      initial: gateValue?.value,
+      query_param_override: FeatureFlagService.getQueryParamFeatureGateOverrides(featureGate),
+      window_param_override: FeatureFlagService.getWindowFeatureGateOverrides(featureGate),
+      stored_override: FeatureFlagService.getStoredFeatureGateOverrides(featureGate),
+    };
+  };
+
+  getFullFlagValues = (): Record<string, FullFlagValue> => {
+    const featureGates = Object.values(FeatureGates).map((featureGate: FeatureGates) => [
+      featureGate,
+      this.getFullFlagValue(featureGate),
+    ]);
+
+    return featureGates.length > 0
+      ? featureGates.reduce<Record<string, FullFlagValue>>((acc, entry) => {
+          const [name, value] = entry as [FeatureGates, FullFlagValue];
+          if (name && value != null) {
+            return { ...acc, [`feature_gate.${name}`]: value };
+          }
+          return acc;
+        }, {})
+      : {};
+  };
+
+  static persistFeatureGateOverrides(): void {
+    if (typeof window === 'undefined' || typeof window.localStorage === 'undefined') {
+      return;
+    }
+    const overrides = Object.values(FeatureGates)
+      .map(
+        featureGate =>
+          [featureGate, FeatureFlagService.getFeatureFlagOverride(featureGate)] as const,
+      )
+      .filter(([, value]) => value !== undefined)
+      .reduce<Record<string, boolean>>((acc, [key, value]) => ({ ...acc, [key]: value! }), {});
+    window.localStorage.setItem(FEATURE_FLAGS_STORAGE_KEY, JSON.stringify(overrides));
+  }
+}

package/src/services/ga4ProjectionService/__tests__/ga4ProjectionService.test.ts

@@ -229,6 +229,42 @@ describe('projectToGA4', () => {
       expect(window.dataLayer[0]).toHaveProperty('interaction_suggestion_id', 'sug-456');
     });
 
+    it('should extract product_id and option_name but not option_value for variant_option_selected', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetInteraction, {
+        'context.page_type': 'pdp',
+        'context.page_id': 'product-123',
+        'trigger.widget': 'floating_chat',
+        'trigger.widget_interaction': 'variant_option_selected',
+        'trigger.widget_interaction_data': {
+          variant_option_selected: {
+            product_id: 'sku-789',
+            option_name: 'Color',
+            option_value: 'Grey',
+          },
+        },
+      });
+
+      const pushed = window.dataLayer[0];
+      expect(pushed).toHaveProperty('interaction_product_id', 'sku-789');
+      expect(pushed).toHaveProperty('interaction_option_name', 'Color');
+      expect(pushed).not.toHaveProperty('interaction_option_value');
+      expect(pushed).not.toHaveProperty('option_value');
+    });
+
+    it('should extract interaction_product_id for variant selector open/dismiss', () => {
+      projectToGA4(EnviveMetricsEventName.WidgetInteraction, {
+        'context.page_type': 'pdp',
+        'context.page_id': 'product-123',
+        'trigger.widget': 'floating_chat',
+        'trigger.widget_interaction': 'variant_selector_dismissed',
+        'trigger.widget_interaction_data': {
+          variant_selector_dismissed: { product_id: 'sku-789' },
+        },
+      });
+
+      expect(window.dataLayer[0]).toHaveProperty('interaction_product_id', 'sku-789');
+    });
+
     it('should drop widget_interaction_data for unwhitelisted interactions', () => {
       projectToGA4(EnviveMetricsEventName.WidgetInteraction, {
         'context.page_type': 'pdp',

package/src/services/ga4ProjectionService/ga4EventSchema.ts

@@ -52,6 +52,13 @@ const WIDGET_INTERACTION_DATA_PROJECTIONS: WidgetInteractionDataProjection = {
   widget_collapsed: { interaction_collapse_source: 'widget_collapsed.collapse_source' },
   product_card_clicked: { interaction_product_id: 'product_card_clicked.product_id' },
   suggestion_scrolled: { interaction_suggestion_id: 'suggestion_scrolled.suggestion_id' },
+  variant_selector_opened: { interaction_product_id: 'variant_selector_opened.product_id' },
+  // option_value is intentionally excluded — merchant-defined values are high cardinality
+  variant_option_selected: {
+    interaction_product_id: 'variant_option_selected.product_id',
+    interaction_option_name: 'variant_option_selected.option_name',
+  },
+  variant_selector_dismissed: { interaction_product_id: 'variant_selector_dismissed.product_id' },
 };
 
 export const GA4_EVENT_SCHEMA: Record<EnviveMetricsEventName, GA4EventSchemaEntry> = {