@defcomm/meetingsdk 0.1.0 → 0.1.1

package/README.md

@@ -1,281 +1,355 @@
-# @afosecure/meetingsdk
+# DEFCOMM Meet SDK
 
-React/TypeScript SDK for the **DEFCOMM Rust SFU**.
+`@afosecure/meetingsdk` is the React/TypeScript client SDK used by **DEFCOMM Meet**.
 
-This guide is for developers integrating the SDK into a React application. It covers installation, configuration, joining, media, participants, screen sharing, reconnection, recording, room management, signaling, and production integration.
+It provides the application layer for:
 
-> **Important:** This package is an SFU client. It is **not** a mesh/P2P SDK.
-
-## Quick start
-
-```bash
-npm install @afosecure/meetingsdk
-```
-
-Configure the SDK once:
-
-```ts
-import { updateSDKConfig } from "@afosecure/meetingsdk";
-
-updateSDKConfig({
-  apiBase: "https://your-sfu.example.com/api",
-  wsBase: "wss://your-sfu.example.com/ws",
-});
-```
-
-Then put your meeting UI inside `MeetingProvider`:
-
-```tsx
-import {
-  MeetingProvider,
-  useMeeting,
-  useParticipants,
-} from "@afosecure/meetingsdk";
-
-function MeetingRoom() {
-  const {
-    join,
-    leave,
-    toggleMic,
-    toggleCam,
-    startScreenShare,
-    stopScreenShare,
-    startRecording,
-    stopRecording,
-  } = useMeeting();
+- joining and leaving meetings
+- microphone and camera control
+- remote participant media
+- screen sharing
+- active-speaker detection
+- participant presence and reconnection state
+- private-room admission
+- server-side recording
+- room management
+- chat/PubSub integration
+- WebRTC and SFU signaling orchestration
 
-  const participants = useParticipants();
+The SDK is designed so that a DEFCOMM Meet consumer should **not need to manage WebRTC peer connections, SDP, ICE candidates, RTP tracks, reconnect logic, or browser media plumbing directly**.
 
-  return (
-    <div>
-      <button onClick={join}>Join</button>
-      <button onClick={toggleMic}>Mic</button>
-      <button onClick={toggleCam}>Camera</button>
-      <button onClick={startScreenShare}>Share screen</button>
-      <button onClick={stopScreenShare}>Stop sharing</button>
-      <button onClick={startRecording}>Record</button>
-      <button onClick={stopRecording}>Stop recording</button>
-      <button onClick={leave}>Leave</button>
+---
 
-      {participants.map((participant) => (
-        <div key={participant.id}>{participant.name}</div>
-      ))}
-    </div>
-  );
-}
+## Table of contents
+
+1. [What the SDK does](#what-the-sdk-does)
+2. [Architecture](#architecture)
+3. [Installation](#installation)
+4. [SDK configuration](#sdk-configuration)
+5. [Creating a meeting](#creating-a-meeting)
+6. [Joining a meeting](#joining-a-meeting)
+7. [MeetingProvider](#meetingprovider)
+8. [The `useMeeting` hook](#the-usemeeting-hook)
+9. [Participants](#participants)
+10. [Local participant](#local-participant)
+11. [Remote media](#remote-media)
+12. [Microphone and camera](#microphone-and-camera)
+13. [Active speaker detection](#active-speaker-detection)
+14. [Screen sharing](#screen-sharing)
+15. [Recording](#recording)
+16. [Private rooms and join approval](#private-rooms-and-join-approval)
+17. [Reconnection and participant presence](#reconnection-and-participant-presence)
+18. [Leaving a meeting](#leaving-a-meeting)
+19. [Room management](#room-management)
+20. [Meeting preview](#meeting-preview)
+21. [Chat](#chat)
+22. [Error handling](#error-handling)
+23. [Recommended DEFCOMM Meet structure](#recommended-defcomm-meet-structure)
+24. [Important implementation rules](#important-implementation-rules)
+25. [Build and publish](#build-and-publish)
 
-export function MeetingPage({ roomCode }: { roomCode: string }) {
-  return (
-    <MeetingProvider roomCode={roomCode} displayName="Afolabi">
-      <MeetingRoom />
-    </MeetingProvider>
-  );
-}
-```
+---
 
-Call `join()` from a user action so the browser can request camera/microphone permission normally. The SDK then obtains the SFU token, opens `/ws`, sends JOIN, creates publisher/subscriber PeerConnections, publishes local media, and subscribes to remote tracks. fileciteturn9file0L87-L113
+# What the SDK does
 
----
+DEFCOMM Meet is built around an **SFU architecture**.
 
-# 1. Architecture
+The browser does not establish a separate peer connection with every participant.
 
-The SDK uses one publisher PeerConnection and one subscriber PeerConnection per participant:
+Instead:
 
 ```text
-Browser
-  ├── Publisher RTCPeerConnection ── publish_offer ──> Rust SFU
-  │
-  └── Subscriber RTCPeerConnection <─ subscribe_offer ── Rust SFU
-                                              │
-                                          MediaRouter
-                                              │
-                                      other participants
+Participant A ──┐
+Participant B ──┼──► DEFCOMM Rust SFU ──► Participants
+Participant C ──┘
 ```
 
