@tribe-nest/forge 3.41.1 → 3.42.1

package/src/ui/styled/broadcast/BroadcastPlayer.tsx

@@ -28,7 +28,26 @@ import {
 // `mediasoup-client`, and a value import here would put a browser-only package
 // on the server path of every site that loads `@tribe-nest/forge/ui`. It is
 // reached through the `import()` in the effect below, which no server runs.
+import type { BroadcastMoqStageProps } from "./BroadcastMoqStage";
 import type { BroadcastRealtimeStageProps } from "./BroadcastRealtimeStage";
+
+/** The relay lane's half of a `viewer-token` response. */
+type BroadcastMoqCredentials = { url: string; name: string; expiresAt: string; path: string };
+
+/**
+ * Renders the lazily-loaded relay stage.
+ *
+ * A named component rather than `<moqStage ... />` inline: a component read out
+ * of state and rendered directly is a new type on every render that produces a
+ * different one, which unmounts and remounts the player underneath. Naming it
+ * here keeps the element type stable across renders.
+ */
+function MoqStageRenderer({
+  Stage,
+  ...props
+}: BroadcastMoqStageProps & { Stage: ComponentType<BroadcastMoqStageProps> }) {
+  return <Stage {...props} />;
+}
 import { BroadcastPollPanel } from "./BroadcastPollPanel";
 import { useBroadcastPoll } from "../../headless/broadcast/useBroadcastPoll";
 import type { BroadcastPoll } from "../../../data/queries/useBroadcasts";
@@ -132,10 +151,22 @@ export interface BroadcastPlayerProps {
  *
  * ## Why the quality picker is not on the new path
  *
- * The plane has no simulcast. Every viewer receives the program feed's single
- * encoding, so High, Medium and Low would be three controls that change
- * nothing. A control that lies about what it does is worse than no control.
+ * The plane DOES publish three simulcast layers now (`REALTIME_PROGRAM_VIDEO`),
+ * so the old reason for leaving the picker off - "there is only one encoding,
+ * three buttons would all do nothing" - no longer holds. What holds instead is
+ * that the node's own layer choice tracks the viewer's actual bandwidth, and a
+ * manual override is a way to pin yourself to a layer your connection cannot
+ * carry. The picker below stays on the v1 Cloudflare path, which is where it
+ * was built and where it is wired.
  */
+/**
+ * How long the v1 Cloudflare lane may deliver nothing before HLS takes over.
+ *
+ * Long enough that a slow negotiation is not cut off, short enough that a
+ * viewer is not staring at a spinner while the broadcast is being published.
+ */
+const LEGACY_REALTIME_DEADLINE_MS = 12_000;
+
 export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: BroadcastPlayerProps) {
   const t = useForgeT();
   const theme = useForgeTheme();
@@ -152,6 +183,21 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
   const videoRef = useRef<HTMLVideoElement>(null);
   const audioRef = useRef<HTMLAudioElement>(null);
   const videoContainerRef = useRef<HTMLDivElement>(null);
+  /**
+   * The v1 Cloudflare lane gave up, so HLS may have the viewer.
+   *
+   * The plane and the relay both fall back: every way they can fail ends at
+   * HLS, and `chooseBroadcastStage` holds that rule. The v1 lane had no such
+   * exit. `isLegacyRealtime` SUPPRESSED the HLS stage outright, so a broadcast
+   * whose Cloudflare room was gone - retired, expired, never created for a v2
+   * broadcast that still carries a stale `realtimeConfig` - showed a spinner
+   * and nothing else, for ever, with no way for the viewer to reach a stream
+   * that was being published the whole time.
+   *
+   * Reported from production as a live HLS broadcast showing nothing on the
+   * site.
+   */
+  const [legacyFailed, setLegacyFailed] = useState(false);
   const [isAudioLoaded, setIsAudioLoaded] = useState(false);
   const [isVideoLoaded, setIsVideoLoaded] = useState(false);
   const [isPlaying, setIsPlaying] = useState(false);
@@ -178,6 +224,17 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
   const [PlaneStage, setPlaneStage] = useState<ComponentType<BroadcastRealtimeStageProps> | null>(null);
   const [credentialsReady, setCredentialsReady] = useState(false);
   const [credentialsError, setCredentialsError] = useState<BroadcastCredentialsError | null>(null);
+  /**
+   * The relay lane, as `viewer-token` reported it.
+   *
+   * Held separately from the plane credentials because the two are independent
+   * answers: an instance may offer a relay and no plane, a plane and no relay,
+   * or both. `planeAvailable` reads the plane's half off the same response.
+   */
+  const [moqStage, setMoqStage] = useState<ComponentType<BroadcastMoqStageProps> | null>(null);
+  const [moqCredentials, setMoqCredentials] = useState<BroadcastMoqCredentials | null>(null);
+  const [moqFailed, setMoqFailed] = useState(false);
+  const [planeAvailable, setPlaneAvailable] = useState(true);
   const [roomState, setRoomState] = useState<BroadcastRoomState | undefined>(undefined);
   /** The ticket the probe already minted, spent on the SDK's FIRST attempt. */
   const primedCredentials = useRef<BroadcastViewerCredentials | null>(null);
@@ -223,6 +280,24 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
         if (cancelled) return;
         primedCredentials.current = credentials;
         setPlaneStage(() => module.BroadcastRealtimeStage);
+        // A response with no `mediaUrl` is a relay-only instance. Recording it
+        // is what stops the chooser falling to a plane room that is not there
+        // if the relay lane later gives up.
+        setPlaneAvailable(Boolean((credentials as { mediaUrl?: string }).mediaUrl));
+        const moq = (credentials as { moq?: BroadcastMoqCredentials }).moq ?? null;
+        setMoqCredentials(moq);
+        if (moq) {
+          import("./BroadcastMoqStage")
+            .then((moqModule) => {
+              if (cancelled) return;
+              setMoqStage(() => moqModule.BroadcastMoqStage);
+            })
+            .catch(() => {
+              if (cancelled) return;
+              // The relay chunk did not load. The lane is over before it began.
+              setMoqFailed(true);
+            });
+        }
         setCredentialsReady(true);
       })
       .catch((error: unknown) => {
@@ -266,17 +341,33 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
    */
   const handleRoomState = useCallback((next: BroadcastRoomState) => setRoomState(next), []);
 
+  /**
+   * The relay lane gave up. Never cleared back to false, for the same reason
+   * `roomState` is never cleared: the failure is why we left, so forgetting it
+   * would choose the relay again, mount it again, and watch it fail again.
+   */
+  const handleMoqFailed = useCallback(() => setMoqFailed(true), []);
+
   const stageInput = useMemo(
-    () => ({ realtimeAvailable, credentialsReady, credentialsError, roomState }),
-    [realtimeAvailable, credentialsReady, credentialsError, roomState],
+    () => ({
+      realtimeAvailable,
+      credentialsReady,
+      credentialsError,
+      roomState,
+      moqAvailable: Boolean(moqCredentials && moqStage),
+      moqFailed,
+      planeAvailable,
+    }),
+    [realtimeAvailable, credentialsReady, credentialsError, roomState, moqCredentials, moqStage, moqFailed, planeAvailable],
   );
   const stage = chooseBroadcastStage(stageInput);
+  const showMoq = stage === "moq" && !!moqStage && !!moqCredentials;
   const showPlane = stage === "realtime" && !!PlaneStage;
   // Nothing is mounted while the ticket is in flight. `react-player` builds an
   // hls.js instance on mount and starts fetching immediately, so rendering the
   // HLS stage "meanwhile" made every realtime viewer download the broadcast a
   // second time, over the CDN, for a stage that was about to be replaced.
-  const showHls = stage === "hls" && !isLegacyRealtime;
+  const showHls = stage === "hls" && (!isLegacyRealtime || legacyFailed);
   const fellBack = broadcastFellBack(stageInput);
 
   const { data: audienceData } = useBroadcastAudience(broadcast.id, !broadcast.endedAt);
@@ -295,6 +386,24 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
     });
   }, [comments]);
 
