@tribe-nest/forge 3.29.0 → 3.34.0

package/src/ui/media/bookingSession.tsx

@@ -0,0 +1,182 @@
+import { useCallback, type ReactNode } from "react";
+
+import { MediaRoomProvider } from "@tribe-nest/media-client/react";
+import { MediaError, type MediaErrorCode, type MediaGrants } from "@tribe-nest/media-protocol";
+
+import { useForge } from "../../provider/ForgeProvider";
+
+/**
+ * Live video for a coaching session, on the platform's own media network.
+ *
+ * A coaching product whose location is `video` holds its sessions in a room
+ * this platform provisions, rather than on a link the coach pasted in. There is
+ * no URL to render and there deliberately never will be: entry is a signed
+ * ticket minted per attempt and valid for minutes, so anything durable enough
+ * to put in a page or an email would be a forwardable key to somebody else's
+ * session.
+ *
+ * ## What a site does
+ *
+ * ```tsx
+ * const call = bookingCallWindow(booking);
+ *
+ * return call.isOpen ? (
+ *   <BookingCallProvider bookingId={booking.id} fallback={<p>Connecting…</p>}>
+ *     <CallStage />
+ *   </BookingCallProvider>
+ * ) : null;
+ * ```
+ *
+ * Inside the provider the whole surface is `useParticipants()`,
+ * `useRemoteTrack(producerId)`, `useLocalMedia()` and `useMediaRoom()` - the
+ * same hooks every other call surface uses, because there is one call UI.
+ *
+ * ## Why the credential is a CALLBACK
+ *
+ * `getCredentials` is called before EVERY connection attempt, not once. A join
+ * ticket expires in minutes and a session lasts an hour, so a token fetched
+ * once means the first reconnect after a lift or a wifi handover presents an
+ * expired one and the call does not come back. Passing the callback (rather
+ * than a token) is what makes reconnection work at all.
+ *
+ * ## What the server owns and this file does not mirror
+ *
+ * - **Who you are in the room.** Identity, name and grants are all derived
+ *   server-side from the booking: the client who bought it, or the coach who
+ *   holds `coaching.write` on the profile selling it. Nothing here can ask to
+ *   be somebody else, and there is no field through which it could.
+ * - **Whether the room is open.** `bookingCallWindow` below is for DRAWING
+ *   the button; the server refuses a ticket outside the window regardless, and
+ *   its answer is the one that counts.
+ * - **Whether the session is a video session.** Read `booking.location.type`,
+ *   already resolved server-side (this booking's override, else the product's
+ *   default). Re-deriving it in the browser would give two answers to one
+ *   question, and the wrong one sends a client to an empty room.
+ */
+
+/** Which side of the call this viewer is on. Derived by the server, never asked for. */
+export type BookingSessionRole = "host" | "guest";
+
+/**
+ * One join ticket, plus the window it belongs to.
+ *
+ * The first six fields are the flat shape every credential endpoint on this
+ * platform returns and the media SDK consumes; `role` and the two window
+ * timestamps are extras the SDK ignores and a call UI usually wants.
+ */
+export type BookingSessionCredentials = {
+  /** The signalling entrypoint. A load balancer, never a node this client picked. */
+  mediaUrl: string;
+  token: string;
+  /** ISO. When THIS ticket dies, not when the call does. */
+  expiresAt: string;
+  /** This viewer's identity in the room, as the other participants see it. */
+  identity: string;
+  roomId: string;
+  grants: MediaGrants;
+  role: BookingSessionRole;
+  /** ISO. The earliest moment the server will hand out a ticket for this session. */
+  roomOpensAt: string;
+  /** ISO. After this it refuses new tickets; anyone already connected stays. */
+  roomClosesAt: string;
+};
+
+/**
+ * Fetch a fresh join ticket for one booking. Hand this to
+ * `<MediaRoomProvider>`, or use `<BookingCallProvider>` which does it for you.
+ *
+ * The identity of the caller is the SESSION's - the endpoint takes the booking
+ * id and nothing else, and answers 404 for a booking that is not yours rather
+ * than 403, which would confirm the id exists.
+ */
+export function useBookingSessionCredentials(bookingId: string): () => Promise<BookingSessionCredentials> {
+  const { client } = useForge();
+
+  // Stable across renders for a given booking: an inline arrow would be a new
+  // function on every parent render, and `<MediaRoomProvider>` holds its
+  // options in a ref precisely because that is the default mistake.
+  return useCallback(async () => {
+    try {
+      const res = await client.post(`/public/coaching/bookings/${bookingId}/session/join`, {});
+      return res.data as BookingSessionCredentials;
+    } catch (error) {
+      throw credentialRefusal(error);
+    }
+  }, [client, bookingId]);
+}
+
+/**
+ * The server's refusal, in the SDK's vocabulary, so the screen shows it.
+ *
+ * The join endpoint answers a person who belongs in the call with the REAL
+ * reason when it says no: the room opens in ten minutes, the session is not
+ * confirmed, the window has closed. Left as an axios error, that sentence never
+ * reached the screen: the SDK's `causeFromError` reads a non-`MediaError` as a
+ * dropped socket ("Request failed with status code 409"), and `callStatus`
+ * then says "Connection lost" about a call the person was never in. As a
+ * `MediaError` the cause is `refused`, which the screen renders as "Could not
+ * join this call" with the server's own sentence and a Try again. That is what
+ * every docblock on this surface promised and what the wire could not deliver.
+ *
+ * Only a response with a status is translated. A network failure (no
+ * response) really is a connection problem and keeps its own reading.
+ */
+function credentialRefusal(error: unknown): unknown {
+  const response = (error as { response?: { status?: number; data?: { message?: unknown } } } | null)?.response;
+  const status = response?.status;
+  if (typeof status !== "number") return error;
+
+  const message = typeof response?.data?.message === "string" ? response.data.message : undefined;
+  const code: MediaErrorCode =
+    status === 401 ? "unauthorized" : status === 404 ? "no_such_room" : status >= 500 ? "internal" : "bad_request";
+  return new MediaError(code, message ?? `${status}`, status >= 500);
+}
+
+export type BookingCallProviderProps = {
+  bookingId: string;
+  /** Rendered while the first connection is in flight. */
+  fallback?: ReactNode;
+  /**
+   * Follow the node's active speaker set automatically. On by default, and
+   * leaving it on is almost always right: a client that does not follow it
+   * shows black tiles in any room over the threshold.
+   */
+  autoSubscribe?: boolean;
+  children: ReactNode;
+};
+
+/**
+ * The room for one booking, wired to the credential endpoint.
+ *
+ * Mount it only when the call should be live. The provider connects on mount
+ * and closes on unmount, so rendering it behind a "Join" control is what stops
+ * a portal page from opening a media connection for every session in the list.
+ */
+export function BookingCallProvider({
+  bookingId,
+  fallback,
+  autoSubscribe = true,
+  children,
+}: BookingCallProviderProps): ReactNode {
+  const getCredentials = useBookingSessionCredentials(bookingId);
+
+  return (
+    <MediaRoomProvider getCredentials={getCredentials} autoSubscribe={autoSubscribe} fallback={fallback}>
+      {children}
+    </MediaRoomProvider>
+  );
+}
+
+/**
+ * The window logic lives in `bookingWindow.ts`, a module with NO media
+ * dependency, so `AccountDashboard` (in the `./ui` entry every site loads) can
+ * decide whether to DRAW a Join control without pulling the SDK into that
+ * bundle. Re-exported here so `@tribe-nest/forge/media` keeps its surface.
+ */
+export {
+  BOOKING_CALL_CLOSES_MINUTES_AFTER,
+  BOOKING_CALL_OPENS_MINUTES_BEFORE,
+  bookingCallWindow,
+  type BookingCallSubject,
+  type BookingCallWindow,
+} from "./bookingWindow";

