agora-appbuilder-core 4.1.24 → 4.1.25-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agora-appbuilder-core",
-  "version": "4.1.24",
+  "version": "4.1.25-beta.2",
   "description": "React Native template for RTE app builder",
   "main": "index.js",
   "files": [

package/template/defaultConfig.js

@@ -77,8 +77,8 @@ const DefaultConfig = {
   CHAT_ORG_NAME: "",
   CHAT_APP_NAME: "",
   CHAT_URL: "",
-  CLI_VERSION: "3.1.24",
-  CORE_VERSION: "4.1.24",
+  CLI_VERSION: "3.1.25-beta.2",
+  CORE_VERSION: "4.1.25-beta.2",
   DISABLE_LANDSCAPE_MODE: false,
   STT_AUTO_START: false,
   CLOUD_RECORDING_AUTO_START: false,

package/template/src/components/__tests__/pinnedLayoutState.test.ts

@@ -26,16 +26,24 @@ describe('pinned layout state', () => {
     });
   });
 
-  it('does not offer View in large for either pinned position', () => {
-    expect(canViewInLarge(101, 101, 100)).toBe(false);
-    expect(canViewInLarge(100, 101, 100)).toBe(false);
-    expect(canViewInLarge(200, 101, 100)).toBe(true);
+  it('does not offer View in large for either pinned position while in pinned layout', () => {
+    expect(canViewInLarge(101, 101, 100, undefined, true)).toBe(false);
+    expect(canViewInLarge(100, 101, 100, undefined, true)).toBe(false);
+    expect(canViewInLarge(200, 101, 100, undefined, true)).toBe(true);
   });
 
-  it('does not offer View in large for the fallback maximized UID', () => {
-    expect(canViewInLarge(101, undefined, 100, 101)).toBe(false);
-    expect(canViewInLarge(100, undefined, 100, 101)).toBe(false);
-    expect(canViewInLarge(200, undefined, 100, 101)).toBe(true);
+  it('does not offer View in large for the fallback maximized UID while in pinned layout', () => {
+    expect(canViewInLarge(101, undefined, 100, 101, true)).toBe(false);
+    expect(canViewInLarge(100, undefined, 100, 101, true)).toBe(false);
+    expect(canViewInLarge(200, undefined, 100, 101, true)).toBe(true);
+  });
+
+  it('still offers View in large in Grid even when pin/fallback state remains from pinned layout', () => {
+    // Reproduction: View in Large for 101, then switch to Grid without clearing pin.
+    expect(canViewInLarge(101, 101, undefined, 101, false)).toBe(true);
+    // Reproduction: pin cleared but UserPin left 101 at activeUids[0].
+    expect(canViewInLarge(101, undefined, undefined, 101, false)).toBe(true);
+    expect(canViewInLarge(101, 0, undefined, 101, false)).toBe(true);
   });
 
   it('identifies explicit and fallback maximized UIDs for tile actions', () => {

package/template/src/components/participants/UserActionMenuOptions.tsx

@@ -208,17 +208,26 @@ export default function UserActionMenuOptionsOptions(
       )
     ) {
       if (enablePinForMe) {
-        if (
-          canViewInLarge(
-            user.uid,
-            pinnedUid,
-            secondaryPinnedUid,
-            activeUids?.[0],
-          )
-        ) {
+        const isPinnedLayout = currentLayout === getPinnedLayoutName();
+        // Fallback maximized UID is only meaningful in pinned/sidebar layout.
+        // Passing activeUids[0] in Grid incorrectly hides View in Large for the
+        // user who was previously promoted (UserPin leaves them at index 0).
+        const fallbackMaximizedUid = isPinnedLayout
+          ? activeUids?.[0]
+          : undefined;
+        const allowViewInLarge = canViewInLarge(
+          user.uid,
+          pinnedUid,
+          secondaryPinnedUid,
+          fallbackMaximizedUid,
+          isPinnedLayout,
+        );
+        if (allowViewInLarge) {
           const viewInLargeKey = ActionMenuKeys.VIEW_IN_LARGE;
           const viewInLargeConfig = userActionMenuItems?.[viewInLargeKey] ?? {};
-          const isPinned = pinnedUid === user.uid;
+          // In Grid, a leftover pinnedUid must not suppress View in Large —
+          // Grid has no large tile, so the action should re-promote the user.
+          const isPinned = isPinnedLayout && pinnedUid === user.uid;
           const isWhiteboard = user.uid === getWhiteboardUid();
           const isOnlyOneActive = activeUids?.length === 1;
 
@@ -766,6 +775,7 @@ export default function UserActionMenuOptionsOptions(
     disableChatUids,
     secondaryPinnedUid,
     currentLayout,
+    activeUids,
     spotlightUid,
     extraMenuItems,
     setActionMenuVisible,

package/template/src/components/pinnedLayoutState.ts

@@ -33,11 +33,27 @@ export const isUidMaximized = (
   fallbackMaximizedUid?: UidType,
 ) => uid === (pinnedUid || fallbackMaximizedUid);
 
+/**
+ * Whether the tile action menu may offer "View in large".
+ *
+ * Pinned-layout rules (explicit pin, pin-to-top, fallback max at activeUids[0])
+ * only apply while the current layout is pinned/sidebar. In Grid there is no
+ * large tile, so the action must stay available even if pinnedUid or
+ * activeUids[0] still point at this user from a prior pinned session.
+ */
 export const canViewInLarge = (
   uid: UidType,
   pinnedUid?: UidType,
   secondaryPinnedUid?: UidType,
   fallbackMaximizedUid?: UidType,
-) =>
-  !isUidMaximized(uid, pinnedUid, fallbackMaximizedUid) &&
-  uid !== secondaryPinnedUid;
+  isPinnedLayout: boolean = true,
+) => {
+  if (!isPinnedLayout) {
+    return true;
+  }
+
+  return (
+    !isUidMaximized(uid, pinnedUid, fallbackMaximizedUid) &&
+    uid !== secondaryPinnedUid
+  );
+};

package/template/src/subComponents/caption/__tests__/transcriptStreamListener.test.ts

@@ -0,0 +1,47 @@
+import {
+  registerTranscriptStreamListener,
+  removeTranscriptStreamListener,
+  TranscriptStreamEngine,
+} from '../transcriptStreamListener';
+
+describe('transcript stream listener lifecycle', () => {
+  it('tracks and removes a native listener when addListener returns void', () => {
+    const listener = jest.fn();
+    const engine: TranscriptStreamEngine = {
+      addListener: jest.fn(),
+      removeListener: jest.fn(),
+    };
+
+    const registration = registerTranscriptStreamListener(engine, listener);
+
+    expect(registration).toEqual({subscription: null});
+    expect(engine.addListener).toHaveBeenCalledTimes(1);
+    expect(engine.addListener).toHaveBeenCalledWith(
+      'onStreamMessage',
+      listener,
+    );
+
+    removeTranscriptStreamListener(engine, listener, registration, false);
+
+    expect(engine.removeListener).toHaveBeenCalledTimes(1);
+    expect(engine.removeListener).toHaveBeenCalledWith(
+      'onStreamMessage',
+      listener,
+    );
+  });
+
+  it('uses the subscription returned by the web bridge', () => {
+    const listener = jest.fn();
+    const remove = jest.fn();
+    const engine: TranscriptStreamEngine = {
+      addListener: jest.fn(() => ({remove})),
+      removeListener: jest.fn(),
+    };
+
+    const registration = registerTranscriptStreamListener(engine, listener);
+    removeTranscriptStreamListener(engine, listener, registration, true);
+
+    expect(remove).toHaveBeenCalledTimes(1);
+    expect(engine.removeListener).not.toHaveBeenCalled();
+  });
+});

package/template/src/subComponents/caption/transcriptJourney.ts

@@ -0,0 +1 @@
+export const TRANSCRIPT_JOURNEY = '[TRANSCRIPT_JOURNEY]';

package/template/src/subComponents/caption/transcriptStreamListener.ts

@@ -0,0 +1,50 @@
+export type TranscriptStreamListener = (...args: any[]) => void;
+
+type TranscriptStreamSubscription = {
+  remove: () => void;
+};
+
+export type TranscriptStreamEngine = {
+  addListener: (
+    event: 'onStreamMessage',
+    listener: TranscriptStreamListener,
+  ) => unknown;
+  removeListener: (
+    event: 'onStreamMessage',
+    listener: TranscriptStreamListener,
+  ) => void;
+};
+
+export type TranscriptStreamListenerRegistration = {
+  subscription: TranscriptStreamSubscription | null;
+};
+
+export const registerTranscriptStreamListener = (
+  engine: TranscriptStreamEngine,
+  listener: TranscriptStreamListener,
+): TranscriptStreamListenerRegistration => {
+  const result = engine.addListener('onStreamMessage', listener);
+  const subscription =
+    result &&
+    typeof (result as TranscriptStreamSubscription).remove === 'function'
+      ? (result as TranscriptStreamSubscription)
+      : null;
+
+  // Native Agora returns void from addListener. The registration object is our
+  // platform-independent proof that registration completed successfully.
+  return {subscription};
+};
+
+export const removeTranscriptStreamListener = (
+  engine: TranscriptStreamEngine,
+  listener: TranscriptStreamListener,
+  registration: TranscriptStreamListenerRegistration,
+  web: boolean,
+) => {
+  if (web) {
+    registration.subscription?.remove();
+    return;
+  }
+
+  engine.removeListener('onStreamMessage', listener);
+};

package/template/src/subComponents/caption/useCaption.tsx

@@ -21,6 +21,13 @@ import {useRoomInfo} from '../../components/room-info/useRoomInfo';
 import {useContent, useRtc} from 'customization-api';
 import useStreamMessageUtils from './useStreamMessageUtils';
 import {isWebInternal} from '../../utils/common';
+import {TRANSCRIPT_JOURNEY} from './transcriptJourney';
+import {
+  registerTranscriptStreamListener,
+  removeTranscriptStreamListener,
+  TranscriptStreamEngine,
+  TranscriptStreamListenerRegistration,
+} from './transcriptStreamListener';
 
 // Types
 type GlobalSttState = {
@@ -320,22 +327,20 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
       prevSpeakerRef,
       selectedTranslationLanguageRef,
     });
-  const transcriptListenerSubscriptionRef = React.useRef<{
-    remove: () => void;
-  } | null>(null);
-
-  const handleStreamMessageCallback = React.useCallback(
-    (...args: any[]) => {
-      if (isWebInternal()) {
-        const [uid, data] = args;
-        streamMessageCallback([uid, data]);
-      } else {
-        const [, uid, , data] = args;
-        streamMessageCallback([uid, data]);
-      }
-    },
-    [streamMessageCallback],
-  );
+  const streamMessageCallbackRef = React.useRef(streamMessageCallback);
+  streamMessageCallbackRef.current = streamMessageCallback;
+  const transcriptListenerRegistrationRef =
+    React.useRef<TranscriptStreamListenerRegistration | null>(null);
+
+  const handleStreamMessageCallback = React.useCallback((...args: any[]) => {
+    if (isWebInternal()) {
+      const [uid, data] = args;
+      streamMessageCallbackRef.current([uid, data]);
+    } else {
+      const [, uid, , data] = args;
+      streamMessageCallbackRef.current([uid, data]);
+    }
+  }, []);
 
   // Register once for the lifetime of the active call. Keeping collection in
   // the provider makes it independent of whether caption/transcript UI is open.
@@ -343,24 +348,73 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
     if (
       !$config.ENABLE_STT ||
       !callActive ||
-      transcriptListenerSubscriptionRef.current
+      transcriptListenerRegistrationRef.current
     ) {
       return;
     }
 
-    transcriptListenerSubscriptionRef.current = RtcEngineUnsafe.addListener(
-      'onStreamMessage',
-      handleStreamMessageCallback,
+    logger.log(
+      LogSource.Internals,
+      'TRANSCRIPT',
+      `${TRANSCRIPT_JOURNEY} stream listener registration requested`,
+      {stage: 'listener_registration', outcome: 'started'},
     );
-    setIsSTTListenerAdded(true);
-  }, [RtcEngineUnsafe, callActive, handleStreamMessageCallback]);
+    try {
+      transcriptListenerRegistrationRef.current =
+        registerTranscriptStreamListener(
+          RtcEngineUnsafe as unknown as TranscriptStreamEngine,
+          handleStreamMessageCallback,
+        );
+      setIsSTTListenerAdded(true);
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} stream listener registered`,
+        {stage: 'listener_registration', outcome: 'success'},
+      );
+    } catch (error) {
+      logger.error(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} stream listener registration failed`,
+        {
+          stage: 'listener_registration',
+          outcome: 'failure',
+          error: error ?? null,
+        },
+      );
+      return;
+    }
 
-  React.useEffect(() => {
     return () => {
-      transcriptListenerSubscriptionRef.current?.remove();
-      transcriptListenerSubscriptionRef.current = null;
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} stream listener cleanup requested`,
+        {
+          stage: 'listener_cleanup',
+          outcome: 'started',
+          listenerRegistered: !!transcriptListenerRegistrationRef.current,
+        },
+      );
+      if (transcriptListenerRegistrationRef.current) {
+        removeTranscriptStreamListener(
+          RtcEngineUnsafe as unknown as TranscriptStreamEngine,
+          handleStreamMessageCallback,
+          transcriptListenerRegistrationRef.current,
+          isWebInternal(),
+        );
+      }
+      transcriptListenerRegistrationRef.current = null;
+      setIsSTTListenerAdded(false);
+      logger.log(
+        LogSource.Internals,
+        'TRANSCRIPT',
+        `${TRANSCRIPT_JOURNEY} stream listener removed and local references cleared`,
+        {stage: 'listener_cleanup', outcome: 'completed'},
+      );
     };
-  }, []);
+  }, [RtcEngineUnsafe, callActive, handleStreamMessageCallback]);
 
   const flushPendingTranscript = React.useCallback(async () => {
     await flushStreamMessageQueue();
@@ -393,12 +447,17 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
   const updateErrorLabel = useString(sttUpdateError)();
 
   // --- Derived readiness flag for STT ---
+  const localUidReady = !!localUid;
+  const localBotUidReady = !!localBotUid;
+  const rtmJoined = !!hasUserJoinedRTM;
+  const activeCallReady = !!callActive;
+  const roomInfoReady = !!(roomId?.host || roomId?.attendee);
   const sttDepsReady =
-    !!localUid &&
-    !!localBotUid &&
-    !!hasUserJoinedRTM &&
-    !!callActive &&
-    !!(roomId?.host || roomId?.attendee);
+    localUidReady &&
+    localBotUidReady &&
+    rtmJoined &&
+    activeCallReady &&
+    roomInfoReady;
 
   const sttStartGuardRef = React.useRef(false);
   const sttAutoStartGuardRef = React.useRef(false);
@@ -409,6 +468,46 @@ const CaptionProvider: React.FC<CaptionProviderProps> = ({
     sttDepsReadyRef.current = sttDepsReady;
   }, [sttDepsReady]);
 
+  React.useEffect(() => {
+    const missingDependencies = [
+      !localUidReady && 'localUid',
+      !localBotUidReady && 'localBotUid',
+      !rtmJoined && 'RTM',
+      !activeCallReady && 'activeCall',
+      !roomInfoReady && 'roomInfo',
+      !isSTTListenerAdded && 'streamListener',
+    ].filter(Boolean);
+    const transcriptReady = sttDepsReady && isSTTListenerAdded;
+
+    logger.log(
+      LogSource.Internals,
+      'TRANSCRIPT',
+      `${TRANSCRIPT_JOURNEY} STT readiness: ${
+        transcriptReady
+          ? 'READY'
+          : `WAITING (missing: ${missingDependencies.join(', ')})`
+      }`,
+      {
+        stage: 'stt_readiness',
+        outcome: transcriptReady ? 'ready' : 'waiting',
+        localUidReady,
+        localBotUidReady,
+        rtmJoined,
+        callActive: activeCallReady,
+        roomInfoReady,
+        listenerRegistered: isSTTListenerAdded,
+      },
+    );
+  }, [
+    activeCallReady,
+    isSTTListenerAdded,
+    localBotUidReady,
+    localUidReady,
+    roomInfoReady,
+    rtmJoined,
+    sttDepsReady,
+  ]);
+
   React.useEffect(() => {
     if (sttDepsReadyRef.current && !hasFlushedSttQueueRef.current) {
       hasFlushedSttQueueRef.current = true;

package/template/src/subComponents/screenshare/ScreenshareConfigure.native.tsx

@@ -57,6 +57,7 @@ import {
   getScreenshareRecoveryDecision,
   ScreenshareRecoveryCandidate,
 } from './screenshareInterruptionRecovery';
+import {getScreenshareLayoutSwitchLog} from './screenshareJourney';
 
 export const ScreenshareContextConsumer = ScreenshareContext.Consumer;
 
@@ -119,7 +120,7 @@ export const ScreenshareConfigure = (props: {children: React.ReactNode}) => {
 
   const triggerChangeLayout = useCallback(
     (pinned: boolean, screenShareUid?: UidType, parentUid?: UidType) => {
-      let layout = currentLayoutRef.current.currentLayout;
+      const fromLayout = currentLayoutRef.current.currentLayout;
       //screenshare is started set the layout to Pinned View
       if (pinned && screenShareUid) {
         isPinned.current = screenShareUid;
@@ -141,11 +142,51 @@ export const ScreenshareConfigure = (props: {children: React.ReactNode}) => {
             value: [parentUid],
           });
         }
-        layout !== getPinnedLayoutName() && setPinnedLayout();
+        const toLayout = getPinnedLayoutName();
+        const layoutSwitched = fromLayout !== toLayout;
+        if (layoutSwitched) {
+          setPinnedLayout();
+        }
+        const layoutSwitchLog = getScreenshareLayoutSwitchLog(
+          'screenshare start',
+          fromLayout,
+          toLayout,
+        );
+        logger.log(
+          LogSource.Internals,
+          'SCREENSHARE',
+          layoutSwitchLog.message,
+          {
+            action: 'start',
+            ...layoutSwitchLog.fields,
+            screenShareUid,
+            parentUid: parentUid || null,
+          },
+        );
       } else {
         isPinned.current = 0;
         //screenshare is stopped set the layout Grid View
-        layout !== getGridLayoutName() && changeLayout();
+        const toLayout = getGridLayoutName();
+        const layoutSwitched = fromLayout !== toLayout;
+        if (layoutSwitched) {
+          changeLayout();
+        }
+        const layoutSwitchLog = getScreenshareLayoutSwitchLog(
+          'screenshare stop',
+          fromLayout,
+          toLayout,
+        );
+        logger.log(
+          LogSource.Internals,
+          'SCREENSHARE',
+          layoutSwitchLog.message,
+          {
+            action: 'stop',
+            ...layoutSwitchLog.fields,
+            screenShareUid: screenShareUid || null,
+            parentUid: parentUid || null,
+          },
+        );
       }
     },
     [changeLayout, dispatch, setPinnedLayout],
@@ -207,13 +248,31 @@ export const ScreenshareConfigure = (props: {children: React.ReactNode}) => {
       } else if (decision === 'restore') {
         isPinned.current = candidate.uid;
         dispatch({type: 'UserPin', value: [candidate.uid]});
-        if (
+        const fromLayout = currentLayout;
+        const toLayout = getPinnedLayoutName();
+        const layoutSwitched =
           candidate.previousLayout === getPinnedLayoutName() &&
-          currentLayout !== getPinnedLayoutName()
-        ) {
+          fromLayout !== toLayout;
+        if (layoutSwitched) {
           setPinnedLayout();
         }
         recoveryCandidateRef.current = null;
+        const layoutSwitchLog = getScreenshareLayoutSwitchLog(
+          'screenshare recover',
+          fromLayout,
+          layoutSwitched ? toLayout : fromLayout,
+        );
+        logger.log(
+          LogSource.Internals,
+          'SCREENSHARE',
+          layoutSwitchLog.message,
+          {
+            action: 'recover',
+            ...layoutSwitchLog.fields,
+            screenShareUid: candidate.uid,
+            restoredPinnedUid: candidate.previousPinnedUid,
+          },
+        );
       } else if (decision.startsWith('cancel_')) {
         recoveryCandidateRef.current = null;
       }

package/template/src/subComponents/screenshare/ScreenshareConfigure.tsx

@@ -47,6 +47,7 @@ import {
   getScreenshareSessionBoundaryMessage,
   getScreenshareSessionId,
   getScreenshareError,
+  getScreenshareLayoutSwitchLog,
   isUserCancelOrPermissionDenied,
   SCREENSHARE_JOURNEY,
 } from './screenshareJourney';
@@ -184,7 +185,7 @@ export const ScreenshareConfigure = (props: {
     screenShareUid?: UidType,
     parentUid?: UidType,
   ) => {
-    let layout = currentLayoutRef.current.currentLayout;
+    const fromLayout = currentLayoutRef.current.currentLayout;
     //screenshare is started set the layout to Pinned View
     if (pinned && screenShareUid) {
       isPinned.current = screenShareUid;
@@ -206,11 +207,55 @@ export const ScreenshareConfigure = (props: {
           value: [parentUid],
         });
       }
-      layout !== getPinnedLayoutName() && setPinnedLayout();
+      const toLayout = getPinnedLayoutName();
+      const layoutSwitched = fromLayout !== toLayout;
+      if (layoutSwitched) {
+        setPinnedLayout();
+      }
+      const layoutSwitchLog = getScreenshareLayoutSwitchLog(
+        'screenshare start',
+        fromLayout,
+        toLayout,
+      );
+      logger.log(
+        LogSource.Internals,
+        'SCREENSHARE',
+        layoutSwitchLog.message,
+        {
+          action: 'start',
+          ...layoutSwitchLog.fields,
+          screenshareSessionId:
+            activeScreenshareSessionIdRef.current || 'unknown-session',
+          screenShareUid,
+          parentUid: parentUid || null,
+        },
+      );
     } else {
       isPinned.current = 0;
       //screenshare is stopped set the layout Grid View
-      layout !== getGridLayoutName() && changeLayout();
+      const toLayout = getGridLayoutName();
+      const layoutSwitched = fromLayout !== toLayout;
+      if (layoutSwitched) {
+        changeLayout();
+      }
+      const layoutSwitchLog = getScreenshareLayoutSwitchLog(
+        'screenshare stop',
+        fromLayout,
+        toLayout,
+      );
+      logger.log(
+        LogSource.Internals,
+        'SCREENSHARE',
+        layoutSwitchLog.message,
+        {
+          action: 'stop',
+          ...layoutSwitchLog.fields,
+          screenshareSessionId:
+            activeScreenshareSessionIdRef.current || 'unknown-session',
+          screenShareUid: screenShareUid || null,
+          parentUid: parentUid || null,
+        },
+      );
     }
   };
 
@@ -281,13 +326,20 @@ export const ScreenshareConfigure = (props: {
         // newer user pin or screen-share session cancels this path below.
         isPinned.current = candidate.uid;
         dispatch({type: 'UserPin', value: [candidate.uid]});
-        if (
+        const fromLayout = currentLayout;
+        const toLayout = getPinnedLayoutName();
+        const layoutSwitched =
           candidate.previousLayout === getPinnedLayoutName() &&
-          currentLayout !== getPinnedLayoutName()
-        ) {
+          fromLayout !== toLayout;
+        if (layoutSwitched) {
           setPinnedLayout();
         }
         recoveryCandidateRef.current = null;
+        const layoutSwitchLog = getScreenshareLayoutSwitchLog(
+          'screenshare recover',
+          fromLayout,
+          layoutSwitched ? toLayout : fromLayout,
+        );
         logger.log(
           LogSource.Internals,
           'SCREENSHARE',
@@ -304,6 +356,19 @@ export const ScreenshareConfigure = (props: {
             elapsedMs: Date.now() - candidate.detectedAt,
           },
         );
+        logger.log(
+          LogSource.Internals,
+          'SCREENSHARE',
+          layoutSwitchLog.message,
+          {
+            action: 'recover',
+            ...layoutSwitchLog.fields,
+            screenshareSessionId:
+              activeScreenshareSessionIdRef.current || 'unknown-session',
+            screenShareUid: candidate.uid,
+            restoredPinnedUid: candidate.previousPinnedUid,
+          },
+        );
       } else if (decision.startsWith('cancel_')) {
         // An authoritative stop, replacement share, or user layout choice
         // takes precedence over automatic interruption recovery.

package/template/src/subComponents/screenshare/__tests__/screenshareJourney.test.ts

@@ -1,5 +1,6 @@
 import {
   getScreenshareError,
+  getScreenshareLayoutSwitchLog,
   getScreenshareReleaseOrigin,
   getScreenshareSessionBoundaryMessage,
   getScreenshareSessionId,
@@ -12,6 +13,48 @@ describe('screenshare journey logging', () => {
     expect(SCREENSHARE_JOURNEY).toBe('[SCREENSHARE_JOURNEY]');
   });
 
+  it('describes screenshare-driven layout switches for Datadog', () => {
+    expect(
+      getScreenshareLayoutSwitchLog('screenshare start', 'grid', 'pinned'),
+    ).toEqual({
+      message:
+        '[SCREENSHARE_JOURNEY] layout switched from grid to pinned (screenshare start)',
+      fields: {
+        stage: 'layout_update',
+        reason: 'screenshare start',
+        fromLayout: 'grid',
+        toLayout: 'pinned',
+        layoutSwitched: true,
+      },
+    });
+    expect(
+      getScreenshareLayoutSwitchLog('screenshare stop', 'pinned', 'grid'),
+    ).toEqual({
+      message:
+        '[SCREENSHARE_JOURNEY] layout switched from pinned to grid (screenshare stop)',
+      fields: {
+        stage: 'layout_update',
+        reason: 'screenshare stop',
+        fromLayout: 'pinned',
+        toLayout: 'grid',
+        layoutSwitched: true,
+      },
+    });
+    expect(
+      getScreenshareLayoutSwitchLog('screenshare stop', 'grid', 'grid'),
+    ).toEqual({
+      message:
+        '[SCREENSHARE_JOURNEY] layout unchanged at grid (screenshare stop)',
+      fields: {
+        stage: 'layout_update',
+        reason: 'screenshare stop',
+        fromLayout: 'grid',
+        toLayout: 'grid',
+        layoutSwitched: false,
+      },
+    });
+  });
+
   it('puts the session ID directly in start and end boundary messages', () => {
     expect(getScreenshareSessionBoundaryMessage('start', 'session-123')).toBe(
       '----- [SCREENSHARE_JOURNEY] SCREEN SHARE SESSION START | sessionId=session-123 -----',

package/template/src/subComponents/screenshare/screenshareJourney.ts

@@ -1,5 +1,34 @@
 export const SCREENSHARE_JOURNEY = '[SCREENSHARE_JOURNEY]';
 
+export type ScreenshareLayoutSwitchReason =
+  | 'screenshare start'
+  | 'screenshare stop'
+  | 'screenshare recover';
+
+/**
+ * Message + fields for Datadog correlation of screenshare-driven layout changes.
+ * Search: `[SCREENSHARE_JOURNEY] layout switched` or `layout unchanged`.
+ */
+export const getScreenshareLayoutSwitchLog = (
+  reason: ScreenshareLayoutSwitchReason,
+  fromLayout: string,
+  toLayout: string,
+) => {
+  const layoutSwitched = fromLayout !== toLayout;
+  return {
+    message: layoutSwitched
+      ? `${SCREENSHARE_JOURNEY} layout switched from ${fromLayout} to ${toLayout} (${reason})`
+      : `${SCREENSHARE_JOURNEY} layout unchanged at ${fromLayout} (${reason})`,
+    fields: {
+      stage: 'layout_update' as const,
+      reason,
+      fromLayout,
+      toLayout,
+      layoutSwitched,
+    },
+  };
+};
+
 export const getScreenshareSessionBoundaryMessage = (
   boundary: 'start' | 'end',
   screenshareSessionId: string,

package/template/src/utils/__tests__/activeSpeakerState.test.ts

@@ -0,0 +1,23 @@
+import {
+  getCurrentActiveSpeaker,
+  resetCurrentActiveSpeakerForTests,
+  setCurrentActiveSpeaker,
+} from '../activeSpeakerState';
+
+describe('activeSpeakerState', () => {
+  afterEach(() => {
+    resetCurrentActiveSpeakerForTests();
+  });
+
+  it('stores the current active speaker for remount hydration', () => {
+    expect(getCurrentActiveSpeaker()).toBeUndefined();
+    expect(setCurrentActiveSpeaker(101)).toBe(101);
+    expect(getCurrentActiveSpeaker()).toBe(101);
+  });
+
+  it('clears the cache when nobody is speaking (uid 0)', () => {
+    setCurrentActiveSpeaker(101);
+    expect(setCurrentActiveSpeaker(0)).toBeUndefined();
+    expect(getCurrentActiveSpeaker()).toBeUndefined();
+  });
+});

package/template/src/utils/activeSpeakerState.ts

@@ -0,0 +1,25 @@
+import {UidType} from '../../agora-rn-uikit';
+
+/**
+ * Last known active-speaker uid shared across tile mounts.
+ * Video tiles remount when moving into the large slot; without this cache
+ * useActiveSpeaker would start as undefined and miss the current speaker
+ * until the next ACTIVE_SPEAKER event (which is deduped for the same uid).
+ */
+let currentActiveSpeaker: UidType | undefined = undefined;
+
+export const getCurrentActiveSpeaker = (): UidType | undefined =>
+  currentActiveSpeaker;
+
+export const setCurrentActiveSpeaker = (
+  uid: UidType | undefined,
+): UidType | undefined => {
+  // 0 means nobody is speaking — normalize to undefined for consumers.
+  currentActiveSpeaker = uid ? uid : undefined;
+  return currentActiveSpeaker;
+};
+
+/** @internal test helper */
+export const resetCurrentActiveSpeakerForTests = () => {
+  currentActiveSpeaker = undefined;
+};

package/template/src/utils/useActiveSpeaker.ts

@@ -13,16 +13,31 @@ import {useEffect, useState} from 'react';
 import LocalEventEmitter, {
   LocalEventsEnum,
 } from '../rtm-events-api/LocalEvents';
+import {
+  getCurrentActiveSpeaker,
+  setCurrentActiveSpeaker,
+} from './activeSpeakerState';
 
 /**
- * Returns active speaker uid or undefined if nobody speaking
- * @returns function
+ * Returns active speaker uid or undefined if nobody speaking.
+ * Hydrates from the shared last-known uid so remounted tiles (e.g. large slot)
+ * keep the highlight without waiting for a duplicate ACTIVE_SPEAKER emit.
  */
 function useActiveSpeaker() {
-  const [activeSpeaker, setActiveSpeaker] = useState(undefined);
+  const [activeSpeaker, setActiveSpeaker] = useState(() =>
+    getCurrentActiveSpeaker(),
+  );
+
   useEffect(() => {
+    const hydrated = getCurrentActiveSpeaker();
+    // Re-sync if an emit landed between first render and effect attach.
+    if (hydrated !== activeSpeaker) {
+      setActiveSpeaker(hydrated);
+    }
+
     const listenActiveSpeaker = data => {
-      setActiveSpeaker(data);
+      const next = setCurrentActiveSpeaker(data);
+      setActiveSpeaker(next);
     };
     LocalEventEmitter.on(LocalEventsEnum.ACTIVE_SPEAKER, listenActiveSpeaker);
     return () => {
@@ -31,7 +46,9 @@ function useActiveSpeaker() {
         listenActiveSpeaker,
       );
     };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- mount-only hydrate + subscribe
   }, []);
+
   return activeSpeaker;
 }
 

package/template/src/utils/useFindActiveSpeaker.ts

@@ -14,6 +14,7 @@ import LocalEventEmitter, {
   LocalEventsEnum,
 } from '../rtm-events-api/LocalEvents';
 import {LogSource, logger} from '../logger/AppBuilderLogger';
+import {setCurrentActiveSpeaker} from './activeSpeakerState';
 
 enum volumeEnum {
   IS_SPEAKING = 'IS_SPEAKING',
@@ -37,6 +38,9 @@ const useFindActiveSpeaker = () => {
     const timenow = Date.now();
     if (uid !== activeSpeakerUid.current) {
       activeSpeakerUid.current = uid;
+      // Keep shared state in sync before emit so remounted tiles can hydrate
+      // even when this uid is not re-emitted later (deduped while still speaking).
+      setCurrentActiveSpeaker(uid);
       uid
         ? logger.log(
             LogSource.Internals,