fix: DCL Cast admin panel — auto-open, slide state, and reliable late-joiner replication (#1358)

* fix: auto-open the admin DCL Cast panel on presentation start and receive slide state

Two bugs in the admin toolkit's DCL Cast section:

1. The panel never auto-opened when a presentation started, for admins who were
   not already sitting on the DCL Cast sub-tab. Presentation detection lived
   inside the DclCast React component, so it only ran once the panel was already
   open — a passive admin detected nothing.

2. Slide state (page count, current slide, video) never populated. The runtime's
   `consumeMessages` resolves to a bare array of { sender, data }, but the code
   destructured `const { messages }`, which yields undefined, throws on `.length`,
   and is silently swallowed by the surrounding try/catch — dropping every reply.

Fixes (all scene-side; no explorer or cast-presenter-server changes needed):
- Move presentation detection into a boot-time, admin-gated background service
  (presentation-detector.ts) that auto-opens the panel to Video Control when the
  presentation bot's LiveKit track appears, independent of the active tab. Data
  flows one way: detector -> state.videoControl.presentationState -> views.
- Read consumeMessages as an array (tolerating a { messages } wrapper too).
- ensurePresenterRole: parse { presenters: string[] } correctly and compare
  addresses case-insensitively (it previously always re-promoted); sequence
  getDclCastInfo -> ensurePresenterRole so the promotion targets an existing room.
- Extract showcaseState/sharePresentationState into a pure DclCast/state.ts;
  add findActiveCastScreenIndex helper so auto-open selects the casting screen.

* docs: note that ~system/CommsApi consumeMessages returns a bare array

Records the gotcha behind this fix: the runtime returns [{ sender, data }], not
the { messages } wrapper the type implies, so `const { messages } = await
consumeMessages(...)` throws and is swallowed by the surrounding try/catch.

* fix: harden DCL Cast presentation detector per review

Address PR review feedback on the presentation detector's lifecycle and
error handling:

- Split the conflated `presentationSubscribed` flag into an edge tracker
  (`presentationActive`, drives the one-shot auto-open) and a liveness flag
  (`presentationSystem`, only assigned on successful setup). A failed setup
  no longer wedges detection permanently — the next poll tick retries. (P1)
- Await `startPresentationSystem` inside the poll and wrap its setup in
  try/catch/finally so it never leaves an unhandled rejection or a dangling
  in-flight guard; bail if the presentation ended mid-setup. (P1)
- Add `stopPresentationDetection` — removes the poll interval and consume
  systems and resets module state, giving the detector a real reset path. (P1)
- Log (console.error) instead of silently swallowing consume failures. (P1)
- Replace the unsafe double `as` casts in `consumePresentationMessages` with
  a validating `extractMessages` helper that narrows each entry to a string
  `data` before JSON.parse. (P2)
- Use `CAST_SRC_PREFIX` instead of the inline 'livekit-video://' literal, and
  remove the leftover debug track-dump console.log. (P2)
- Retry button now calls `fetchDclCastInfo` so loading/error state updates. (P2)

* perf: tighten DCL Cast detection to 1s and throttle status consume to 250ms

- Detection poll 5s -> 1s so the panel auto-opens ~1s after a presentation
  starts. The poll stays continuous by design (it's the authoritative
  teardown/re-arm path and the only backstop for an ungraceful bot exit);
  documented on the constant so it isn't "optimized" into a stop-on-detect.
- Status consume: drain the presentation comms topic every ~250ms (4Hz) via
  the setInterval helper instead of every frame (~30Hz). Visually instant for
  a slide counter/video state and the dominant cost, so net RPC during a
  presentation drops ~6x even with the faster detection poll.

No logic change beyond cadence; each drain still returns the latest state, so
throttling never drops the final message (including presentation:stopped).

* refactor: make Admin Toolkit UI event-driven (single view-state owner + transitions)

Consolidate all panel/tab/sub-view state into a single store, mutated only through
named transitions, with the render a pure function of that state. This removes the
local-useState shadow and the imperative "blink" remount tricks that made the DCL Cast
auto-open unreliable, and gives the presentation lifecycle a deterministic path.

- New store.ts (single state owner) + actions.ts (named transitions); repointing the
  state importers breaks the detector -> VideoControl/utils -> index import cycle.
- DCL Cast sub-view now reads state.videoControl.selectedTab, so a presentation
  auto-opens the panel to Video Control -> DCL Cast regardless of remount or whether a
  screen is casting yet.
- Presentation start -> showPresentation(); end (bot 'stopped' or track gone) ->
  dismissPresentation() returns to the full DCL Cast panel. Manual Stop Sharing uses
  the same end transition.
- Fold the showcase/share/moderation singletons and the announcement banner into the
  store behind transitions; the announcement banner now resets on new input.
- Remove dead code: the unrendered RewardsControl tab and the now-unused nextTick
  blink array + drain system.

* fix: reliably replicate cast stream to late joiners

A client joining after an admin enabled the cast intermittently showed the
default video (and, for admins, a stale "Activate" panel) instead of the cast.
The late-joiner handshake in the admin message bus was single-shot: the client
sent REQUEST_STATE once at init and applied the first SYNC_STATE reply. Both are
best-effort comms; if either was dropped the client never learned the trusted
src, and the per-frame revert system then pinned the screen to defaultURL even
though the cast src had already arrived over CRDT.

Retry REQUEST_STATE (1s interval, up to 10 attempts) until a remote SYNC_STATE
reply is applied, then stop. Keys strictly on receivedRemoteState (a full reply
from another participant) rather than adminHasActed, so a live SET_ANNOUNCEMENT
cannot stop the retry before the missing video state arrives. Only recovers
state that predates the join; live changes after joining still arrive via
SET_VIDEO.

* refactor: address review feedback on the Admin Toolkit event-driven refactor

Follow-up to the event-driven refactor tightening the "actions are the only
writers" invariant and hardening the presentation detector.

- Route the remaining direct state writes through actions: the video-player
  dropdown (selectVideoPlayer), the stream toggles in DclCastInfo/ShowStreamKey
  (setStream), the minimize/expand chevrons (minimizeCast/expandCast), and the
  detector's dclCast/presentationState writes (setDclCastInfo / setPresentationState
  / clearPresentationState).
