feat: added support for breakouts to Locus hash trees (5k webinars) by marcin-bazyl · Pull Request #4775 · webex/webex-js-sdk

marcin-bazyl · 2026-03-13T19:49:30Z

COMPLETES #SPARK-758861

This pull request addresses

Breakouts support for 5k webinars. Locus wiki explaining how it should work:
https://sqbu-github.cisco.com/pages/WebExSquared/locus/guides/convergedWebinar5k/breakoutMoves.html

by making the following changes

Changed LocusInfo so that it now has a map of HashTreeParsers instead of just a single parser. We have a separate parser for each locusUrl now, so when we move between breakouts and locusUrl changes, we change the parsers. The old one is stopped. It can be resumed if user goes back. Right now stop() clears all the hash trees and resume() starts from scratch, because that's what Locus team wants clients to do. We can potentially change that if needed in the future and keep the old hash trees. We may still be getting some messages for the old locusUrl, so it's good to keep the old HashTreeParser and route the messages to it and the parser just ignores them when it's stopped. Otherwise, if there was no parser to handle them, the messages could potentially cause a creation of a new meeting object.

When testing, you will see that when moving between sessions there is a delay before the participant list is populated. This is because Locus doesn't send us participant list in the 1st message for the new session and we rely on the sync algorithm, so the messages arrive a bit later or if they don't arrive, we do the sync. This is by design. Locus team have been informed that the delay is unacceptably long right now and they are considering various solutions to this, but they want the client implementation to remain as is - so no initial sync, no proactive getting of participant list.

All unit tests were created solely by AI, I've looked through them, they're not perfect, but pretty good, I think good enough.

Change Type

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update
Tooling change
Internal code refactor

The following scenarios were tested

unit tests

The GAI Coding Policy And Copyright Annotation Best Practices

I certified that

I have read and followed contributing guidelines
I discussed changes with code owners prior to submitting this pull request
I have not skipped any automated checks
All existing and new tests passed
I have updated the documentation accordingly

Make sure to have followed the contributing guidelines before submitting.

aws-amplify-us-east-2 · 2026-03-13T20:01:35Z

This pull request is automatically being deployed by Amplify Hosting (learn more).

Access this pull request here: https://pr-4775.d3m3l2kee0btzx.amplifyapp.com

marcin-bazyl · 2026-03-20T18:15:15Z

packages/@webex/plugin-meetings/src/hashTree/hashTreeParser.ts

-    this.visibleDataSets = (
-      cloneDeep(options.metadata?.visibleDataSets || []) as VisibleDataSetInfo[]
-    ).filter((vds) => !this.isExcludedDataSet(vds.name));
+    this.setVisibleDataSets(options.metadata?.visibleDataSets || [], dataSets);


extracted this block of code into a setVisibleDataSets() method, because I needed to have the same logic in resume() method

marcin-bazyl · 2026-03-20T18:17:53Z

packages/@webex/plugin-meetings/src/locus-info/index.ts

+      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


the fact that some API responses don't have dataSets and metadata but the body is just a locus object is something I found needed handling while working on breakouts, it's not strictly related to breakouts, but I've kept it in this PR.

marcin-bazyl · 2026-03-20T18:18:53Z

packages/@webex/plugin-meetings/src/locus-info/index.ts