-The SFU-generated track ID is the authoritative bridge between signaling metadata and browser `MediaStreamTrack` objects. fileciteturn9file0L5-L20
-
-Think of the system as:
+The SDK sits between the React application and the SFU:
 
 ```text
-Your React application
-        │
-        ▼
-@afosecure/meetingsdk
-        │
-        ├── WebSocket signaling
-        └── WebRTC media
+┌───────────────────────────────┐
+│        DEFCOMM Meet App       │
+│                               │
+│   Meeting UI / Participant UI │
+└───────────────┬───────────────┘
                 │
                 ▼
-        DEFCOMM Rust SFU
+┌───────────────────────────────┐
+│     @afosecure/meetingsdk     │
+│                               │
+│ React hooks                   │
+│ Meeting state                 │
+│ WebRTC                       │
+│ WebSocket signaling           │
+│ Reconnection                  │
+│ Active speaker detection      │
+│ Media attachment              │
+│ Recording controls            │
+└───────────────┬───────────────┘
                 │
-        ┌───────┴────────┐
-        │                │
-     RTP/RTCP         Recording
-        │
-     MediaRouter
+                ▼
+┌───────────────────────────────┐
+│       DEFCOMM Rust SFU        │
+│                               │
+│ Rooms                         │
+│ Participants                  │
+│ Admission                     │
+│ SDP / ICE                     │
+│ RTP forwarding                │
+│ Track state                   │
+│ Recording                     │
+└───────────────────────────────┘
 ```
 
-The application owns the UI. The SDK owns browser WebRTC/signaling orchestration. The SFU owns authoritative room and media state.
+### The responsibility split
+
+**Your application owns:**
+
+- layout
+- buttons
+- participant tiles
+- navbar
+- chat UI
+- recording indicator
+- active-speaker styling
+- loading/error screens
+
+**The SDK owns:**
+
+- browser media access
+- publisher PeerConnection
+- subscriber PeerConnection
+- WebSocket signaling
+- media track mapping
+- reconnect/resume behavior
+- active-speaker detection
+- SDK meeting state
+
+**The SFU owns:**
+
+- room state
+- participant membership
+- admission/approval
+- signaling authority
+- media forwarding
+- track publication/subscription
+- server-side recording
 
 ---
 
-# 2. Installation
+# Installation
 
 ```bash
 npm install @afosecure/meetingsdk
 ```
 
-The package is intended for React + TypeScript applications.
+The SDK is intended for browser-based React + TypeScript applications.
 
 ---
 
-# 3. Configuration
+# Creating a meeting
 
-```ts
-import { updateSDKConfig } from "@afosecure/meetingsdk";
+The SDK exposes room management through `VideoSDKCore` and `useMeeting()`.
 
-updateSDKConfig({
-  apiBase: "https://your-sfu.example.com/api",
-  wsBase: "wss://your-sfu.example.com/ws",
+```tsx
+const { createRoom } = useMeeting();
+
+const room = await createRoom({
+  name: "Engineering Standup",
+  description: "Daily engineering meeting",
+  capacity: 50,
+  is_private: true,
 });
 ```
 
-Use:
-
-```text
-apiBase → REST API base
-wsBase  → WebSocket signaling endpoint
-```
+A room can also be retrieved:
 
-For local development:
+```tsx
+const { getRoom } = useMeeting();
 
-```ts
-updateSDKConfig({
-  apiBase: "http://localhost:8080/api",
-  wsBase: "ws://localhost:8080/ws",
-});
+const room = await getRoom(roomCode);
 ```
 
-For production:
+And deleted when appropriate:
 
-```ts
-updateSDKConfig({
-  apiBase: "https://sfu.example.com/api",
-  wsBase: "wss://sfu.example.com/ws",
-});
+```tsx
+const { deleteRoom } = useMeeting();
+
+await deleteRoom(roomCode);
 ```
 
-Do **not** use the old mesh `/watch/:room` endpoint. The current SFU uses `/ws` plus REST room/token APIs. fileciteturn9file0L76-L85
+Room creation and deletion should normally be restricted to the appropriate application role.
 
 ---
 
-# 4. Meeting lifecycle
+# Joining a meeting
+
+The normal React integration starts with `MeetingProvider`.
 
-A normal meeting follows:
+```tsx
+import { MeetingProvider, useMeeting } from "@afosecure/meetingsdk";
+
+function MeetingRoom() {
+  const { join, leave } = useMeeting();
+
+  return (
+    <div>
+      <button onClick={() => join()}>Join meeting</button>
+
+      <button onClick={() => leave()}>Leave</button>
+    </div>
+  );
+}
+
+export function MeetingPage() {
+  return (
+    <MeetingProvider
+      config={{
+        roomId: "room-code",
+        name: "Afolabi",
+        audioMuted: false,
+        videoMuted: false,
+      }}
+    >
+      <MeetingRoom />
+    </MeetingProvider>
+  );
+}
+```
+
+`MeetingProvider` accepts:
+
+```ts
+type MeetingConfig = {
+  roomId: string;
+  name: string;
+  audioMuted?: boolean;
+  videoMuted?: boolean;
+  token?: string;
+};
+```
+
+### Recommended join flow
 
 ```text
-Configure SDK
+Meeting page
     ↓
 MeetingProvider
     ↓
 User clicks Join
     ↓
-Get SFU access token
-    ↓
-Open WebSocket
+join()
     ↓
-JOIN
+Browser requests camera/microphone
     ↓
-Create publisher/subscriber PCs
+SDK connects to SFU
     ↓
-Publish microphone + camera
+Publisher PeerConnection
     ↓
-Subscribe to remote tracks
+Subscriber PeerConnection
     ↓
