feat(lotus): report remote screenshare audio to the host (cinny #277)

New fromWidget action io.lotus.screenshare_audio_state { present }: each
LivekitRoomAudioRenderer reports whether a remote participant's
ScreenShareAudio track is being received; the combined answer is sent to
the host on change, and cleared when a renderer unmounts. cinny uses it to
show "Mute Screenshare Audio" only when there is something to mute.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_017PCb59uY3UKqDqt7B6hzd5

src/livekit/MatrixAudioRenderer.tsx

@@ -19,6 +19,10 @@ import { logger as rootLogger } from "matrix-js-sdk/lib/logger";
 import { useEarpieceAudioConfig } from "../MediaDevicesContext";
 import { useReactiveState } from "../useReactiveState";
 import * as controls from "../controls";
+import {
+  clearScreenshareAudio,
+  reportScreenshareAudio,
+} from "../lotus/lotusScreenshareAudio";
 
 export interface MatrixAudioRendererProps {
   /**
@@ -97,6 +101,18 @@ export function LivekitRoomAudioRenderer({
       return true;
     });
 
+  // [lotus / cinny #277] Tell the host whether remote screenshare audio is
+  // playing, so its "Mute Screenshare Audio" control only shows when useful.
+  const hasScreenshareAudio = tracks.some(
+    (ref) =>
+      !ref.participant.isLocal &&
+      ref.publication.source === Track.Source.ScreenShareAudio,
+  );
+  useEffect(() => {
+    reportScreenshareAudio(url, hasScreenshareAudio);
+  }, [url, hasScreenshareAudio]);
+  useEffect(() => (): void => clearScreenshareAudio(url), [url]);
+
   // This component is also (in addition to the "only play audio for connected members" logic above)
   // responsible for mimicking earpiece audio on iPhones.
   // The Safari audio devices enumeration does not expose an earpiece audio device.

src/lotus/lotusActions.ts

@@ -56,6 +56,12 @@ export enum LotusWidgetActions {
   SetAudioOutput = "io.lotus.set_audio_output",
   /** fromWidget: the currently selected output `{ deviceId }` (#119). */
   AudioOutputState = "io.lotus.audio_output_state",
+  /**
+   * fromWidget: `{ present: boolean }`, whether any remote screenshare audio
+   * is being received, so the host's "Mute Screenshare Audio" control only
+   * shows when there is something to mute (cinny #277). Sent on change.
+   */
+  ScreenshareAudioState = "io.lotus.screenshare_audio_state",
   /**
    * fromWidget: local screenshare reminder `{ kind: "ended" | "no-frames" | "alone" }`
    * — window closed, no frames for 15 s, or 30 min of sharing with nobody

src/lotus/lotusScreenshareAudio.test.ts

@@ -0,0 +1,59 @@
+/*
+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 { beforeEach, expect, test, vi } from "vitest";
+
+import { LotusWidgetActions } from "./lotusActions";
+import {
+  clearScreenshareAudio,
+  reportScreenshareAudio,
+  resetScreenshareAudioPresence,
+} from "./lotusScreenshareAudio";
+
+const send = vi.fn().mockResolvedValue({});
+
+vi.mock("../widget", () => ({
+  widget: {
+    api: { transport: { send: (...a: unknown[]): unknown => send(...a) } },
+  },
+}));
+
+const sent = (): unknown[] =>
+  send.mock.calls
+    .filter(([action]) => action === LotusWidgetActions.ScreenshareAudioState)
+    .map(([, data]) => data);
+
+beforeEach(() => {
+  resetScreenshareAudioPresence();
+  send.mockClear();
+});
+
+test("[cinny #277] reports presence only when the combined answer changes", () => {
+  reportScreenshareAudio("sfu-a", false);
+  reportScreenshareAudio("sfu-a", false);
+  reportScreenshareAudio("sfu-a", true);
+  reportScreenshareAudio("sfu-a", true);
+  reportScreenshareAudio("sfu-a", false);
+  expect(sent()).toEqual([
+    { present: false },
+    { present: true },
+    { present: false },
+  ]);
+});
+
+test("[cinny #277] any room with screenshare audio counts as present", () => {
+  reportScreenshareAudio("sfu-a", true);
+  reportScreenshareAudio("sfu-b", false);
+  expect(sent()).toEqual([{ present: true }]);
+  // A share is still playing in sfu-b after sfu-a's stops.
+  reportScreenshareAudio("sfu-b", true);
+  reportScreenshareAudio("sfu-a", false);
+  expect(sent()).toEqual([{ present: true }]);
+  // The renderer for sfu-b unmounts (call left): nothing is playing.
+  clearScreenshareAudio("sfu-b");
+  expect(sent()).toEqual([{ present: true }, { present: false }]);
+});

src/lotus/lotusScreenshareAudio.ts

@@ -8,6 +8,8 @@ Please see LICENSE in the repository root for full details.
 import { BehaviorSubject } from "rxjs";
 
 import { globalScope } from "../state/ObservableScope";
+import { LotusWidgetActions } from "./lotusActions";
+import { lotusSendToHost } from "./lotusWidget";
 
 /**
  * Whether the host has muted remote screenshare AUDIO (`io.lotus.set_deafen`
@@ -25,3 +27,40 @@ export const setScreenshareAudioMuted$ = new BehaviorSubject(false);
 export const muteScreenshareAudio$ = globalScope.behavior(
   setScreenshareAudioMuted$,
 );
+
+/**
+ * [cinny #277] Whether any remote participant's screenshare AUDIO is being
+ * received, so the host shows its "Mute Screenshare Audio" control only when
+ * there is something to mute. Each `LivekitRoomAudioRenderer` (one per SFU)
+ * reports for its own room; the host gets `io.lotus.screenshare_audio_state
+ * { present }` whenever the combined answer changes.
+ */
+const presentByRoom = new Map<string, boolean>();
+let lastSent: boolean | undefined;
+
+function sendIfChanged(): void {
+  const present = [...presentByRoom.values()].some(Boolean);
+  if (present === lastSent) return;
+  lastSent = present;
+  lotusSendToHost(LotusWidgetActions.ScreenshareAudioState, { present });
+}
+
+export function reportScreenshareAudio(
+  roomKey: string,
+  present: boolean,
+): void {
+  presentByRoom.set(roomKey, present);
+  sendIfChanged();
+}
+
+/** The renderer for `roomKey` went away (call left, SFU switched). */
+export function clearScreenshareAudio(roomKey: string): void {
+  presentByRoom.delete(roomKey);
+  sendIfChanged();
+}
+
+/** Test-only: forget all reports. */
+export function resetScreenshareAudioPresence(): void {
+  presentByRoom.clear();
+  lastSent = undefined;
+}