+export type HashTreeParserEntry = {
+  parser: HashTreeParser;
+  replacedAt?: string;


we need to store replacedAt to handle cases where user moves: BO 1 -> BO 2 -> BO 1 again - we need to check that replacedAt is newer when moving back to BO 1

marcin-bazyl · 2026-03-20T18:24:00Z

packages/@webex/plugin-meetings/src/locus-info/index.ts

+export type HashTreeParserEntry = {
+  parser: HashTreeParser;
+  replacedAt?: string;
+  initializedFromHashTree: boolean;


this flag is needed, because we need to clear Locus when switching parsers. I was debating whether that state belonged more into HashTreeParser itself or LocusInfo, but decided it belongs in LocusInfo, because in some cases (like when we get full locus) HashTreeParser will not know that LocusInfo has all the data already initialized

marcin-bazyl · 2026-03-20T18:29:10Z

packages/@webex/plugin-meetings/src/locus-info/index.ts

            initialLocus: {
              locus: null,
-              dataSets: [], // empty, because they will be populated in initializeFromMessage() call  // dataSets: data.hashTreeMessage.dataSets,
+              dataSets: data.hashTreeMessage.dataSets,


we need to pass dataSets from message now here, because they're needed by HashTreeParser constructor when it sets visible data sets - see HashTreeParser.setVisibleDataSets(). I think this is a cleaner way of dealing with edge cases where we get messages from Locus with visible data sets that are not listed in dataSets list

marcin-bazyl · 2026-03-20T18:31:11Z

packages/@webex/plugin-meetings/src/locus-info/index.ts

    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 is a fix for a bug I found during breakout testing - we were not handling the case of participant's id being equal to zero correctly here

nitpick: should we be checking for undefined instead of checking the type of the id?

hmm not sure, this was suggested by ai and I kind of like the fact that we're checking that it's a number, so if the id was null or anything unexpected it would also fail the check

marcin-bazyl · 2026-03-20T18:34:27Z

packages/@webex/plugin-meetings/src/meetings/index.ts

    const associateBreakoutLocus = this.breakoutLocusForHandleLater[existIndex];
    this.handleLocusEvent({
-      eventType: LOCUSEVENT.SDK_NO_EVENT,
+      eventType: LOCUSEVENT.SDK_LOCUS_FROM_SYNC_MEETINGS,


here I've realised that breakoutLocusForHandleLater stores locus objects we got from /sync call so we should set the eventType accordingly

marcin-bazyl · 2026-03-20T18:38:54Z

packages/@webex/plugin-meetings/src/meeting/index.ts

 * @memberof Meeting
 */

+export function storeEventForDebugging(


this is something I've been using when testing, it's very handy, because it allows me to easily see all received messages (both from LLM and mercury) from a specific point in time (for example after moving to a breakout - I just do window.locusEvents=[] just before initiating the breakout move). I forgot to remove it when raising the PR, but now I'm thinking that maybe it could be useful for others too, so maybe leave it here?

yeah I think it is fine to leave it here for now. I agree, useful for debugging

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e8664b3fb0

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-03-23T09:49:43Z

packages/@webex/plugin-meetings/src/locus-info/index.ts

+    if (this.hashTreeParsers.size > 0) {
      this.handleHashTreeMessage(
        meeting,
        data.eventType,


Handle breakout loci from syncMeetings in hash-tree mode

When a meeting is created from GET /loci, it already has a hashTreeParsers entry. checkHandleBreakoutLocus() now replays the associated breakout DTO as SDK_LOCUS_FROM_SYNC_MEETINGS, but this branch still routes every subsequent event through handleHashTreeMessage(), which immediately rejects anything except HASH_TREE_DATA_UPDATED. On reconnect/refresh while the user is already in breakout, the replayed breakout locus from the sync response is therefore dropped, so the SDK stays on the main-session state until some later Mercury/LLM move event arrives.

Useful? React with 👍 / 👎.

I've created https://jira-eng-gpk2.cisco.com/jira/browse/SPARK-790957 to deal with this in a separate jira

chatgpt-codex-connector · 2026-03-23T09:49:43Z

packages/@webex/plugin-meetings/src/locus-info/index.ts

+        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(


Seed the first switched-parser update with the new locus URL

On the first update for a newly created or resumed parser, this path intentionally starts from an empty locus and forces member replacement. The problem is that the empty state does not carry locusUrl, and hash-tree messages are often partial (the meeting creation path above explicitly notes they may contain only self). If that first post-move update has no Locus object, updateLocusUrl() never fires, so the meeting keeps the previous session URL and follow-up operations like leave, lock, reactions, or token refresh still target the old breakout until a later full locus update happens.

Useful? React with 👍 / 👎.

I think it's fine, because Locus is supposed to always send us the main LOCUS object with SELF in the 1st message for the new breakout session

dominiccarrington · 2026-03-23T10:51:21Z

packages/@webex/plugin-meetings/src/locus-info/index.ts

+ * @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) {


nitpick: could we add ReplacesInfo as the return type?

dominiccarrington · 2026-03-23T10:53:29Z

packages/@webex/plugin-meetings/src/locus-info/index.ts

@@ -513,10 +625,11 @@ export default class LocusInfo extends EventsScope {
            'Locus-info:index#initialSetup --> creating HashTreeParser from message'
          );
          // first create the HashTreeParser, but don't initialize it with any data yet


question: this is comment still valid?

yes it's still valid

dominiccarrington · 2026-03-23T11:08:37Z

packages/@webex/plugin-meetings/src/hashTree/hashTreeParser.ts

        dataSet.heartbeatWatchdogTimer = undefined;
      }
    });
+    this.state = 'stopped';


issue: move to stop() function

dominiccarrington · 2026-03-23T11:51:53Z

packages/@webex/plugin-meetings/src/locus-info/index.ts

   * @param {Meeting} meeting - The meeting object
   * @param {eventType} eventType - The event type
   * @param {HashTreeMessage} message incoming hash tree message
+   * @param {any} replaces - if this message indicates that a new locusUrl replaces some old locusUrl, this object contains info about the old locus


issue: replaces is not part of the parameters

dominiccarrington · 2026-03-23T11:55:33Z

packages/@webex/plugin-meetings/src/locus-info/index.ts

    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') {


nitpick: should we be checking for undefined instead of checking the type of the id?

dominiccarrington · 2026-03-23T11:57:43Z

packages/@webex/plugin-meetings/src/locus-info/index.ts

  onDeltaLocus(locus: any) {
-    const isReplaceMembers = ControlsUtils.isNeedReplaceMembers(this.controls, locus.controls);
+    const isReplaceMembers =
+      locus.jsSdkMeta?.forceReplaceMembers !== undefined


if forceReplaceMembers is set to false, isReplaceMembers always be false and it won't check isNeedReplaceMembers. Is this expected?

yes, that's the intention - if the forceReplaceMembers field is set, it should override whatever comes from ControlsUtils.isNeedReplaceMembers() - basically ControlsUtils.isNeedReplaceMembers() shouldn't be even called

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 9c02016398

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

packages/@webex/plugin-meetings/src/meeting/index.ts

packages/@webex/plugin-meetings/src/locus-info/index.ts

packages/@webex/plugin-meetings/src/hashTree/hashTreeParser.ts

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 37e5f89253

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

packages/@webex/plugin-meetings/src/locus-info/index.ts

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 154e75fa53

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

packages/@webex/plugin-meetings/src/meetings/index.ts

packages/@webex/plugin-meetings/src/locus-info/index.ts

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: af67d7934f

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-03-27T10:47:43Z

packages/@webex/plugin-meetings/src/meeting/index.ts

+    stateElementsMessage?: HashTreeMessage;
+  }
+) {
+  if ((window as any)?.locusEvents) {


Guard debug event storage with typeof window

Fresh evidence: this implementation uses (window as any)?.locusEvents, but optional chaining does not protect against an undeclared global identifier, so in Node/SSR/test environments resolving window still throws ReferenceError before locus processing continues. This turns an optional debug path into a runtime failure whenever non-browser clients receive hash-tree events.

Useful? React with 👍 / 👎.

I've added a config entry for this, so only customers who use SDK in the browser and want to debug the hash tree events (so in essence only our web app) will use this

packages/@webex/plugin-meetings/src/locus-info/index.ts

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: e347f03d3d

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".

chatgpt-codex-connector · 2026-03-27T11:45:23Z

packages/@webex/plugin-meetings/src/locus-info/index.ts

+      // 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 || '')) {


Preserve replacement ordering before resuming stopped parser

When a parser is stopped without recording replacedAt (the new-parser path only logs a warning if replaces is missing), this resume gate compares against '', so any later delayed message from the old locus with a non-empty replaces.replacedAt is treated as newer and reactivates the old parser. In out-of-order breakout move traffic, that can switch the meeting back to a stale locus and cause subsequent state updates/actions to target the wrong session.

Useful? React with 👍 / 👎.

github-actions · 2026-03-27T12:21:35Z

🎉 Your changes are now available!
Released in: `v3.12.0-next.1`
📖 View full changelog →

Packages Updated	Version
`webex`	`3.12.0-next.1`
`@webex/plugin-meetings`	`3.12.0-next.1`

Thank you for your contribution!
🤖 This is an automated message. For questions, please refer to the documentation.

marcin-bazyl added 3 commits March 20, 2026 15:24

fix: breakouts implementation for hash trees

cf4e890

test: existing tests are passing now

1662e8a

test: new tests added

e8664b3

marcin-bazyl force-pushed the spark-758861 branch from 026c946 to e8664b3 Compare March 20, 2026 18:01

marcin-bazyl added the validated If the pull request is validated for automation. label Mar 20, 2026

marcin-bazyl commented Mar 20, 2026

View reviewed changes

marcin-bazyl marked this pull request as ready for review March 23, 2026 09:43

marcin-bazyl requested review from a team as code owners March 23, 2026 09:44

chatgpt-codex-connector bot reviewed Mar 23, 2026

View reviewed changes

dominiccarrington reviewed Mar 23, 2026

View reviewed changes

fix: pr comments

9c02016

chatgpt-codex-connector bot reviewed Mar 23, 2026

View reviewed changes

packages/@webex/plugin-meetings/src/meeting/index.ts Outdated Show resolved Hide resolved

packages/@webex/plugin-meetings/src/locus-info/index.ts Show resolved Hide resolved

packages/@webex/plugin-meetings/src/hashTree/hashTreeParser.ts Show resolved Hide resolved

fix: ai pr comments

37e5f89

chatgpt-codex-connector bot reviewed Mar 24, 2026

View reviewed changes

packages/@webex/plugin-meetings/src/locus-info/index.ts Outdated Show resolved Hide resolved

fix: more ai pr comments

154e75f

chatgpt-codex-connector bot reviewed Mar 24, 2026

View reviewed changes

packages/@webex/plugin-meetings/src/meetings/index.ts Show resolved Hide resolved

packages/@webex/plugin-meetings/src/locus-info/index.ts Show resolved Hide resolved

fix: adding self to participants when isReplaceMembers is set

1a77de6

Coread approved these changes Mar 27, 2026

View reviewed changes

mickelr approved these changes Mar 27, 2026

View reviewed changes

Merge branch 'next' into spark-758861

af67d79

chatgpt-codex-connector bot reviewed Mar 27, 2026

View reviewed changes

fix: put storing of events for debugging behind a config flag

e347f03

chatgpt-codex-connector bot reviewed Mar 27, 2026

View reviewed changes

marcin-bazyl merged commit 0b705ea into webex:next Mar 27, 2026
12 checks passed

Conversation

marcin-bazyl commented Mar 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

COMPLETES #SPARK-758861

This pull request addresses

by making the following changes

Change Type

The following scenarios were tested

The GAI Coding Policy And Copyright Annotation Best Practices

I certified that

Uh oh!

aws-amplify-us-east-2 bot commented Mar 13, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot Mar 23, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector bot left a comment

Choose a reason for hiding this comment

marcin-bazyl commented Mar 13, 2026 •

edited

Loading