agora-appbuilder-core 4.1.25-beta.1 → 4.1.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agora-appbuilder-core",
-  "version": "4.1.25-beta.1",
+  "version": "4.1.25",
   "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.25-beta.1",
-  CORE_VERSION: "4.1.25-beta.1",
+  CLI_VERSION: "3.1.25",
+  CORE_VERSION: "4.1.25",
   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/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,