-Attach media to UI
+Remote tracks become available
 ```
 
-The current protocol includes joining/leaving, SDP negotiation, subscriptions, ICE, track state, screen sharing, recording, admission control, and related events. fileciteturn9file0L22-L64
+Call `join()` from a user action whenever possible. This gives the browser a normal user-initiated context for requesting media permissions.
 
 ---
 
-# 5. Stable participant identity
-
-The SDK creates a browser participant ID only when one does not already exist.
-
-Storage key:
-
-```text
-defcomm:participant_id
-```
-
-Therefore:
-
-```text
-First load       → generate ID
-Reload           → reuse ID
-Temporary outage → reuse ID
-Reconnect        → reuse ID
-```
+# The `useMeeting` hook
 
-The room-specific resume token is stored as:
+`useMeeting()` is the main application API.
 
-```text
-defcomm:sfu:resume:<roomCode>
-```
-
-A transient network failure does not clear the resume token. An intentional `leave()` does. fileciteturn9file0L116-L132
+```tsx
+const {
+  join,
+  leave,
 
-This distinction is critical:
+  toggleMic,
+  toggleCam,
 
-```text
-Network loss
-    → reconnect/resume
+  startScreenShare,
+  stopScreenShare,
 
-User clicked Leave
-    → actual departure
-```
+  startRecording,
+  stopRecording,
+  getRecordingStatus,
 
----
+  participants,
+  localParticipant,
+  activeSpeakerIds,
+  presenterId,
+  room,
 
-# 6. Joining a meeting
+  approveJoinRequest,
+  rejectJoinRequest,
 
-```tsx
-const {
-  join,
-  leave,
+  sendMessage,
 } = useMeeting();
 ```
 
-Join from a user interaction:
+The hook also supports event handlers:
 
 ```tsx
-<button onClick={join}>Join meeting</button>
+const meeting = useMeeting({
+  onError: (error) => {
+    console.error(error);
+  },
+
+  onActiveSpeakersChanged: (participantIds) => {
+    console.log("Active speakers:", participantIds);
+  },
+
+  onRecordingStarted: (recording) => {
+    console.log("Recording started:", recording);
+  },
+
+  onRecordingStopped: (recording) => {
+    console.log("Recording stopped:", recording);
+  },
+});
 ```
 
-Leave intentionally:
+For normal React rendering, prefer the state exposed by the hook:
 
 ```tsx
-<button onClick={leave}>Leave</button>
+const { activeSpeakerIds } = useMeeting();
 ```
 
-Do not close the WebSocket manually to simulate leaving. Use the SDK's `leave()` method so the SFU receives the proper leave operation and local state is cleaned up.
+Use event callbacks when the application needs to perform an additional side effect.
 
 ---
 
-# 7. Participant model
+# Participants
 
-Conceptually:
+Use `useParticipants()` when the component only needs the participant list.
+
+```tsx
+import { useParticipants } from "@afosecure/meetingsdk";
+
+function ParticipantList() {
+  const participants = useParticipants();
+
+  return (
+    <div>
+      {participants.map((participant) => (
+        <div key={participant.id}>{participant.name}</div>
+      ))}
+    </div>
+  );
+}
+```
+
+A participant contains:
 
 ```ts
 type Participant = {
   id: string;
   name?: string;
+  isHost?: boolean;
+  isLocal?: boolean;
+  isPresenter?: boolean;
 
-  connectionState?:
-    | "connected"
-    | "reconnecting"
-    | "disconnected";
+  connectionState?: "connected" | "reconnecting" | "disconnected";
 
   media?: {
     stream?: MediaStream | null;
@@ -288,713 +362,986 @@ type Participant = {
     micEnabled: boolean;
     camEnabled: boolean;
     isScreenSharing: boolean;
+
+    remoteScreenStreamId?: string;
+    cameraStreamId?: string;
   };
 };
 ```
 
-The SDK exposes these connection and media states for meeting UI. fileciteturn9file0L367-L385
-
 ---
 
-# 8. Remote audio/video
+# Local participant
 
-Use `useRemoteMedia(participantId)`:
+Use `useLocalParticipant()` when you need the local participant and local video.
 
 ```tsx
-import { useRemoteMedia } from "@afosecure/meetingsdk";
+import { useLocalParticipant } from "@afosecure/meetingsdk";
 
-function RemoteMedia({ participantId }: { participantId: string }) {
-  const {
-    videoRef,
-    audioRef,
-    isCamActive,
-    isMicEnabled,
-  } = useRemoteMedia(participantId);
+function LocalVideo() {
+  const { participant, videoRef } = useLocalParticipant();
 
-  return (
-    <>
-      <video
-        ref={videoRef}
-        autoPlay
-        playsInline
-        muted
-      />
-
-      <audio
-        ref={audioRef}
-        autoPlay
-      />
-    </>
-  );
+  return <video ref={videoRef} autoPlay muted playsInline />;
 }
 ```
 
-The video element is muted because remote audio is attached separately through the audio element. fileciteturn9file0L161-L178
+The local participant exposes:
+
+```tsx
+participant?.media?.micEnabled;
+participant?.media?.camEnabled;
+participant?.media?.isScreenSharing;
+```
+
+Use these values to render local microphone/camera state.
 
 ---
 
-# 9. Track mapping
+# Remote media
 
-The SDK maps:
+Use `useRemoteMedia(participantId)` for a remote participant.
 
-```text
-SFU TrackInfo.track_id
-        ↓
-browser track.id ("track-" + id)
-        ↓
-normalize ID
-        ↓
-TrackInfo.participant_id
-        ↓
-Participant
-        ↓
-MediaStream
-```
+```tsx
+import { useRemoteMedia } from "@afosecure/meetingsdk";
 
-Do not rely on:
+function RemoteParticipant({ participantId }: { participantId: string }) {
+  const { videoRef, audioRef, isCamActive, isMicEnabled } =
+    useRemoteMedia(participantId);
 
-```ts
-track.participant_id
+  return (
+    <div>
+      <video ref={videoRef} autoPlay playsInline muted />
+
+      <audio ref={audioRef} autoPlay />
+
+      {!isMicEnabled && <span>Muted</span>}
+      {!isCamActive && <span>Camera off</span>}
+    </div>
+  );
+}
 ```
 
-Browsers do not provide `participant_id` as a standard `MediaStreamTrack` property. fileciteturn9file0L144-L159
+### Why are video and audio separate?
+
+The SDK attaches the remote `MediaStream` to both elements:
+
+- `<video>` is muted
+- `<audio>` handles remote audio
+
+This makes media rendering explicit and avoids accidentally routing remote audio through the video element.
 
 ---
 
-# 10. Microphone and camera
+# Microphone and camera
+
+The SDK exposes:
 
 ```tsx