+  /**
+   * The v1 lane also fails by never arriving, which no `catch` will report.
+   *
+   * A peer connection that negotiates and then delivers no track raises
+   * nothing at all: `subscribe()` resolves, and the viewer watches a spinner.
+   * So the deadline is the backstop, and it is what makes the fallback
+   * guaranteed rather than dependent on the failure being the polite kind.
+   *
+   * Twelve seconds: long enough that a slow negotiation is not cut off, short
+   * enough that a viewer is not staring at nothing while the broadcast runs.
+   */
+  useEffect(() => {
+    if (!isLegacyRealtime || legacyFailed) return;
+    if (isVideoLoaded || isAudioLoaded) return;
+    const timer = setTimeout(() => setLegacyFailed(true), LEGACY_REALTIME_DEADLINE_MS);
+    return () => clearTimeout(timer);
+  }, [isLegacyRealtime, legacyFailed, isVideoLoaded, isAudioLoaded]);
+
   // ── WebRTC subscription, v1 (Cloudflare Calls) ─────────────────────────────
   useEffect(() => {
     const config = broadcast.realtimeConfig;
@@ -345,9 +454,10 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
     };
 
     subscribe().catch(() => {
-      // Nothing useful to say to a viewer here: the spinner over the stage is
-      // already the honest report that no track arrived.
+      // A spinner is not an honest report when there is a stream the viewer
+      // could be watching. Falling back is.
       isSubscribingRef.current = false;
+      setLegacyFailed(true);
     });
     // `sessionApi` is rebuilt each render and is deliberately not a dependency:
     // including it would re-negotiate the peer connection on every render.
@@ -469,10 +579,45 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
   return (
     <div
       style={{
+        /**
+         * The video dominates, and the chat takes what is left.
+         *
+         * `flexWrap` wraps rather than shrinking, so the two panels stacked
+         * the moment their BASES no longer fit on a line - and with both
+         * growing at the same rate, the chat took half of every extra pixel,
+         * so the video was never big even side by side. On an ordinary
+         * desktop that read as a small video sitting on top of a chat.
+         *
+         * The bases below stay on one line down to about 800px, and the video
+         * grows three times faster than the chat, so the space a wider screen
+         * provides goes almost entirely to the picture. Stacking is then what
+         * happens on a genuinely narrow screen, which is where it is right.
+         */
         display: "flex",
         flexWrap: "wrap",
         gap: 32,
-        padding: 16,
+        // No padding at the TOP: the shell and the close button above already
+        // put the player well down the page, and on a phone that was most of
+        // the first screen spent before any video.
+        padding: "0 16px 16px",
+        /**
+         * FILL the parent rather than being sized by what is inside.
+         *
+         * Without this the container was shrink-to-fit, so its width came from
+         * its content - and the HLS stage puts its player in an absolutely
+         * positioned `inset: 0` box (which is what stops the player resizing
+         * its own container on a rendition change). Absolutely positioned
+         * children contribute NO intrinsic width, so the content measured as
+         * almost nothing and the whole player collapsed to about 400px inside a
+         * 1300px column, then wrapped.
+         *
+         * The realtime stages hid it: they render an in-flow `<video>` with a
+         * real intrinsic width, so the same container came out wide enough. It
+         * looked like "HLS stacks and the SFU does not", and it was neither -
+         * it was a container taking its width from whatever happened to be
+         * inside it.
+         */
+        width: "100%",
         maxWidth: 1700,
         marginInline: "auto",
         flex: 1,
@@ -480,7 +625,20 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
         fontFamily: theme.fontFamily,
       }}
     >
-      <div style={{ flex: "1 1 520px", minWidth: 0, ...panel }}>
+      <div style={{ flex: "3 1 420px", minWidth: 0, ...panel }}>
+        {showMoq && moqStage && moqCredentials && (
+          <MoqStageRenderer
+            Stage={moqStage}
+            url={moqCredentials.url}
+            name={moqCredentials.name}
+            // Not muted: this is the broadcast the viewer came for, and the
+            // plane stage does not mute either. The element paints video to a
+            // canvas independently of its audio emitter, so a browser that
+            // blocks autoplay audio still shows a picture rather than nothing.
+            muted={false}
+            onFailed={handleMoqFailed}
+          />
+        )}
         {showPlane && PlaneStage && <PlaneStage getCredentials={getCredentials} onRoomState={handleRoomState} />}
 
         {stage === "pending" && (
@@ -490,7 +648,26 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
         )}
 
         {showHls && (
-          <div data-testid="broadcast-hls-stage" style={{ aspectRatio: "16/9" }}>
+          /*
+            The ratio box, and INSIDE it an absolutely filled box that the
+            player cannot resize.
+
+            `renderPlayer` is host-supplied (the starter passes `react-player`),
+            so this cannot dictate how the player sizes itself - and the
+            conventional `height: "100%"` a player is given resolves against a
+            parent whose height comes from `aspect-ratio`, which is not reliably
+            a definite height. The player then falls back to the stream's
+            intrinsic size and the panel jumps every time HLS changes rendition.
+
+            An absolutely positioned `inset: 0` box HAS a definite height, so a
+            child asking for 100% gets a real answer, and nothing the child does
+            can change the box it is in.
+          */
+          <div
+            data-testid="broadcast-hls-stage"
+            style={{ aspectRatio: "16/9", position: "relative", lineHeight: 0 }}
+          >
+            <div style={{ position: "absolute", inset: 0 }}>
             {renderPlayer ? (
               renderPlayer({ src: broadcast.liveUrl })
             ) : (
@@ -499,9 +676,20 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
                 controls
                 autoPlay
                 playsInline
-                style={{ width: "100%", height: "100%", background: "#000" }}
+                // Same reasoning as the realtime stage below: HLS renditions
+                // change resolution mid-stream too, and `height: 100%` off an
+                // `aspect-ratio` parent leaves the box following the source.
+                style={{
+                  display: "block",
+                  width: "100%",
+                  height: "auto",
+                  aspectRatio: "16 / 9",
+                  objectFit: "contain",
+                  background: "#000",
+                }}
               />
             )}
+            </div>
           </div>
         )}
 
@@ -532,16 +720,51 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
           </div>
         )}
 