- Wire up the now-used minimize/expand transitions and drop the dead closePanel.
- Clear the stored modal handlers in closeShowcase/closeSharePresentation so their
  captured render closures are not retained while the modal is hidden.
- Detector: add a poll reentrancy guard + top-level try/catch, remove the unused
  stopPresentationDetection export and the vestigial injected state param (it is
  now purely action-driven), and drop the discarded interval handle.

* chore: clear pre-existing lint in admin-toolkit-ui

Fix the 11 pre-existing ESLint errors in files the event-driven refactor did not
touch, so the directory lints clean end to end.

- consistent-type-imports: Active, Card, Loading, AddUserInput. Card keeps ReactEcs
  as a value import (it is the JSX factory) with a targeted rule disable.
- no-unused-vars: drop the unused UiTransform import (Loading), add the JSX-factory
  disable for ReactEcs (BanUserDescription), and remove three dead params from the
  SmartItemsControl helper components.

* style: prettier-format the late-joiner REQUEST_STATE retry block

* refactor: address follow-up review on admin toolkit UI

- Complete the "actions are the only writers" migration: route the remaining
  direct state writes in SmartItemsControl, TextAnnouncementsControl and the
  UI-entity bootstrap through named actions, so the actions.ts invariant holds.
- Make unbanMessage `string | undefined` to match every other store optional.
- Drop the unnecessary export on handleGetDclCastInfo (used only in its module).
- Dedupe the presentation end callback so dismissPresentation fires once per
  presentation (the comms 'stopped' message and the track-gone poll edge both
  signal the end; latch resets on the start edge).

* fix: close review findings on the admin toolkit DCL Cast fixes