package/src/ui/media/bookingWindow.ts

@@ -0,0 +1,81 @@
+/**
+ * When a coaching session's video room is open, computed WITHOUT the media SDK.
+ *
+ * This module deliberately imports nothing from `@tribe-nest/media-client`.
+ * `AccountDashboard` lives in the `./ui` entry that every code website loads,
+ * and it needs to know whether to draw a Join control long before anybody
+ * presses it. Keeping the window pure means that decision costs the site
+ * nothing; the call UI itself is loaded on the click (see `BookingCallScreen`).
+ * `@tribe-nest/forge/media` re-exports everything here, so a site that already
+ * imports from that barrel sees no difference.
+ */
+
+/**
+ * How early the room opens, and how long it stays open.
+ *
+ * A MIRROR of the server's `SESSION_JOIN_OPENS_MINUTES_BEFORE` and
+ * `SESSION_JOIN_CLOSES_MINUTES_AFTER` (`apps/backend/src/services/public/
+ * coaching/commands/bookingSession.ts`), and a mirror is the most this side
+ * can hold. The server's own `roomOpensAt` / `roomClosesAt` arrive only with a
+ * join ticket, and a ticket is only minted INSIDE the window, so the one moment
+ * a site needs "opens at" copy (before the window) is the one moment the
+ * server's timestamps are unreachable. These constants exist for that pre-join
+ * draw and nothing else: the decision is the server's, its refusal names the
+ * real window, and `<CallStage>` shows that refusal verbatim. Change the server
+ * and this pair together.
+ */
+export const BOOKING_CALL_OPENS_MINUTES_BEFORE = 15;
+export const BOOKING_CALL_CLOSES_MINUTES_AFTER = 120;
+
+const MINUTE = 60_000;
+
+/** What a booking has to carry for the window to be computable. */
+export type BookingCallSubject = {
+  status: string;
+  sessionStartTime: string;
+  sessionEndTime: string;
+  location?: { type: string } | null;
+};
+
+export type BookingCallWindow = {
+  /** Does this session happen on a platform video call at all? */
+  isVideo: boolean;
+  /** May a ticket be minted right now? Draw the Join control from this. */
+  isOpen: boolean;
+  /** Before the window, so the answer is "come back at". */
+  opensAt: Date;
+  /** After it the server refuses new tickets. */
+  closesAt: Date;
+};
+
+/**
+ * Is this session's room open, and when does it open?
+ *
+ * For DRAWING the control and nothing else. The server applies the same window
+ * and its refusal is the decision: a clock that is ten minutes fast must not be
+ * able to talk itself into a room, and a clock that is ten minutes slow must
+ * not hide a session that has already started. Show the server's refusal
+ * verbatim when a join fails rather than pre-judging it here.
+ *
+ * `now` is a parameter so a caller can drive it from a ticking value and get a
+ * re-render at the moment the window opens; a hook reading the clock itself
+ * would be stale until something else happened to re-render.
+ */
+export function bookingCallWindow(booking: BookingCallSubject, now: Date = new Date()): BookingCallWindow {
+  const startsAt = new Date(booking.sessionStartTime);
+  const endsAt = new Date(booking.sessionEndTime);
+  const opensAt = new Date(startsAt.getTime() - BOOKING_CALL_OPENS_MINUTES_BEFORE * MINUTE);
+  const closesAt = new Date(endsAt.getTime() + BOOKING_CALL_CLOSES_MINUTES_AFTER * MINUTE);
+
+  // A cancelled session has no room to enter, which is also why the server
+  // withholds `location` for anything that is not confirmed - so this reads
+  // `isVideo: false` for one, rather than offering a button that 409s.
+  const isVideo = booking.status === "confirmed" && booking.location?.type === "video";
+
+  return {
+    isVideo,
+    isOpen: isVideo && now.getTime() >= opensAt.getTime() && now.getTime() <= closesAt.getTime(),
+    opensAt,
+    closesAt,
+  };
+}

