@tribe-nest/media-client 0.1.0 → 0.1.1

package/src/core/_tests/signal.spec.ts

@@ -43,7 +43,12 @@ describe("the handshake", () => {
 
     const first = server.received[0];
     expect(first?.method).toBe("join");
-    expect(first).toMatchObject({ method: "join", id: 0, token: "join-ticket", protocolVersion: MEDIA_PROTOCOL_VERSION });
+    expect(first).toMatchObject({
+      method: "join",
+      id: 0,
+      token: "join-ticket",
+      protocolVersion: MEDIA_PROTOCOL_VERSION,
+    });
     expect(server.invalidFrames).toEqual([]);
   });
 
@@ -78,9 +83,12 @@ describe("the handshake", () => {
     // The reply says the token was accepted; the EVENT carries the router
     // capabilities, the peer snapshot and the recording flag. Resolving early
     // hands the caller a room it knows nothing about.
-    const { server, signal } = harness({ autoJoin: false, onRequest: (frame, socket, srv) => {
-      if (frame.method === "join") srv.reply(frame.id, { accepted: true }, socket);
-    } });
+    const { server, signal } = harness({
+      autoJoin: false,
+      onRequest: (frame, socket, srv) => {
+        if (frame.method === "join") srv.reply(frame.id, { accepted: true }, socket);
+      },
+    });
 
     let settled = false;
     const pending = signal.connect().then(() => (settled = true));
@@ -93,9 +101,12 @@ describe("the handshake", () => {
   });
 
   it("rejects with the refusal code and closes the socket", async () => {
-    const { server, signal, closes } = harness({ autoJoin: false, onRequest: (frame, socket, srv) => {
-      if (frame.method === "join") srv.fail(frame.id, "unauthorized", "no", socket);
-    } });
+    const { server, signal, closes } = harness({
+      autoJoin: false,
+      onRequest: (frame, socket, srv) => {
+        if (frame.method === "join") srv.fail(frame.id, "unauthorized", "no", socket);
+      },
+    });
 
     await expect(signal.connect()).rejects.toMatchObject({ name: "MediaError", code: "unauthorized" });
     expect(signal.phase).toBe("closed");
@@ -148,6 +159,62 @@ describe("the handshake", () => {
     expect(signal.phase).toBe("closed");
   });
 
+  /**
+   * A credential fetch that FAILS.
+   *
+   * The other side of the same window: no socket exists yet, so no close event
+   * is ever going to arrive to end the attempt. Left alone, the phase stayed
+   * `connecting`, no close handler fired, and every later `connect()` was
+   * refused as "already connecting", which in a UI was a spinner for the rest
+   * of the session after one 409 from the ticket endpoint.
+   */
+  it("ends the attempt when the credential fetch rejects, reports the cause, and permits another connect", async () => {
+    const server = new FakeSignalServer();
+    const closes: DisconnectCause[] = [];
+    let calls = 0;
+    const signal = new MediaSignal({
+      getCredentials: async () => {
+        calls += 1;
+        if (calls === 1) throw new Error("HTTP 409: window not open");
+        return { mediaUrl: MEDIA_URL, token: "join-ticket" };
+      },
+      webSocket: server.factory,
+    });
+    signal.onClose((cause) => closes.push(cause));
+
+    await expect(signal.connect()).rejects.toThrow(/HTTP 409/);
+
+    // Ended the way a failed handshake is: phase reset, cause reported, and no
+    // socket was ever opened for it.
+    expect(signal.phase).toBe("closed");
+    expect(closes).toEqual([{ type: "socket_closed", reason: "HTTP 409: window not open" }]);
+    expect(server.sockets).toEqual([]);
+
+    // And the next attempt is not refused as "already connecting".
+    await expect(signal.connect()).resolves.toMatchObject({ event: "joined" });
+    expect(signal.phase).toBe("joined");
+    expect(server.sockets).toHaveLength(1);
+    signal.close();
+  });
+
+  it("reports a MediaError thrown by the credential fetch as a refusal", async () => {
+    const server = new FakeSignalServer();
+    const closes: DisconnectCause[] = [];
+    const signal = new MediaSignal({
+      getCredentials: async () => {
+        throw new MediaError("forbidden", "sealed");
+      },
+      webSocket: server.factory,
+    });
+    signal.onClose((cause) => closes.push(cause));
+
+    await expect(signal.connect()).rejects.toMatchObject({ name: "MediaError", code: "forbidden" });
+    // Carried as `refused` so the reconnect policy can decide on the CODE, the
+    // same way it does for a refusal from the node itself.
+    expect(closes).toEqual([{ type: "refused", code: "forbidden", message: "sealed" }]);
+    expect(signal.phase).toBe("closed");
+  });
+
   it("opens one socket, not two, when a second connect starts inside the first credential fetch", async () => {
     const server = new FakeSignalServer();
     const gates: (() => void)[] = [];
@@ -186,9 +253,11 @@ describe("the handshake", () => {
 describe("request and reply correlation", () => {
   it("routes each reply to its own request, whatever order they arrive in", async () => {
     const ids: number[] = [];
-    const { server, signal } = harness({ onRequest: (frame) => {
-      if (frame.method !== "join") ids.push(frame.id);
-    } });
+    const { server, signal } = harness({
+      onRequest: (frame) => {
+        if (frame.method !== "join") ids.push(frame.id);
+      },
+    });
     await signal.connect();
 
     const first = signal.request({ method: "pauseProducer", producerId: "p-1" });
@@ -206,9 +275,11 @@ describe("request and reply correlation", () => {
   });
 
   it("turns an ok:false reply into a MediaError carrying the code", async () => {
-    const { signal } = harness({ onRequest: (frame, socket, srv) => {
-      if (frame.method === "consume") srv.fail(frame.id, "not_subscribable", undefined, socket);
-    } });
+    const { signal } = harness({
+      onRequest: (frame, socket, srv) => {
+        if (frame.method === "consume") srv.fail(frame.id, "not_subscribable", undefined, socket);
+      },
+    });
     await signal.connect();
 
     const error = await signal
@@ -222,12 +293,14 @@ describe("request and reply correlation", () => {
   it("ignores a second reply to an id it has already settled", async () => {
     // "exactly one reply with that id" is the protocol. A node that breaks it
     // must not corrupt the client, and must not do it quietly either.
-    const { signal, logs } = harness({ onRequest: (frame, socket, srv) => {
-      if (frame.method === "closeProducer") {
-        srv.reply(frame.id, { closed: true }, socket);
-        srv.reply(frame.id, { closed: "again" }, socket);
-      }
-    } });
+    const { signal, logs } = harness({
+      onRequest: (frame, socket, srv) => {
+        if (frame.method === "closeProducer") {
+          srv.reply(frame.id, { closed: true }, socket);
+          srv.reply(frame.id, { closed: "again" }, socket);
+        }
+      },
+    });
     await signal.connect();
 
     expect(await signal.request({ method: "closeProducer", producerId: "p-1" })).toEqual({ closed: true });
@@ -308,6 +381,24 @@ describe("why the connection ended", () => {
     expect(closes).toEqual([{ type: "draining", reconnectAfterMs: 5_000 }]);
   });
 
+  it("reports a client close over a drain the node had announced", async () => {
+    const { server, signal, closes } = harness({
+      onRequest: (frame, socket, srv) => {
+        if (frame.method === "leave") srv.reply(frame.id, {}, socket);
+      },
+    });
+    await signal.connect();
+
+    // The node asks to be left, and the person leaves before it hangs up.
+    server.event({ event: "draining", reconnectAfterMs: 5_000 });
+    await flush();
+    await signal.leave();
+
+    // Reported as the drain, this became a reconnect the room then declined,
+    // and the screen offered a way back into a call somebody had just ended.
+    expect(closes).toEqual([{ type: "closed_by_client" }]);
+  });
+
   it("reports a closed room rather than a dropped socket", async () => {
     const { server, signal, closes } = harness();
     await signal.connect();
@@ -334,9 +425,11 @@ describe("why the connection ended", () => {
   });
 
   it("reports a client-initiated close, and leave() sends the frame first", async () => {
-    const { server, signal, closes } = harness({ onRequest: (frame, socket, srv) => {
-      if (frame.method === "leave") srv.reply(frame.id, {}, socket);
-    } });
+    const { server, signal, closes } = harness({
+      onRequest: (frame, socket, srv) => {
+        if (frame.method === "leave") srv.reply(frame.id, {}, socket);
+      },
+    });
     await signal.connect();
 
     await signal.leave();

package/src/core/_tests/state.spec.ts

@@ -46,6 +46,18 @@ describe("joining", () => {
     expect(rejoined.phase).toBe("joined");
   });
 
+  it("keeps an active set that arrived AHEAD of the snapshot, pruned to what the snapshot names", () => {
+    // The contract fixes no order between `joined` and the node's first
+    // `activeSpeakers`. Resetting the set on `joined` discarded an instruction
+    // the node had already given, and the client consumed nothing until the
+    // next speaker change.
+    const early = reduceRoomState(initialRoomState, { event: "activeSpeakers", producerIds: ["pa", "gone"] });
+    const state = reduceRoomState(early, joined());
+
+    expect(state.activeSpeakers).toEqual(["pa"]);
+    expect(activeProducers(state).map((p) => p.producerId)).toEqual(["pa"]);
+  });
+
   it("clears a drain flag from the previous connection", () => {
     const draining = reduceRoomState(afterJoin(), { event: "draining", reconnectAfterMs: 3_000 });
     expect(draining.draining).toEqual({ reconnectAfterMs: 3_000 });
@@ -102,7 +114,12 @@ describe("peers and producers", () => {
     expect(state.activeSpeakers).toEqual(["pc", "pa"]);
     expect(activeProducers(state).map((p) => p.producerId)).toEqual(["pa"]);
 
-    const arrived = reduceRoomState(state, { event: "producerAppeared", producerId: "pc", identity: "c", kind: "video" });
+    const arrived = reduceRoomState(state, {
+      event: "producerAppeared",
+      producerId: "pc",
+      identity: "c",
+      kind: "video",
+    });
     expect(activeProducers(arrived).map((p) => p.producerId)).toEqual(["pc", "pa"]);
   });
 
@@ -134,7 +151,10 @@ describe("the information barrier", () => {
 
   it("keeps only the named identities under an allow rule, and nothing under none", () => {
     const state = afterJoin();
-    const allowed = reduceRoomState(state, { event: "subscribeRuleChanged", subscribe: { mode: "allow", identities: ["b"] } });
+    const allowed = reduceRoomState(state, {
+      event: "subscribeRuleChanged",
+      subscribe: { mode: "allow", identities: ["b"] },
+    });
     expect(visibleProducers(allowed).map((p) => p.identity)).toEqual(["b"]);
 
     const none = reduceRoomState(state, { event: "subscribeRuleChanged", subscribe: { mode: "none" } });

package/src/core/reconnect.ts

@@ -196,8 +196,14 @@ function delayFor(cause: DisconnectCause, attempt: number, o: ReconnectOptions):
  *
  * Deliberately knows nothing about sockets: `attempt` returns whatever a
  * session is and `waitForClose` resolves with why it ended. That is what makes
- * the whole loop testable with no server, and it is the same loop the room API
- * (P3b) should use rather than deriving a second one.
+ * the whole loop testable with no server.
+ *
+ * Who uses it: headless callers with nothing else to do between attempts (the
+ * load harness, an egress leg, the SIP gateway). `room/room.ts` does NOT: the
+ * room needs a retry it can cancel from `close()`, and has to publish whether
+ * one is booked (`isRecovering`) between attempts, so it holds its own timer
+ * and calls `decideReconnect` directly. Both drivers share the ONE policy in
+ * `decideReconnect`; neither restates it.
  */
 export async function superviseConnection<TSession>(input: {
   attempt: () => Promise<TSession>;

package/src/core/signal.ts

@@ -119,7 +119,9 @@ export function assertTokenNotInUrl(mediaUrl: string): void {
   }
   for (const key of url.searchParams.keys()) {
     if (/token|jwt|ticket|auth/i.test(key)) {
-      throw new Error(`refusing to connect: mediaUrl carries "${key}" in the query string. The token goes in the first frame.`);
+      throw new Error(
+        `refusing to connect: mediaUrl carries "${key}" in the query string. The token goes in the first frame.`,
+      );
     }
   }
 }
@@ -189,13 +191,32 @@ export class MediaSignal {
     const attempt = ++this.attempt;
     this.phaseValue = "connecting";
 
-    const credentials = await this.options.getCredentials();
-    // Fetching a ticket is a network round trip of its own, so this window is
-    // seconds wide and a caller giving up inside it is ordinary. Every later
-    // step has a socket and is cancelled by `handleClose`; this one is the only
-    // part of a connect that a `close()` could not reach.
-    this.assertAttemptIsCurrent(attempt);
-    assertTokenNotInUrl(credentials.mediaUrl);
+    let credentials: MediaCoreCredentials;
+    try {
+      credentials = await this.options.getCredentials();
+      // Fetching a ticket is a network round trip of its own, so this window is
+      // seconds wide and a caller giving up inside it is ordinary. Every later
+      // step has a socket and is cancelled by `handleClose`; this one is the
+      // only part of a connect that a `close()` could not reach.
+      this.assertAttemptIsCurrent(attempt);
+      assertTokenNotInUrl(credentials.mediaUrl);
+    } catch (error) {
+      // No socket exists yet, so nothing is going to arrive and end this attempt
+      // for us: without this the phase stays `connecting` for ever, no close
+      // handler ever fires, and every later `connect()` is refused as "already
+      // connecting". A ticket endpoint answering 409 at the edge of the booking
+      // window was a spinner for the rest of the session. So a failed fetch is
+      // ended the way a failed handshake is: cause recorded, close handlers
+      // told, phase reset. Only when this attempt is still the live one,
+      // though. An attempt that `close()` or a second `connect()` overtook has
+      // already been ended by whichever did it, and must not close THEIR
+      // attempt on the way out.
+      if (attempt === this.attempt && this.phaseValue === "connecting") {
+        if (!this.terminalCause) this.terminalCause = causeFromError(error);
+        this.closeSocket();
+      }
+      throw error;
+    }
 
     const factory = this.options.webSocket ?? defaultWebSocketFactory;
     const socket = factory(credentials.mediaUrl);
@@ -229,10 +250,16 @@ export class MediaSignal {
   request(frame: SignalRequest, timeoutMs?: number): Promise<unknown> {
     const socket = this.socket;
     if (!socket || this.phaseValue === "closed" || this.phaseValue === "idle") {
-      return Promise.reject(new MediaError("internal", `cannot send ${frame.method}: the signal connection is ${this.phaseValue}`));
+      return Promise.reject(
+        new MediaError("internal", `cannot send ${frame.method}: the signal connection is ${this.phaseValue}`),
+      );
     }
     const id = this.nextId++;
-    const promise = this.track(id, frame.method, timeoutMs ?? this.options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
+    const promise = this.track(
+      id,
+      frame.method,
+      timeoutMs ?? this.options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+    );
     try {
       this.send({ ...frame, id } as RequestFrame);
     } catch (error) {
@@ -260,9 +287,18 @@ export class MediaSignal {
     this.close();
   }
 
-  /** Closes the socket. Idempotent. */
+  /**
+   * Closes the socket. Idempotent.
+   *
+   * A close the CLIENT asked for is the cause, whatever the node had announced
+   * before it. `draining` is recorded the moment the frame arrives, seconds
+   * before the node actually hangs up, and a person who presses Leave inside
+   * that window has left: reporting the drain instead sent the room to
+   * "reconnecting" over a call somebody had deliberately ended, and the screen
+   * offered them a way back into it.
+   */
   close(): void {
-    if (!this.terminalCause) this.terminalCause = { type: "closed_by_client" };
+    this.terminalCause = { type: "closed_by_client" };
     this.closeSocket();
   }
 

package/src/core/state.ts

@@ -1,4 +1,10 @@
-import { maySubscribe, type EventFrame, type MediaGrants, type Peer, type SubscribeRule } from "@tribe-nest/media-protocol";
+import {
+  maySubscribe,
+  type EventFrame,
+  type MediaGrants,
+  type Peer,
+  type SubscribeRule,
+} from "@tribe-nest/media-protocol";
 
 /**
  * The room as the event frames describe it, as a pure reducer.
@@ -65,22 +71,33 @@ export const initialRoomState: RoomState = {
  */
 export function reduceRoomState(state: RoomState, frame: EventFrame): RoomState {
   switch (frame.event) {
-    case "joined":
+    case "joined": {
       // A wholesale replace, not a merge. `joined` also arrives after a
       // reconnect, and merging would leave peers who left while we were away
       // on screen for the rest of the call.
+      //
+      // The active set is the ONE field carried across, pruned to the producers
+      // this snapshot names. The contract fixes no order between `joined` and
+      // the node's first `activeSpeakers` broadcast, so a set that lands first
+      // is the node's current instruction, not a stale one, and resetting it
+      // here left a client that had been told what to consume consuming
+      // nothing until the next speaker change. A set left over from a PREVIOUS
+      // connection is not this reducer's to recognise (a rejoin and a first
+      // join look the same from here); the room clears it on disconnect.
+      const producers = frame.producers.map((p) => ({ ...p, paused: false }));
       return {
         phase: "joined",
         identity: frame.identity,
         room: frame.room,
         peers: frame.peers,
-        producers: frame.producers.map((p) => ({ ...p, paused: false })),
-        activeSpeakers: [],
+        producers,
+        activeSpeakers: pruneSpeakers(state.activeSpeakers, producers),
         recording: frame.recording,
         subscribeRule: null,
         draining: null,
         closedReason: null,
       };
+    }
 
     case "peerJoined": {
       const without = state.peers.filter((p) => p.identity !== frame.peer.identity);

package/src/react/_tests/hooks.spec.tsx

@@ -89,10 +89,18 @@ function nodeWith(producers: { producerId: string; identity: string; kind: "audi
     onRequest: (frame, socket) => {
       if (frame.method === "join") return;
       if (frame.method === "createTransport") {
-        return server.reply(frame.id, { transportId: "t-1", iceParameters: {}, iceCandidates: [], dtlsParameters: {} }, socket);
+        return server.reply(
+          frame.id,
+          { transportId: "t-1", iceParameters: {}, iceCandidates: [], dtlsParameters: {} },
+          socket,
+        );
       }
       if (frame.method === "consume") {
-        return server.reply(frame.id, { consumerId: "c-1", producerId: frame.producerId, kind: "audio", rtpParameters: {} }, socket);
+        return server.reply(
+          frame.id,
+          { consumerId: "c-1", producerId: frame.producerId, kind: "audio", rtpParameters: {} },
+          socket,
+        );
       }
       return server.reply(frame.id, {}, socket);
     },
@@ -409,7 +417,14 @@ describe("one press, one publish", () => {
       ...fakeTransport(),
       async produce(input: { appData?: Record<string, unknown> }) {
         produced.push(String(input.appData?.source));
-        return { id: `p-${produced.length}`, kind: "audio" as const, closed: false, pause: vi.fn(), resume: vi.fn(), close: vi.fn() };
+        return {
+          id: `p-${produced.length}`,
+          kind: "audio" as const,
+          closed: false,
+          pause: vi.fn(),
+          resume: vi.fn(),
+          close: vi.fn(),
+        };
       },
     }),
   });
@@ -463,6 +478,79 @@ describe("one press, one publish", () => {
   });
 });
 
+/**
+ * A mute is a pause, and the hook says so.
+ *
+ * `setPaused` is what a Mute or a camera-off control calls, in place of the
+ * unpublish-then-publish a toggle used to do. The difference the person sees is
+ * on Safari, which puts a permission prompt in front of EVERY `getUserMedia`,
+ * so a toggle that re-captured asked permission on every unmute. What is pinned
+ * here is that the hook reflects it: `paused` follows the room, the capture is
+ * never re-asked for, and `isMicrophoneEnabled` still means "published".
+ */
+describe("useLocalMedia pauses in place of republishing", () => {
+  afterEach(() => {
+    delete (navigator as { mediaDevices?: unknown }).mediaDevices;
+  });
+
+  it("mutes and unmutes without a second capture, and reports it", async () => {
+    const track = { kind: "audio", stop: vi.fn(), enabled: true } as unknown as MediaStreamTrack;
+    const getUserMedia = vi.fn(async () => ({ getTracks: () => [track] }) as unknown as MediaStream);
+    Object.defineProperty(navigator, "mediaDevices", {
+      configurable: true,
+      value: { getUserMedia, getDisplayMedia: getUserMedia },
+    });
+    const server = nodeWith();
+
+    let controls: ReturnType<typeof useLocalMedia> | undefined;
+    function Probe() {
+      controls = useLocalMedia();
+      return <div data-testid="muted">{String(controls.paused.microphone)}</div>;
+    }
+    const { getByTestId } = render(wrap(server, <Probe />));
+    await waitFor(() => expect(controls).toBeDefined());
+
+    await act(async () => {
+      await controls?.publishMicrophone();
+    });
+    expect(getByTestId("muted").textContent).toBe("false");
+
+    await act(async () => {
+      await controls?.setPaused("microphone", true);
+    });
+    await waitFor(() => expect(getByTestId("muted").textContent).toBe("true"));
+    // Still published, so a control can draw "muted" rather than "off".
+    expect(controls?.isMicrophoneEnabled).toBe(true);
+    expect(server.received.filter((f) => f.method === "pauseProducer")).toHaveLength(1);
+
+    await act(async () => {
+      await controls?.setPaused("microphone", false);
+    });
+    await waitFor(() => expect(getByTestId("muted").textContent).toBe("false"));
+    // The whole point: one capture, one permission prompt, for the whole call.
+    expect(getUserMedia).toHaveBeenCalledTimes(1);
+    expect(server.received.filter((f) => f.method === "closeProducer")).toHaveLength(0);
+  });
+
+  it("does nothing for a source that is not published", async () => {
+    const server = nodeWith();
+    let controls: ReturnType<typeof useLocalMedia> | undefined;
+    function Probe() {
+      controls = useLocalMedia();
+      return null;
+    }
+    render(wrap(server, <Probe />));
+    await waitFor(() => expect(controls).toBeDefined());
+
+    await act(async () => {
+      await controls?.setPaused("camera", true);
+    });
+
+    expect(server.received.filter((f) => f.method === "pauseProducer")).toHaveLength(0);
+    expect(controls?.paused.camera).toBe(false);
+  });
+});
+
 /**
  * The subscribe barrier, applied where it is rendered.
  *

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
@@ -274,16 +272,37 @@ export function useRemoteTrack(producerId: string): {
   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 +316,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 +331,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 +404,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 +438,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 +471,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,