@conference-kit/react 0.0.1 → 0.0.2

package/README.md

@@ -0,0 +1,75 @@
+# @conference-kit/react
+
+React hooks and tiny UI primitives for building peer-to-peer calls on top of the `@conference-kit/core` peer and a signaling server.
+
+## Install
+
+```bash
+npm install @conference-kit/react
+```
+
+Peer deps: React 18+.
+
+## Key hooks
+
+- `useMeshRoom` — mesh everyone in a room; exposes roster, participants, local stream, raised hands, waiting-room/host state, and helpers like `requestStream`, `admitPeer`, `rejectPeer`, `raiseHand`, `leave`.
+- `useCall` / `useCallState` — 1:1 call helper with local/remote streams and call lifecycle.
+- `useDataChannel` / `useDataChannelMessages` — send/receive arbitrary data over an RTC data channel.
+- `useMediaStream`, `useScreenShare`, `useWebRTC` — focused utilities for media capture and connection wiring.
+
+## Components
+
+- `VideoPlayer`, `AudioPlayer` — attach a `MediaStream` to media elements.
+- `StatusBadge`, `ErrorBanner` — lightweight status UI.
+
+## Feature flags
+
+`mergeFeatures` and `defaultFeatures` let you toggle capabilities (data channel, screen share, waiting room, host controls, active speaker detection) when calling `useMeshRoom`.
+
+## Quick mesh example
+
+```tsx
+import { useMeshRoom, VideoPlayer } from "@conference-kit/react";
+
+function Mesh({
+  peerId,
+  room,
+  signalingUrl,
+}: {
+  peerId: string;
+  room: string;
+  signalingUrl: string;
+}) {
+  const mesh = useMeshRoom({
+    peerId,
+    room,
+    signalingUrl,
+    isHost: false,
+    mediaConstraints: { audio: true, video: true },
+    features: { enableWaitingRoom: true, enableHostControls: true },
+  });
+
+  return (
+    <div>
+      <button onClick={() => mesh.requestStream()}>Request media</button>
+      <div>
+        {mesh.participants.map((p) => (
+          <VideoPlayer key={p.id} stream={p.remoteStream} muted={false} />
+        ))}
+      </div>
+    </div>
+  );
+}
+```
+
+## Signaling client
+
+`SignalingClient` is exposed if you need to build a custom hook or UI. It handles reconnects and emits presence, signal, broadcast, and control events.
+
+## Build
+
+```bash
+npm run build
+```
+
+Outputs ESM and types to `dist/`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conference-kit/react",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",

package/src/config/features.ts

