@tribe-nest/media-client 0.1.0 → 0.2.1

package/src/react/index.tsx

@@ -17,6 +17,7 @@ import {
   MediaRoom,
   type ConnectionState,
   type LocalPublication,
+  type LocalPublicationSource,
   type MediaRoomOptions,
   type MediaTrack,
 } from "../room/room";
@@ -140,10 +141,7 @@ function useRoomSnapshot<T>(select: (room: MediaRoom) => T, fallback: T): T {
   // module-level selectors below.
   const { room } = useRoomContext();
 
-  const subscribe = useCallback(
-    (onChange: () => void) => (room ? room.onChange(onChange) : () => undefined),
-    [room],
-  );
+  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
@@ -250,11 +248,21 @@ export function useRecording(): boolean {
  * 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.
+ * ## Why the callback is STABLE, and an effect does the re-attaching
+ *
+ * The callback used to be memoised on `[track]`, so a new track identity made
+ * React run the OLD callback with `null` (which pauses the element and clears
+ * `srcObject`) and then the new one with the element. That is a black frame and
+ * a stall on the viewer's screen, and it fires for reasons that have nothing to
+ * do with the picture: the room's snapshot is rebuilt on every change, and a
+ * consumer that is closed and re-created (`syncSubscriptions` following the
+ * active set) produces a fresh `MediaTrack` for the SAME underlying
+ * `MediaStreamTrack`.
+ *
+ * So the ref callback is now stable - it mounts and unmounts, nothing else -
+ * and an effect assigns `srcObject` whenever the underlying track actually
+ * changes. `applied` is what makes that idempotent: assigning the same track
+ * again is not free, it restarts the element's load and shows as a flicker.
  */
 export function useRemoteTrack(producerId: string): {
   track: MediaTrack | undefined;
@@ -262,28 +270,89 @@ export function useRemoteTrack(producerId: string): {
 } {
   const tracks = useRoomSnapshot(selectTracks, EMPTY_TRACKS);
   const track = tracks.find((t) => t.producerId === producerId);
+  const mediaTrack = track?.track ?? null;
+
+  // The element this callback last attached to, so DETACHING can undo it.
+  const attached = useRef<HTMLMediaElement | null>(null);
+  // The `MediaStreamTrack` currently on that element. Compared by identity, so
+  // the same track arriving inside a new `MediaTrack` record is a no-op.
+  const applied = useRef<MediaStreamTrack | null>(null);
+  // Read by the ref callback, which must not depend on the track (see above).
+  const latest = useRef<MediaStreamTrack | null>(mediaTrack);
+  latest.current = mediaTrack;
+
+  const attach = useCallback((element: HTMLMediaElement | null) => {
+    // React calls a ref callback with null when the element goes away, and
+    // ignoring that leaves a detached element holding the stream and still
+    // PLAYING it. Nothing on screen shows the orphan; you only hear it,
+    // as the same audio a second time, slightly out of step with itself.
+    // A remount is enough to cause it, and StrictMode remounts everything
+    // once in development, so this reproduced on every dev page load.
+    if (!element) {
+      const previous = attached.current;
+      attached.current = null;
+      applied.current = null;
+      if (previous) {
+        previous.pause();
+        previous.srcObject = null;
+      }
+      return;
+    }
+    // A newly mounted element is always written to, even with no track yet: an
+    // explicit `null` is what says "this element holds nothing", and skipping
+    // it would leave whatever a reused element was carrying.
+    const previousElement = attached.current;
+    attached.current = element;
+    if (previousElement === element && applied.current === latest.current) return;
+    applied.current = latest.current;
+    element.srcObject = latest.current ? new MediaStream([latest.current]) : null;
+  }, []);
 
-  const attach = useCallback(
-    (element: HTMLMediaElement | null) => {
-      if (!element) return;
-      element.srcObject = track ? new MediaStream([track.track]) : null;
-    },
-    [track],
-  );
+  // The track almost never exists when the element mounts: the consume round
+  // trip lands milliseconds later. This is what puts it on the element then,
+  // and what swaps it if the consumer is ever rebuilt.
+  useEffect(() => {
+    const element = attached.current;
+    if (!element) return;
+    if (applied.current === mediaTrack) return;
+    applied.current = mediaTrack;
+    element.srcObject = mediaTrack ? new MediaStream([mediaTrack]) : null;
+  }, [mediaTrack]);
 
   return { track, attach };
 }
 
-export type LocalSource = "camera" | "microphone" | "screen";
+export type LocalSource = LocalPublicationSource;
 
 export type LocalMediaControls = {
   publishCamera: () => Promise<void>;
   publishMicrophone: () => Promise<void>;
   publishScreen: () => Promise<void>;
   unpublish: (source: LocalSource) => Promise<void>;
+  /**
+   * Mute or unmute a source that is already published, keeping its capture.
+   *
+   * What a Mute button and a camera-off button call. NOT `unpublish` and a
+   * later re-publish: that path starts with `getUserMedia` again, and Safari
+   * puts a permission prompt in front of every call to it, so a toggle built
+   * that way asked permission on every unmute. No-op for a source that is not
+   * published.
+   */
+  setPaused: (source: LocalSource, paused: boolean) => Promise<void>;
+  /** Published, whether or not currently paused. */
   isCameraEnabled: boolean;
   isMicrophoneEnabled: boolean;
   screenSharing: boolean;
+  /** Published AND paused at the source: muted, camera off. */
+  paused: Record<LocalSource, boolean>;
+  /**
+   * What the person was sending when the connection dropped, and is not now.
+   *
+   * A drop stops every local capture (the camera light goes out, on purpose)
+   * and the SDK does not turn it back on by itself. This is what a screen tells
+   * the person so they press the button. Cleared per source on republish.
+   */
+  lostSources: readonly LocalSource[];
   /**
    * A capture or a publish is in flight for this source.
    *
@@ -297,6 +366,8 @@ export type LocalMediaControls = {
 };
 
 const NOTHING_PENDING: Record<LocalSource, boolean> = { camera: false, microphone: false, screen: false };
+const NOTHING_PAUSED: Record<LocalSource, boolean> = NOTHING_PENDING;
+const selectLostSources = (room: MediaRoom): readonly LocalSource[] => room.lostPublicationSources;
 
 /**
  * Capture and publish.
@@ -310,8 +381,19 @@ export function useLocalMedia(): LocalMediaControls {
   const [error, setError] = useState<Error | undefined>(undefined);
   const [pending, setPending] = useState<Record<LocalSource, boolean>>(NOTHING_PENDING);
   const publications = useRoomSnapshot(selectPublications, EMPTY_PUBLICATIONS);
+  const lostSources = useRoomSnapshot(selectLostSources, EMPTY_SOURCES);
 
   const has = (source: string) => publications.some((p) => p.source === source);
+  // Rebuilt only when the publications snapshot moves, which is the only time
+  // a pause flag can have changed.
+  const paused = useMemo<Record<LocalSource, boolean>>(() => {
+    const isPaused = (source: LocalSource) => {
+      const mine = publications.filter((p) => p.source === source);
+      return mine.length > 0 && mine.every((p) => p.paused);
+    };
+    const next = { camera: isPaused("camera"), microphone: isPaused("microphone"), screen: isPaused("screen") };
+    return next.camera || next.microphone || next.screen ? next : NOTHING_PAUSED;
+  }, [publications]);
 
   /**
    * One operation per source at a time, held in a REF.
@@ -372,9 +454,7 @@ export function useLocalMedia(): LocalMediaControls {
           const stream =
             source === "screen"
               ? await navigator.mediaDevices.getDisplayMedia({ video: true })
-              : await navigator.mediaDevices.getUserMedia(
-                  source === "camera" ? { video: true } : { audio: 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`);
@@ -408,14 +488,30 @@ export function useLocalMedia(): LocalMediaControls {
     [room, exclusively],
   );
 
+  // Under the same lock, for the same reason: a mute pressed while the publish
+  // it is muting is still capturing would find nothing to pause.
+  const setPaused = useCallback(
+    async (source: LocalSource, value: boolean) =>
+      exclusively(source, async () => {
+        if (!room) return;
+        for (const publication of room.localPublications.filter((p) => p.source === source)) {
+          await room.setPaused(publication.producerId, value);
+        }
+      }),
+    [room, exclusively],
+  );
+
   return {
     publishCamera: useCallback(() => publish("camera"), [publish]),
     publishMicrophone: useCallback(() => publish("microphone"), [publish]),
     publishScreen: useCallback(() => publish("screen"), [publish]),
     unpublish,
+    setPaused,
     isCameraEnabled: has("camera"),
     isMicrophoneEnabled: has("microphone"),
     screenSharing: has("screen"),
+    paused,
+    lostSources,
     pending,
     error,
   };
@@ -425,6 +521,7 @@ export function useLocalMedia(): LocalMediaControls {
  * `useSyncExternalStore` a new array on every read and loop it. */
 const EMPTY_TRACKS: readonly MediaTrack[] = [];
 const EMPTY_PUBLICATIONS: MediaRoom["localPublications"] = [];
+const EMPTY_SOURCES: readonly LocalSource[] = [];
 const EMPTY_STATE: RoomState = {
   phase: "idle",
   identity: null,