feat(call): in-call soundboard, quality controls, room call-permissions

Element Call is now consumed as our self-built fork
(@lotusguild/element-call-embedded); wire up its previously-dormant
capabilities and document the fork as live.

Soundboard (P5-15): a call-bar button plays user-uploaded audio clips into the
call as a real published track (io.lotus.inject_audio) plus local playback.
Clips are uploadable like emoji/sticker packs, stored in io.lotus.soundboard
account data (synced across devices). Gated by a Settings toggle + volume.

Quality controls (P5-31): per-user mic/screenshare bitrate + screenshare
framerate (Settings -> Calls), applied via io.lotus.set_quality clamped to any
room cap. Room admins set caps and hard call-permissions (allow_screenshare /
allow_camera) in Room Settings -> Voice; the call bar hides blocked buttons.

- New: CallSoundboard, useSoundboard, soundboardClips; RoomQuality,
  useCallQuality, callQuality (+ unit tests).
- Optimistic-write RoomQuality admin UI (no stale-state clobber).
- Docs: mark EC fork live across README/FEATURES/TODO/BUGS/TESTING; add D2
  manual-test steps.

Numeric quality caps are client-cooperative; screenshare/camera permissions are
hard-enforced server-side (see LotusGuild/matrix voice-limit-guard).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

src/app/hooks/useCallQuality.ts

@@ -0,0 +1,41 @@
+import { useEffect } from 'react';
+import { useAtomValue } from 'jotai';
+import { CallEmbed } from '../plugins/call';
+import { settingsAtom } from '../state/settings';
+import { useStateEvent } from './useStateEvent';
+import { StateEvent } from '../../types/matrix/room';
+import { buildQualityPayload, RoomQualityContent } from '../utils/callQuality';
+
+/**
+ * [P5-31] Apply the user's call quality settings (clamped by any room-level
+ * cap) to the Element Call fork via the `io.lotus.set_quality` widget action.
+ *
+ * The fork stores the settings and re-applies them on every (re)publish and
+ * reconnect, so we only need to (re)send when the payload changes or the widget
+ * becomes ready — no need to poll the track lifecycle here.
+ */
+export function useCallQuality(embed: CallEmbed): void {
+  const { callAudioBitrate, screenshareBitrate, screenshareFramerate } = useAtomValue(settingsAtom);
+
+  const roomQualityEvent = useStateEvent(embed.room, StateEvent.LotusRoomQuality);
+  const roomCaps = roomQualityEvent?.getContent<RoomQualityContent>();
+
+  // Depend on the primitive cap values (not the event object) so re-renders
+  // don't resend needlessly.
+  const audioCap = roomCaps?.audio_max_kbps;
+  const ssCap = roomCaps?.screenshare_max_kbps;
+  const fpsCap = roomCaps?.screenshare_max_fps;
+
+  useEffect(() => {
+    const payload = buildQualityPayload(
+      { callAudioBitrate, screenshareBitrate, screenshareFramerate },
+      { audio_max_kbps: audioCap, screenshare_max_kbps: ssCap, screenshare_max_fps: fpsCap },
+    );
+    const send = (): void => embed.control.setQuality(payload);
+    // Send now (settings are sticky fork-side even if tracks aren't up yet) and
+    // again once the widget signals ready, in case the transport wasn't up.
+    send();
+    const off = embed.onReady(send);
+    return off;
+  }, [embed, callAudioBitrate, screenshareBitrate, screenshareFramerate, audioCap, ssCap, fpsCap]);
+}

src/app/hooks/useSoundboard.ts

@@ -0,0 +1,101 @@
+import { useCallback, useEffect, useState } from 'react';
+import { useMatrixClient } from './useMatrixClient';
+import { useAccountDataCallback } from './useAccountDataCallback';
+import { AccountDataEvent } from '../../types/matrix/accountData';
+import {
+  SoundboardClip,
+  SoundboardContent,
+  SOUNDBOARD_MAX_CLIP_BYTES,
+  SOUNDBOARD_MAX_CLIPS,
+  SOUNDBOARD_NAME_MAX,
+  readSoundboardClips,
+} from '../utils/soundboardClips';
+
+const KEY = AccountDataEvent.LotusSoundboard;
+
+/**
+ * [P5-15] Read/write the user's personal soundboard, stored in the
+ * `io.lotus.soundboard` account data event (synced across devices like custom
+ * emoji/sticker packs). Uploading writes the audio to the media repo and
+ * appends an mxc reference.
+ */
+export function useSoundboard(): {
+  clips: SoundboardClip[];
+  addClip: (file: File, name?: string) => Promise<void>;
+  removeClip: (id: string) => Promise<void>;
+  renameClip: (id: string, name: string) => Promise<void>;
+} {
+  const mx = useMatrixClient();
+  const [clips, setClips] = useState<SoundboardClip[]>(() => readSoundboardClips(mx));
+
+  useAccountDataCallback(
+    mx,
+    useCallback((evt) => {
+      if (evt.getType() === KEY) {
+        const content = evt.getContent<SoundboardContent>();
+        setClips(Array.isArray(content?.clips) ? content.clips : []);
+      }
+    }, []),
+  );
+
+  useEffect(() => {
+    setClips(readSoundboardClips(mx));
+  }, [mx]);
+
+  const persist = useCallback(
+    async (next: SoundboardClip[]) => {
+      const content: SoundboardContent = { clips: next };
+      await (
+        mx as unknown as { setAccountData: (t: string, c: unknown) => Promise<void> }
+      ).setAccountData(KEY, content);
+    },
+    [mx],
+  );
+
+  const addClip = useCallback(
+    async (file: File, name?: string) => {
+      const current = readSoundboardClips(mx);
+      if (current.length >= SOUNDBOARD_MAX_CLIPS) {
+        throw new Error(`Soundboard is full (max ${SOUNDBOARD_MAX_CLIPS} clips).`);
+      }
+      if (file.size > SOUNDBOARD_MAX_CLIP_BYTES) {
+        throw new Error('Clip is too large (max 1 MB).');
+      }
+      const res = await mx.uploadContent(file, { type: file.type || 'audio/mpeg' });
+      const mxc = res.content_uri;
+      if (!mxc) throw new Error('Upload failed.');
+      const label = (name ?? file.name.replace(/\.[^/.]+$/, ''))
+        .trim()
+        .slice(0, SOUNDBOARD_NAME_MAX);
+      const clip: SoundboardClip = {
+        id: `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        name: label || 'Clip',
+        url: mxc,
+        mimetype: file.type || undefined,
+        size: file.size,
+      };
+      await persist([...current, clip]);
+    },
+    [mx, persist],
+  );
+
+  const removeClip = useCallback(
+    async (id: string) => {
+      const next = readSoundboardClips(mx).filter((c) => c.id !== id);
+      await persist(next);
+    },
+    [mx, persist],
+  );
+
+  const renameClip = useCallback(
+    async (id: string, name: string) => {
+      const trimmed = name.trim().slice(0, SOUNDBOARD_NAME_MAX);
+      if (!trimmed) return;
+      const next = readSoundboardClips(mx).map((c) => (c.id === id ? { ...c, name: trimmed } : c));
+      await persist(next);
+    },
+    [mx, persist],
+  );
+
+  return { clips, addClip, removeClip, renameClip };
+}