@tribe-nest/forge 3.31.0 → 3.34.0

package/src/ui/media/_tests/CallStage.spec.tsx

@@ -5,8 +5,10 @@ import { afterEach, beforeAll, describe, expect, it, vi } from "vitest";
 
 import { MediaRoomProvider, type MediaRoomProviderProps } from "@tribe-nest/media-client/react";
 import type { MediaDevice, MediaTransport } from "@tribe-nest/media-client";
+import { MediaError } from "@tribe-nest/media-protocol";
 
 import { CallStage } from "../CallStage";
+import { ForgeI18nProvider } from "../../../i18n";
 import { ForgeThemeProvider, type ForgeTheme } from "../../theme/ForgeThemeProvider";
 import { FakeNode, settle } from "./fakeNode";
 
@@ -67,7 +69,14 @@ const fakeTransport = (): MediaTransport => ({
   id: "t-1",
   async produce(input) {
     produced.push(String((input.appData as { source?: string } | undefined)?.source));
-    return { id: `p-local-${produced.length}`, kind: "audio", closed: false, pause: vi.fn(), resume: vi.fn(), close: vi.fn() };
+    return {
+      id: `p-local-${produced.length}`,
+      kind: "audio",
+      closed: false,
+      pause: vi.fn(),
+      resume: vi.fn(),
+      close: vi.fn(),
+    };
   },
   async consume(input) {
     return {
@@ -105,27 +114,36 @@ const FAST_RECOVERY: Recovery = { baseMs: 1, maxMs: 4, factor: 1, jitter: "none"
 const mount = (
   node: FakeNode,
   children: ReactNode,
-  options: { autoSubscribe?: boolean; reconnect?: Recovery } = {},
+  options: { autoSubscribe?: boolean; reconnect?: Recovery; locale?: string } = {},
 ) =>
   render(
-    <ForgeThemeProvider theme={theme}>
-      <MediaRoomProvider
-        getCredentials={() => ({ mediaUrl: "wss://media.example", token: "t" })}
-        device={fakeDevice}
-        webSocket={node.factory}
-        autoSubscribe={options.autoSubscribe ?? false}
-        reconnect={options.reconnect ?? NO_RECOVERY}
-      >
-        {children}
-      </MediaRoomProvider>
-    </ForgeThemeProvider>,
+    <ForgeI18nProvider locale={options.locale ?? "en"}>
+      <ForgeThemeProvider theme={theme}>
+        <MediaRoomProvider
+          getCredentials={() => ({ mediaUrl: "wss://media.example", token: "t" })}
+          device={fakeDevice}
+          webSocket={node.factory}
+          autoSubscribe={options.autoSubscribe ?? false}
+          reconnect={options.reconnect ?? NO_RECOVERY}
+        >
+          {children}
+        </MediaRoomProvider>
+      </ForgeThemeProvider>
+    </ForgeI18nProvider>,
   );
 
-/** A permission prompt and a capture, as the browser would give them. */
-const stubCapture = () => {
-  const track = { kind: "audio", stop: vi.fn(), enabled: true } as unknown as MediaStreamTrack & {
-    stop: ReturnType<typeof vi.fn>;
-  };
+/**
+ * A permission prompt and a capture, as the browser would give them.
+ *
+ * The track is an `EventTarget`, as a real `MediaStreamTrack` is, so a spec can
+ * end it the way the browser's own "Stop sharing" bar does.
+ */
+const stubCapture = (kind: "audio" | "video" = "audio") => {
+  const target = new EventTarget() as EventTarget & { kind: string; stop: ReturnType<typeof vi.fn>; enabled: boolean };
+  target.kind = kind;
+  target.stop = vi.fn();
+  target.enabled = true;
+  const track = target as unknown as MediaStreamTrack & { stop: ReturnType<typeof vi.fn> };
   const getUserMedia = vi.fn(async () => ({ getTracks: () => [track] }) as unknown as MediaStream);
   Object.defineProperty(navigator, "mediaDevices", {
     configurable: true,
@@ -381,7 +399,8 @@ describe("the grid", () => {
 
     const { container, getByTestId } = mount(node, <CallStage />);
     await waitFor(() => expect(getByTestId("tile-ben")).toBeTruthy());
-    const order = () => [...container.querySelectorAll("[data-testid^='tile-']")].map((n) => n.getAttribute("data-testid"));
+    const order = () =>
+      [...container.querySelectorAll("[data-testid^='tile-']")].map((n) => n.getAttribute("data-testid"));
     const before = order();
 
     node.event({ event: "activeSpeakers", producerIds: ["p-ben-audio"] });
@@ -466,6 +485,47 @@ describe("the connection state, said honestly", () => {
     expect(getByText("Try again")).toBeTruthy();
   });
 
+  /**
+   * The ticket endpoint said no BEFORE any socket existed. This used to wedge
+   * the room on "Connecting" for ever (the SDK never ran its close path for a
+   * failure with no socket), and the docblocks promising the server's refusal
+   * would be shown verbatim could not be kept. Now it is a refusal like any
+   * other: the sentence, and a control.
+   */
+  it("shows the credential endpoint's refusal verbatim, with a retry, rather than a spinner", async () => {
+    const node = new FakeNode({});
+    let attempts = 0;
+    const { getByRole, getByText } = render(
+      <ForgeThemeProvider theme={theme}>
+        <MediaRoomProvider
+          getCredentials={() => {
+            attempts += 1;
+            if (attempts === 1) {
+              throw new MediaError("bad_request", "The room opens 15 minutes before the session.");
+            }
+            return { mediaUrl: "wss://media.example", token: "t" };
+          }}
+          device={fakeDevice}
+          webSocket={node.factory}
+          autoSubscribe={false}
+          reconnect={NO_RECOVERY}
+        >
+          <CallStage />
+        </MediaRoomProvider>
+      </ForgeThemeProvider>,
+    );
+
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Could not join this call"));
+    expect(getByRole("status").textContent).toContain("The room opens 15 minutes before the session.");
+    expect(getByRole("status").textContent).not.toContain("Connection lost");
+
+    // And Try again is not decoration: the next attempt fetches a ticket again
+    // and gets in.
+    fireEvent.click(getByText("Try again"));
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Connected"));
+    expect(attempts).toBe(2);
+  });
+
   it("says the call ended when the node closes the room", async () => {
     const node = new FakeNode({});
     const { getByRole } = mount(node, <CallStage />);
@@ -683,3 +743,189 @@ describe("the things that must stay visible", () => {
     await waitFor(() => expect(queryByText(/means that person has their camera off/)).toBeTruthy());
   });
 });
+
+/**
+ * The screen speaks the site's language.
+ *
+ * Every string on the call screen was English, written into the component,
+ * against Forge's own convention: a German site rendered a German account page
+ * with an English call in the middle of it, and `callStatus` returned sentences
+ * a translator could not reach. This pins that the SAME component, under the
+ * SAME provider every Forge component reads, is German when the site is.
+ */
+describe("the screen is translated", () => {
+  it("renders the status and the controls in the site's language", async () => {
+    const node = new FakeNode({});
+    const { getByRole, getByText, queryByText } = mount(node, <CallStage />, { locale: "de" });
+
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Verbunden"));
+    expect(getByText("Stummschaltung aufheben")).toBeTruthy();
+    expect(getByText("Kamera starten")).toBeTruthy();
+    expect(getByText("Verlassen")).toBeTruthy();
+    expect(getByText(/In diesem Anruf:/).textContent).toBe("In diesem Anruf: 1");
+    expect(queryByText("Unmute")).toBeNull();
+  });
+
+  it("keeps the server's own sentence verbatim inside a translated status", async () => {
+    const node = new FakeNode({});
+    const { getByRole } = mount(node, <CallStage />, { locale: "de" });
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Verbunden"));
+
+    node.event({ event: "roomClosed", reason: "the host ended it" });
+
+    // The headline is ours and is German; the reason is the server's and is not
+    // put through a translator, because a friendlier version of a refusal is a
+    // lie about why.
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Der Anruf ist beendet"));
+    expect(getByRole("status").textContent).toContain("the host ended it");
+  });
+
+  it("falls back to English outside any i18n provider, so a site without one still gets a call", async () => {
+    const node = new FakeNode({});
+    const { getByRole } = render(
+      <ForgeThemeProvider theme={theme}>
+        <MediaRoomProvider
+          getCredentials={() => ({ mediaUrl: "wss://media.example", token: "t" })}
+          device={fakeDevice}
+          webSocket={node.factory}
+          autoSubscribe={false}
+          reconnect={NO_RECOVERY}
+        >
+          <CallStage />
+        </MediaRoomProvider>
+      </ForgeThemeProvider>,
+    );
+
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Connected"));
+  });
+});
+
+/**
+ * Mute is a pause, not a second permission prompt.
+ *
+ * The toggles were unpublish-then-publish, and every publish starts with
+ * `getUserMedia`. Safari asks permission on EVERY call to it, so a person on an
+ * iPad was asked whether the site may use the microphone each time they
+ * unmuted. Now the first press captures and every press after that pauses or
+ * resumes the publication the room already holds.
+ */
+describe("mute and camera-off keep the capture", () => {
+  it("mutes and unmutes with ONE capture, and tells the node each time", async () => {
+    const { getUserMedia } = stubCapture();
+    const node = new FakeNode({});
+    const { getByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByText("Unmute")).toBeTruthy());
+    fireEvent.click(getByText("Unmute"));
+    await waitFor(() => expect(getByText("Mute")).toBeTruthy());
+
+    fireEvent.click(getByText("Mute"));
+    await waitFor(() => expect(getByText("Unmute")).toBeTruthy());
+    expect(node.received.filter((f) => f.method === "pauseProducer")).toHaveLength(1);
+    // Paused, not closed: the microphone is still published, just silent.
+    expect(node.received.filter((f) => f.method === "closeProducer")).toHaveLength(0);
+
+    fireEvent.click(getByText("Unmute"));
+    await waitFor(() => expect(getByText("Mute")).toBeTruthy());
+    expect(node.received.filter((f) => f.method === "resumeProducer")).toHaveLength(1);
+    // The whole point: one prompt for the whole call.
+    expect(getUserMedia).toHaveBeenCalledTimes(1);
+    expect(produced).toEqual(["microphone"]);
+  });
+
+  it("shows the name in the local preview while the camera is paused, and explains the light behind a ?", async () => {
+    stubCapture("video");
+    const node = new FakeNode({});
+    const { getByText, getByTestId, getByLabelText, queryByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByText("Start camera")).toBeTruthy());
+    fireEvent.click(getByText("Start camera"));
+    await waitFor(() => expect(getByText("Stop camera")).toBeTruthy());
+    await waitFor(() => expect(getByTestId("tile-local").querySelector("video")).toBeTruthy());
+
+    fireEvent.click(getByText("Stop camera"));
+
+    // What the others see is the name, so that is what the preview shows.
+    await waitFor(() => expect(getByText("Start camera")).toBeTruthy());
+    await waitFor(() => expect(getByTestId("tile-local").querySelector("video")).toBeNull());
+    expect(node.received.filter((f) => f.method === "pauseProducer")).toHaveLength(1);
+    // The camera stays open (the light can stay on), and that is an explanation,
+    // so it lives behind a ? with a name that says what it explains.
+    expect(queryByText(/keeps the camera open/)).toBeNull();
+    fireEvent.click(getByLabelText("What does Stop camera do?"));
+    await waitFor(() => expect(queryByText(/keeps the camera open/)).toBeTruthy());
+  });
+});
+
+/**
+ * The browser can end a share without asking us.
+ *
+ * Chrome and Firefox draw their own "Stop sharing" bar over a screen share.
+ * Nothing about it went near `unpublish`, so the node kept a producer nobody
+ * was feeding, everybody else kept a frozen tile, and this button read "Stop
+ * sharing" about a share that had ended.
+ */
+describe("a screen share stopped from the browser's own bar", () => {
+  it("is unpublished, and the control follows", async () => {
+    const { track } = stubCapture("video");
+    const node = new FakeNode({});
+    const { getByText } = mount(node, <CallStage />);
+
+    await waitFor(() => expect(getByText("Share screen")).toBeTruthy());
+    fireEvent.click(getByText("Share screen"));
+    await waitFor(() => expect(getByText("Stop sharing")).toBeTruthy());
+
+    track.dispatchEvent(new Event("ended"));
+
+    await waitFor(() => expect(getByText("Share screen")).toBeTruthy());
+    expect(node.received.filter((f) => f.method === "closeProducer")).toHaveLength(1);
+  });
+});
+
+/**
+ * A recovered connection is not a recovered microphone, and the screen says so.
+ *
+ * The drop stops every local capture (right: a light left on over a dead
+ * session is retained capture) and the SDK does not turn it back on by itself
+ * (also right: capture is a permission, and it is the person's press). What
+ * was wrong is that nothing then told them. The room came back, the status
+ * read "Connected", and a coach who had been talking for ten minutes was
+ * talking to nobody until the client asked whether they were still there.
+ */
+describe("what a drop took away is said, once the room is back", () => {
+  it("names the microphone, and stops once it is back on", async () => {
+    stubCapture();
+    const node = new FakeNode({});
+    const { getByText, getByRole, queryByText } = mount(node, <CallStage />, { reconnect: FAST_RECOVERY });
+
+    await waitFor(() => expect(getByText("Unmute")).toBeTruthy());
+    fireEvent.click(getByText("Unmute"));
+    await waitFor(() => expect(getByText("Mute")).toBeTruthy());
+
+    node.socket.drop();
+
+    await waitFor(() => expect(node.sockets.length).toBe(2));
+    await waitFor(() => expect(getByRole("status").textContent).toContain("Connected"));
+    // Content, not a hint: this is the thing they have to act on.
+    await waitFor(() => expect(queryByText(/Your microphone was turned off/)).toBeTruthy());
+    expect(getByText("Unmute")).toBeTruthy();
+
+    fireEvent.click(getByText("Unmute"));
+    await waitFor(() => expect(getByText("Mute")).toBeTruthy());
+    await waitFor(() => expect(queryByText(/Your microphone was turned off/)).toBeNull());
+  });
+
+  it("says nothing after a deliberate leave", async () => {
+    stubCapture();
+    const node = new FakeNode({});
+    const { getByText, queryByText } = mount(node, <CallStage />, { reconnect: FAST_RECOVERY });
+    await waitFor(() => expect(getByText("Unmute")).toBeTruthy());
+    fireEvent.click(getByText("Unmute"));
+    await waitFor(() => expect(getByText("Mute")).toBeTruthy());
+
+    fireEvent.click(getByText("Leave"));
+
+    await settle(30);
+    expect(queryByText(/Your microphone was turned off/)).toBeNull();
+  });
+});

package/src/ui/media/_tests/bookingSession.spec.tsx

@@ -1,6 +1,7 @@
 // @vitest-environment jsdom
 import { beforeEach, describe, expect, it, vi } from "vitest";
 import { renderHook } from "@testing-library/react";
+import { MediaError } from "@tribe-nest/media-protocol";
 
 import {
   BOOKING_CALL_CLOSES_MINUTES_AFTER,
@@ -167,6 +168,53 @@ describe("useBookingSessionCredentials", () => {
     expect(credentials.role).toBe("guest");
   });
 
+  /**
+   * The server's refusal must reach the screen as the server's SENTENCE. Left
+   * as an axios error, the SDK read it as a dropped socket and the screen said
+   * "Connection lost" about a call the person was never in.
+   */
+  it("turns the server's refusal into a MediaError carrying its message", async () => {
+    post.mockRejectedValueOnce({
+      response: { status: 409, data: { message: "The room opens 15 minutes before the session." } },
+    });
+    const getCredentials = renderHook(() => useBookingSessionCredentials("booking-1")).result.current;
+
+    const error: unknown = await getCredentials().then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+
+    expect(error).toBeInstanceOf(MediaError);
+    expect((error as MediaError).message).toBe("The room opens 15 minutes before the session.");
+    expect((error as MediaError).code).toBe("bad_request");
+    expect((error as MediaError).retryable).toBe(false);
+  });
+
+  it("maps a 401 and a 404 to the SDK's own codes, and a 5xx to a retryable internal", async () => {
+    const getCredentials = renderHook(() => useBookingSessionCredentials("booking-1")).result.current;
+    const refusal = async (status: number) => {
+      post.mockRejectedValueOnce({ response: { status, data: { message: `status ${status}` } } });
+      return getCredentials().then(
+        () => undefined,
+        (e: unknown) => e as MediaError,
+      );
+    };
+
+    expect((await refusal(401))?.code).toBe("unauthorized");
+    expect((await refusal(404))?.code).toBe("no_such_room");
+    const internal = await refusal(503);
+    expect(internal?.code).toBe("internal");
+    expect(internal?.retryable).toBe(true);
+  });
+
+  it("leaves a network failure alone, because that one really is a connection problem", async () => {
+    const network = new Error("Network Error");
+    post.mockRejectedValueOnce(network);
+    const getCredentials = renderHook(() => useBookingSessionCredentials("booking-1")).result.current;
+
+    await expect(getCredentials()).rejects.toBe(network);
+  });
+
   it("keeps ONE callback identity per booking", () => {
     const { result, rerender } = renderHook(() => useBookingSessionCredentials("booking-1"));
     const first = result.current;

package/src/ui/media/_tests/callState.spec.ts

@@ -3,6 +3,7 @@ import { describe, expect, it } from "vitest";
 import type { ProducerEntry } from "@tribe-nest/media-client";
 import type { Peer } from "@tribe-nest/media-protocol";
 
+import { FORGE_LOCALES, getForgeMessages, translateForge } from "../../../i18n";
 import { callHeadCount, callStatus, callTiles, canPublishSource, remoteAudioProducerIds } from "../callState";
 
 /**
@@ -22,12 +23,12 @@ const peer = (identity: string, name?: string): Peer => ({
 /** The recording process, which joins the room as a real peer. */
 const recorder = (identity: string): Peer => ({ identity, kind: "egress" });
 
-const producer = (
-  producerId: string,
-  identity: string,
-  kind: "audio" | "video",
-  paused = false,
-): ProducerEntry => ({ producerId, identity, kind, paused });
+const producer = (producerId: string, identity: string, kind: "audio" | "video", paused = false): ProducerEntry => ({
+  producerId,
+  identity,
+  kind,
+  paused,
+});
 
 describe("callTiles keeps the grid from collapsing", () => {
   it("draws a tile for somebody with NO video at all", () => {
@@ -256,21 +257,67 @@ describe("callStatus is honest about what is happening", () => {
     // other is worth pressing a button about.
     expect(dropped.tone).toBe("reconnecting");
     expect(refused.tone).toBe("failed");
-    expect(dropped.headline).not.toBe(refused.headline);
+    expect(dropped.headlineKey).not.toBe(refused.headlineKey);
   });
 
   it("shows the server's own words for a refusal rather than a friendly lie", () => {
-    expect(callStatus({ connectionState: "reconnecting", error: { type: "refused", code: "room_closed" } }).detail).toBe(
-      "room_closed",
-    );
+    // As TEXT, not as a key: a refusal is the one thing on the screen that must
+    // never be put through a translator, because the server's sentence is the
+    // reason and a friendlier version of it is a lie about why.
+    const refusedByCode = callStatus({
+      connectionState: "reconnecting",
+      error: { type: "refused", code: "room_closed" },
+    });
+    expect(refusedByCode.detailText).toBe("room_closed");
+    expect(refusedByCode.detailKey).toBeUndefined();
     expect(
       callStatus({
         connectionState: "reconnecting",
         error: { type: "refused", code: "unauthorized", message: "this session has ended" },
-      }).detail,
+      }).detailText,
     ).toBe("this session has ended");
   });
 
+  /**
+   * Keys, not sentences. `callStatus` has no locale, and every English string
+   * it used to return was rendered as-is on sites whose every other word was
+   * German. What it names has to exist in every bundle, or a German visitor
+   * reads a raw dotted key at the one moment they are being told the call is
+   * over.
+   */
+  it("names copy by key, and every key it can produce exists in every bundle", () => {
+    const seen = new Set<string>();
+    const inputs: Parameters<typeof callStatus>[0][] = [
+      { connectionState: "idle", error: undefined },
+      { connectionState: "connecting", error: undefined },
+      { connectionState: "connected", error: undefined },
+      { connectionState: "connected", error: undefined, phase: "closed" },
+      { connectionState: "closed", error: { type: "closed_by_client" } },
+      { connectionState: "closed", error: { type: "room_closed", reason: "x" } },
+      { connectionState: "reconnecting", error: { type: "refused", code: "unauthorized" } },
+      { connectionState: "reconnecting", error: { type: "room_closed", reason: "x" } },
+      { connectionState: "reconnecting", error: { type: "draining", reconnectAfterMs: 1 }, recovering: true },
+      { connectionState: "reconnecting", error: { type: "draining", reconnectAfterMs: 1 } },
+      { connectionState: "reconnecting", error: { type: "closed_by_client" } },
+      { connectionState: "reconnecting", error: { type: "socket_closed" }, recovering: true },
+      { connectionState: "reconnecting", error: { type: "socket_closed" } },
+    ];
+    for (const input of inputs) {
+      const status = callStatus(input);
+      seen.add(status.headlineKey);
+      if (status.detailKey) seen.add(status.detailKey);
+    }
+    for (const locale of FORGE_LOCALES) {
+      const bundle = getForgeMessages(locale);
+      const missing = [...seen].filter((key) => !key.startsWith("forge.call_stage.") || bundle[key] === undefined);
+      expect(missing, `${locale} is missing: ${missing.join(", ")}`).toEqual([]);
+    }
+    // And translated English reads as the sentences the screen specs assert on.
+    expect(translateForge("en", callStatus({ connectionState: "connected", error: undefined }).headlineKey)).toBe(
+      "Connected",
+    );
+  });
+
   it("does not offer a retry for something retrying cannot fix", () => {
     expect(callStatus({ connectionState: "connected", error: undefined }).canRetry).toBe(false);
     expect(callStatus({ connectionState: "connecting", error: undefined }).canRetry).toBe(false);
@@ -319,7 +366,7 @@ describe("callStatus is honest about what is happening", () => {
       // ever opened.
       expect(stranded.tone).toBe("failed");
       expect(stranded.canRetry).toBe(true);
-      expect(stranded.headline).not.toBe(moving.headline);
+      expect(stranded.headlineKey).not.toBe(moving.headlineKey);
     });
 
     it("stops saying `reconnecting` about a dropped socket nothing is retrying", () => {
@@ -330,8 +377,8 @@ describe("callStatus is honest about what is happening", () => {
       });
       const givenUp = callStatus({ connectionState: "reconnecting", error: { type: "socket_closed", code: 1006 } });
 
-      expect(retrying.headline).toBe("Connection lost, reconnecting");
-      expect(givenUp.headline).toBe("Connection lost");
+      expect(translateForge("en", retrying.headlineKey)).toBe("Connection lost, reconnecting");
+      expect(translateForge("en", givenUp.headlineKey)).toBe("Connection lost");
       expect(givenUp.tone).toBe("failed");
       expect(givenUp.canRetry).toBe(true);
     });
@@ -359,7 +406,7 @@ describe("callStatus is honest about what is happening", () => {
     for (const connectionState of ["closed", "reconnecting"] as const) {
       const status = callStatus({ connectionState, error: { type: "room_closed", reason: "the host ended it" } });
       expect(status.tone).toBe("ended");
-      expect(status.detail).toBe("the host ended it");
+      expect(status.detailText).toBe("the host ended it");
     }
   });
 
@@ -376,7 +423,7 @@ describe("callStatus is honest about what is happening", () => {
     });
 
     expect(status.tone).toBe("ended");
-    expect(status.detail).toBe("the host ended it");
+    expect(status.detailText).toBe("the host ended it");
   });
 
   it("is live only when the room says connected", () => {

package/src/ui/media/bookingSession.tsx

@@ -1,7 +1,7 @@
 import { useCallback, type ReactNode } from "react";
 
 import { MediaRoomProvider } from "@tribe-nest/media-client/react";
-import type { MediaGrants } from "@tribe-nest/media-protocol";
+import { MediaError, type MediaErrorCode, type MediaGrants } from "@tribe-nest/media-protocol";
 
 import { useForge } from "../../provider/ForgeProvider";
 
@@ -96,11 +96,42 @@ export function useBookingSessionCredentials(bookingId: string): () => Promise<B
   // function on every parent render, and `<MediaRoomProvider>` holds its
   // options in a ref precisely because that is the default mistake.
   return useCallback(async () => {
-    const res = await client.post(`/public/coaching/bookings/${bookingId}/session/join`, {});
-    return res.data as BookingSessionCredentials;
+    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. */
@@ -136,59 +167,16 @@ export function BookingCallProvider({
   );
 }
 
-/** How early the room opens, and how long it stays open. Mirrors the server. */
-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.
+ * 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 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,
-  };
-}
+export {
+  BOOKING_CALL_CLOSES_MINUTES_AFTER,
+  BOOKING_CALL_OPENS_MINUTES_BEFORE,
+  bookingCallWindow,
+  type BookingCallSubject,
+  type BookingCallWindow,
+} from "./bookingWindow";