-const {
-  toggleMic,
-  toggleCam,
-} = useMeeting();
+const { toggleMic, toggleCam } = useMeeting();
 ```
 
 Use:
 
 ```tsx
-<button onClick={toggleMic}>Mic</button>
-<button onClick={toggleCam}>Camera</button>
-```
+<button onClick={toggleMic}>
+  Microphone
+</button>
 
-The state flow is:
-
-```text
-toggleMic()
-   ↓
-MediaStreamTrack.enabled
-   ↓
-track_state
-   ↓
-Rust SFU
-   ↓
-track_state_changed
-   ↓
-remote UI
+<button onClick={toggleCam}>
+  Camera
+</button>
 ```
 
-The same mechanism is used for camera state. fileciteturn9file0L180-L204
+The SDK updates the local media track and sends the corresponding media state to the SFU.
 
-### Important
+Remote participants receive the authoritative track state through the meeting state.
 
-Remote mute/camera icons should be **signaling authoritative**.
+For participant UI, use:
 
-Do not infer a remote participant's state only from:
-
-```ts
-remoteTrack.muted
+```tsx
+participant.media?.micEnabled;
+participant.media?.camEnabled;
 ```
 
-or missing RTP.
-
-Use:
+rather than trying to infer another participant's mute state from RTP or `MediaStreamTrack.muted`.
 
-```ts
-participant.media?.micEnabled
-participant.media?.camEnabled
-```
+---
 
-The SFU is authoritative for these states. fileciteturn9file0L202-L204
+# Active speaker detection
 
----
+DEFCOMM Meet performs active-speaker detection **inside the SDK**.
 
-# 11. Professional participant tile
+The application does not need to use Web Audio APIs, `AnalyserNode`, audio RMS calculations, timers, or WebRTC statistics.
 
-A participant tile should combine media and connection state:
+The SDK exposes:
 
 ```tsx
-function ParticipantTile({ participant }: { participant: Participant }) {
-  const reconnecting =
-    participant.connectionState === "reconnecting";
+const { activeSpeakerIds } = useMeeting();
+```
 
-  const micEnabled =
-    participant.media?.micEnabled ?? false;
+`activeSpeakerIds` is:
 
-  const camEnabled =
-    participant.media?.camEnabled ?? false;
+```ts
+string[]
+```
 
-  const sharing =
-    participant.media?.isScreenSharing ?? false;
+containing participant IDs currently detected as speaking.
 
