@tribe-nest/media-client 0.1.0

package/src/react/index.tsx

@@ -0,0 +1,439 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+  type ReactNode,
+} from "react";
+
+import type { MediaGrants, Peer } from "@tribe-nest/media-protocol";
+
+import { createBrowserDevice } from "../room/browserDevice";
+import {
+  MediaRoom,
+  type ConnectionState,
+  type LocalPublication,
+  type MediaRoomOptions,
+  type MediaTrack,
+} from "../room/room";
+import { visibleProducers } from "../core";
+import type { DisconnectCause, ProducerEntry, RoomState } from "../core";
+
+/**
+ * The React surface.
+ *
+ * ## Why `useSyncExternalStore` rather than state in the provider
+ *
+ * The room is an external mutable object with its own event loop, which is
+ * precisely the case React 18 added that hook for. The alternative - mirroring
+ * room state into `useState` on every event - tears: a component reading
+ * `room.tracks` directly during a render sees a newer value than the mirrored
+ * copy it was rendered from, and the bug shows up as a tile that is one event
+ * behind exactly when the room is busiest.
+ *
+ * ## Why every hook takes NO arguments
+ *
+ * `useMediaRoom()` reads the provider. A hook that took credentials would let
+ * two components mount two rooms against one call, and the second would take
+ * the identity from the first and be refused with `duplicate_identity`. One
+ * room per provider, and the provider owns its lifetime.
+ */
+
+type MediaRoomContextValue = {
+  room: MediaRoom | null;
+  connectionState: ConnectionState;
+  error: DisconnectCause | undefined;
+  /**
+   * Is the SDK actually coming back on its own?
+   *
+   * `connectionState` is `reconnecting` both while an attempt is booked and
+   * after the policy has given up, so a screen reading only that spins for ever
+   * over a call that is finished. This is the half that says which, and it is
+   * what a UI turns "wait" against "press something" on.
+   */
+  recovering: boolean;
+  retry: () => void;
+};
+
+const MediaRoomContext = createContext<MediaRoomContextValue | null>(null);
+
+export type MediaRoomProviderProps = Omit<MediaRoomOptions, "device"> &
+  Partial<Pick<MediaRoomOptions, "device">> & {
+    children: ReactNode;
+    /** Rendered while the first connection is in flight. */
+    fallback?: ReactNode;
+  };
+
+export function MediaRoomProvider({ children, fallback, device, ...options }: MediaRoomProviderProps): ReactNode {
+  const [room, setRoom] = useState<MediaRoom | null>(null);
+  const [connectionState, setConnectionState] = useState<ConnectionState>("idle");
+  const [error, setError] = useState<DisconnectCause | undefined>(undefined);
+  const [recovering, setRecovering] = useState(false);
+  const [attempt, setAttempt] = useState(0);
+
+  // Held in a ref so changing a callback identity does not tear down a live
+  // call. A parent that re-renders every second must not reconnect the room
+  // every second, and inline arrow props make that the DEFAULT mistake.
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  useEffect(() => {
+    let cancelled = false;
+    const instance = new MediaRoom({
+      ...optionsRef.current,
+      getCredentials: () => optionsRef.current.getCredentials(),
+      device: device ?? createBrowserDevice,
+    });
+
+    const unsubscribe = instance.onChange(() => {
+      if (cancelled) return;
+      setConnectionState(instance.connectionState);
+      setError(instance.error);
+      setRecovering(instance.isRecovering);
+    });
+
+    setRoom(instance);
+    instance.connect().catch(() => {
+      // The cause is on the room; `error` is already mirrored by the listener
+      // above. Swallowed here so a failed connect does not surface as an
+      // unhandled rejection in the host application's console.
+      if (!cancelled) setConnectionState(instance.connectionState);
+    });
+
+    return () => {
+      cancelled = true;
+      unsubscribe();
+      void instance.close().catch(() => undefined);
+    };
+    // `attempt` is what `retry()` bumps. `device` is read once per room.
+  }, [attempt, device]);
+
+  const value = useMemo<MediaRoomContextValue>(
+    () => ({ room, connectionState, error, recovering, retry: () => setAttempt((n) => n + 1) }),
+    [room, connectionState, error, recovering],
+  );
+
+  return (
+    <MediaRoomContext.Provider value={value}>
+      {connectionState === "connecting" && fallback ? fallback : children}
+    </MediaRoomContext.Provider>
+  );
+}
+
+function useRoomContext(): MediaRoomContextValue {
+  const value = useContext(MediaRoomContext);
+  if (!value) throw new Error("useMediaRoom must be used inside a <MediaRoomProvider>");
+  return value;
+}
+
+export function useMediaRoom(): MediaRoomContextValue {
+  return useRoomContext();
+}
+
+/** Subscribe to the room's own change notifications. */
+function useRoomSnapshot<T>(select: (room: MediaRoom) => T, fallback: T): T {
+  // `select` and `fallback` must be stable across renders - see the note on the
+  // module-level selectors below.
+  const { room } = useRoomContext();
+
+  const subscribe = useCallback(
+    (onChange: () => void) => (room ? room.onChange(onChange) : () => undefined),
+    [room],
+  );
+
+  // The selector must return a STABLE reference for unchanged state, or
+  // `useSyncExternalStore` re-renders forever. `RoomState` is produced by a
+  // reducer that returns the same object when nothing changed, which is what
+  // makes reading it directly safe.
+  const getSnapshot = useCallback(() => (room ? select(room) : fallback), [room, select, fallback]);
+
+  return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+/**
+ * Module-level selectors, and that is not a style preference.
+ *
+ * `useRoomSnapshot` memoises `getSnapshot` on the selector's identity. An
+ * inline arrow is a new function every render, so the memo never holds, and
+ * `useSyncExternalStore` re-subscribes and re-reads on every pass.
+ */
+const selectState = (room: MediaRoom): RoomState => room.state;
+const selectTracks = (room: MediaRoom): readonly MediaTrack[] => room.tracks;
+const selectPublications = (room: MediaRoom): MediaRoom["localPublications"] => room.localPublications;
+
+export function useRoomState(): RoomState {
+  return useRoomSnapshot(selectState, EMPTY_STATE);
+}
+
+export function useParticipants(): readonly Peer[] {
+  return useRoomState().peers;
+}
+
+export function useActiveSpeakers(): readonly string[] {
+  return useRoomState().activeSpeakers;
+}
+
+/**
+ * The producers this participant may actually receive. What a UI renders.
+ *
+ * NOT `useRoomState().producers`, and the difference is the subscribe barrier.
+ * The reducer keeps every producer the node has ever announced, deliberately,
+ * so that a rule which narrows mid-call and later widens is reversible - there
+ * is no `producerAppeared` replay to bring back a producer it had deleted. The
+ * price of keeping them is that the raw list contains people this seat has been
+ * barred from, and on a sealed consultation room the mere PRESENCE of the other
+ * party is most of what the barrier was hiding. A UI mapping over the raw list
+ * therefore draws a tile carrying their identity and mounts an `<audio>` for
+ * them, and the node's own filtering does not save it: `revokeNewlyForbidden`
+ * only closes producers this session had a live consumer for, so one that was
+ * announced and never consumed stays in the list for the rest of the call.
+ *
+ * Memoised on the state OBJECT rather than used as a store selector: the filter
+ * builds a new array per call, and `useSyncExternalStore` compares snapshots
+ * with `Object.is`, so reading it through `useRoomSnapshot` would re-render for
+ * ever. The reducer returns the same state object when nothing changed, which
+ * is what makes this settle.
+ */
+export function useVisibleProducers(): readonly ProducerEntry[] {
+  const state = useRoomState();
+  return useMemo(() => visibleProducers(state), [state]);
+}
+
+/**
+ * What THIS participant is publishing right now, with the live tracks.
+ *
+ * `useLocalMedia()` answers "is the camera on" and that is enough for a button,
+ * but a local preview needs the `MediaStreamTrack` itself, and reading
+ * `room.localPublications` from `useMediaRoom()` is not reactive: the preview
+ * would stay black until something else happened to re-render it.
+ *
+ * The snapshot is the room's cached array, rebuilt only when a publication
+ * changed, which is what keeps this out of the `getSnapshot` loop.
+ */
+export function useLocalPublications(): readonly LocalPublication[] {
+  return useRoomSnapshot(selectPublications, EMPTY_PUBLICATIONS);
+}
+
+/** What the NODE says this token may do. For rendering, never for a decision:
+ * the node enforces independently and is the only side that counts. */
+export function useGrants(): MediaGrants | undefined {
+  const { room } = useRoomContext();
+  return room?.grants;
+}
+
+/** True while any egress participant is present. A consent signal. */
+export function useRecording(): boolean {
+  return useRoomState().recording;
+}
+
+/**
+ * One remote track, and a ref callback that attaches it.
+ *
+ * `attach` exists because `srcObject` cannot be set through JSX: it takes a
+ * `MediaStream` object, not a string, so every consumer of this hook would
+ * otherwise write the same `useEffect`.
+ *
+ * ## Why it is keyed on the TRACK
+ *
+ * A ref callback runs when the element mounts and again only when the callback
+ * IDENTITY changes. The track almost never exists at mount: a producer reaches
+ * `state.producers` the moment the node announces it, and the consume round
+ * trip that produces the track finishes some milliseconds later. So a callback
+ * memoised on `[room, producerId]` - both stable - ran exactly once, against no
+ * track, set `srcObject` to `null` and was never called again. An element that
+ * is only ever mounted once therefore stayed silent for the whole call, which
+ * is what happened to remote AUDIO: a `<video>` escapes it because a tile
+ * renders one only after the track arrives, and every remote `<video>` is
+ * `muted`, so a call had picture and no sound in either direction.
+ *
+ * Depending on `track` is what makes React re-run it: the identity changes when
+ * the track appears, React calls the old callback with `null` and the new one
+ * with the element. `MediaTrack` objects are created once per consumer and the
+ * room's snapshot array is rebuilt only when a track changes, so this settles
+ * rather than churning.
+ */
+export function useRemoteTrack(producerId: string): {
+  track: MediaTrack | undefined;
+  attach: (element: HTMLMediaElement | null) => void;
+} {
+  const tracks = useRoomSnapshot(selectTracks, EMPTY_TRACKS);
+  const track = tracks.find((t) => t.producerId === producerId);
+
+  const attach = useCallback(
+    (element: HTMLMediaElement | null) => {
+      if (!element) return;
+      element.srcObject = track ? new MediaStream([track.track]) : null;
+    },
+    [track],
+  );
+
+  return { track, attach };
+}
+
+export type LocalSource = "camera" | "microphone" | "screen";
+
+export type LocalMediaControls = {
+  publishCamera: () => Promise<void>;
+  publishMicrophone: () => Promise<void>;
+  publishScreen: () => Promise<void>;
+  unpublish: (source: LocalSource) => Promise<void>;
+  isCameraEnabled: boolean;
+  isMicrophoneEnabled: boolean;
+  screenSharing: boolean;
+  /**
+   * A capture or a publish is in flight for this source.
+   *
+   * Exposed so a control can be disabled rather than silently ignoring the
+   * second press: a permission prompt takes seconds, during which every flag
+   * above still reads `false`, and a button that looks unchanged is a button
+   * people press again.
+   */
+  pending: Record<LocalSource, boolean>;
+  error: Error | undefined;
+};
+
+const NOTHING_PENDING: Record<LocalSource, boolean> = { camera: false, microphone: false, screen: false };
+
+/**
+ * Capture and publish.
+ *
+ * `getUserMedia` lives here rather than in the room because permission is a
+ * BROWSER concern with a UI consequence - a denied prompt is something a person
+ * has to be told about - and the room has no way to say so.
+ */
+export function useLocalMedia(): LocalMediaControls {
+  const { room } = useRoomContext();
+  const [error, setError] = useState<Error | undefined>(undefined);
+  const [pending, setPending] = useState<Record<LocalSource, boolean>>(NOTHING_PENDING);
+  const publications = useRoomSnapshot(selectPublications, EMPTY_PUBLICATIONS);
+
+  const has = (source: string) => publications.some((p) => p.source === source);
+
+  /**
+   * One operation per source at a time, held in a REF.
+   *
+   * Every control above this is a read-then-write: it reads
+   * `isMicrophoneEnabled` and calls publish or unpublish accordingly. That flag
+   * is derived from `publications`, which does not move until the publish has
+   * resolved - and a publish begins with a `getUserMedia` permission prompt
+   * that can sit on screen for seconds. So the ordinary human response to a
+   * button that appears to have done nothing (press it again) put two captures
+   * through two `room.publish` calls and produced TWO audio producers from one
+   * identity: everyone else mounts two `<audio>` elements and hears the person
+   * doubled, and unpublishing both later does not undo the seconds of garbled
+   * audio. The screen-share shape is worse, opening a second picker.
+   *
+   * A ref rather than the `pending` state because the check has to be true
+   * SYNCHRONOUSLY: two clicks in one tick are both handled before React has
+   * re-rendered anything, so a state flag would be `false` in both of them.
+   * `pending` exists to grey the button out, not to guard it.
+   */
+  const inFlight = useRef<Set<LocalSource>>(new Set());
+
+  const exclusively = useCallback(async (source: LocalSource, work: () => Promise<void>): Promise<void> => {
+    if (inFlight.current.has(source)) return;
+    inFlight.current.add(source);
+    setPending((current) => ({ ...current, [source]: true }));
+    try {
+      await work();
+    } finally {
+      inFlight.current.delete(source);
+      setPending((current) => ({ ...current, [source]: false }));
+    }
+  }, []);
+
+  /**
+   * Captured tracks are OWNED here until the room takes one.
+   *
+   * `getUserMedia` turns the camera light on. If the publish that follows
+   * fails - the node refusing the grant, the transport failing, the browser
+   * unable to produce the kind - the capture is still live, and nothing in the
+   * UI can stop it: no publication was recorded, so the button still reads
+   * "Start camera" and `unpublish("camera")` finds nothing to close. The light
+   * stays on until the provider unmounts, and every retry opens another one.
+   *
+   * So everything captured is stopped unless it was handed over, including the
+   * extra tracks a capture can carry (Chrome adds a system-audio track to a
+   * screen share when the person ticks "share audio", and only one track is
+   * published).
+   */
+  const publish = useCallback(
+    async (source: LocalSource) =>
+      exclusively(source, async () => {
+        if (!room) return;
+        setError(undefined);
+        let captured: MediaStreamTrack[] = [];
+        let published: MediaStreamTrack | undefined;
+        try {
+          const stream =
+            source === "screen"
+              ? await navigator.mediaDevices.getDisplayMedia({ video: true })
+              : await navigator.mediaDevices.getUserMedia(
+                  source === "camera" ? { video: true } : { audio: true },
+                );
+          captured = stream.getTracks();
+          const track = captured[0];
+          if (!track) throw new Error(`no ${source} track was captured`);
+          await room.publish(track, source);
+          published = track;
+        } catch (err) {
+          // Surfaced rather than thrown: a denied permission prompt is an
+          // ordinary outcome that the UI has to explain, not an exception.
+          setError(err instanceof Error ? err : new Error(String(err)));
+        } finally {
+          for (const track of captured) {
+            if (track !== published) track.stop();
+          }
+        }
+      }),
+    [room, exclusively],
+  );
+
+  // Under the same lock as `publish`, because the pair is what a toggle
+  // alternates between: a stop pressed while a start is still capturing would
+  // otherwise find no publication to close and leave the capture that lands a
+  // moment later running with the button reading "Mute".
+  const unpublish = useCallback(
+    async (source: LocalSource) =>
+      exclusively(source, async () => {
+        if (!room) return;
+        for (const publication of room.localPublications.filter((p) => p.source === source)) {
+          await room.unpublish(publication.producerId);
+        }
+      }),
+    [room, exclusively],
+  );
+
+  return {
+    publishCamera: useCallback(() => publish("camera"), [publish]),
+    publishMicrophone: useCallback(() => publish("microphone"), [publish]),
+    publishScreen: useCallback(() => publish("screen"), [publish]),
+    unpublish,
+    isCameraEnabled: has("camera"),
+    isMicrophoneEnabled: has("microphone"),
+    screenSharing: has("screen"),
+    pending,
+    error,
+  };
+}
+
+/** Stable empty values, so an unmounted or pre-connect room does not hand
+ * `useSyncExternalStore` a new array on every read and loop it. */
+const EMPTY_TRACKS: readonly MediaTrack[] = [];
+const EMPTY_PUBLICATIONS: MediaRoom["localPublications"] = [];
+const EMPTY_STATE: RoomState = {
+  phase: "idle",
+  identity: null,
+  room: null,
+  peers: [],
+  producers: [],
+  activeSpeakers: [],
+  recording: false,
+  subscribeRule: null,
+  draining: null,
+  closedReason: null,
+};