@envive-ai/react-hooks 0.3.55 → 0.3.57

package/src/contexts/userIdentityContext/__tests__/userIdentityContext.test.tsx

@@ -177,13 +177,12 @@ describe('UserIdentityProvider', () => {
     it('should allow components to access context via useUserIdentity hook', async () => {
       renderWithProviders(<MockComponent />);
 
+      // Verify all context methods are accessible. The user id is populated by an async
+      // effect, so the content assertions must wait for it rather than assert right away.
       await waitFor(() => {
-        expect(screen.getByTestId('user-id')).toBeInTheDocument();
+        expect(screen.getByTestId('user-id').textContent).toContain('spiffy-user-id-');
+        expect(screen.getByTestId('is-ready').textContent).toBe('true');
       });
-
-      // Verify all context methods are accessible
-      expect(screen.getByTestId('user-id').textContent).toContain('spiffy-user-id-');
-      expect(screen.getByTestId('is-ready').textContent).toBe('true');
     });
 
     it('should throw error when used outside of UserIdentityProvider', () => {

package/src/hooks/ChatToggle/__tests__/useChatToggle.test.ts

@@ -0,0 +1,273 @@
+import { renderHook } from '@testing-library/react';
+import { ChatElementDisplayLocationV3 } from 'src/application/models';
+import { EnviveMetricsEventName } from 'src/contexts/amplitudeContext';
+import {
+  WidgetInteraction,
+  WidgetInteractionComponent,
+  WidgetInteractionType,
+} from '../../WidgetInteraction/types';
+import { useChatToggle } from '../useChatToggle';
+
+const mockTrackEvent = vi.fn();
+const mockTrackWidgetInteraction = vi.fn<(props: WidgetInteraction) => void>();
+const mockOnToggle = vi.fn();
+
+let isOpen = false;
+
+vi.mock('src/contexts/amplitudeContext/amplitudeContext', async () => {
+  const actual = await vi.importActual('src/contexts/amplitudeContext/amplitudeContext');
+  return {
+    ...actual,
+    useAmplitude: () => ({ trackEvent: mockTrackEvent }),
+  };
+});
+
+vi.mock('../../WidgetInteraction', () => ({
+  useWidgetInteraction: () => ({ trackWidgetInteraction: mockTrackWidgetInteraction }),
+}));
+
+vi.mock('jotai', async () => {
+  const actual = await vi.importActual('jotai');
+  return {
+    ...actual,
+    useAtomValue: () => ({ isOpen }),
+    useSetAtom: () => mockOnToggle,
+  };
+});
+
+const emitted = (): WidgetInteraction[] =>
+  (mockTrackWidgetInteraction.mock.calls as unknown as WidgetInteraction[][]).map(
+    ([interaction]) => interaction,
+  );
+
+/** Every WidgetInteraction emission made during the call, as [widget, interactionType] pairs. */
+const emissions = () =>
+  emitted().map(({ trigger }) => [trigger.widget, trigger.widget_interaction]);
+
+const emissionsOfType = (type: WidgetInteractionType) =>
+  emitted().filter(({ trigger }) => trigger.widget_interaction === type);
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  isOpen = false;
+});
+
+describe('useChatToggle — open', () => {
+  it('attributes the click to the widget that was actually clicked', () => {
+    const { result } = renderHook(() => useChatToggle());
+
+    result.current.toggle(ChatElementDisplayLocationV3.SOCIAL_PROOF_PRIMARY_BUTTON);
+
+    expect(emissions()).toEqual([
+      [WidgetInteractionComponent.SOCIAL_PROOF, WidgetInteractionType.WIDGET_CLICKED],
+    ]);
+  });
+
+  it.each([
+    [
+      ChatElementDisplayLocationV3.CHAT_PREVIEW_PROMPT_BUTTON,
+      WidgetInteractionComponent.CHAT_PREVIEW,
+    ],
+    [ChatElementDisplayLocationV3.TYPING_ANIMATION, WidgetInteractionComponent.EMBEDDED_WIDGET],
+    [ChatElementDisplayLocationV3.PROMPT_CAROUSEL, WidgetInteractionComponent.SUGGESTION_BAR],
+    [
+      ChatElementDisplayLocationV3.PRODUCT_CARD_TEXT_FIELD,
+      WidgetInteractionComponent.IMAGE_PROMPT_CARD,
+    ],
+    [ChatElementDisplayLocationV3.FLOATING_BUTTON, WidgetInteractionComponent.FLOATING_BUTTON],
+  ])('attributes %s to %s', (location, expectedWidget) => {
+    const { result } = renderHook(() => useChatToggle());
+
+    result.current.toggle(location);
+
+    expect(emissions()).toEqual([[expectedWidget, WidgetInteractionType.WIDGET_CLICKED]]);
+  });
+
+  it.each([
+    ChatElementDisplayLocationV3.AUTOMATIC_PROMPT,
+    ChatElementDisplayLocationV3.REFERRER_BASED_PROMPT,
+    ChatElementDisplayLocationV3.WINDOW_API_CALL,
+  ])('emits no widget interaction for the system-initiated trigger %s', location => {
+    const { result } = renderHook(() => useChatToggle());
+
+    result.current.toggle(location);
+
+    expect(mockTrackWidgetInteraction).not.toHaveBeenCalled();
+  });
+
+  it('still emits the v2 expanded event for system-initiated opens', () => {
+    // B2 suppresses only the v3 intentional click. The v2 event is unchanged, so merchants
+    // still on v2 dashboards see no difference at all.
+    const { result } = renderHook(() => useChatToggle());
+
+    result.current.toggle(ChatElementDisplayLocationV3.AUTOMATIC_PROMPT);
+
+    expect(mockTrackEvent).toHaveBeenCalledTimes(1);
+    expect(mockTrackEvent.mock.calls[0][0].eventProps.message_metadata.trigger_location).toBe(
+      ChatElementDisplayLocationV3.AUTOMATIC_PROMPT,
+    );
+    expect(mockOnToggle).toHaveBeenCalledTimes(1);
+  });
+
+  it('never emits a collapse when opening', () => {
+    const { result } = renderHook(() => useChatToggle());
+
+    result.current.toggle(ChatElementDisplayLocationV3.SOCIAL_PROOF_PRIMARY_BUTTON);
+
+    expect(emissionsOfType(WidgetInteractionType.WIDGET_COLLAPSED)).toHaveLength(0);
+  });
+});
+
+describe('useChatToggle — close', () => {
+  beforeEach(() => {
+    isOpen = true;
+  });
+
+  it('emits exactly one collapse, attributed to the floating chat', () => {
+    const { result } = renderHook(() => useChatToggle());
+
+    result.current.closeChat(
+      ChatElementDisplayLocationV3.FLOATING_CHAT_OVERLAY,
+      undefined,
+      'body_click',
+    );
+
+    expect(emissions()).toEqual([
+      [WidgetInteractionComponent.FLOATING_CHAT, WidgetInteractionType.WIDGET_COLLAPSED],
+    ]);
+  });
+
+  it.each(['body_click', 'swipe', 'close_button'] as const)(
+    'carries collapse_source %s',
+    source => {
+      const { result } = renderHook(() => useChatToggle());
+
+      result.current.closeChat(
+        ChatElementDisplayLocationV3.FLOATING_CHAT_CLOSE_BUTTON,
+        undefined,
+        source,
+      );
+
+      const [collapse] = emissionsOfType(WidgetInteractionType.WIDGET_COLLAPSED);
+      expect(collapse.trigger.widget_interaction_data).toEqual({
+        widget_collapsed: { collapse_source: source },
+      });
+    },
+  );
+
+  it('omits widget_interaction_data when no collapse source is given', () => {
+    const { result } = renderHook(() => useChatToggle());
+
+    result.current.closeChat(ChatElementDisplayLocationV3.WINDOW_API_CALL);
+
+    const [collapse] = emissionsOfType(WidgetInteractionType.WIDGET_COLLAPSED);
+    expect(collapse.trigger.widget_interaction_data).toBeUndefined();
+  });
+
+  it('never emits a click when closing', () => {
+    const { result } = renderHook(() => useChatToggle());
+
+    result.current.closeChat(ChatElementDisplayLocationV3.FLOATING_CHAT_CLOSE_BUTTON);
+
+    expect(emissionsOfType(WidgetInteractionType.WIDGET_CLICKED)).toHaveLength(0);
+  });
+});
+
+describe('useChatToggle — guards', () => {
+  it('openChat does nothing when the chat is already open', () => {
+    isOpen = true;
+    const { result } = renderHook(() => useChatToggle());
+
+    result.current.openChat(ChatElementDisplayLocationV3.SOCIAL_PROOF_PRIMARY_BUTTON);
+
+    expect(mockTrackWidgetInteraction).not.toHaveBeenCalled();
+    expect(mockOnToggle).not.toHaveBeenCalled();
+  });
+
+  it('closeChat does nothing when the chat is already closed', () => {
+    const { result } = renderHook(() => useChatToggle());
+
+    result.current.closeChat(ChatElementDisplayLocationV3.FLOATING_CHAT_CLOSE_BUTTON);
+
+    expect(mockTrackWidgetInteraction).not.toHaveBeenCalled();
+    expect(mockOnToggle).not.toHaveBeenCalled();
+  });
+
+  it('hover stays attributed to the floating button', () => {
+    // onHover is only wired to the floating button itself, so it is intentionally unchanged.
+    const { result } = renderHook(() => useChatToggle());
+
+    result.current.onHover();
+
+    expect(emissions()).toEqual([
+      [WidgetInteractionComponent.FLOATING_BUTTON, WidgetInteractionType.WIDGET_HOVERED],
+    ]);
+  });
+});
+
+describe('useChatToggle — adaptive storefront safety', () => {
+  it('emits no ASF widget under any trigger location', () => {
+    // The ASF dashboard filters on v3_widget in {full_page_sales_agent,
+    // full_page_sales_agent_recommendations}. This hook must never produce either value, or the
+    // change could move ASF product-surface metrics.
+    const asfWidgets: WidgetInteractionComponent[] = [
+      WidgetInteractionComponent.FULL_PAGE_SALES_AGENT,
+      WidgetInteractionComponent.FULL_PAGE_SALES_AGENT_RECOMMENDATIONS,
+      WidgetInteractionComponent.FULL_PAGE_SALES_AGENT_RECOMMENDATIONS_ATC_FALLBACK,
+    ];
+
+    for (const location of Object.values(ChatElementDisplayLocationV3)) {
+      vi.clearAllMocks();
+
+      isOpen = false;
+      const opened = renderHook(() => useChatToggle());
+      opened.result.current.toggle(location);
+
+      isOpen = true;
+      const closed = renderHook(() => useChatToggle());
+      closed.result.current.toggle(location);
+
+      for (const [widget] of emissions()) {
+        expect(asfWidgets).not.toContain(widget);
+      }
+    }
+  });
+
+  it('only ever emits click, collapse or hover — never an ASF-dashboard interaction type', () => {
+    // The ASF product funnels filter on product_card_clicked / add_to_cart_clicked, and the
+    // engagement funnels on interaction_class=intentional. This hook must not emit any
+    // product-related type.
+    const forbidden = [
+      WidgetInteractionType.PRODUCT_CARD_CLICKED,
+      WidgetInteractionType.ADD_TO_CART_CLICKED,
+      WidgetInteractionType.MESSAGE_SUBMITTED,
+      WidgetInteractionType.SUGGESTION_CLICKED,
+    ];
+
+    for (const location of Object.values(ChatElementDisplayLocationV3)) {
+      vi.clearAllMocks();
+
+      isOpen = false;
+      renderHook(() => useChatToggle()).result.current.toggle(location);
+
+      isOpen = true;
+      renderHook(() => useChatToggle()).result.current.toggle(location);
+
+      for (const [, type] of emissions()) {
+        expect(forbidden).not.toContain(type);
+      }
+    }
+  });
+});
+
+describe('useChatToggle — event names', () => {
+  it('emits the v3 widget interaction event name', () => {
+    const { result } = renderHook(() => useChatToggle());
+
+    result.current.toggle(ChatElementDisplayLocationV3.SOCIAL_PROOF_PRIMARY_BUTTON);
+
+    expect(mockTrackWidgetInteraction.mock.calls[0][0].eventName).toBe(
+      EnviveMetricsEventName.WidgetInteraction,
+    );
+  });
+});

package/src/hooks/ChatToggle/useChatToggle.ts

@@ -7,7 +7,12 @@ import {
   useAmplitude,
 } from 'src/contexts/amplitudeContext/amplitudeContext';
 import { useWidgetInteraction } from '../WidgetInteraction';
-import { WidgetInteractionComponent, WidgetInteractionType } from '../WidgetInteraction/types';
+import {
+  CHAT_TRIGGER_WIDGET,
+  Collapse,
+  WidgetInteractionComponent,
+  WidgetInteractionType,
+} from '../WidgetInteraction/types';
 
 export const useChatToggle = () => {
   const onToggle = useSetAtom(chatOnToggleAtom);
@@ -15,15 +20,27 @@ export const useChatToggle = () => {
   const { trackEvent } = useAmplitude();
   const { trackWidgetInteraction } = useWidgetInteraction();
 
-  const toggle = (triggerLocation: ChatElementDisplayLocationV3, triggerId?: string) => {
+  const toggle = (
+    triggerLocation: ChatElementDisplayLocationV3,
+    triggerId?: string,
+    collapseSource?: Collapse['collapse_source'],
+  ) => {
+    // null for system-initiated triggers, undefined if a caller passed no location at all.
+    const triggerWidget = CHAT_TRIGGER_WIDGET[triggerLocation] ?? null;
+
     if (!isOpen) {
-      trackWidgetInteraction({
-        eventName: EnviveMetricsEventName.WidgetInteraction,
-        trigger: {
-          widget: WidgetInteractionComponent.FLOATING_BUTTON,
-          widget_interaction: WidgetInteractionType.WIDGET_CLICKED,
-        },
-      });
+      // Only a real user click on a real widget counts as an intentional interaction. System
+      // triggers (auto-popup, referrer prompt, window API) are still recorded by the floating
+      // chat's own WIDGET_EXPANDED event, so nothing is lost by skipping the click here.
+      if (triggerWidget) {
+        trackWidgetInteraction({
+          eventName: EnviveMetricsEventName.WidgetInteraction,
+          trigger: {
+            widget: triggerWidget,
+            widget_interaction: WidgetInteractionType.WIDGET_CLICKED,
+          },
+        });
+      }
 
       trackEvent({
         eventName: SpiffyMetricsEventName.ChatComponentExpanded,
@@ -35,11 +52,17 @@ export const useChatToggle = () => {
         },
       });
     } else {
+      // The thing being collapsed is always the floating chat, whatever triggered the close.
+      // This is the single emitter for WIDGET_COLLAPSED — callers pass collapseSource rather
+      // than firing their own duplicate event.
       trackWidgetInteraction({
         eventName: EnviveMetricsEventName.WidgetInteraction,
         trigger: {
-          widget: WidgetInteractionComponent.FLOATING_BUTTON,
+          widget: WidgetInteractionComponent.FLOATING_CHAT,
           widget_interaction: WidgetInteractionType.WIDGET_COLLAPSED,
+          ...(collapseSource
+            ? { widget_interaction_data: { widget_collapsed: { collapse_source: collapseSource } } }
+            : {}),
         },
       });
 
@@ -63,9 +86,13 @@ export const useChatToggle = () => {
     }
   };
 
-  const closeChat = (triggerLocation: ChatElementDisplayLocationV3, triggerId?: string) => {
+  const closeChat = (
+    triggerLocation: ChatElementDisplayLocationV3,
+    triggerId?: string,
+    collapseSource?: Collapse['collapse_source'],
+  ) => {
     if (isOpen) {
-      toggle(triggerLocation, triggerId);
+      toggle(triggerLocation, triggerId, collapseSource);
     }
   };
 

package/src/hooks/Intersection/useIntersection.ts

@@ -1,4 +1,7 @@
 import { RefObject, useEffect, useRef, useState } from 'react';
+import Logger from 'src/application/logging/logger';
+
+const logger = new Logger('useIntersection');
 
 // https://rasilbaidar.medium.com/trigger-event-when-element-enters-viewport-the-react-way-168509da2e23
 export const useIntersection = (element: RefObject<HTMLElement>, rootMargin: string) => {
@@ -10,21 +13,21 @@ export const useIntersection = (element: RefObject<HTMLElement>, rootMargin: str
   // Bails immediately once the observer is attached, keeping per-render cost O(1).
   useEffect(() => {
     const current = element?.current;
-    console.debug('[useIntersection] effect ran', {
+    logger.logDebug('effect ran', {
       elementCurrent: current,
       rootMargin,
       alreadyObserving: !!observerRef.current,
     });
 
     if (!current) {
-      console.debug('[useIntersection] element.current is null — observer NOT attached');
+      logger.logDebug('element.current is null — observer NOT attached');
       return;
     }
     if (observerRef.current) return; // already observing
 
     const observer = new IntersectionObserver(
       ([entry]) => {
-        console.debug('[useIntersection] IntersectionObserver fired', {
+        logger.logDebug('IntersectionObserver fired', {
           isIntersecting: entry.isIntersecting,
           intersectionRatio: entry.intersectionRatio,
           boundingClientRect: entry.boundingClientRect,
@@ -37,7 +40,7 @@ export const useIntersection = (element: RefObject<HTMLElement>, rootMargin: str
 
     observer.observe(current);
     observerRef.current = observer;
-    console.debug('[useIntersection] observer attached to element', current);
+    logger.logDebug('observer attached to element', current);
   });
 
   // Disconnect on unmount only — intentionally separate from the setup effect above.

package/src/hooks/TrackComponentVisibleEvent/useTrackComponentVisibleEvent.ts

@@ -1,5 +1,6 @@
 import { useAtomValue } from 'jotai';
 import { RefObject, useEffect, useRef } from 'react';
+import Logger from 'src/application/logging/logger';
 import { pageVariantInfoAtom } from 'src/atoms/app';
 import { useAmplitude } from 'src/contexts/amplitudeContext/amplitudeContext';
 import { PageVariantInfo } from 'src/contexts/pageContext/types';
@@ -10,6 +11,8 @@ import {
   SpiffyMetricsEventName,
 } from 'src/services/amplitudeService/amplitudeService';
 
+const logger = new Logger('useTrackComponentVisibleEvent');
+
 /**
  * Tracks a component and logs `SpiffyMetricsEventName.ChatComponentVisible` when visible.
  *
@@ -44,7 +47,7 @@ export const useTrackComponentVisibleEvent = (
   const renderOffsetMs = useRef(safeNow()).current;
 
   useEffect(() => {
-    console.debug('[useTrackComponentVisibleEvent] effect ran', {
+    logger.logDebug('effect ran', {
       enabled,
       isVisible,
       hasTrackedEvent: hasTrackedEvent.current,
@@ -52,19 +55,19 @@ export const useTrackComponentVisibleEvent = (
     });
 
     if (!enabled) {
-      console.debug('[useTrackComponentVisibleEvent] skipped — enabled is false');
+      logger.logDebug('skipped — enabled is false');
       return;
     }
     if (hasTrackedEvent.current) {
-      console.debug('[useTrackComponentVisibleEvent] skipped — event already tracked');
+      logger.logDebug('skipped — event already tracked');
       return;
     }
     if (!isVisible) {
-      console.debug('[useTrackComponentVisibleEvent] skipped — element not visible');
+      logger.logDebug('skipped — element not visible');
       return;
     }
 
-    console.debug('[useTrackComponentVisibleEvent] firing tracking events', eventProps);
+    logger.logDebug('firing tracking events', eventProps);
     trackEvent({
       eventName: SpiffyMetricsEventName.ChatComponentVisible,
       eventProps,

package/src/hooks/WidgetInteraction/__tests__/chatTriggerWidget.test.ts

@@ -0,0 +1,51 @@
+import { ChatElementDisplayLocationV3 } from '../../../application/models';
+import { CHAT_TRIGGER_WIDGET, WidgetInteractionComponent } from '../types';
+
+// System-initiated triggers: the chat opens without the shopper clicking a widget. These must not
+// produce an intentional WIDGET_CLICKED, or they inflate every "meaningful engagement" metric.
+const SYSTEM_TRIGGERS = [
+  ChatElementDisplayLocationV3.WINDOW_API_CALL,
+  ChatElementDisplayLocationV3.REFERRER_BASED_PROMPT,
+  ChatElementDisplayLocationV3.AUTOMATIC_PROMPT,
+];
+
+describe('CHAT_TRIGGER_WIDGET', () => {
+  it('maps every display location', () => {
+    for (const location of Object.values(ChatElementDisplayLocationV3)) {
+      expect(CHAT_TRIGGER_WIDGET[location]).not.toBeUndefined();
+    }
+  });
+
+  it('attributes system-initiated triggers to no widget', () => {
+    for (const location of SYSTEM_TRIGGERS) {
+      expect(CHAT_TRIGGER_WIDGET[location]).toBeNull();
+    }
+  });
+
+  it('attributes user-initiated triggers to a widget', () => {
+    const userTriggers = Object.values(ChatElementDisplayLocationV3).filter(
+      location => !SYSTEM_TRIGGERS.includes(location),
+    );
+
+    for (const location of userTriggers) {
+      expect(CHAT_TRIGGER_WIDGET[location]).not.toBeNull();
+    }
+  });
+
+  it('attributes a social proof trigger to social_proof, not floating_button', () => {
+    // Regression guard: useChatToggle used to hardcode FLOATING_BUTTON for every open,
+    // so a suggestion click on the social proof widget was credited to the floating button.
+    expect(CHAT_TRIGGER_WIDGET[ChatElementDisplayLocationV3.SOCIAL_PROOF_PRIMARY_BUTTON]).toBe(
+      WidgetInteractionComponent.SOCIAL_PROOF,
+    );
+    expect(CHAT_TRIGGER_WIDGET[ChatElementDisplayLocationV3.SOCIAL_PROOF_TEXT_FIELD]).toBe(
+      WidgetInteractionComponent.SOCIAL_PROOF,
+    );
+  });
+
+  it('still attributes the floating button to floating_button', () => {
+    expect(CHAT_TRIGGER_WIDGET[ChatElementDisplayLocationV3.FLOATING_BUTTON]).toBe(
+      WidgetInteractionComponent.FLOATING_BUTTON,
+    );
+  });
+});

package/src/hooks/WidgetInteraction/types.ts

@@ -1,3 +1,4 @@
+import { ChatElementDisplayLocationV3 } from '../../application/models';
 import { EnviveMetricsEventName, SpiffyMetricsEventName } from '../../contexts/amplitudeContext';
 
 export interface WidgetInteractionContext {
@@ -114,6 +115,58 @@ export const INTERACTION_TYPE_CLASS: Record<WidgetInteractionType, InteractionCl
   [WidgetInteractionType.VARIANT_SELECTOR_DISMISSED]: InteractionClass.NAVIGATIONAL,
 };
 
+/**
+ * Attribution map: which widget a chat open/close should be credited to, given the surface that
+ * triggered it.
+ *
+ * `null` marks a *system-initiated* trigger — the auto-popup timer, a referrer-based prompt, or a
+ * merchant `window` API call. Those are not user clicks, so they must not emit an intentional
+ * WIDGET_CLICKED. The chat's own WIDGET_EXPANDED still records that the chat opened, so no signal
+ * is lost by skipping them.
+ *
+ * Keyed exhaustively on purpose: adding a ChatElementDisplayLocationV3 member is a compile error
+ * until it is given an attribution here, rather than silently defaulting to the wrong widget.
+ */
+export const CHAT_TRIGGER_WIDGET: Record<
+  ChatElementDisplayLocationV3,
+  WidgetInteractionComponent | null
+> = {
+  [ChatElementDisplayLocationV3.PROMPT_CAROUSEL]: WidgetInteractionComponent.SUGGESTION_BAR,
+  [ChatElementDisplayLocationV3.TITLED_PROMPT_CAROUSEL]: WidgetInteractionComponent.EMBEDDED_WIDGET,
+  [ChatElementDisplayLocationV3.TYPING_ANIMATION]: WidgetInteractionComponent.EMBEDDED_WIDGET,
+  [ChatElementDisplayLocationV3.SOCIAL_PROOF_PRIMARY_BUTTON]:
+    WidgetInteractionComponent.SOCIAL_PROOF,
+  [ChatElementDisplayLocationV3.SOCIAL_PROOF_SECONDARY_BUTTON]:
+    WidgetInteractionComponent.SOCIAL_PROOF,
+  [ChatElementDisplayLocationV3.SOCIAL_PROOF_TEXT_FIELD]: WidgetInteractionComponent.SOCIAL_PROOF,
+  [ChatElementDisplayLocationV3.CHAT_PREVIEW_COMPARISON_PROMPT_BUTTON]:
+    WidgetInteractionComponent.POST_INTERACTION_COMPARISON,
+  [ChatElementDisplayLocationV3.CHAT_PREVIEW_COMPARISON_TEXT_FIELD]:
+    WidgetInteractionComponent.POST_INTERACTION_COMPARISON,
+  [ChatElementDisplayLocationV3.CHAT_PREVIEW_PROMPT_BUTTON]:
+    WidgetInteractionComponent.CHAT_PREVIEW,
+  [ChatElementDisplayLocationV3.CHAT_PREVIEW_TEXT_FIELD]: WidgetInteractionComponent.CHAT_PREVIEW,
+  [ChatElementDisplayLocationV3.PROMPT_BUTTON_CAROUSEL_WITH_IMAGE_PROMPT_BUTTON]:
+    WidgetInteractionComponent.SINGLE_IMAGE_PROMPT,
+  [ChatElementDisplayLocationV3.PROMPT_BUTTON_CAROUSEL_WITH_IMAGE_TEXT_FIELD]:
+    WidgetInteractionComponent.SINGLE_IMAGE_PROMPT,
+  [ChatElementDisplayLocationV3.FLOATING_BUTTON]: WidgetInteractionComponent.FLOATING_BUTTON,
+  [ChatElementDisplayLocationV3.FLOATING_CHAT_OVERLAY]: WidgetInteractionComponent.FLOATING_CHAT,
+  [ChatElementDisplayLocationV3.FLOATING_CHAT_CLOSE_BUTTON]:
+    WidgetInteractionComponent.FLOATING_CHAT,
+  [ChatElementDisplayLocationV3.FLOATING_CHAT_PROMPT_BUTTON]:
+    WidgetInteractionComponent.FLOATING_CHAT,
+  [ChatElementDisplayLocationV3.FLOATING_CHAT_TEXT_INPUT]: WidgetInteractionComponent.FLOATING_CHAT,
+  [ChatElementDisplayLocationV3.PRODUCT_CARD_PROMPT_BUTTON]:
+    WidgetInteractionComponent.IMAGE_PROMPT_CARD,
+  [ChatElementDisplayLocationV3.PRODUCT_CARD_TEXT_FIELD]:
+    WidgetInteractionComponent.IMAGE_PROMPT_CARD,
+  // System-initiated — see note above.
+  [ChatElementDisplayLocationV3.WINDOW_API_CALL]: null,
+  [ChatElementDisplayLocationV3.REFERRER_BASED_PROMPT]: null,
+  [ChatElementDisplayLocationV3.AUTOMATIC_PROMPT]: null,
+};
+
 export type URL = {
   url: string;
 };

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

@@ -241,6 +241,82 @@ describe('AmplitudeService', () => {
       expect(eventProps).toHaveProperty('chat_user_message_input.count', 5);
     });
 
+    it('should encode supplementary Unicode in widget text events for Amplitude transport', async () => {
+      const service = createService();
+
+      await service.trackEvent({
+        eventName: EnviveMetricsEventName.WidgetTextResponse,
+        eventProps: {
+          widget_text: {
+            text_field_placeholder_text: [{ id: 'item-1', value: 'Have a question? Ask away 🙂' }],
+          },
+          response_id: 'response-1',
+        },
+      });
+
+      const eventProps = mockTrack.mock.calls[0][1];
+      expect(eventProps.widget_text).toEqual({
+        text_field_placeholder_text: [
+          {
+            id: 'item-1',
+            value: '__spiffy_utf8__:Have%20a%20question%3F%20Ask%20away%20%F0%9F%99%82',
+          },
+        ],
+      });
+      expect(eventProps.response_id).toBe('response-1');
+      expect(eventProps['widget_text_response.widget_text']).toEqual(eventProps.widget_text);
+
+      await service.trackEvent({
+        eventName: EnviveMetricsEventName.WidgetTextClicked,
+        eventProps: {
+          response_id: 'response-1',
+          string_id: 'item-1',
+          text: 'Have a question? Ask away 🙂',
+        },
+      });
+
+      const clickEventProps = mockTrack.mock.calls[1][1];
+      expect(clickEventProps.text).toBe(
+        '__spiffy_utf8__:Have%20a%20question%3F%20Ask%20away%20%F0%9F%99%82',
+      );
+      expect(clickEventProps['widget_text_clicked.text']).toBe(clickEventProps.text);
+    });
+
+    it.each([
+      ['emoji', '🙂', '__spiffy_utf8__:%F0%9F%99%82'],
+      ['ZWJ sequence', '👩‍💻', '__spiffy_utf8__:%F0%9F%91%A9%E2%80%8D%F0%9F%92%BB'],
+      ['flag', '🇧🇷', '__spiffy_utf8__:%F0%9F%87%A7%F0%9F%87%B7'],
+      ['skin tone', '👍🏽', '__spiffy_utf8__:%F0%9F%91%8D%F0%9F%8F%BD'],
+      ['non-emoji supplementary character', '𝄞', '__spiffy_utf8__:%F0%9D%84%9E'],
+      ['BMP text', 'café', 'café'],
+    ])('should preserve %s across widget click transport', async (_name, text, expected) => {
+      const service = createService();
+
+      await service.trackEvent({
+        eventName: EnviveMetricsEventName.WidgetTextClicked,
+        eventProps: {
+          response_id: 'response-matrix',
+          string_id: 'item-matrix',
+          text,
+        },
+      });
+
+      const eventProps = mockTrack.mock.calls[0][1];
+      expect(eventProps.text).toBe(expected);
+      expect(eventProps['widget_text_clicked.text']).toBe(expected);
+    });
+
+    it('should leave supplementary Unicode unchanged for unrelated events', async () => {
+      const service = createService();
+
+      await service.trackEvent({
+        eventName: SpiffyMetricsEventName.ChatUserMessageInput,
+        eventProps: { message: 'Hello 🙂' },
+      });
+
+      expect(mockTrack.mock.calls[0][1].message).toBe('Hello 🙂');
+    });
+
     it('should generate insert_id from event data', async () => {
       const service = createService();