@webex/plugin-meetings 3.11.0 → 3.12.0-next.2

package/src/locus-info/index.ts

@@ -35,10 +35,14 @@ import HashTreeParser, {
   DataSet,
   HashTreeMessage,
   LocusInfoUpdateType,
+  Metadata,
 } from '../hashTree/hashTreeParser';
 import {HashTreeObject, ObjectType, ObjectTypeToLocusKeyMap} from '../hashTree/types';
-import {isSelf} from '../hashTree/utils';
-import {Links, LocusDTO, LocusFullState} from './types';
+import {isMetadata, isSelf} from '../hashTree/utils';
+import {Links, LocusDTO, ReplacesInfo} from './types';
+import MeetingsUtil from '../meetings/util';
+import {MEETING_KEY} from '../meetings/meetings.types';
+import MeetingCollection from '../meetings/collection';
 
 export type LocusLLMEvent = {
   data: {
@@ -52,6 +56,7 @@ export type LocusLLMEvent = {
 const LocusDtoTopLevelKeys = [
   'controls',
   'fullState',
+  'embeddedApps',
   'host',
   'info',
   'links',
@@ -66,10 +71,13 @@ const LocusDtoTopLevelKeys = [
   'htMeta', // only exists when hash trees are used
 ];
 
-export type LocusApiResponseBody = {
-  dataSets?: DataSet[];
-  locus: LocusDTO; // this LocusDTO here might not be the full one (for example it won't have all the participants, but it should have self)
-};
+export type LocusApiResponseBody =
+  | {
+      dataSets?: DataSet[];
+      locus: LocusDTO; // this LocusDTO here might not be the full one (for example it won't have all the participants, but it should have self)
+      metadata?: Metadata;
+    }
+  | LocusDTO; // when we invoke APIs on the whole Locus like "mute all" backend returns the whole Locus in the response like this
 
 const LocusObjectStateAfterUpdates = {
   unchanged: 'unchanged',
@@ -79,6 +87,167 @@ const LocusObjectStateAfterUpdates = {
 
 type LocusObjectStateAfterUpdates = Enum<typeof LocusObjectStateAfterUpdates>;
 
+export type HashTreeParserEntry = {
+  parser: HashTreeParser;
+  replacedAt?: string;
+  initializedFromHashTree: boolean;
+};
+
+/**
+ * Gets the replacement information
+ *
+ * @param {any} self - "self" object from Locus DTO
+ * @param {string} deviceUrl - The URL of the user's device
+ * @returns {any} The replace information if available, otherwise undefined
+ */
+function getReplaceInfoFromSelf(self: any, deviceUrl: string): ReplacesInfo | undefined {
+  if (self) {
+    const device = MeetingsUtil.getThisDevice({self}, deviceUrl);
+
+    if (device?.replaces?.length > 0) {
+      return device.replaces[0];
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Finds a meeting by its locus URL in meeting collection. It checks all HashTreeParsers of all meetings in the collection.
+ *
+ * @param {MeetingCollection} meetingCollection - The collection of meetings to search
+ * @param {string} locusUrl - The locus URL to search for
+ * @returns {any} The meeting if found, otherwise undefined
+ */
+function findLocusUrlInAnyHashTreeParser(
+  meetingCollection: MeetingCollection,
+  locusUrl: string
+): any {
+  for (const meeting of Object.values(meetingCollection.getAll()) as any[]) {
+    if (meeting?.locusInfo?.hashTreeParsers?.has(locusUrl)) {
+      return meeting;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Finds a meeting for a given hash tree message.
+ *
+ * @param {HashTreeMessage} message - The hash tree message to find the meeting for
+ * @param {MeetingCollection} meetingCollection - The collection of meetings to search
+ * @param {string} deviceUrl - The URL of the user's device
+ * @returns {any} The meeting if found, otherwise undefined
+ */
+export function findMeetingForHashTreeMessage(
+  message: HashTreeMessage,
+  meetingCollection: MeetingCollection,
+  deviceUrl: string
+): any {
+  let foundMeeting = findLocusUrlInAnyHashTreeParser(meetingCollection, message.locusUrl);
+
+  if (foundMeeting) {
+    return foundMeeting;
+  }
+
+  // if we haven't found anything, it may mean that message has a new locusUrl
+  // check if it indicates that it replaces some existing current locusUrl (this is indicated in "self")
+  const self = message.locusStateElements?.find((el) => isSelf(el))?.data;
+  const replaces = getReplaceInfoFromSelf(self, deviceUrl);
+
+  if (replaces?.locusUrl) {
+    foundMeeting = findLocusUrlInAnyHashTreeParser(meetingCollection, replaces.locusUrl);
+
+    return foundMeeting;
+  }
+
+  return undefined;
+}
+
+/**
+ * Creates a locus object from the objects received in a hash tree message. It usually will be
+ * incomplete, because hash tree messages only contain the parts of locus that have changed,
+ * and some updates come separately over Mercury or LLM in separate messages.
+ *
+ * @param {HashTreeMessage} message hash tree message to created the locus from
+ * @returns {Object} the created locus object and metadata if present
+ */
+export function createLocusFromHashTreeMessage(message: HashTreeMessage): {
+  locus: LocusDTO;
+  metadata?: Metadata;
+} {
+  const locus: LocusDTO = {
+    participants: [],
+    url: message.locusUrl,
+  };
+  let metadata: Metadata | undefined;
+
+  if (!message.locusStateElements) {
+    return {locus, metadata};
+  }
+
+  for (const element of message.locusStateElements) {
+    if (!element.data) {
+      // eslint-disable-next-line no-continue
+      continue;
+    }
+
+    const type = element.htMeta.elementId.type.toLowerCase();
+
+    switch (type) {
+      case ObjectType.locus: {
+        // spread locus object data onto the top level, but remove keys managed by other ObjectTypes
+        const locusObjectData = {...element.data};
+
+        Object.values(ObjectTypeToLocusKeyMap).forEach((locusDtoKey) => {
+          delete locusObjectData[locusDtoKey];
+        });
+
+        Object.assign(locus, locusObjectData);
+        break;
+      }
+      case ObjectType.participant:
+        locus.participants.push(element.data);
+        break;
+      case ObjectType.mediaShare:
+        if (!locus.mediaShares) {
+          locus.mediaShares = [];
+        }
+        locus.mediaShares.push(element.data);
+        break;
+      case ObjectType.embeddedApp:
+        if (!locus.embeddedApps) {
+          locus.embeddedApps = [];
+        }
+        locus.embeddedApps.push(element.data);
+        break;
+      case ObjectType.control:
+        if (!locus.controls) {
+          locus.controls = {};
+        }
+        Object.assign(locus.controls, element.data);
+        break;
+      case ObjectType.links:
+      case ObjectType.info:
+      case ObjectType.fullState:
+      case ObjectType.self: {
+        const locusDtoKey = ObjectTypeToLocusKeyMap[type];
+        locus[locusDtoKey] = element.data;
+        break;
+      }
+      case ObjectType.metadata:
+        // metadata is not part of Locus DTO
+        metadata = {...element.data, htMeta: element.htMeta} as Metadata;
+        break;
+      default:
+        break;
+    }
+  }
+
+  return {locus, metadata};
+}
+
 /**
  * @description LocusInfo extends ChildEmitter to convert locusInfo info a private emitter to parent object
  * @export
@@ -112,7 +281,7 @@ export default class LocusInfo extends EventsScope {
   links?: Links;
   mainSessionLocusCache: any;
   self: any;
-  hashTreeParser?: HashTreeParser;
+  hashTreeParsers: Map<string, HashTreeParserEntry>;
   hashTreeObjectId2ParticipantId: Map<number, string>; // mapping of hash tree object ids to participant ids
   classicVsHashTreeMismatchMetricCounter = 0;
 
@@ -134,6 +303,7 @@ export default class LocusInfo extends EventsScope {
     this.meetingId = meetingId;
     this.updateMeeting = updateMeeting;
     this.locusParser = new LocusDeltaParser();
+    this.hashTreeParsers = new Map();
     this.hashTreeObjectId2ParticipantId = new Map();
   }
 
@@ -239,7 +409,7 @@ export default class LocusInfo extends EventsScope {
             'Locus-info:index#doLocusSync --> got full DTO when we asked for delta'
           );
         }
-        meeting.locusInfo.onFullLocus(res.body);
+        meeting.locusInfo.onFullLocus('classic Locus sync', res.body);
       })
       .catch((e) => {
         LoggerProxy.logger.info(
@@ -356,24 +526,56 @@ export default class LocusInfo extends EventsScope {
   }
 
   /**
-   * Creates the HashTreeParser instance.
-   * @param {Object} initial locus data
-   * @returns {void}
+   * Creates a HashTreeParser instance for a given locusUrl and stores it in the map.
+   * @param {Object} params
+   * @param {string} params.locusUrl - the locus URL used as the map key
+   * @param {Object} params.initialLocus - initial locus data
+   * @param {Object} params.metadata - hash tree metadata
+   * @param {string} params.replacedAt - timestamp from Locus indicating when the replacement happened
+   * @returns {HashTreeParser} the newly created parser
    */
   private createHashTreeParser({
+    locusUrl,
     initialLocus,
+    metadata,
+    replacedAt,
   }: {
+    locusUrl: string;
     initialLocus: {
       dataSets: Array<DataSet>;
       locus: any;
     };
-  }) {
-    return new HashTreeParser({
+    metadata: Metadata;
+    replacedAt?: string;
+  }): HashTreeParser {
+    const parser = new HashTreeParser({
       initialLocus,
+      metadata,
       webexRequest: this.webex.request.bind(this.webex),
-      locusInfoUpdateCallback: this.updateFromHashTree.bind(this),
-      debugId: `HT-${this.meetingId.substring(0, 4)}`,
+      locusInfoUpdateCallback: this.updateFromHashTree.bind(this, locusUrl),
+      debugId: `HT-${locusUrl.split('/').pop().substring(0, 4)}`,
+      excludedDataSets: this.webex.config.meetings.locus?.excludedDataSets,
     });
+
+    // When a new HashTreeParser is created, previous one should be stopped.
+    // Locus will only be sending us updates for the current one.
+    for (const [existingLocusUrl, existingEntry] of this.hashTreeParsers) {
+      if (existingEntry.parser.state !== 'stopped') {
+        existingEntry.parser.stop();
+        if (replacedAt) {
+          existingEntry.replacedAt = replacedAt;
+        } else {
+          LoggerProxy.logger.warn(
+            `Locus-info:index#createHashTreeParser --> no replacedAt timestamp provided for new HashTreeParser with locusUrl ${locusUrl}, replacing ${existingLocusUrl}`
+          );
+        }
+      }
+    }
+
+    this.hashTreeParsers.set(locusUrl, {parser, initializedFromHashTree: false});
+    this.hashTreeObjectId2ParticipantId.clear();
+
+    return parser;
   }
 
   /**
@@ -387,6 +589,7 @@ export default class LocusInfo extends EventsScope {
           trigger: 'join-response';
           locus: LocusDTO;
           dataSets?: DataSet[];
+          metadata?: Metadata;
         }
       | {
           trigger: 'locus-message';
@@ -401,41 +604,50 @@ export default class LocusInfo extends EventsScope {
     switch (data.trigger) {
       case 'locus-message':
         if (data.hashTreeMessage) {
-          // we need the SELF object to be in the received message, because it contains visibleDataSets
+          // we need the Metadata object to be in the received message, because it contains visibleDataSets
           // and these are needed to initialize all the hash trees
-          const selfObject = data.hashTreeMessage.locusStateElements?.find((el) => isSelf(el));
+          const metadataObject = data.hashTreeMessage.locusStateElements?.find((el) =>
+            isMetadata(el)
+          );
 
-          if (!selfObject?.data?.visibleDataSets) {
-            LoggerProxy.logger.warn(
-              `Locus-info:index#initialSetup --> cannot initialize HashTreeParser, SELF object with visibleDataSets is missing in the message`
+          if (!metadataObject?.data?.visibleDataSets) {
+            // this is a common case (not an error)
+            // it happens for example after we leave the meeting and still get some heartbeats or delayed messages
+            LoggerProxy.logger.info(
+              `Locus-info:index#initialSetup --> cannot initialize HashTreeParser, Metadata object with visibleDataSets is missing in the message`
             );
 
-            throw new Error('SELF object with visibleDataSets is missing in the message');
+            // throw so that handleLocusEvent() catches it and destroys the partially created meeting object
+            throw new Error('Metadata object with visibleDataSets is missing in the message');
           }
 
           LoggerProxy.logger.info(
             'Locus-info:index#initialSetup --> creating HashTreeParser from message'
           );
           // first create the HashTreeParser, but don't initialize it with any data yet
-          // pass just a fake locus that contains only the visibleDataSets
-          this.hashTreeParser = this.createHashTreeParser({
+          const hashTreeParser = this.createHashTreeParser({
+            locusUrl: data.hashTreeMessage.locusUrl,
             initialLocus: {
-              locus: {self: {visibleDataSets: selfObject.data.visibleDataSets}},
-              dataSets: [], // empty, because they will be populated in initializeFromMessage() call  // dataSets: data.hashTreeMessage.dataSets,
+              locus: null,
+              dataSets: data.hashTreeMessage.dataSets,
+            },
+            metadata: {
+              htMeta: metadataObject.htMeta,
+              visibleDataSets: metadataObject.data.visibleDataSets,
             },
           });
 
           // now handle the message - that should populate all the visible datasets
-          await this.hashTreeParser.initializeFromMessage(data.hashTreeMessage);
+          await hashTreeParser.initializeFromMessage(data.hashTreeMessage);
         } else {
           // "classic" Locus case, no hash trees involved
           this.updateLocusCache(data.locus);
-          this.onFullLocus(data.locus, undefined);
+          this.onFullLocus('classic locus message', data.locus, undefined);
         }
         break;
       case 'join-response':
         this.updateLocusCache(data.locus);
-        this.onFullLocus(data.locus, undefined, data.dataSets);
+        this.onFullLocus('join response', data.locus, undefined, data.dataSets, data.metadata);
         break;
       case 'get-loci-response':
         if (data.locus?.links?.resources?.visibleDataSets?.url) {
@@ -443,20 +655,21 @@ export default class LocusInfo extends EventsScope {
             'Locus-info:index#initialSetup --> creating HashTreeParser from get-loci-response'
           );
           // first create the HashTreeParser, but don't initialize it with any data yet
-          // pass just a fake locus that contains only the visibleDataSets
-          this.hashTreeParser = this.createHashTreeParser({
+          const hashTreeParser = this.createHashTreeParser({
+            locusUrl: data.locus.url,
             initialLocus: {
-              locus: {self: {visibleDataSets: data.locus?.self?.visibleDataSets}},
+              locus: null,
               dataSets: [], // empty, because we don't have them yet
             },
+            metadata: null, // get-loci-response doesn't contain Metadata object
           });
 
           // now initialize all the data
-          await this.hashTreeParser.initializeFromGetLociResponse(data.locus);
+          await hashTreeParser.initializeFromGetLociResponse(data.locus);
         } else {
           // "classic" Locus case, no hash trees involved
           this.updateLocusCache(data.locus);
-          this.onFullLocus(data.locus, undefined);
+          this.onFullLocus('classic get-loci-response', data.locus, undefined);
         }
     }
     // Change it to true after it receives it first locus object
@@ -470,34 +683,42 @@ export default class LocusInfo extends EventsScope {
    * @returns {void}
    */
   handleLocusAPIResponse(meeting, responseBody: LocusApiResponseBody): void {
-    if (this.hashTreeParser) {
-      if (!responseBody.dataSets) {
-        this.sendClassicVsHashTreeMismatchMetric(
-          meeting,
-          `expected hash tree dataSets in API response but they are missing`
+    const isWrapped = 'locus' in responseBody;
+    const locusUrl = isWrapped ? responseBody.locus?.url : responseBody.url;
+    const hashTreeParserEntry = locusUrl && this.hashTreeParsers.get(locusUrl);
+    if (hashTreeParserEntry) {
+      if (isWrapped) {
+        if (!responseBody.dataSets) {
+          this.sendClassicVsHashTreeMismatchMetric(
+            meeting,
+            `expected hash tree dataSets in API response but they are missing`
+          );
+          // continuing as we can still manage without responseBody.dataSets, but this is very suspicious
+        }
+        LoggerProxy.logger.info(
+          'Locus-info:index#handleLocusAPIResponse --> passing Locus API response to HashTreeParser: ',
+          responseBody
         );
-        // continuing as we can still manage without responseBody.dataSets, but this is very suspicious
+        // update the data in our hash trees
+        hashTreeParserEntry.parser.handleLocusUpdate(responseBody);
+      } else {
+        // LocusDTO without wrapper - pass it through as if it had no dataSets
+        hashTreeParserEntry.parser.handleLocusUpdate({locus: responseBody});
       }
-      LoggerProxy.logger.info(
-        'Locus-info:index#handleLocusAPIResponse --> passing Locus API response to HashTreeParser: ',
-        responseBody
-      );
-      // update the data in our hash trees
-      this.hashTreeParser.handleLocusUpdate(responseBody);
     } else {
-      if (responseBody.dataSets) {
+      if (isWrapped && responseBody.dataSets) {
         this.sendClassicVsHashTreeMismatchMetric(
           meeting,
           `unexpected hash tree dataSets in API response`
         );
       }
       // classic Locus delta
-      this.handleLocusDelta(responseBody.locus, meeting);
+      const locus = isWrapped ? responseBody.locus : responseBody;
+      this.handleLocusDelta(locus, meeting);
     }
   }
 
   /**
-   *
    * @param {HashTreeObject} object data set object
    * @param {any} locus
    * @returns {void}
@@ -571,6 +792,31 @@ export default class LocusInfo extends EventsScope {
           );
         }
         break;
+      case ObjectType.embeddedApp:
+        if (object.data) {
+          LoggerProxy.logger.info(
+            `Locus-info:index#updateLocusFromHashTreeObject --> embeddedApp id=${object.htMeta.elementId.id} url='${object.data.url}' updated version=${object.htMeta.elementId.version}:`,
+            object.data
+          );
+          const existingEmbeddedApp = locus.embeddedApps?.find(
+            (ms) => ms.htMeta.elementId.id === object.htMeta.elementId.id
+          );
+
+          if (existingEmbeddedApp) {
+            Object.assign(existingEmbeddedApp, object.data);
+          } else {
+            locus.embeddedApps = locus.embeddedApps || [];
+            locus.embeddedApps.push(object.data);
+          }
+        } else {
+          LoggerProxy.logger.info(
+            `Locus-info:index#updateLocusFromHashTreeObject --> embeddedApp id=${object.htMeta.elementId.id} removed, version=${object.htMeta.elementId.version}`
+          );
+          locus.embeddedApps = locus.embeddedApps?.filter(
+            (ms) => ms.htMeta.elementId.id !== object.htMeta.elementId.id
+          );
+        }
+        break;
       case ObjectType.participant:
         LoggerProxy.logger.info(
           `Locus-info:index#updateLocusFromHashTreeObject --> participant id=${
@@ -588,6 +834,23 @@ export default class LocusInfo extends EventsScope {
           locus.jsSdkMeta.removedParticipantIds.push(participantId);
           this.hashTreeObjectId2ParticipantId.delete(object.htMeta.elementId.id);
         }
+        // Create self from the participant if it matches self identity and is being moved.
+        // We need this, because participant update comes in LLM message often before the self update from Mercury.
+        // Other parts of the code detect move only by looking at self, while some other parts of the SDK/webapp code
+        // look at participant for roles etc, so if participant is updated but not self, then it looks like we our lost roles temporarily
+        // (until self is updated)
+        // This will be fixed properly in SPARK-790239
+        if (
+          object.data &&
+          object.data.identity === locus.self?.identity &&
+          object.data.state === 'LEFT' &&
+          object.data.reason === 'MOVED'
+        ) {
+          LoggerProxy.logger.info(
+            `Locus-info:index#updateLocusFromHashTreeObject --> FOUND a match for MOVED self in participant object ${object.htMeta.elementId.id}`
+          );
+          Object.assign(locus[ObjectTypeToLocusKeyMap[ObjectType.self]], object.data);
+        }
         break;
       case ObjectType.control:
         if (object.data) {
@@ -643,6 +906,12 @@ export default class LocusInfo extends EventsScope {
           }
         }
         break;
+      case ObjectType.metadata:
+        LoggerProxy.logger.info(
+          `Locus-info:index#updateLocusFromHashTreeObject --> metadata object updated to version ${object.htMeta.elementId.version}`
+        );
+        // we don't use hash tree metadata right now for anything, it's mainly used internally by HashTreeParser
+        break;
       default:
         LoggerProxy.logger.warn(
           `Locus-info:index#updateLocusFromHashTreeObject --> received unsupported object type ${type}`
@@ -675,6 +944,92 @@ export default class LocusInfo extends EventsScope {
     }
   }
 
+  /**
+   * Checks if the hash tree message should trigger a switch to a different HashTreeParser
+   *
+   * @param {HashTreeMessage} message incoming hash tree message
+   * @returns {boolean} true if the message was handled as a parser switch, false otherwise
+   */
+  private handleHashTreeParserSwitch(message: HashTreeMessage): boolean {
+    const entry = this.hashTreeParsers.get(message.locusUrl);
+
+    const self = message.locusStateElements?.find((el) => isSelf(el))?.data;
+    const replaces = getReplaceInfoFromSelf(
+      self,
+      // @ts-ignore
+      this.webex.internal.device.url
+    );
+
+    if (!entry) {
+      // Metadata object that contains information about visible datasets is needed to initialize the HashTreeParser,
+      // but it's buried inside the message, we need to find it and pass it to HashTreeParser constructor
+      const metadata = message.locusStateElements?.find((el) => isMetadata(el));
+
+      if (metadata?.data?.visibleDataSets?.length > 0) {
+        LoggerProxy.logger.info(
+          `Locus-info:index#handleHashTreeParserSwitch --> no hash tree parser found for locusUrl ${message.locusUrl}, creating a new one`
+        );
+
+        const parser = this.createHashTreeParser({
+          locusUrl: message.locusUrl,
+          initialLocus: {
+            locus: null,
+            dataSets: message.dataSets,
+          },
+          metadata: {
+            htMeta: metadata.htMeta,
+            visibleDataSets: metadata.data.visibleDataSets,
+          },
+          replacedAt: replaces?.replacedAt,
+        });
+
+        // handle the message with the new parser
+        parser.handleMessage(message);
+      }
+
+      return true;
+    }
+    if (entry.parser.state === 'stopped') {
+      // the message matches a stopped parser, we need to check if maybe this is a new "replacement" and we need to re-activate the parser
+      // this happens when you move from breakout A -> breakout B -> back to breakout A
+      if (replaces) {
+        if (replaces.replacedAt > (entry.replacedAt || '')) {
+          LoggerProxy.logger.info(
+            `Locus-info:index#handleHashTreeParserSwitch --> resuming a HashTreeParser for locusUrl=${message.locusUrl}, which replaces ${replaces.locusUrl}`
+          );
+          const replacedEntry = this.hashTreeParsers.get(replaces.locusUrl);
+
+          if (replacedEntry) {
+            replacedEntry.replacedAt = replaces.replacedAt;
+            entry.initializedFromHashTree = false;
+            this.hashTreeObjectId2ParticipantId.clear();
+
+            replacedEntry.parser.stop();
+            entry.parser.resume(message);
+          } else {
+            LoggerProxy.logger.warn(
+              `Locus-info:index#handleHashTreeParserSwitch --> the parser that is supposed to be replaced with the currently resumed parser is not found, locusUrl=${replaces.locusUrl}`
+            );
+          }
+        } else {
+          LoggerProxy.logger.info(
+            `Locus-info:index#handleHashTreeParserSwitch --> received message for stopped HashTreeParser with locusUrl ${message.locusUrl}, but replaces info provided is not newer, so not re-activating the parser`
+          );
+        }
+
+        return true;
+      }
+
+      LoggerProxy.logger.info(
+        `Locus-info:index#handleHashTreeParserSwitch --> received message for stopped HashTreeParser with locusUrl ${message.locusUrl}, but no replaces info provided, so not re-activating the parser`
+      );
+
+      return true;
+    }
+
+    return false;
+  }
+
   /**
    * Handles a hash tree message received from Locus.
    *
@@ -693,18 +1048,28 @@ export default class LocusInfo extends EventsScope {
       return;
     }
 
-    this.hashTreeParser.handleMessage(message);
+    const parserSwitched = this.handleHashTreeParserSwitch(message);
+
+    if (parserSwitched) {
+      return;
+    }
+
+    const entry = this.hashTreeParsers.get(message.locusUrl);
+
+    entry.parser.handleMessage(message);
   }
 
   /**
    * Callback registered with HashTreeParser to receive locus info updates.
    * Updates our locus info based on the data parsed by the hash tree parser.
    *
+   * @param {string} locusUrl - the locus URL for which the update is received
    * @param {LocusInfoUpdateType} updateType - The type of update received.
    * @param {Object} [data] - Additional data for the update, if applicable.
    * @returns {void}
    */
   private updateFromHashTree(
+    locusUrl: string,
     updateType: LocusInfoUpdateType,
     data?: {updatedObjects: HashTreeObject[]}
   ) {
@@ -713,7 +1078,10 @@ export default class LocusInfo extends EventsScope {
         // initialize our new locus
         let locus: LocusDTO = {
           participants: [],
-          jsSdkMeta: {removedParticipantIds: []},
+          jsSdkMeta: {
+            removedParticipantIds: [],
+            forceReplaceMembers: false,
+          },
         };
 
         // first go over all the updates and check what happens with the main locus object
@@ -746,12 +1114,23 @@ export default class LocusInfo extends EventsScope {
           }
         });
 
-        // if Locus object is unchanged or removed, we need to keep using the existing locus
-        // because the rest of the locusInfo code expects locus to always be present (with at least some of the fields)
-        // if it gets updated, we only need to have the fields that are not part of "locus" object (like "info" or "mediaShares")
-        // so that when Locus object gets updated, if the new one is missing some field, that field will
-        // be removed from our locusInfo
-        if (
+        const hashTreeParserEntry = this.hashTreeParsers.get(locusUrl);
+
+        if (!hashTreeParserEntry.initializedFromHashTree) {
+          // this is the first time we're getting an update for this locusUrl,
+          // so it's probably a move to/from breakout. We need to start from a clean state,
+          // so empty locus and we rely on Locus giving us sufficient data in the updates to populate it.
+          LoggerProxy.logger.info(
+            `Locus-info:index#updateFromHashTree --> first INITIAL update for locusUrl ${locusUrl}, starting from empty state`
+          );
+          hashTreeParserEntry.initializedFromHashTree = true;
+          locus.jsSdkMeta.forceReplaceMembers = true;
+        } else if (
+          // if Locus object is unchanged or removed, we need to keep using the existing locus
+          // because the rest of the locusInfo code expects locus to always be present (with at least some of the fields)
+          // if it gets updated, we only need to have the fields that are not part of "locus" object (like "info" or "mediaShares")
+          // so that when Locus object gets updated, if the new one is missing some field, that field will
+          // be removed from our locusInfo
           locusObjectStateAfterUpdates === LocusObjectStateAfterUpdates.unchanged ||
           locusObjectStateAfterUpdates === LocusObjectStateAfterUpdates.removed
         ) {
@@ -792,11 +1171,14 @@ export default class LocusInfo extends EventsScope {
       }
 
       case LocusInfoUpdateType.MEETING_ENDED: {
-        LoggerProxy.logger.info(
-          `Locus-info:index#updateFromHashTree --> received signal that meeting ended, destroying meeting ${this.meetingId}`
-        );
         const meeting = this.webex.meetings.meetingCollection.get(this.meetingId);
-        this.webex.meetings.destroy(meeting, MEETING_REMOVED_REASON.SELF_REMOVED);
+
+        if (meeting) {
+          LoggerProxy.logger.info(
+            `Locus-info:index#updateFromHashTree --> received signal that meeting ended, destroying meeting ${this.meetingId}`
+          );
+          this.webex.meetings.destroy(meeting, MEETING_REMOVED_REASON.SELF_REMOVED);
+        }
       }
     }
   }
@@ -808,15 +1190,25 @@ export default class LocusInfo extends EventsScope {
    * @memberof LocusInfo
    */
   parse(meeting: any, data: any) {
-    if (this.hashTreeParser) {
+    if (this.hashTreeParsers.size > 0) {
       this.handleHashTreeMessage(
         meeting,
         data.eventType,
         data.stateElementsMessage as HashTreeMessage
       );
     } else {
-      // eslint-disable-next-line @typescript-eslint/no-shadow
       const {eventType} = data;
+
+      if (eventType === LOCUSEVENT.HASH_TREE_DATA_UPDATED) {
+        // this can happen when we get an event before join http response
+        // it's OK to just ignore it
+        LoggerProxy.logger.info(
+          `Locus-info:index#parse --> received locus hash tree event before hashTreeParser is created`
+        );
+
+        return;
+      }
+
       const locus = this.getTheLocusToUpdate(data.locus);
       LoggerProxy.logger.info(`Locus-info:index#parse --> received locus data: ${eventType}`);
 
@@ -837,17 +1229,11 @@ export default class LocusInfo extends EventsScope {
         case LOCUSEVENT.PARTICIPANT_DECLINED:
         case LOCUSEVENT.FLOOR_GRANTED:
         case LOCUSEVENT.FLOOR_RELEASED:
-          this.onFullLocus(locus, eventType);
+          this.onFullLocus(`classic locus event ${eventType}`, locus, eventType);
           break;
         case LOCUSEVENT.DIFFERENCE:
           this.handleLocusDelta(locus, meeting);
           break;
-        case LOCUSEVENT.HASH_TREE_DATA_UPDATED:
-          this.sendClassicVsHashTreeMismatchMetric(
-            meeting,
-            `got ${eventType}, expected classic events`
-          );
-          break;
 
         default:
           // Why will there be a event with no eventType ????
@@ -871,46 +1257,63 @@ export default class LocusInfo extends EventsScope {
   /**
    * Function for handling full locus when it's using hash trees (so not the "classic" one).
    *
+   * @param {string} debugText string explaining the trigger for this call, added to logs for debugging purposes
    * @param {object} locus locus object
+   * @param {object} metadata locus hash trees metadata
    * @param {string} eventType locus event
    * @param {DataSet[]} dataSets
    * @returns {void}
    */
-  private onFullLocusWithHashTrees(locus: any, eventType?: string, dataSets?: Array<DataSet>) {
-    if (!this.hashTreeParser) {
-      LoggerProxy.logger.info(`Locus-info:index#onFullLocus --> creating hash tree parser`);
+  private onFullLocusWithHashTrees(
+    debugText: string,
+    locus: any,
+    metadata: Metadata,
+    eventType?: string,
+    dataSets?: Array<DataSet>
+  ) {
+    if (!this.hashTreeParsers.has(locus.url)) {
       LoggerProxy.logger.info(
-        'Locus-info:index#onFullLocus --> dataSets:',
+        `Locus-info:index#onFullLocus (${debugText}) --> creating hash tree parser for locusUrl=${locus.url}`
+      );
+      LoggerProxy.logger.info(
+        `Locus-info:index#onFullLocus (${debugText}) --> dataSets:`,
         dataSets,
         ' and locus:',
-        locus
+        locus,
+        ' and metadata:',
+        metadata
       );
-      this.hashTreeParser = this.createHashTreeParser({
+      this.createHashTreeParser({
+        locusUrl: locus.url,
         initialLocus: {locus, dataSets},
+        metadata,
       });
+      // we have a full locus to start with, so we consider Locus info to be "initialized"
+      this.hashTreeParsers.get(locus.url).initializedFromHashTree = true;
       this.onFullLocusCommon(locus, eventType);
     } else {
       // in this case the Locus we're getting is not necessarily the full one
       // so treat it like if we just got it in any api response
 
       LoggerProxy.logger.info(
-        'Locus-info:index#onFullLocus --> hash tree parser already exists, handling it like a normal API response'
+        `Locus-info:index#onFullLocus (${debugText}) --> hash tree parser already exists, handling it like a normal API response`
       );
-      this.handleLocusAPIResponse(undefined, {dataSets, locus});
+      this.handleLocusAPIResponse(undefined, {dataSets, locus, metadata});
     }
   }
 
   /**
    * Function for handling full locus when it's the "classic" one (not hash trees)
    *
+   * @param {string} debugText string explaining the trigger for this call, added to logs for debugging purposes
    * @param {object} locus locus object
    * @param {string} eventType locus event
    * @returns {void}
    */
-  private onFullLocusClassic(locus: any, eventType?: string) {
+  private onFullLocusClassic(debugText: string, locus: any, eventType?: string) {
     if (!this.locusParser.isNewFullLocus(locus)) {
       LoggerProxy.logger.info(
-        `Locus-info:index#onFullLocus --> ignoring old full locus DTO, eventType=${eventType}`
+        `Locus-info:index#onFullLocus (${debugText}) --> ignoring old full locus DTO, eventType=${eventType}`
       );
 
       return;
@@ -920,24 +1323,37 @@ export default class LocusInfo extends EventsScope {
 
   /**
    * updates the locus with full locus object
+   * @param {string} debugText string explaining the trigger for this call, added to logs for debugging purposes
    * @param {object} locus locus object
    * @param {string} eventType locus event
    * @param {DataSet[]} dataSets
+   * @param {object} metadata locus hash trees metadata
    * @returns {object} null
    * @memberof LocusInfo
    */
-  onFullLocus(locus: any, eventType?: string, dataSets?: Array<DataSet>) {
+  onFullLocus(
+    debugText: string,
+    locus: any,
+    eventType?: string,
+    dataSets?: Array<DataSet>,
+    metadata?: Metadata
+  ) {
     if (!locus) {
       LoggerProxy.logger.error(
-        'Locus-info:index#onFullLocus --> object passed as argument was invalid, continuing.'
+        `Locus-info:index#onFullLocus (${debugText}) --> object passed as argument was invalid, continuing.`
       );
     }
 
     if (dataSets) {
+      if (!metadata) {
+        throw new Error(
+          `Locus-info:index#onFullLocus (${debugText}) --> hash tree metadata is missing with full Locus`
+        );
+      }
       // this is the new hashmap Locus DTO format (only applicable to webinars for now)
-      this.onFullLocusWithHashTrees(locus, eventType, dataSets);
+      this.onFullLocusWithHashTrees(debugText, locus, metadata, eventType, dataSets);
     } else {
-      this.onFullLocusClassic(locus, eventType);
+      this.onFullLocusClassic(debugText, locus, eventType);
     }
   }
 
@@ -952,7 +1368,7 @@ export default class LocusInfo extends EventsScope {
     this.participants = locus.participants;
     this.participants?.forEach((participant) => {
       // participant.htMeta is set only for hash tree based locus
-      if (participant.htMeta?.elementId.id) {
+      if (typeof participant.htMeta?.elementId.id === 'number') {
         this.hashTreeObjectId2ParticipantId.set(participant.htMeta.elementId.id, participant.id);
       }
     });
@@ -1015,20 +1431,61 @@ export default class LocusInfo extends EventsScope {
     }
   }
 
+  /**
+   * Makes sure that passed in locus object has a participant object for self.
+   *
+   * @param {LocusDTO} locus The locus object to check and modify if needed
+   * @returns {void}
+   */
+  ensureSelfParticipantExists(locus: any) {
+    const {self} = locus;
+
+    // sanity check, this should never fail
+    if (!self?.identity || !Array.isArray(locus.participants)) {
+      LoggerProxy.logger.warn(
+        `Locus-info:index#ensureSelfParticipantExists --> locus object is missing required fields, cannot ensure self participant exists. self?.identity="${self?.identity}"`
+      );
+
+      return;
+    }
+
+    const selfExists = locus.participants.some(
+      (participant) => participant.identity === self.identity
+    );
+
+    if (!selfExists) {
+      locus.participants.push({...self});
+    }
+  }
+
   /**
    * @param {Object} locus
    * @returns {undefined}
    * @memberof LocusInfo
    */
   onDeltaLocus(locus: any) {
-    const isReplaceMembers = ControlsUtils.isNeedReplaceMembers(this.controls, locus.controls);
+    const isReplaceMembers =
+      locus.jsSdkMeta?.forceReplaceMembers !== undefined
+        ? locus.jsSdkMeta.forceReplaceMembers
+        : ControlsUtils.isNeedReplaceMembers(this.controls, locus.controls);
+
+    if (isReplaceMembers) {
+      // when we're moving between breakouts, Locus sometimes doesn't send us
+      // any participants at all for a few seconds
+      // Web app relies on having at least the self participant always there
+      // so we copy self into participants if it's not there.
+      this.ensureSelfParticipantExists(locus);
+    }
     this.mergeParticipants(this.participants, locus.participants);
-    this.updateLocusInfo(locus);
-    this.updateParticipants(
-      locus.participants,
-      locus.jsSdkMeta?.removedParticipantIds,
-      isReplaceMembers
-    );
+    const updatesApplied = this.updateLocusInfo(locus);
+
+    if (updatesApplied) {
+      this.updateParticipants(
+        locus.participants,
+        locus.jsSdkMeta?.removedParticipantIds,
+        isReplaceMembers
+      );
+    }
     this.isMeetingActive();
   }
 
@@ -1042,7 +1499,7 @@ export default class LocusInfo extends EventsScope {
       // When moved to a breakout session locus sends a message for the previous locus
       // indicating that we have been moved. It isn't helpful to continue parsing this
       // as it gets interpreted as if we have left the call
-      return;
+      return false;
     }
 
     this.updateControls(locus.controls, locus.self);
@@ -1062,6 +1519,8 @@ export default class LocusInfo extends EventsScope {
     this.updateLinks(locus.links);
     this.compareAndUpdate();
     // update which required to compare different objects from locus
+
+    return true;
   }
 
   /**
@@ -1217,27 +1676,6 @@ export default class LocusInfo extends EventsScope {
             shouldLeave: false,
           }
         );
-      } else if (this.fullState && this.fullState.removed) {
-        // user has been dropped from a meeting
-
-        // @ts-ignore
-        this.webex.internal.newMetrics.submitClientEvent({
-          name: 'client.call.remote-ended',
-          options: {
-            meetingId: this.meetingId,
-          },
-        });
-        this.emitScoped(
-          {
-            file: 'locus-info',
-            function: 'isMeetingActive',
-          },
-          EVENTS.DESTROY_MEETING,
-          {
-            reason: MEETING_REMOVED_REASON.FULLSTATE_REMOVED,
-            shouldLeave: false,
-          }
-        );
       }
       // If you are  guest and you are removed from the meeting
       // You wont get any further events
@@ -1373,6 +1811,7 @@ export default class LocusInfo extends EventsScope {
           hasMeetingContainerChanged,
           hasTranscribeChanged,
           hasHesiodLLMIdChanged,
+          hasAiSummaryNotificationChanged,
           hasTranscribeSpokenLanguageChanged,
           hasManualCaptionChanged,
           hasEntryExitToneChanged,
@@ -1529,6 +1968,19 @@ export default class LocusInfo extends EventsScope {
         );
       }
 
+      if (hasAiSummaryNotificationChanged) {
+        this.emitScoped(
+          {
+            file: 'locus-info',
+            function: 'updateControls',
+          },
+          LOCUSINFO.EVENTS.CONTROLS_AI_SUMMARY_NOTIFICATION_UPDATED,
+          {
+            aiSummaryNotification: current.transcribe.aiSummaryNotification,
+          }
+        );
+      }
+
       if (hasTranscribeSpokenLanguageChanged) {
         const {spokenLanguage} = current.transcribe;
 
@@ -1561,6 +2013,7 @@ export default class LocusInfo extends EventsScope {
 
       if (hasBreakoutChanged) {
         const {breakout} = current;
+
         breakout.breakoutMoveId = SelfUtils.getReplacedBreakoutMoveId(
           self,
           this.webex.internal.device.url
@@ -2038,6 +2491,19 @@ export default class LocusInfo extends EventsScope {
         );
       }
 
+      if (parsedSelves.updates.selfIdChanged) {
+        this.emitScoped(
+          {
+            file: 'locus-info',
+            function: 'updateSelf',
+          },
+          LOCUSINFO.EVENTS.SELF_ID_CHANGED,
+          {
+            selfId: parsedSelves.current.selfId,
+          }
+        );
+      }
+
       if (parsedSelves.updates.interpretationChanged) {
         this.emitScoped(
           {