- P1: guard the consume .then() with presentationActive so a late-resolving
  consumePresentationMessages can't repopulate stale slide state after the
  falling-edge teardown cleared it (there was no self-healing path once the
  consume system was stopped).
- ensurePresenterRole now returns whether the player is/became a presenter;
  startPresentationSystem bails (leaving presentationSystem null) on failure so
  the 1s poll retries, instead of running a consume loop that never receives
  presenter-only state.
- setSmartItemAction drops the unsafe `as SelectedSmartItem` cast (guards on
  presence); setSmartItemVisibility uses copy-on-write to match its siblings.
- receivedRemoteState only latches on a SYNC_STATE that carries video state, so
  an announcement-only reply no longer stops the late-joiner video retry early.

Author: cyaiox

CLAUDE.md

@@ -173,6 +173,16 @@ post-`Composite.instance` in `add-child.ts` (`remapSyncComponentIds`, beside the
 `{self}` id/trigger remap). When adding a placeholder-bearing field — or debugging
 a `Cannot convert … to a BigInt` serialize crash — ensure both paths resolve it.
 
+### `~system/CommsApi` `consumeMessages` returns a bare array
+
+`consumeMessages({ topic })` resolves to a **bare array** of `{ sender, data }`, not
+the `{ messages: [...] }` wrapper its TypeScript type implies (the explorer's
+`CommsApiWrap.ConsumeMessages` serializes a raw JSON array). Destructuring
+`const { messages } = await consumeMessages(...)` yields `undefined` and throws on
+`.length` — and inside a `try/catch` that silently drops every message with no error.
+Read it as an array, tolerating both shapes:
+`Array.isArray(res) ? res : (res?.messages ?? [])`.
+
 ## Skills
 
 Skills live in `.ai/skills/*/SKILL.md`. Read the relevant `SKILL.md` when a task matches a skill's domain.

packages/asset-packs/src/admin-toolkit-ui/Active.tsx

@@ -1,6 +1,7 @@
-import { IEngine } from '@dcl/ecs';
+import type { IEngine } from '@dcl/ecs';
 import { Color4 } from '@dcl/ecs-math';
-import ReactEcs, { Label, UiEntity, UiTransformProps } from '@dcl/react-ecs';
+import type { UiTransformProps } from '@dcl/react-ecs';
+import ReactEcs, { Label, UiEntity } from '@dcl/react-ecs';
 import { clearInterval, setInterval } from './utils';
 import { COLORS } from './VideoControl';
 

packages/asset-packs/src/admin-toolkit-ui/Card.tsx