@@ -1,11 +1,17 @@
 export type FeatureConfig = {
   enableDataChannel?: boolean;
   enableScreenShare?: boolean;
+  enableWaitingRoom?: boolean;
+  enableHostControls?: boolean;
+  enableActiveSpeaker?: boolean;
 };
 
 export const defaultFeatures: Required<FeatureConfig> = {
   enableDataChannel: true,
   enableScreenShare: true,
+  enableWaitingRoom: false,
+  enableHostControls: false,
+  enableActiveSpeaker: false,
 };
 
 export function mergeFeatures(

package/src/hooks/useMeshRoom.ts

@@ -16,6 +16,7 @@ export type UseMeshRoomOptions = {
   peerId: string;
   room: string;
   signalingUrl: string;
+  isHost?: boolean;
   mediaConstraints?: MediaStreamConstraints;
   rtcConfig?: RTCConfiguration;
   trickle?: boolean;
@@ -28,6 +29,7 @@ export function useMeshRoom(options: UseMeshRoomOptions) {
     peerId,
     room,
     signalingUrl,
+    isHost,
     mediaConstraints,
     rtcConfig,
     trickle,
@@ -54,9 +56,18 @@ export function useMeshRoom(options: UseMeshRoomOptions) {
         url: signalingUrl,
         peerId,
         room,
+        isHost,
+        enableWaitingRoom: features.enableWaitingRoom,
         autoReconnect,
       }),
-    [autoReconnect, peerId, room, signalingUrl]
+    [
+      autoReconnect,
+      features.enableWaitingRoom,
+      isHost,
+      peerId,
+      room,
+      signalingUrl,
+    ]
   );
 
   const peers = useRef<Map<string, Peer>>(new Map());
@@ -64,6 +75,12 @@ export function useMeshRoom(options: UseMeshRoomOptions) {
   const [roster, setRoster] = useState<string[]>([]);
   const [participants, setParticipants] = useState<MeshParticipant[]>([]);
   const [error, setError] = useState<Error | null>(null);
+  const [waitingList, setWaitingList] = useState<string[]>([]);
+  const [inWaitingRoom, setInWaitingRoom] = useState(
+    features.enableWaitingRoom && !isHost
+  );
+  const [activeSpeakerId, setActiveSpeakerId] = useState<string | null>(null);
+  const [raisedHands, setRaisedHands] = useState<Set<string>>(new Set());
   const [signalingStatus, setSignalingStatus] = useState<
     "idle" | "connecting" | "open" | "closed"
   >("idle");
@@ -109,6 +126,7 @@ export function useMeshRoom(options: UseMeshRoomOptions) {
   const ensurePeer = useCallback(
     (id: string, side?: PeerSide) => {
       if (id === peerId) return null;
+      if (features.enableWaitingRoom && inWaitingRoom) return null;
       const existing = peers.current.get(id);
       if (existing) return existing;
       // enableDataChannel is supported in the runtime PeerConfig but may lag in published typings; cast to satisfy TS.
@@ -203,6 +221,51 @@ export function useMeshRoom(options: UseMeshRoomOptions) {
     return () => signaling.off("presence", onPresence as any);
   }, [destroyPeer, ensurePeer, peerId, signaling]);
 
+  useEffect(() => {
+    const onControl = ({ action, data }: { action: string; data?: any }) => {
+      if (action === "waiting-list") {
+        const waiting = (data?.waiting as string[]) ?? [];
+        setWaitingList(waiting);
+        return;
+      }
+      if (action === "waiting") {
+        setInWaitingRoom(true);
+        return;
+      }
+      if (action === "admitted") {
+        setInWaitingRoom(false);
+        return;
+      }
+      if (action === "rejected") {
+        setInWaitingRoom(false);
+        setError(new Error("Rejected by host"));
+        return;
+      }
+      if (action === "raise-hand") {
+        const peer = (data?.peerId as string) ?? null;
+        if (!peer) return;
+        setRaisedHands((prev) => {
+          const next = new Set(prev);
+          next.add(peer);
+          return next;
+        });
+        return;
+      }
+      if (action === "hand-lowered") {
+        const peer = (data?.peerId as string) ?? null;
+        if (!peer) return;
+        setRaisedHands((prev) => {
+          const next = new Set(prev);
+          next.delete(peer);
+          return next;
+        });
+        return;
+      }
+    };
+    signaling.on("control", onControl as any);
+    return () => signaling.off("control", onControl as any);
+  }, [signaling]);
+
   useEffect(() => {
     const onSignal = ({ from, data }: { from: string; data: unknown }) => {
       const peer = ensurePeer(from, sideForPeer(from));
@@ -217,10 +280,39 @@ export function useMeshRoom(options: UseMeshRoomOptions) {
     peers.current.clear();
     setParticipants([]);
     setRoster([]);
+    setWaitingList([]);
+    setInWaitingRoom(false);
+    setRaisedHands(new Set());
     stopStream();
     signaling.close();
   }, [signaling, stopStream]);
 
+  const admitPeer = useCallback(
+    (id: string) => {
+      if (!features.enableWaitingRoom || !isHost) return;
+      signaling.sendControl("admit", { peerId: id });
+    },
+    [features.enableWaitingRoom, isHost, signaling]
+  );
+
+  const rejectPeer = useCallback(
+    (id: string) => {
+      if (!features.enableWaitingRoom || !isHost) return;
+      signaling.sendControl("reject", { peerId: id });
+    },
+    [features.enableWaitingRoom, isHost, signaling]
+  );
+
+  const raiseHand = useCallback(() => {
+    if (!features.enableHostControls) return;
+    signaling.sendControl("raise-hand", { peerId });
+  }, [features.enableHostControls, peerId, signaling]);
+
+  const lowerHand = useCallback(() => {
+    if (!features.enableHostControls) return;
+    signaling.sendControl("hand-lowered", { peerId });
+  }, [features.enableHostControls, peerId, signaling]);
+
   useEffect(() => {
     if (previousStream.current === localStream) return;
     const prev = previousStream.current;
@@ -231,6 +323,75 @@ export function useMeshRoom(options: UseMeshRoomOptions) {
     previousStream.current = localStream ?? null;
   }, [localStream]);
 
+  const analyzers = useRef<
+    Map<
+      string,
+      {
+        ctx: AudioContext;
+        analyser: AnalyserNode;
+        source: MediaStreamAudioSourceNode;
+      }
+    >
+  >(new Map());
+
+  useEffect(() => {
+    if (!features.enableActiveSpeaker) return;
+
+    const ensureAnalyzer = (id: string, stream: MediaStream) => {
+      if (analyzers.current.has(id)) return;
+      const ctx = new AudioContext();
+      const source = ctx.createMediaStreamSource(stream);
+      const analyser = ctx.createAnalyser();
+      analyser.fftSize = 256;
+      source.connect(analyser);
+      analyzers.current.set(id, { ctx, analyser, source });
+    };
+
+    participants.forEach((p) => {
+      if (p.remoteStream) ensureAnalyzer(p.id, p.remoteStream);
+    });
+
+    const removedIds: string[] = [];
+    analyzers.current.forEach((_value, id) => {
+      const stillPresent = participants.find(
+        (p) => p.id === id && p.remoteStream
+      );
+      if (!stillPresent) {
+        const entry = analyzers.current.get(id);
+        entry?.source.disconnect();
+        entry?.analyser.disconnect();
+        entry?.ctx.close();
+        analyzers.current.delete(id);
+        removedIds.push(id);
+      }
+    });
+
+    const interval = window.setInterval(() => {
+      let loudestId: string | null = null;
+      let loudest = 0;
+      analyzers.current.forEach((entry, id) => {
+        const data = new Uint8Array(entry.analyser.frequencyBinCount);
+        entry.analyser.getByteFrequencyData(data);
+        const avg = data.reduce((acc, v) => acc + v, 0) / data.length;
+        if (avg > loudest) {
+          loudest = avg;
+          loudestId = avg > 20 ? id : null;
+        }
+      });
+      setActiveSpeakerId((prev) => (prev === loudestId ? prev : loudestId));
+    }, 500);
+
+    return () => {
+      window.clearInterval(interval);
+      analyzers.current.forEach((entry) => {
+        entry.source.disconnect();
+        entry.analyser.disconnect();
+        entry.ctx.close();
+      });
+      analyzers.current.clear();
+    };
+  }, [features.enableActiveSpeaker, participants]);
+
   return {
     localStream,
     ready,
@@ -238,7 +399,15 @@ export function useMeshRoom(options: UseMeshRoomOptions) {
     mediaError,
     participants,
     roster,
+    waitingList,
+    inWaitingRoom,
+    activeSpeakerId,
+    raisedHands,
     signalingStatus,
+    admitPeer,
+    rejectPeer,
+    raiseHand,
+    lowerHand,
     requestStream,
     stopStream,
     leave,

package/src/signaling/SignalingClient.ts

@@ -4,6 +4,12 @@ export type EventMap = {
   error: Error;
   signal: { from: string; data: unknown };
   broadcast: { from: string; room?: string | null; data: unknown };
+  control: {
+    action: string;
+    from: string;
+    room?: string | null;
+    data?: unknown;
+  };
   presence: {
     room?: string | null;
     peerId: string;
@@ -42,6 +48,8 @@ export type SignalingClientOptions = {
   url: string;
   peerId: string;
   room?: string | null;
+  isHost?: boolean;
+  enableWaitingRoom?: boolean;
   autoReconnect?: boolean;
   reconnectDelayMs?: number;
 };
@@ -49,6 +57,13 @@ export type SignalingClientOptions = {
 type IncomingMessage =
   | { type: "signal"; from: string; data: unknown }
   | { type: "broadcast"; from: string; room?: string | null; data: unknown }
+  | {
+      type: "control";
+      from: string;
+      room?: string | null;
+      action: string;
+      data?: unknown;
+    }
   | {
       type: "presence";
       room?: string | null;
@@ -59,7 +74,8 @@ type IncomingMessage =
 
 type OutgoingMessage =
   | { type: "signal"; to: string; data: unknown }
-  | { type: "broadcast"; data: unknown };
+  | { type: "broadcast"; data: unknown }
+  | { type: "control"; action: string; data?: unknown };
 
 export class SignalingClient {
   private ws: WebSocket | null = null;
@@ -84,10 +100,12 @@ export class SignalingClient {
       return;
     }
 
-    const { url, peerId, room } = this.options;
-    const wsUrl = `${url}?peerId=${encodeURIComponent(peerId)}${
-      room ? `&room=${encodeURIComponent(room)}` : ""
-    }`;
+    const { url, peerId, room, isHost, enableWaitingRoom } = this.options;
+    const params = new URLSearchParams({ peerId });
+    if (room) params.set("room", room);
+    if (isHost) params.set("host", "1");
+    if (enableWaitingRoom) params.set("waitingRoom", "1");
+    const wsUrl = `${url}?${params.toString()}`;
     this.ws = new WebSocket(wsUrl);
 
     this.ws.addEventListener("open", () => {
@@ -114,6 +132,13 @@ export class SignalingClient {
             peers: parsed.peers,
             action: parsed.action,
           });
+        } else if (parsed.type === "control") {
+          this.emitter.emit("control", {
+            from: parsed.from,
+            room: parsed.room,
+            action: parsed.action,
+            data: parsed.data,
+          });
         }
       } catch (error) {
         this.emitter.emit("error", error as Error);
@@ -145,6 +170,10 @@ export class SignalingClient {
     this.enqueue({ type: "broadcast", data });
   }
 
+  sendControl(action: string, data?: unknown) {
+    this.enqueue({ type: "control", action, data });
+  }
+
   on<K extends EventKey>(event: K, handler: Handler<K>) {
     this.emitter.on(event, handler);
   }