-        {isLegacyRealtime && (
+        {isLegacyRealtime && !legacyFailed && (
           <div
             ref={videoContainerRef}
             data-testid="broadcast-realtime-stage"
             onClick={togglePlay}
             onMouseEnter={() => setShowControls(true)}
             onMouseLeave={() => setShowControls(false)}
-            style={{ aspectRatio: "16/9", position: "relative", background: "#000", cursor: "pointer" }}
+            style={{
+              aspectRatio: "16/9",
+              position: "relative",
+              background: "#000",
+              cursor: "pointer",
+              lineHeight: 0,
+            }}
           >
-            <video ref={videoRef} playsInline style={{ width: "100%", height: "100%" }} />
+            {/*
+              The RATIO is on the video element itself, and `height` is `auto`.
+
+              This is the same fix `BroadcastRealtimeStage` carries, and this
+              path is where it was actually needed: it is the one with a quality
+              picker, so the incoming resolution changes whenever the viewer
+              chooses a layer (or the auto policy chooses one for them).
+
+              `height: 100%` did not hold the box still. A percentage height
+              needs a definite parent height, and one derived from the parent's
+              own `aspect-ratio` is not reliably that, so the replaced element
+              fell back to the track's INTRINSIC height and the whole panel
+              jumped on every quality change. `aspect-ratio` with `height: auto`
+              overrides the intrinsic ratio outright: the box is 16/9 of
+              whatever width it is given, whatever arrives on the wire.
+
+              `object-fit: contain` then letterboxes a source that is not 16/9
+              inside that fixed box rather than resizing the box to suit it.
+            */}
+            <video
+              ref={videoRef}
+              playsInline
+              style={{
+                display: "block",
+                width: "100%",
+                height: "auto",
+                aspectRatio: "16 / 9",
+                objectFit: "contain",
+              }}
+            />
             <audio ref={audioRef} />
 
             {(!isAudioLoaded || !isVideoLoaded) && (
@@ -669,7 +892,7 @@ export function BroadcastPlayer({ broadcast, broadcastPass, renderPlayer }: Broa
         </div>
       </div>
 
-      <div style={{ flex: "1 1 340px", maxWidth: 400, height: 600, position: "relative", overflow: "hidden", ...panel }}>
+      <div style={{ flex: "1 1 300px", maxWidth: 400, height: 600, position: "relative", overflow: "hidden", ...panel }}>
         <p style={{ fontSize: 18, padding: 16, borderBottom: `1px solid ${theme.colors.primary}30` }}>
           {t("forge.broadcast_player.chat")}
         </p>

package/src/ui/styled/broadcast/BroadcastRealtimeStage.tsx

@@ -48,9 +48,12 @@ import { programTracks, type BroadcastRoomState } from "./broadcastStage";
  * mute plus a blank screen plus a lie about being able to go back. The HLS
  * stage keeps its transport controls because there the buffer makes them true.
  *
- * There is no quality selector either. The plane has no simulcast: every viewer
- * receives the program feed's single encoding, so a picker offering High,
- * Medium and Low would be three buttons that all do the same nothing.
+ * There is no quality selector either, though not for the reason there used to
+ * be: the program feed publishes three simulcast layers, and the node moves a
+ * viewer between them on its own reading of their connection. A manual override
+ * is mostly a way to pin yourself above what your link can carry, so the choice
+ * stays with the node. What this file owes the viewer instead is that the
+ * SWITCH is invisible, which is what the sizing below is about.
  */
 
 export type BroadcastRealtimeStageProps = {

package/src/ui/styled/broadcast/broadcastStage.spec.ts

@@ -0,0 +1,32 @@
+
+/**
+ * The v1 Cloudflare lane must end at HLS like the other two.
+ *
+ * `isLegacyRealtime` SUPPRESSED the HLS stage outright, so a broadcast whose
+ * Cloudflare room was gone - retired, expired, or never created for a v2
+ * broadcast still carrying a stale `realtimeConfig` - showed a spinner and
+ * nothing else, for ever, while HLS was being published the whole time.
+ * Reported from production as a live broadcast showing nothing on the site.
+ *
+ * The rule lives in the component (it needs the lane's load state, which this
+ * pure chooser has no business knowing), so this pins the SHAPE of it: three
+ * lanes, and every one of them has an exit to HLS.
+ */
+describe("every realtime lane has an exit to HLS", () => {
+  const showHls = (input: { stage: string; isLegacyRealtime: boolean; legacyFailed: boolean }) =>
+    input.stage === "hls" && (!input.isLegacyRealtime || input.legacyFailed);
+
+  it("keeps HLS hidden while the v1 lane is still trying", () => {
+    // Not a regression: mounting an HLS engine beside a working realtime lane
+    // makes the viewer download the broadcast twice.
+    expect(showHls({ stage: "hls", isLegacyRealtime: true, legacyFailed: false })).toBe(false);
+  });
+
+  it("shows HLS once the v1 lane has given up", () => {
+    expect(showHls({ stage: "hls", isLegacyRealtime: true, legacyFailed: true })).toBe(true);
+  });
+
+  it("shows HLS normally when there is no v1 lane at all", () => {
+    expect(showHls({ stage: "hls", isLegacyRealtime: false, legacyFailed: false })).toBe(true);
+  });
+});

package/src/ui/styled/broadcast/broadcastStage.ts

@@ -28,7 +28,16 @@ import type { ConnectionState, DisconnectCause, ProducerEntry, RoomState } from
  * picture.
  */
 
-/** `realtime` is the media plane. `hls` is the stream everybody can always watch. */
+/**
+ * `moq` is a relay, `realtime` is the media plane, and `hls` is the stream
+ * everybody can always watch.
+ *
+ * `moq` outranks `realtime` because the two show the same picture at the same
+ * latency and cost very different amounts: a relay viewer is one more
+ * subscriber on a cached object, and a plane viewer is a WebRTC consumer with
+ * its own SRTP context and its own bandwidth estimate, capped at
+ * `STREAM_V2_REALTIME_VIEWER_CAP` because the node runs out.
+ */
 /**
  * Which stage the player shows.
  *
@@ -37,7 +46,7 @@ import type { ConnectionState, DisconnectCause, ProducerEntry, RoomState } from
  * was showing HLS meanwhile, and an HLS engine starts fetching the moment it
  * mounts, so a realtime viewer pulled segments they would never watch.
  */
-export type BroadcastStage = "realtime" | "hls" | "pending";
+export type BroadcastStage = "moq" | "realtime" | "hls" | "pending";
 
 /**
  * The viewer-token endpoint said no.
@@ -78,6 +87,25 @@ export type BroadcastStageInput = {
   /** The refusal, when the fetch failed. `null` while it has not. */
   credentialsError: BroadcastCredentialsError | null;
   roomState?: BroadcastRoomState;
+  /** The token endpoint returned a relay ticket for this viewer. */
+  moqAvailable?: boolean;
+  /**
+   * The relay lane was tried and is over.
+   *
+   * Separate from `moqAvailable` for the same reason `realtimeIsOver` is
+   * separate from `credentialsReady`: a ticket that exists is not a lane that
+   * is working, and the fallback has to be able to happen after a connection
+   * that started fine.
+   */
+  moqFailed?: boolean;
+  /**
+   * Is the plane lane offered at all?
+   *
+   * `false` on an instance that runs relays and no media plane, which is what
+   * `credentials: null` from `viewer-token` means. Without it the chooser would
+   * fall to `realtime` after a relay failure and mount a room that is not there.
+   */
+  planeAvailable?: boolean;
 };
 
 /**
@@ -115,7 +143,12 @@ export function chooseBroadcastStage(input: BroadcastStageInput): BroadcastStage
   // about to be replaced, so a realtime viewer downloaded the broadcast twice.
   // Nothing is drawn until the answer is known.
   if (!input.credentialsReady) return "pending";
+  // The relay first, and only while it is actually working.
+  if (input.moqAvailable && !input.moqFailed) return "moq";
   if (realtimeIsOver(input.roomState)) return "hls";
+  // The relay failed and there is no plane behind it. `planeAvailable` defaults
+  // to true so every existing caller keeps its behaviour unchanged.
+  if (input.planeAvailable === false) return "hls";
   return "realtime";
 }
 
@@ -135,6 +168,9 @@ export function broadcastFellBack(input: BroadcastStageInput): boolean {
   if (!input.realtimeAvailable) return false;
   if (input.credentialsError) return true;
   if (!input.credentialsReady) return false;
+  // A working relay is not a fallback, it is the best lane there is.
+  if (input.moqAvailable && !input.moqFailed) return false;
+  if (input.moqAvailable && input.moqFailed && input.planeAvailable === false) return true;
   return realtimeIsOver(input.roomState);
 }
 

package/src/ui/styled/broadcast/relayReachable.spec.ts

@@ -0,0 +1,42 @@
+import { describe, expect, it, vi } from "vitest";
+
+import { relayIsReachable } from "./relayReachable";
+
+/**
+ * The lane must be able to give up. `<moq-watch>` retries a refused connection
+ * for ever and never raises an `error` event, so without this the viewer sits
+ * on a dead stage while HLS is being published.
+ */
+describe("probing the MoQ relay before handing a viewer to it", () => {
+  it("is reachable when the fingerprint responds", async () => {
+    expect(await relayIsReachable("https://relay.example/room/name", vi.fn(async () => new Response("")))).toBe(true);
+  });
+
+  it("is NOT reachable when the connection is refused", async () => {
+    // The dev case: no relay running on localhost:4444.
+    const refused = vi.fn(async () => {
+      throw new TypeError("Failed to fetch");
+    });
+    expect(await relayIsReachable("http://localhost:4444/room/name", refused)).toBe(false);
+  });
+
+  it("asks the relay ORIGIN, not the ticketed path", async () => {
+    const fetchImpl = vi.fn(async () => new Response(""));
+    await relayIsReachable("https://relay.example/room/name?jwt=abc", fetchImpl);
+    expect(fetchImpl.mock.calls[0]?.[0]).toBe("https://relay.example/certificate.sha256");
+  });
+
+  it("gives up rather than hanging when nothing answers", async () => {
+    const hangs = vi.fn(
+      (_url: string, init?: { signal?: AbortSignal }) =>
+        new Promise<Response>((_resolve, reject) => {
+          init?.signal?.addEventListener("abort", () => reject(new Error("aborted")));
+        }),
+    );
+    expect(await relayIsReachable("https://relay.example/x", hangs as unknown as typeof fetch, 10)).toBe(false);
+  });
+
+  it("treats an unparseable URL as unreachable rather than throwing", async () => {
+    expect(await relayIsReachable("not a url", vi.fn())).toBe(false);
+  });
+});

package/src/ui/styled/broadcast/relayReachable.ts

@@ -0,0 +1,47 @@
+/**
+ * Is the MoQ relay actually there, before a viewer is handed to it?
+ *
+ * `<moq-watch>` owns its own reconnect loop: a refused connection produces a
+ * console error and a retry, for ever, and never an `error` event. So the
+ * lane's `onFailed` never fires, `chooseBroadcastStage` keeps answering "moq",
+ * and the HLS stage is never mounted - the viewer watches nothing while the
+ * broadcast is being published the whole time.
+ *
+ * A blind timeout would be the wrong fix: it cannot tell a slow relay from a
+ * dead one and would cut off a stream that was about to work. This asks the
+ * question that actually has an answer. The element fetches
+ * `/certificate.sha256` from the relay origin before it connects; if that is
+ * unreachable, so is the relay, and the lane is over before it began.
+ *
+ * The common case is not an outage. It is a developer with no relay running
+ * locally, where the URL is `http://localhost:4444` and correct.
+ */
+export const RELAY_PROBE_TIMEOUT_MS = 3000;
+
+export async function relayIsReachable(
+  url: string,
+  fetchImpl: typeof fetch = fetch,
+  timeoutMs: number = RELAY_PROBE_TIMEOUT_MS,
+): Promise<boolean> {
+  let origin: string;
+  try {
+    origin = new URL("/certificate.sha256", url).toString();
+  } catch {
+    // An unparseable relay URL is not reachable by any definition.
+    return false;
+  }
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    // `no-cors` on purpose: the answer wanted is "did the connection happen",
+    // not what the body says. An opaque response is a reachable relay, and it
+    // keeps this probe from needing CORS the element itself may not need.
+    await fetchImpl(origin, { mode: "no-cors", signal: controller.signal });
+    return true;
+  } catch {
+    return false;
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/ui/styled/broadcast/vendor/moq-watch.bundle.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `@moq/watch`, vendored as a self-contained ESM bundle.
+ *
+ * Side-effect only: importing it registers the `<moq-watch>` custom element.
+ * There is nothing to import by name, which is why this declares an empty
+ * module rather than a surface.
+ *
+ * Built by `scripts/build-moq-player.mjs`; see its header for why this is an
+ * asset rather than a dependency.
+ */
+declare const _default: void;
+export default _default;