element-call/src/lotus/lotusActions.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.
*/

/**
 * Custom widget actions exchanged between the Lotus host (cinny) and this fork.
 * Kept dependency-free so both `widget.ts` and `lotus/*` can import it without
 * a circular dependency.
 */
export enum LotusWidgetActions {
  /**
   * fromWidget: in-call per-participant speaking / mute state.
   * NOTE: matrix-widget-api `transport.send` is request/response — the host
   * MUST register a handler that replies/acks each one (cinny's `listenAction`
   * does, replying `{}`). If the host has no handler, ClientWidgetApi
   * immediately error-replies "unsupported from-widget action", so the data is
   * silently dropped and each throttled send rejects (caught) — functional miss
   * + log churn, not a hang.
   */
  CallState = "io.lotus.call_state",
  /** toWidget: pin/spotlight (or clear, with userId=null) a participant. */
  FocusParticipant = "io.lotus.focus_participant",
  /** toWidget: play an audio clip into the call as a separate published track. */
  InjectAudio = "io.lotus.inject_audio",
  /** toWidget: set audio/screenshare encoding quality (bitrate/framerate). */
  SetQuality = "io.lotus.set_quality",
  /** toWidget: per-user avatar-decoration image URLs for in-call tiles. */
  Decorations = "io.lotus.decorations",
  /** toWidget: deafen remote audio (and optionally mute screenshare audio). */
  SetDeafen = "io.lotus.set_deafen",
}

/** toWidget Lotus actions that must be allow-listed in `initializeWidget`. */
export const LOTUS_TO_WIDGET_ACTIONS: LotusWidgetActions[] = [
  LotusWidgetActions.FocusParticipant,
  LotusWidgetActions.InjectAudio,
  LotusWidgetActions.SetQuality,
  LotusWidgetActions.Decorations,
  LotusWidgetActions.SetDeafen,
];