@@ -1,4 +1,6 @@
-import ReactEcs, { UiEntity, UiTransformProps } from '@dcl/react-ecs';
+// eslint-disable-next-line @typescript-eslint/consistent-type-imports -- ReactEcs is the JSX factory (runtime value), not just the ReactEcs.JSX.Element type
+import ReactEcs, { UiEntity } from '@dcl/react-ecs';
+import type { UiTransformProps } from '@dcl/react-ecs';
 import { containerBackgroundColor } from '.';
 
 export function Card({

packages/asset-packs/src/admin-toolkit-ui/FeedbackButton.tsx

@@ -1,8 +1,8 @@
 import ReactEcs, { UiEntity, Label } from '@dcl/react-ecs';
 import { Color4 } from '@dcl/sdk/math';
 import { startTimeout, stopTimeout } from '../timer';
-import { Button, ButtonVariant, type CompositeButtonProps } from './Button';
-import { state } from '.';
+import { Button, type ButtonVariant, type CompositeButtonProps } from './Button';
+import { state } from './store';
 
 const FEEDBACK_TIMEOUT_ACTION_PREFIX = 'feedback_button_';
 

packages/asset-packs/src/admin-toolkit-ui/Loading.tsx

@@ -1,6 +1,7 @@
-import { IEngine, UiTransform } from '@dcl/ecs';
+import type { IEngine } from '@dcl/ecs';
 import { Color4 } from '@dcl/ecs-math';
-import ReactEcs, { UiEntity, UiTransformProps } from '@dcl/react-ecs';
+import type { UiTransformProps } from '@dcl/react-ecs';
+import ReactEcs, { UiEntity } from '@dcl/react-ecs';
 import { clearInterval, setInterval } from './utils';
 
 interface LoadingProps {

packages/asset-packs/src/admin-toolkit-ui/ModerationControl/AddUserInput.tsx

@@ -8,7 +8,7 @@ import {
 import { handleAddAdmin, handleBanUser } from './utils';
 import { BanUserDescription } from './BanUserDescription';
 
-import { SceneAdmin } from '.';
+import type { SceneAdmin } from '.';
 
 export enum PermissionType {
   ADMIN = 'admin',

packages/asset-packs/src/admin-toolkit-ui/ModerationControl/BanUserDescription.tsx

@@ -1,3 +1,4 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- ReactEcs is required for JSX factory
 import ReactEcs, { UiEntity } from '@dcl/react-ecs';
 import { getAddUserInputStyles, getBanUserTextStyles } from './styles/AddUserInputStyles';
 

packages/asset-packs/src/admin-toolkit-ui/ModerationControl/RemoveAdminConfirmation.tsx

@@ -6,8 +6,8 @@ import { Button } from '../Button';
 import { LoadingDots } from '../Loading';
 import { Error } from '../Error';
 import { fetchAndSyncSceneAdmins } from '..';
+import { cancelRemoveAdmin } from '../actions';
 import { deleteSceneAdmin } from './api';
-import { moderationControlState } from '.';
 import type { SceneAdmin } from '.';
 
 export function RemoveAdminConfirmation({ admin, engine }: { admin: SceneAdmin; engine: IEngine }) {
@@ -89,7 +89,7 @@ export function RemoveAdminConfirmation({ admin, engine }: { admin: SceneAdmin;
                 margin: { right: 30, left: 30 },
               }}
               onMouseDown={() => {
-                moderationControlState.adminToRemove = undefined;
+                cancelRemoveAdmin();
               }}
             />
           )}
@@ -114,7 +114,7 @@ export function RemoveAdminConfirmation({ admin, engine }: { admin: SceneAdmin;
                   if (error) {
                     setError(error);
                   } else {
-                    moderationControlState.adminToRemove = undefined;
+                    cancelRemoveAdmin();
                     await fetchAndSyncSceneAdmins();
                   }
                   setIsLoading(false);

packages/asset-packs/src/admin-toolkit-ui/ModerationControl/UsersList.tsx

@@ -5,10 +5,12 @@ import ReactEcs, { UiEntity, Label } from '@dcl/react-ecs';
 import { getContentUrl } from '../constants';
 import { Button } from '../Button';
 import { clearInterval, setInterval } from '../utils';
+import { state } from '../store';
+import { closeAdminList, closeBanList, confirmRemoveAdmin, setUnbanMessage } from '../actions';
 import { RemoveAdminConfirmation } from './RemoveAdminConfirmation';
 import { type SceneBanUser } from './api';
 import { handleUnbanUser } from './utils';
-import { moderationControlState, type SceneAdmin } from './.';
+import { type SceneAdmin } from './.';
 import {
   getModalStyles,
   getModalBackgrounds,
@@ -74,9 +76,9 @@ const getActionButtonText = (type: UserListType) => {
 
 const closeModal = (type: UserListType) => {
   if (type === UserListType.ADMIN) {
-    moderationControlState.showModalAdminList = false;
+    closeAdminList();
   } else {
-    moderationControlState.showModalBanList = false;
+    closeBanList();
   }
 };
 
@@ -88,42 +90,43 @@ export function ModalUserList({ users, engine, type }: ModalUserListProps) {
 
   const handleRemoveUser = async (user: SceneAdmin | SceneBanUser) => {
     if (type === UserListType.ADMIN) {
-      moderationControlState.adminToRemove = user as SceneAdmin;
+      confirmRemoveAdmin(user as SceneAdmin);
     } else {
       const bannedUser = user as SceneBanUser;
 
       const success = await handleUnbanUser(bannedUser.bannedAddress);
       if (success) {
         const username = bannedUser.name || bannedUser.bannedAddress;
-        moderationControlState.unbanMessage = `${username} has been unbanned from your scene`;
+        setUnbanMessage(`${username} has been unbanned from your scene`);
       } else {
-        moderationControlState.unbanMessage = 'We were unable to unban this user';
+        setUnbanMessage('We were unable to unban this user');
       }
     }
   };
 
   ReactEcs.useEffect(() => {
-    if (moderationControlState.unbanMessage) {
+    if (state.moderationControl.unbanMessage) {
       let counter = 0;
       const interval = setInterval(
         engine,
         () => {
           counter += 100;
           if (counter >= 3000) {
-            moderationControlState.unbanMessage = null;
+            setUnbanMessage(undefined);
           }
         },
         100,
       );
 
       return () => clearInterval(engine, interval);
     }
-  }, [moderationControlState.unbanMessage]);
+  }, [state.moderationControl.unbanMessage]);
 
-  if (moderationControlState.adminToRemove) {
+  const adminToRemove = state.moderationControl.adminToRemove;
+  if (adminToRemove) {
     return (
       <RemoveAdminConfirmation
-        admin={moderationControlState.adminToRemove}
+        admin={adminToRemove}
         engine={engine}
       />
     );
@@ -288,10 +291,10 @@ export function ModalUserList({ users, engine, type }: ModalUserListProps) {
           </UiEntity>
         )}
 
-        {type === UserListType.BAN && moderationControlState.unbanMessage && (
+        {type === UserListType.BAN && state.moderationControl.unbanMessage && (
           <UiEntity uiTransform={styles.messageContainer}>
             <Label
-              value={moderationControlState.unbanMessage}
+              value={state.moderationControl.unbanMessage}
               fontSize={14}
               color={Color4.White()}
               uiTransform={styles.messageLabel}

packages/asset-packs/src/admin-toolkit-ui/ModerationControl/index.tsx

@@ -8,6 +8,7 @@ import { Header } from '../Header';
 import { Button } from '../Button';
 import { Card } from '../Card';
 import { fetchSceneBans } from '..';
+import { openAdminList, openBanList } from '../actions';
 import { AddUserInput, PermissionType } from './AddUserInput';
 import {
   getModerationControlStyles,
@@ -42,19 +43,6 @@ export type SceneAdmin = {
   canBeRemoved: boolean;
 };
 
-type State = {
-  showModalAdminList?: boolean;
-  adminToRemove?: SceneAdmin;
-  showModalBanList?: boolean;
-  unbanMessage?: string | null;
-};
-export const moderationControlState: State = {
-  showModalAdminList: false,
-  showModalBanList: false,
-  adminToRemove: undefined,
-  unbanMessage: null as string | null,
-};
-
 export function ModerationControl({ engine: _engine, player: _player, sceneAdmins }: Props) {
   const styles = getModerationControlStyles();
   const colors = getModerationControlColors();
@@ -79,7 +67,7 @@ export function ModerationControl({ engine: _engine, player: _player, sceneAdmin
           uiTransform={styles.viewListButton}
           icon={MODERATION_ICONS.VERIFIED_USER_ICON}
           iconTransform={styles.viewListIcon}
-          onMouseDown={() => (moderationControlState.showModalAdminList = true)}
+          onMouseDown={() => openAdminList()}
         />
         <UiEntity uiTransform={styles.divider} />
         <AddUserInput
@@ -97,7 +85,7 @@ export function ModerationControl({ engine: _engine, player: _player, sceneAdmin
           iconTransform={styles.viewListIcon}
           onMouseDown={async () => {
             await fetchSceneBans();
-            moderationControlState.showModalBanList = true;
+            openBanList();
           }}
         />
       </UiEntity>