package/src/ui/media/callState.ts

@@ -0,0 +1,360 @@
+import type { ConnectionState, DisconnectCause, ProducerEntry, RoomState } from "@tribe-nest/media-client";
+import {
+  mayPublish,
+  type MediaGrants,
+  type ParticipantKind,
+  type Peer,
+  type PublishSource,
+} from "@tribe-nest/media-protocol";
+
+/**
+ * The call UI's decisions, as pure functions.
+ *
+ * Everything a call screen has to work out from room state lives here rather
+ * than inside a component, because these are the parts that are worth being
+ * sure about and a component is the hardest place to be sure about anything.
+ * Two of them have a specific failure they exist to prevent.
+ *
+ * ## The grid must not collapse
+ *
+ * `callTiles` derives one tile per PARTICIPANT, never one tile per video
+ * stream. A participant with the camera off is an ordinary state, not an
+ * absence: they are still in the room, still speaking, still someone the other
+ * side has to be able to see listed. The commonest bug in this kind of
+ * component is a grid built by mapping over video tracks, which quietly drops
+ * everybody who is not publishing video and re-flows the whole layout the
+ * moment one person turns a camera off.
+ *
+ * ## The connection state must be honest
+ *
+ * `callStatus` maps the room's own five states onto something a person can act
+ * on, and it deliberately keeps "reconnecting" and "failed" apart. A spinner
+ * that means both is a spinner that means nothing: one is worth waiting
+ * through, the other is worth pressing a button about, and only the UI can say
+ * which because only the UI is being looked at.
+ */
+
+/** One rendered tile. A tile with no `videoProducerId` is NORMAL, not broken. */
+export type CallTile = {
+  /**
+   * React key. Deliberately the participant plus an ORDINAL rather than the
+   * producer id: a camera going on and off must change what a tile shows, not
+   * unmount and remount the tile.
+   */
+  key: string;
+  identity: string;
+  /** What to print. The peer's name when it has one, else its identity, which
+   * at least tells two unnamed participants apart. */
+  name: string;
+  kind: ParticipantKind;
+  /** The node put one of this participant's audio producers in the active set. */
+  isSpeaking: boolean;
+  /** Attach this with `useRemoteTrack`. Absent means "no camera", not "error". */
+  videoProducerId?: string;
+  /** The publisher paused it at source. Their choice, and shown as such. */
+  videoPaused: boolean;
+  /** They are publishing audio at all. A room can be joined listen-only. */
+  hasAudio: boolean;
+};
+
+export type CallTileInput = {
+  /** Our own identity, so we are not drawn twice: self is the local preview. */
+  identity: string | null;
+  peers: readonly Peer[];
+  producers: readonly ProducerEntry[];
+  /** Producer ids, as the node sent them. Not identities. */
+  activeSpeakers: readonly string[];
+};
+
+const displayName = (identity: string, name?: string): string => {
+  const trimmed = name?.trim();
+  return trimmed && trimmed.length > 0 ? trimmed : identity;
+};
+
+/**
+ * Every participant, once, plus an extra tile for each additional video stream.
+ *
+ * A participant publishing both a camera and a screen has two video producers
+ * and the wire does not label which is which (`source` travels in the
+ * publisher's `appData`, and the node does not echo it). So the second stream
+ * gets its own tile under the same name rather than being guessed at, and
+ * neither one replaces the other: a shared screen must never take the place of
+ * the face that is talking over it.
+ *
+ * ## The recorder is not a participant
+ *
+ * A recording joins the room as a real peer with `kind: "egress"`, so a grid
+ * that maps over `peers` draws a third tile called something like `egress-9f2c`
+ * in a 1:1 session and the head count says three. That happens at exactly the
+ * moment a coach is most likely to be reading the head count, and the thing it
+ * would be telling them (somebody is recording) is already said properly by
+ * `<RecordingIndicator>`, in words, as content. So `egress` is the one kind
+ * that gets no tile. Every other kind is somebody or something a person is
+ * actually talking to - a dial-in caller, an agent - and belongs on screen.
+ */
+export function callTiles(input: CallTileInput): readonly CallTile[] {
+  const speaking = new Set(input.activeSpeakers);
+  const tiles: CallTile[] = [];
+  const recorders = new Set(input.peers.filter((p) => p.kind === "egress").map((p) => p.identity));
+
+  const push = (identity: string, name: string, kind: ParticipantKind) => {
+    const mine = input.producers.filter((p) => p.identity === identity);
+    const videos = mine.filter((p) => p.kind === "video");
+    const hasAudio = mine.some((p) => p.kind === "audio");
+    const isSpeaking = mine.some((p) => p.kind === "audio" && speaking.has(p.producerId));
+
+    if (videos.length === 0) {
+      tiles.push({ key: `${identity}#0`, identity, name, kind, isSpeaking, videoPaused: false, hasAudio });
+      return;
+    }
+    videos.forEach((video, index) => {
+      tiles.push({
+        key: `${identity}#${index}`,
+        identity,
+        name,
+        kind,
+        isSpeaking,
+        videoProducerId: video.producerId,
+        videoPaused: video.paused,
+        hasAudio,
+      });
+    });
+  };
+
+  const seen = new Set<string>();
+  for (const peer of input.peers) {
+    if (peer.identity === input.identity) continue;
+    if (peer.kind === "egress") continue;
+    if (seen.has(peer.identity)) continue;
+    seen.add(peer.identity);
+    push(peer.identity, displayName(peer.identity, peer.name), peer.kind);
+  }
+
+  /**
+   * Producers whose peer we have not been told about yet.
+   *
+   * `producerAppeared` and `peerJoined` are separate frames with no ordering
+   * guarantee, so for a frame or two a stream can exist with nobody to hang it
+   * on. Dropping it would blank a tile that has media in it; drawing it under
+   * the identity is honest and self-corrects on the next frame.
+   */
+  for (const producer of input.producers) {
+    if (producer.identity === input.identity) continue;
+    if (recorders.has(producer.identity)) continue;
+    if (seen.has(producer.identity)) continue;
+    seen.add(producer.identity);
+    push(producer.identity, producer.identity, "human");
+  }
+
+  return tiles;
+}
+
+/**
+ * How many people are in this call, counting the viewer.
+ *
+ * Derived from the tiles' IDENTITIES rather than from how many tiles there are,
+ * because those are different numbers by design: `callTiles` gives a screen
+ * sharer two tiles, one for their face and one for what they are presenting.
+ * Counting tiles therefore announced a third person in the room the instant a
+ * coach shared their screen, which is the one moment a two-person call is
+ * certain to have a second video stream.
+ *
+ * This number is the one thing on the screen a person uses to answer "has my
+ * client actually arrived", so it counts people or it should not be shown.
+ */
+export function callHeadCount(tiles: readonly CallTile[]): number {
+  // +1 for the viewer, who is the local preview and never has a tile here.
+  return new Set(tiles.map((tile) => tile.identity)).size + 1;
+}
+
+/** Remote audio has to be attached to an element or the call is silent. */
+export function remoteAudioProducerIds(input: {
+  identity: string | null;
+  producers: readonly ProducerEntry[];
+}): readonly string[] {
+  return input.producers.filter((p) => p.kind === "audio" && p.identity !== input.identity).map((p) => p.producerId);
+}
+
+export type CallStatusTone = "connecting" | "live" | "reconnecting" | "ended" | "failed";
+
+/**
+ * The connection, as KEYS into Forge's bundles.
+ *
+ * `callStatus` is pure and has no locale, so it names copy rather than
+ * carrying it: `CallStage` puts the keys through `useForgeT()`, and a site
+ * laying out its own status line does the same. Returning English sentences
+ * from here was how the whole call screen shipped in one language on sites
+ * whose every other word was German.
+ *
+ * `detailText` is the exception, on purpose: it is the SERVER'S own sentence
+ * (a refusal message, a close reason) and is shown verbatim, never translated
+ * into a friendlier lie.
+ */
+export type CallStatus = {
+  tone: CallStatusTone;
+  /** Always shown. Connection state is CONTENT, never a help hint. `forge.call_stage.*`. */
+  headlineKey: string;
+  /** Our own second line, when there is one. `forge.call_stage.*`. */
+  detailKey?: string;
+  /** The server's own words when it has any. Shown verbatim. */
+  detailText?: string;
+  /** Is pressing something the right response? Only when waiting will not fix it. */
+  canRetry: boolean;
+};
+
+export type CallStatusInput = {
+  connectionState: ConnectionState;
+  error: DisconnectCause | undefined;
+  /** The ROOM's own phase. `closed` means the node said so, on a live socket. */
+  phase?: RoomState["phase"];
+  closedReason?: string | null;
+  /**
+   * Has the SDK actually booked another attempt?
+   *
+   * `connectionState` is `reconnecting` both while one is in flight and after
+   * the policy has given up, so without this the screen promises a recovery
+   * that may not be happening. Defaults to false, which is the safe reading: it
+   * offers a control rather than a spinner.
+   */
+  recovering?: boolean;
+};
+
+const ENDED = "forge.call_stage.status_ended";
+const LEFT = "forge.call_stage.status_left";
+
+/**
+ * The room's states, told honestly.
+ *
+ * `reconnecting` is the room's state for BOTH "the socket dropped and we are
+ * coming back" and "the node refused us", because the signal client reports one
+ * close path. They are completely different things to a person sitting in front
+ * of it, and the cause is what separates them, so the cause is read here rather
+ * than being flattened into a spinner.
+ *
+ * `phase` is read as well as `connectionState`, and it is not redundant: a
+ * `roomClosed` frame arrives on a socket that is still open, so the connection
+ * is "connected" for as long as it takes the node to hang up. Reading only the
+ * connection would show "Connected" over a call that has ended, which is the
+ * one thing on this list a person would act on wrongly.
+ *
+ * `recovering` is read for the same reason and it is the other half of being
+ * honest. "Moving you to another server" and "Connection lost, reconnecting"
+ * are both PROMISES, and a promise only one side of the SDK is keeping is a
+ * spinner over a call that is finished: the person waits, because the screen
+ * told them to, and the way back into a paid hour turns out to be working out
+ * for themselves that they should reload the page. When nothing is coming, the
+ * words change and a control appears.
+ */
+export function callStatus(input: CallStatusInput): CallStatus {
+  const { connectionState, error } = input;
+  const recovering = input.recovering ?? false;
+
+  if (input.phase === "closed") {
+    return {
+      tone: "ended",
+      headlineKey: ENDED,
+      ...(input.closedReason ? { detailText: input.closedReason } : {}),
+      canRetry: false,
+    };
+  }
+
+  if (connectionState === "connected") {
+    return { tone: "live", headlineKey: "forge.call_stage.status_connected", canRetry: false };
+  }
+
+  if (connectionState === "idle" || connectionState === "connecting") {
+    return { tone: "connecting", headlineKey: "forge.call_stage.status_connecting", canRetry: false };
+  }
+
+  if (connectionState === "closed") {
+    if (error?.type === "room_closed") {
+      return { tone: "ended", headlineKey: ENDED, detailText: error.reason, canRetry: false };
+    }
+    return { tone: "ended", headlineKey: LEFT, canRetry: false };
+  }
+
+  // Everything below is `reconnecting`, where the cause is the whole story.
+  switch (error?.type) {
+    case "refused":
+      return {
+        tone: "failed",
+        headlineKey: "forge.call_stage.status_refused",
+        detailText: error.message ?? error.code,
+        canRetry: true,
+      };
+    case "room_closed":
+      return { tone: "ended", headlineKey: ENDED, detailText: error.reason, canRetry: false };
+    case "draining":
+      // A drain is the node asking to be left, so the move is the SDK's job and
+      // a button would only get in its way - as long as the move is actually
+      // happening. When it is not, this is the worst screen on the list: an
+      // ordinary deploy would otherwise end every call on that node under a
+      // spinner saying nobody was dropped.
+      return recovering
+        ? {
+            tone: "reconnecting",
+            headlineKey: "forge.call_stage.status_moving",
+            detailKey: "forge.call_stage.status_moving_detail",
+            canRetry: false,
+          }
+        : {
+            tone: "failed",
+            headlineKey: "forge.call_stage.status_move_failed",
+            detailKey: "forge.call_stage.status_move_failed_detail",
+            canRetry: true,
+          };
+    case "closed_by_client":
+      return { tone: "ended", headlineKey: LEFT, canRetry: false };
+    default:
+      return recovering
+        ? {
+            tone: "reconnecting",
+            headlineKey: "forge.call_stage.status_reconnecting",
+            detailKey: "forge.call_stage.status_reconnecting_detail",
+            canRetry: true,
+          }
+        : {
+            tone: "failed",
+            headlineKey: "forge.call_stage.status_lost",
+            detailKey: "forge.call_stage.status_lost_detail",
+            canRetry: true,
+          };
+  }
+}
+
+/**
+ * What a control publishes, in the vocabulary the SDK sends.
+ *
+ * The SOURCE, not the grant's kind, and the difference is the whole point:
+ * `room.publish(track, source)` puts one of these three words on the wire and
+ * the node decides against it. A control asking about "audio" would be asking
+ * a question no publish ever asks.
+ *
+ * Re-exported from the protocol rather than restated, because a second list of
+ * the same three words is a second list that can drift from the one the node
+ * reads.
+ */
+export type { PublishSource };
+
+/**
+ * Should this control be drawn at all?
+ *
+ * A UI hint and nothing more. The node checks the same grant on the publish
+ * itself and its answer is the one that counts, so hiding a button here is
+ * about not offering something that will be refused, never about enforcing
+ * anything. `publishKinds` absent means every kind, which is what the protocol
+ * says and what the node does.
+ *
+ * `mayPublish` is the protocol's own function, the same one the node calls, and
+ * that is deliberate rather than tidy. A grant is written in kinds ("audio",
+ * "video", "screen") and a publish declares a source ("microphone", "camera",
+ * "screen"), so a second copy of the translation living here is a second copy
+ * that can disagree with the node - and a button offered for a publish that is
+ * about to be refused is worse than no button at all.
+ *
+ * The track kind is implied by the source, because these three are the only
+ * sources this UI has: a microphone is audio and the other two are video.
+ */
+export function canPublishSource(grants: MediaGrants | undefined, source: PublishSource): boolean {
+  return mayPublish(grants, { source, trackKind: source === "microphone" ? "audio" : "video" });
+}