-  return (
-    <div className="participant-tile">
-      {reconnecting && (
-        <span className="reconnecting">
-          Reconnecting...
-        </span>
-      )}
+### Participant tile
 
-      <video autoPlay playsInline muted />
-
-      <div>{participant.name}</div>
+```tsx
+function ParticipantTile({ participant }: { participant: Participant }) {
+  const { activeSpeakerIds } = useMeeting();
 
-      <MicIcon muted={!micEnabled} />
-      <CameraIcon off={!camEnabled} />
+  const isActiveSpeaker = activeSpeakerIds.includes(participant.id);
 
-      {sharing && <ScreenShareIcon />}
+  return (
+    <div className={isActiveSpeaker ? "ring-2 ring-green-400" : ""}>
+      {participant.name}
     </div>
   );
 }
 ```
 
-Recommended mapping:
+### Better pattern
 
-```text
-connectionState
-    ↓
-reconnecting badge
+For a participant list:
 
-micEnabled
-    ↓
-microphone icon
+```tsx
+const { activeSpeakerIds } = useMeeting();
+
+{
+  participants.map((participant) => (
+    <ParticipantTile
+      key={participant.id}
+      participant={participant}
+      isActiveSpeaker={activeSpeakerIds.includes(participant.id)}
+    />
+  ));
+}
+```
 
-camEnabled
-    ↓
-camera icon
+The tile should only render the state. It should not implement speaker detection itself.
 
-isScreenSharing
-    ↓
-screen-share layout
+### Active speaker event
+
+The SDK also exposes:
+
+```tsx
+useMeeting({
+  onActiveSpeakersChanged: (participantIds) => {
+    console.log("Active speakers:", participantIds);
+  },
+});
 ```
 
-fileciteturn9file0L387-L405
+The event is useful for analytics or application-level side effects. For normal UI rendering, `activeSpeakerIds` is preferred.
 
----
+### Multiple speakers
 
-# 12. Screen sharing
+The API intentionally supports multiple active speakers:
+
+```ts
+activeSpeakerIds: string[]
+```
 
-Screen sharing is a separate publication with:
+rather than:
 
-```text
-source = "screen"
+```ts
+activeSpeakerId: string | null;
 ```
 
-It is not the participant's camera. fileciteturn9file0L206-L233
+This allows the UI to handle overlapping speech naturally.
+
+---
+
+# Screen sharing
 
 Start:
 
 ```tsx
+const { startScreenShare } = useMeeting();
+
 await startScreenShare();
 ```
 
 Stop:
 
 ```tsx
-await stopScreenShare();
+const { stopScreenShare } = useMeeting();
+
+stopScreenShare();
 ```
 
-Remote state:
+A participant's screen share is represented separately from their camera:
 
 ```ts
-participant.media.screenStream
-participant.media.screenTrack
-participant.media.isScreenSharing
+participant.media?.screenStream;
+participant.media?.screenTrack;
+participant.media?.isScreenSharing;
 ```
 
-fileciteturn9file0L235-L244
+### Recommended UI
 
-Recommended layout:
+When someone shares their screen:
 
 ```text
-┌───────────────────────────────────────────────┐
-│                                               │
-│                 SCREEN SHARE                  │
-│                                               │
-│                                               │
-└───────────────────────────────────────────────┘
+┌──────────────────────────────────────────┐
+│                                          │
+│             SCREEN SHARE                 │
+│                                          │
+│                                          │
+└──────────────────────────────────────────┘
+
+ ┌─────────┐ ┌─────────┐ ┌─────────┐
+ │ Alice   │ │ Bob     │ │ Charlie │
+ └─────────┘ └─────────┘ └─────────┘
+```
+
+Do not treat the screen track as the participant's camera track.
+
+---
 
-  ┌────────┐  ┌────────┐  ┌────────┐
-  │ Afolabi│  │  Mega  │  │  John  │
-  └────────┘  └────────┘  └────────┘
+# Recording
+
+DEFCOMM Meet recording is **server-side**.
+
+The browser does not use `MediaRecorder` to create the meeting recording.
+
+Start recording:
+
+```tsx
+const { startRecording } = useMeeting();
+
+await startRecording();
 ```
 
-The screen should be the primary stage. Participant cameras should become a secondary strip.
+Stop recording:
 
-Do not attach the screen track to the participant camera element.
+```tsx
+const { stopRecording } = useMeeting();
 
----
+await stopRecording();
+```
+
+Get current recording status:
 
-# 13. Reconnection and resume
+```tsx
+const { getRecordingStatus } = useMeeting();
 
-The SDK is designed to resume the same logical participant after a temporary network/signaling failure:
+const result = await getRecordingStatus();
 
-```text
-Network interruption
-       ↓
-WebSocket closes
-       ↓
-participant = reconnecting
-       ↓
-refresh access token
-       ↓
-JOIN + resume_token
-       ↓
-same logical participant
-       ↓
-new publisher/subscriber PCs
-       ↓
-republish local tracks
-       ↓
-resubscribe remote tracks
-       ↓
-fresh ICE/SDP
-       ↓
-connected
+console.log(result.recording);
 ```
 
-The SDK intentionally does not immediately destroy the local MediaStream when signaling temporarily disappears. It uses reconnect delays and refreshes the access token before reconnecting. fileciteturn9file0L246-L275
+A recording has:
 
-### UI rule
+```ts
+type RecordingInfo = {
+  recording_id: string;
+  started_at?: string;
+  stopped_at?: string;
+  active?: boolean;
+};
+```
+
+## Recording events
 
-During a transient outage:
+The SDK exposes:
+
+```tsx
+useMeeting({
+  onRecordingStarted: (recording) => {
+    console.log("Recording started", recording);
+  },
+
+  onRecordingStopped: (recording) => {
+    console.log("Recording stopped", recording);
+  },
+});
+```
+
+### Recommended DEFCOMM Meet UI
+
+The meeting application can place the recording control in the meeting navbar:
 
 ```text
-Reconnecting...
+┌───────────────────────────────────────────────────────────────┐
+│ Engineering     🔴 REC                         Chat  People   │
+└───────────────────────────────────────────────────────────────┘
 ```
 
-should be shown rather than immediately removing the participant.
+Host before recording:
 
-Only treat the participant as gone after the SFU reports an actual departure/disconnection.
+```text
+┌───────────────────────────────────────────────────────────────┐
+│ Engineering       [ Start Recording ]          Chat  People   │
+└───────────────────────────────────────────────────────────────┘
+```
 
----
+Host while recording:
 
-# 14. Leave correctly
+```text
+┌───────────────────────────────────────────────────────────────┐
+│ Engineering       🔴 Recording  [ Stop ]       Chat  People   │
+└───────────────────────────────────────────────────────────────┘
+```
 
-Intentional departure:
+Other participants should see the recording status but should not automatically receive the host's recording controls.
 
-```tsx
-await leave();
+### Important recording rule
+
+Do not assume that clicking the button means recording has started.
+
+The UI should use:
+
+```ts
+onRecordingStarted;
 ```
 
-Do not manually close:
+as the authoritative start event and:
 
 ```ts
-websocket.close();
+onRecordingStopped;
 ```
 
-to implement the Leave button.
+as the authoritative stop event.
 
-The intended lifecycle is:
+Recommended state:
 
-```text
-Leave button
-    ↓
-leave
-    ↓
-SFU acknowledgement
-    ↓
-destroy PeerConnections
-    ↓
-clear room resume token
-    ↓
-remove local meeting state
+```tsx
+const [isRecording, setIsRecording] = useState(false);
+
+useMeeting({
+  onRecordingStarted: () => {
+    setIsRecording(true);
+  },
+
+  onRecordingStopped: () => {
+    setIsRecording(false);
+  },
+});
 ```
 
-A temporary network failure is different and should use reconnect/resume.
+This prevents the UI from claiming that a recording is active when the SFU has not confirmed it.
 
 ---
 
-# 15. Private-room admission
+# Private rooms and join approval
 
-For private rooms:
+Private rooms can require host approval.
+
+A host can listen for entry requests:
 
 ```tsx
-const {
-  approveJoinRequest,
-  rejectJoinRequest,
-} = useMeeting();
+useMeeting({
+  onEntryRequested: (request) => {
+    console.log("Join request:", request);
+  },
+});
 ```
 
 Approve:
 
 ```tsx
-await approveJoinRequest(participantId);
+const { approveJoinRequest } = useMeeting();
+
+approveJoinRequest(requestId);
 ```
 
 Reject:
 
 ```tsx
-await rejectJoinRequest(participantId);
+const { rejectJoinRequest } = useMeeting();
+
+rejectJoinRequest(requestId);
 ```
 
-The SFU remains authoritative. The SDK does not fabricate approval state locally. fileciteturn9file0L278-L289
+The SDK exposes the approval flow, while the SFU remains authoritative for whether a participant is admitted.
 
 ---
 
-# 16. Server-side recording
+# Reconnection and participant presence
 
-Recording is **server-side**. The browser does not use `MediaRecorder`. fileciteturn9file0L291-L340
+The SDK distinguishes a temporary connection problem from an intentional leave.
 
-Start:
+A participant can be:
 
-```tsx
-await startRecording();
+```ts
+"connected";
+"reconnecting";
+"disconnected";
 ```
 
-Stop:
+Recommended UI:
 
 ```tsx
-await stopRecording();
+if (participant.connectionState === "reconnecting") {
+  return <ReconnectingBadge />;
+}
 ```
 
-Status:
+A temporary network interruption should not immediately remove a participant from the UI.
 
-```tsx
-const { recording } = await getRecordingStatus();
+The SDK attempts to reconnect and resume the same logical participant session.
+
+Conceptually:
+
+```text
+Network interruption
+        ↓
+WebSocket disconnect
+        ↓
+reconnecting
+        ↓
+refresh/reconnect
+        ↓
+resume
+        ↓
+publisher/subscriber recreated
+        ↓
+media subscriptions restored
+        ↓
+connected
 ```
 
-Lifecycle:
+This is why applications should render `reconnecting` as a state rather than treating every WebSocket close as a participant leaving.
+
+---
+
+# Stable participant identity
+
+The SDK stores a stable browser participant ID using:
 
 ```text
-startRecording()
-      ↓
-start_recording
-      ↓
-Rust SFU RecordingManager
-      ↓
-recording_started
+defcomm:participant_id
 ```
 
-Stop:
+This prevents a browser reload or temporary reconnect from unnecessarily generating a completely new participant identity.
+
+Room resume state uses:
 
 ```text
-stopRecording()
-      ↓
-stop_recording
-      ↓
-RecordingManager finalizes
-      ↓
-recording_stopped
+defcomm:sfu:resume:<roomCode>
 ```
 
-The recording belongs to the meeting/server rather than a particular browser. Recording permissions are enforced by the SFU. fileciteturn9file0L291-L340
+The SDK treats temporary network loss differently from an intentional `leave()`.
+
+Applications should use:
+
+```tsx
+await leave();
+```
+
+for an intentional departure instead of manually closing the WebSocket.
 
 ---
 
-# 17. Room management
+# Leaving a meeting
 
-Create:
+Use:
 
 ```tsx
-const room = await createRoom({
-  name: "Engineering",
+const { leave } = useMeeting();
+
+await leave();
+```
+
+Do not implement the Leave button by doing:
+
+```ts
+websocket.close();
+```
+
+or by directly destroying the SDK's PeerConnections.
+
+The SDK owns cleanup and the SFU leave lifecycle.
+
+---
+
+# Room management
+
+Room management is available through `useMeeting()`:
+
+```tsx
+const { createRoom, getRoom, deleteRoom } = useMeeting();
+```
+
+### Create
+
+```tsx
+await createRoom({
+  name: "Product Review",
+  description: "Weekly product review",
   capacity: 100,
-  is_private: true,
+  is_private: false,
 });
 ```
 
-Get:
+### Get
 
 ```tsx
-const room = await getRoom(roomCode);
+await getRoom(roomCode);
 ```
 
-Delete:
+### Delete
 
 ```tsx
 await deleteRoom(roomCode);
 ```
 
-These use the REST API. fileciteturn9file0L342-L355
+---
+
+# Meeting preview
+
+The SDK exports:
+
+```tsx
+import { useMeetingPreview } from "@afosecure/meetingsdk";
+```
+
+Use preview when the application needs a pre-join screen for room information or local setup.
+
+The actual live meeting begins when `join()` connects the SDK to the SFU.
 
 ---
 
-# 18. Preview
+# Chat
 
-The old mesh SDK used:
+The SDK exposes the current chat interface through:
 
-```text
-/watch/:room
+```tsx
+const { sendMessage } = useMeeting();
 ```
 
-That endpoint is not part of the current Rust SFU.
+Send:
 
-`useMeetingPreview()` therefore uses the current REST room endpoint and does not fabricate live participant/media state. Live participant/media state begins after joining through `/ws`. fileciteturn9file0L358-L365
+```tsx
+sendMessage({
+  message: "Hello everyone",
+});
+```
+
+The input type is:
+
+```ts
+type ChatInput = {
+  message: string;
+  reply_to?: {
+    id: string;
+    name: string;
+  } | null;
+  target?: string | null;
+};
+```
+
+The SDK also exposes:
+
+```tsx
+usePubSub("SECURE_CHAT");
+```
+
+when an application wants the Pub/Sub style interface.
+
+Example:
+
+```tsx
+const chat = usePubSub("SECURE_CHAT");
+
+chat.publish({
+  message: "Hello",
+});
+```
 
 ---
 
-# 19. Current signaling protocol
+# Error handling
 
-### Client → SFU
+Use the SDK error event:
 
-```text
-join
-leave
-publish_offer
-subscribe
-unsubscribe
-subscribe_answer
-ice_candidate
-track_state
-start_screen_share
-stop_screen_share
-start_recording
-stop_recording
-approve_join
-reject_join
-ping
-```
-
-### SFU → Client
+```tsx
+useMeeting({
+  onError: (error) => {
+    console.error(error);
+  },
+});
+```
+
+Errors contain:
+
+```ts
+type SDKError = {
+  code: string;
+  message: string;
+  roomId?: string | null;
+  userId?: string;
+  raw?: any;
+  recoverable?: boolean;
+};
+```
+
+A useful UI rule is:
 
 ```text
-joined
-join_pending
-join_requested
-join_approved
-join_rejected
-publish_answer
-subscribe_offer
-ice_candidate
-track_published
-track_unpublished
-track_state_changed
-participant_joined
-participant_left
-participant_presence
-screen_share_started
-screen_share_stopped
-subscription_updated
-recording_started
-recording_stopped
-pong
-left
-error
-```
-
-fileciteturn9file0L22-L64
-
----
-
-# 20. Recommended React structure
+recoverable = true
+    ↓
+show retry/reconnecting UI
+
+recoverable = false
+    ↓
+show a blocking error or return to the appropriate screen
+```
+
+Always wrap user-triggered asynchronous operations when appropriate:
+
+```tsx
+async function handleJoin() {
+  try {
+    await join();
+  } catch (error) {
+    console.error("Unable to join meeting", error);
+  }
+}
+```
+
+---
+
+# Recommended DEFCOMM Meet structure
+
+A production DEFCOMM Meet page can be structured like this:
 
 ```text
 MeetingPage
 │
 └── MeetingProvider
     │
-    ├── MeetingHeader
-    │   ├── Room name
-    │   ├── Connection state
-    │   └── Recording indicator
+    ├── MeetingNav
+    │   ├── Meeting name
+    │   ├── Recording state/control
+    │   ├── Chat
+    │   └── Participants
     │
     ├── MeetingStage
+    │   │
     │   ├── ScreenShareStage
-    │   └── ActiveSpeakerStage
-    │
-    ├── ParticipantStrip
-    │   └── ParticipantTile[]
-    │       ├── Video
-    │       ├── Name
-    │       ├── Mic icon
-    │       ├── Camera icon
-    │       └── Reconnecting badge
+    │   │
+    │   └── ParticipantGrid
+    │       └── ParticipantTile[]
+    │           ├── Video
+    │           ├── Name
+    │           ├── Mic state
+    │           ├── Camera state
+    │           ├── Active speaker state
+    │           └── Reconnecting state
     │
     └── MeetingControls
-        ├── Mic
+        ├── Microphone
         ├── Camera
         ├── Screen share
-        ├── Record
         └── Leave
 ```
 
-The SDK supplies media and meeting state. Your application owns the visual design.
+The application should consume SDK state rather than recreating WebRTC state locally.
 
 ---
 
-# 21. Error handling
+# Recommended participant tile
 
-Catch operations that can fail:
+A participant tile should combine the SDK's states:
 
 ```tsx
-try {
-  await join();
-} catch (error) {
-  console.error("Unable to join meeting", error);
+function ParticipantTile({ participant }: { participant: Participant }) {
+  const { activeSpeakerIds } = useMeeting();
+
+  const isSpeaking = activeSpeakerIds.includes(participant.id);
+
+  const isReconnecting = participant.connectionState === "reconnecting";
+
+  const micEnabled = participant.media?.micEnabled ?? false;
+
+  const camEnabled = participant.media?.camEnabled ?? false;
+
+  const isScreenSharing = participant.media?.isScreenSharing ?? false;
+
+  return (
+    <div
+      className={
+        isSpeaking ? "participant-tile active-speaker" : "participant-tile"
+      }
+    >
+      {isReconnecting && <div className="reconnecting">Reconnecting...</div>}
+
+      {/* Remote/local media */}
+
+      <div className="participant-name">{participant.name}</div>
+
+      <div className="participant-status">
+        {!micEnabled && <span>Muted</span>}
+        {!camEnabled && <span>Camera off</span>}
+        {isScreenSharing && <span>Sharing</span>}
+      </div>
+    </div>
+  );
 }
 ```
 
-Your UI should distinguish:
+The important design principle is:
 
 ```text
-Connecting
-Reconnecting
-Connected
-Disconnected
-Join rejected
+SDK state → UI
 ```
 
-Do not show "left the meeting" for a temporary ICE/WebSocket interruption.
+not:
+
+```text
+UI → WebRTC internals
+```
 
 ---
 
-# 22. Do not reintroduce mesh logic
+# Public exports
+
+The SDK currently exports:
+
+```ts
+// Core
+VideoSDKCore;
+SFUClient;
+MeetingState;
+ActiveSpeakerDetector;
+
+// React
+MeetingProvider;
+useMeetingContext;
+useMeeting;
+useParticipants;
+useLocalParticipant;
+useRemoteMedia;
+useMeetingPreview;
+
+// Types
+Participant;
+ChatInput;
+RecordingInfo;
+MeetingConfig;
+SFUConnectionState;
+TrackInfo;
+ParticipantInfo;
+```
+
+Most DEFCOMM Meet application developers should only need the React API:
+
+```tsx
+import {
+  MeetingProvider,
+  useMeeting,
+  useParticipants,
+  useLocalParticipant,
+  useRemoteMedia,
+  useMeetingPreview,
+} from "@afosecure/meetingsdk";
+```
+
+Direct use of `VideoSDKCore` or `SFUClient` is intended for advanced integrations.
 
-Never create a PeerConnection per remote participant.
+---
 
-Wrong:
+# Important implementation rules
+
+## 1. Do not build a mesh
+
+Do not create:
 
 ```text
-A ↔ B
-A ↔ C
-B ↔ C
+Participant A ↔ Participant B
+Participant A ↔ Participant C
+Participant B ↔ Participant C
 ```
 
-Correct:
+The SDK is designed for:
 
 ```text
-A ──┐
-B ──┼──► SFU ──► participants
-C ──┘
-```
-
-The SFU owns:
-
-- participant identity
-- room membership
-- admission
-- SDP negotiation
-- ICE
-- track publication
-- subscription
-- RTP forwarding
-- RTCP feedback
-- mute state
-- screen-share state
-- server-side recording
+Participants
+     │
+     ▼
+ DEFCOMM SFU
+     │
+     ▼
+Participants
+```
+
+---
+
+## 2. Do not manipulate the SDK's PeerConnections
+
+Applications should not directly access:
+
+```ts
+RTCPeerConnection;
+RTCSessionDescription;
+RTCIceCandidate;
+RTCRtpSender;
+```
+
+for normal meeting functionality.
+
+The SDK owns those objects.
+
+---
+
+## 3. Do not infer remote mute state from media silence
+
+Use:
+
+```ts
+participant.media?.micEnabled;
+participant.media?.camEnabled;
+```
+
+The SFU signaling state is authoritative.
+
+---
+
+## 4. Do not implement speaker detection in the application
+
+Use:
+
+```tsx
+const { activeSpeakerIds } = useMeeting();
+```
+
+The SDK owns audio analysis and active-speaker state.
 
-The browser SDK owns:
+---
+
+## 5. Do not use browser recording for meeting recording
+
+Use:
+
+```tsx
+await startRecording();
+await stopRecording();
+```
+
+Meeting recording is server-side.
+
+---
+
+## 6. Do not manually close the WebSocket to leave
+
+Use:
+
+```tsx
+await leave();
+```
+
+This allows the SDK to perform the intended cleanup and leave lifecycle.
+
+---
+
+## 7. Do not immediately remove reconnecting participants
+
+Use:
+
+```ts
+participant.connectionState;
+```
 
-- browser media permissions
-- publisher/subscriber PeerConnections
-- signaling transport
-- media attachment
-- local UI state
-- reconnect/resume orchestration
-- React bindings
+and show:
+
+```text
+Reconnecting...
+```
 
-fileciteturn9file0L423-L450
+during transient failures.
 
 ---
 
-# 23. Build
+## 8. Keep screen share separate from camera
+
+Use:
+
+```ts
+participant.media.screenStream;
+participant.media.screenTrack;
+participant.media.isScreenSharing;
+```
+
+instead of replacing the camera stream.
+
+---
+
+# Build and publish
+
+Install dependencies:
 
 ```bash
 npm install
+```
+
+Build:
+
+```bash
 npm run build
 ```
 
-Expected output:
+Before publishing a new SDK version, verify:
 
 ```text
-dist/
-├── index.js
-├── index.mjs
-├── index.d.ts
-└── index.d.mts
+✓ TypeScript build succeeds
+✓ React integration works
+✓ Join/leave works
+✓ Camera works
+✓ Microphone works
+✓ Remote audio/video works
+✓ Screen sharing works
+✓ Active speaker detection works
+✓ Reconnection works
+✓ Private-room admission works
+✓ Recording start/stop works
+✓ Recording callbacks fire
+✓ Production WSS/API configuration works
 ```
 
-The SDK consumes the SFU media path:
+---
 
-```text
-Publisher
-  ↓
-SFU Publisher PC
-  ↓
-PublishedTrackRegistry
-  ↓
-MediaRouter
-  ↓
-TrackLocalStaticRTP
-  ↓
-Subscriber PC
-  ↓
-Browser ontrack
-  ↓
-SDK TrackInfo mapping
-  ↓
-Participant MediaStream
-```
-
-fileciteturn9file0L452-L474
-
----
-
-# 24. Production checklist
-
-Before shipping:
-
-- [ ] Configure `apiBase` and `wsBase`.
-- [ ] Use HTTPS/WSS in production.
-- [ ] Render hooks inside `MeetingProvider`.
-- [ ] Call `join()` from a user action.
-- [ ] Handle camera/microphone permissions.
-- [ ] Render remote video and audio separately.
-- [ ] Keep video elements muted when remote audio is attached separately.
-- [ ] Use SFU signaling for remote mic/camera icons.
-- [ ] Render screen sharing separately from camera.
-- [ ] Show `Reconnecting...` during transient network loss.
-- [ ] Do not remove a participant immediately on temporary connection loss.
-- [ ] Use `leave()` for intentional departure.
-- [ ] Do not create mesh PeerConnections.
-- [ ] Restrict recording controls to authorized users.
-- [ ] Treat recording as server-side.
-- [ ] Test reload, reconnect, leave, and rejoin.
-- [ ] Run `npm run build` before publishing.
-- [ ] Keep the SDK and SFU signaling protocol versions compatible.
-
----
-
-# 25. Developer mental model
-
-The simplest mental model is:
+# DEFCOMM Meet integration principle
+
+The purpose of this SDK is to make the DEFCOMM meeting experience feel like a single integrated platform.
+
+A consumer should be able to think in terms of:
+
+```tsx
+const {
+  join,
+  leave,
+  toggleMic,
+  toggleCam,
+  startScreenShare,
+  stopScreenShare,
+  startRecording,
+  stopRecording,
+  participants,
+  activeSpeakerIds,
+} = useMeeting();
+```
+
+rather than:
 
 ```text
-YOUR APPLICATION
-      │
-      │ UI + meeting controls
-      ▼
-@afosecure/meetingsdk
-      │
-      ├── React hooks
-      ├── WebSocket signaling
-      ├── Publisher PC
-      ├── Subscriber PC
-      ├── Media attachment
-      └── Reconnect/resume
-      │
-      ▼
-DEFCOMM RUST SFU
-      │
-      ├── Rooms
-      ├── Participants
-      ├── Admission
-      ├── SDP / ICE
-      ├── Track registry
-      ├── MediaRouter
-      ├── RTCP feedback
-      ├── Screen-share state
-      └── Recording
-```
-
-**Key rule:** the application owns presentation, the SDK owns browser WebRTC, and the SFU owns authoritative meeting/media state.
+WebSocket messages
+SDP offers/answers
+ICE candidates
+PeerConnections
+RTP tracks
+SSRCs
+audio analysers
+reconnect timers
+resume tokens
+```
+
+Those implementation details belong inside the SDK/SFU layer.
+
+**DEFCOMM Meet owns the meeting experience.  
+The SDK owns the browser media experience.  
+The SFU owns the authoritative meeting/media infrastructure.**