element-call/src/lotus/lotusFocus.ts

/*
Copyright 2026 Lotus Guild

SPDX-License-Identifier: AGPL-3.0-only OR LicenseRef-Element-Commercial
Please see LICENSE in the repository root for full details.
*/

import { type IWidgetApiRequest } from "matrix-widget-api";

import { type CallViewModel } from "../state/CallViewModel/CallViewModel";
import { widget } from "../widget";
import { LotusWidgetActions } from "./lotusActions";

/**
 * Handle the host's `io.lotus.focus_participant` toWidget action (#4): pin a
 * participant to the spotlight by Matrix user id, or clear it with
 * `{ userId: null }`. This replaces cinny's old DOM `.click()` tile-selector
 * hack with a real, layout-aware spotlight override.
 *
 * No effect unless the host actually sends the action, so registering the
 * handler whenever we're a widget is safe. Returns a teardown function.
 */
export function startLotusFocus(vm: CallViewModel): () => void {
  const w = widget;
  if (!w) return () => undefined;

  const handler = (ev: CustomEvent<IWidgetApiRequest>): void => {
    // Always reply so the host transport doesn't time out.
    void w.api.transport.reply(ev.detail, {});
    const data = ev.detail.data as { userId?: unknown } | undefined;
    // Mirror deafen's partial-payload semantics: a payload that OMITS `userId`
    // must keep the current spotlight, not clear it. Only act when the key is
    // actually present — an explicit `null` clears, a string pins that user.
    if (data && "userId" in data) {
      const userId = typeof data.userId === "string" ? data.userId : null;
      vm.setManualSpotlight(userId);
    }
  };

  w.lazyActions.on(LotusWidgetActions.FocusParticipant, handler);
  return () =>
    w.lazyActions.off(LotusWidgetActions.FocusParticipant, handler);
}