@tribe-nest/forge 3.41.1 → 3.42.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.41.1",
+  "version": "3.42.1",
   "publishConfig": {
     "access": "public"
   },
@@ -31,7 +31,7 @@
     "@stripe/react-stripe-js": "^3.8.0",
     "@stripe/stripe-js": "^7.6.1",
     "@tanstack/react-query": "^5.62.7",
-    "@tribe-nest/media-client": "^0.1.0",
+    "@tribe-nest/media-client": "^0.2.1",
     "@tribe-nest/media-protocol": "^1.0.0",
     "axios": "^1.7.9",
     "lucide-react": "^0.510.0",

package/src/_tests/publishedResolvability.spec.ts

@@ -30,12 +30,23 @@ import { join } from "path";
  * creator site, while the whole suite stayed green and the starter's release
  * notes announced the feature.
  *
- * So there are two properties here and they are separate:
+ * So there are three properties here and they are separate:
  *
  *  1. every bare import in the published tree names a package the consumer's
  *     install will actually produce (a dependency, or a peer that npm installs
- *     because it is NOT marked optional), and
- *  2. every workspace package Forge depends on is one npm will publish.
+ *     because it is NOT marked optional),
+ *  2. every workspace package Forge depends on is one npm will publish, and
+ *  3. the RANGE Forge declares for a workspace package accepts the version that
+ *     package is actually at.
+ *
+ * The third failed too, and silently. Forge went on declaring
+ * `"@tribe-nest/media-client": "^0.1.0"` after that package moved to `0.2.0`,
+ * and `^0.1.0` does not accept `0.2.x`. Inside the monorepo nothing shows it -
+ * the symlink means every build, every spec and every `check-types` run sees
+ * the 0.2 source - while a creator site resolved 0.1.1 from npm and got a
+ * `useRemoteTrack` that never detached a media element, so a remount left an
+ * orphan still playing the call's audio. The published surface was a minor
+ * version behind the surface the tests were green against.
  *
  * Specs are excluded: they never ship (`files` is `["src"]`, but a consumer
  * never imports a `.spec` file), and they legitimately reach for vitest, jsdom
@@ -47,6 +58,7 @@ const PACKAGES_ROOT = join(FORGE_ROOT, "..");
 
 type PackageJson = {
   name: string;
+  version?: string;
   private?: boolean;
   files?: string[];
   exports?: Record<string, unknown>;
@@ -181,4 +193,70 @@ describe("what a creator site's install has to produce", () => {
   it("still exports the media entry the Forge manifest advertises", () => {
     expect(forge.exports?.["./media"]).toBe("./src/ui/media/index.ts");
   });
+
+  /**
+   * The declared range has to accept the version the package is AT.
+   *
+   * Deliberately hand-rolled rather than reaching for `semver`: this package
+   * declares its dependencies honestly (that is the whole subject of this
+   * file), and `semver` is only present here as somebody else's transitive.
+   * The cost is that only the range forms this repo actually uses are
+   * understood - anything else fails loudly rather than passing vacuously,
+   * which is the right way round for a guard.
+   */
+  const satisfies = (range: string, version: string): boolean => {
+    const parse = (value: string): [number, number, number] => {
+      const parts = value.split(".").map((n) => Number.parseInt(n, 10));
+      if (parts.length !== 3 || parts.some((n) => !Number.isFinite(n))) {
+        throw new Error(`not a plain semver version: ${value}`);
+      }
+      return [parts[0]!, parts[1]!, parts[2]!];
+    };
+    const atLeast = (a: [number, number, number], b: [number, number, number]) =>
+      a[0] !== b[0] ? a[0] > b[0] : a[1] !== b[1] ? a[1] > b[1] : a[2] >= b[2];
+
+    const [major, minor, patch] = parse(version);
+    if (range === "*") return true;
+    if (/^\d/.test(range)) return range === version; // exact pin
+    if (range.startsWith("^")) {
+      const floor = parse(range.slice(1));
+      if (!atLeast([major, minor, patch], floor)) return false;
+      // Caret on a 0.x version pins the MINOR, which is where a pre-1.0
+      // package puts its breaking changes. `^0.1.0` does not accept `0.2.0`,
+      // and that is exactly the case this test exists for.
+      return floor[0] === 0 ? minor === floor[1] : major === floor[0];
+    }
+    throw new Error(`unsupported range form "${range}" - teach this helper before using it`);
+  };
+
+  it("declares a range that accepts each workspace package's current version", () => {
+    const workspaceDeps = Object.entries(forge.dependencies ?? {}).filter(([name]) =>
+      name.startsWith("@tribe-nest/"),
+    );
+    expect(workspaceDeps.length).toBeGreaterThan(0);
+
+    const stale = workspaceDeps
+      .map(([name, range]) => {
+        const dependency = readPackage(join(PACKAGES_ROOT, name.replace("@tribe-nest/", "")));
+        return { name, range, version: dependency.version };
+      })
+      .filter(({ range, version }) => !satisfies(range, version!))
+      .map(({ name, range, version }) => `${name}: declared ${range}, package is at ${version}`);
+
+    expect(stale).toEqual([]);
+  });
+
+  it("the range check itself knows that a 0.x caret pins the minor", () => {
+    // Without this the test above is only as good as a helper nobody checked,
+    // and the bug it guards is precisely a 0.x caret being read as permissive.
+    expect(satisfies("^0.1.0", "0.1.1")).toBe(true);
+    expect(satisfies("^0.1.0", "0.2.0")).toBe(false);
+    expect(satisfies("^0.2.1", "0.2.1")).toBe(true);
+    expect(satisfies("^0.2.1", "0.2.0")).toBe(false);
+    expect(satisfies("^1.0.0", "1.0.1")).toBe(true);
+    expect(satisfies("^1.0.0", "2.0.0")).toBe(false);
+    expect(satisfies("1.0.1", "1.0.1")).toBe(true);
+    expect(satisfies("1.0.1", "1.0.2")).toBe(false);
+    expect(() => satisfies(">=1.0.0", "1.0.0")).toThrow();
+  });
 });

package/src/data/queries/useAuthActions.ts

@@ -1,6 +1,14 @@
 import { useForge } from "../../provider/ForgeProvider";
 import { useMutation } from "@tanstack/react-query";
 
+/**
+ * Where a Forge site's reset-password page lives.
+ *
+ * Every functional page on a code website is under `/i/`, and the emailed link
+ * is built from whatever the site sends here.
+ */
+export const DEFAULT_RESET_PASSWORD_PATH = "/i/reset-password";
+
 // Stateless account actions (no session state) — kept out of PublicAuthContext.
 //
 // ## Why these hit `/public/sessions/*` and not `/public/accounts/*`
@@ -33,8 +41,8 @@ import { useMutation } from "@tanstack/react-query";
 export function useForgotPassword() {
   const { client, profileId } = useForge();
 
-  return useMutation<unknown, unknown, { email: string; origin?: string; profileId?: string }>({
-    mutationFn: async ({ email, origin, profileId: overrideProfileId }) => {
+  return useMutation<unknown, unknown, { email: string; origin?: string; profileId?: string; resetPath?: string }>({
+    mutationFn: async ({ email, origin, profileId: overrideProfileId, resetPath }) => {
       const contextId = overrideProfileId ?? profileId;
       if (!contextId) {
         // Better than posting without it: the endpoint would 400 on schema
@@ -47,6 +55,11 @@ export function useForgotPassword() {
         // The reset link is built server-side from this, and the association
         // endpoint requires it (the global one treated it as optional).
         origin: origin ?? (typeof window !== "undefined" ? window.location.origin : undefined),
+        // And the PATH, because the backend cannot guess it. Its default is
+        // `apps/client`'s `/reset-password`, which does not exist on a code
+        // website - every functional page there is under `/i/`, so the emailed
+        // link 404'd for everyone on the current default storefront.
+        resetPath: resetPath ?? DEFAULT_RESET_PASSWORD_PATH,
       });
       return res.data;
     },

package/src/ui/styled/ForgotPasswordForm.tsx

@@ -6,12 +6,18 @@ import { useForgeTheme } from "../theme/ForgeThemeProvider";
 export interface ForgotPasswordFormProps {
   /** Href for the "Back to login" / "Login" links. */
   loginHref: string;
+  /**
+   * The path the emailed reset link points at, on this site's own origin.
+   * Defaults to `/i/reset-password`, which is where the starter puts it. Pass
+   * one only if the site moved that route.
+   */
+  resetPath?: string;
 }
 
 const msg = (e: unknown) => (e as { response?: { data?: { message?: string } } })?.response?.data?.message;
 
 /** Themed forgot-password request form, built on `useForgotPassword`. */
-export function ForgotPasswordForm({ loginHref }: ForgotPasswordFormProps) {
+export function ForgotPasswordForm({ loginHref, resetPath }: ForgotPasswordFormProps) {
   const t = useForgeT();
   const theme = useForgeTheme();
   const forgotPassword = useForgotPassword();
@@ -50,7 +56,11 @@ export function ForgotPasswordForm({ loginHref }: ForgotPasswordFormProps) {
     setError("");
     setIsSubmitting(true);
     try {
-      await forgotPassword.mutateAsync({ email, origin: window.location.origin });
+      await forgotPassword.mutateAsync({
+        email,
+        origin: window.location.origin,
+        ...(resetPath ? { resetPath } : {}),
+      });
       setIsSuccess(true);
     } catch (err) {
       setError(msg(err) || t("forge.forgot_password_form.error"));

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

@@ -314,3 +314,44 @@ describe("programTracks", () => {
     expect(tracks.audioProducerIds).toEqual(["a2"]);
   });
 });
+
+describe("the relay lane", () => {
+  const base = {
+    realtimeAvailable: true,
+    credentialsReady: true,
+    credentialsError: null,
+  } as const;
+
+  it("prefers the relay over the plane when both are offered", () => {
+    expect(chooseBroadcastStage({ ...base, moqAvailable: true })).toBe("moq");
+  });
+
+  it("is not a fallback: a working relay is the best lane there is", () => {
+    expect(broadcastFellBack({ ...base, moqAvailable: true })).toBe(false);
+  });
+
+  it("falls to the plane when the relay lane is over and a plane is offered", () => {
+    expect(chooseBroadcastStage({ ...base, moqAvailable: true, moqFailed: true })).toBe("realtime");
+  });
+
+  // The shape of a relay-only instance: `viewer-token` answered with `moq` and
+  // `credentials: null`. Falling to "realtime" here would mount a room that
+  // does not exist and show a black rectangle for ever.
+  it("falls to hls when the relay is over and there is no plane behind it", () => {
+    expect(
+      chooseBroadcastStage({ ...base, moqAvailable: true, moqFailed: true, planeAvailable: false }),
+    ).toBe("hls");
+    expect(
+      broadcastFellBack({ ...base, moqAvailable: true, moqFailed: true, planeAvailable: false }),
+    ).toBe(true);
+  });
+
+  it("still draws nothing while the ticket is in flight", () => {
+    expect(chooseBroadcastStage({ ...base, credentialsReady: false, moqAvailable: true })).toBe("pending");
+  });
+
+  it("leaves every existing caller unchanged", () => {
+    expect(chooseBroadcastStage(base)).toBe("realtime");
+    expect(chooseBroadcastStage({ ...base, realtimeAvailable: false })).toBe("hls");
+  });
+});

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

@@ -0,0 +1,124 @@
+import { useEffect, useRef } from "react";
+
+/**
+ * The relay stage: a broadcast watched over MoQ.
+ *
+ * The player is a VENDORED bundle (`vendor/moq-watch.bundle.js`), not an npm
+ * dependency, because Forge ships source: its `exports` point at `./src/*.ts`
+ * with no build step, so anything it depends on is something every creator site
+ * has to resolve too, and `@moq/json` peer-depends on zod 4 against this repo's
+ * zod 3. See `scripts/build-moq-player.mjs`.
+ *
+ * Loaded LAZILY by the player, never imported on this file's module path,
+ * for the same reason `BroadcastRealtimeStage` is: Forge renders inside
+ * TanStack Start on Cloudflare Workers, and `@moq/watch` reaches for
+ * WebTransport, WebCodecs and a decoder worker the moment it is evaluated.
+ * An effect is code no server ever runs.
+ *
+ * The element is created imperatively rather than written as JSX because it is
+ * a custom element: JSX would need an ambient declaration in every consuming
+ * app, and `document.createElement` needs none.
+ */
+
+export type BroadcastMoqStageProps = {
+  /** The relay URL with the viewer ticket already on it. */
+  url: string;
+  /** The broadcast name beneath the ticket's root. */
+  name: string;
+  muted: boolean;
+  /**
+   * The lane is over: the player should fall back.
+   *
+   * Reported upward rather than handled here for the same reason the plane
+   * stage reports its room state upward: falling back means unmounting this
+   * component, and a component cannot unmount itself. There is one
+   * `chooseBroadcastStage` and it lives above.
+   */
+  onFailed: (reason: string) => void;
+};
+
+export function BroadcastMoqStage({ url, name, muted, onFailed }: BroadcastMoqStageProps) {
+  const hostRef = useRef<HTMLDivElement>(null);
+  // Held in a ref so the effect below does not re-run when the player
+  // re-renders with a new closure, which would tear down a working player.
+  const onFailedRef = useRef(onFailed);
+  onFailedRef.current = onFailed;
+
+  useEffect(() => {
+    const host = hostRef.current;
+    if (!host) return;
+
+    let cancelled = false;
+    let element: HTMLElement | undefined;
+
+    const mount = async () => {
+      try {
+        // Imported for its side effect: the module registers <moq-watch>.
+        await import("./vendor/moq-watch.bundle.js");
+      } catch (error) {
+        // The chunk did not load at all. Identical in consequence to a refused
+        // ticket, and it falls back the same way.
+        onFailedRef.current(`moq player failed to load: ${(error as Error).message}`);
+        return;
+      }
+      if (cancelled) return;
+
+      element = document.createElement("moq-watch");
+      element.setAttribute("url", url);
+      element.setAttribute("name", name);
+      if (muted) element.setAttribute("muted", "");
+      /**
+       * `always`, not the default.
+       *
+       * The default is a visibility THRESHOLD ("20%") driven by an
+       * IntersectionObserver, and until it is met the renderer reports itself
+       * hidden, which disables the decoder, which never subscribes to the video
+       * track. A player inside a tab that has not been scrolled, or measured
+       * before layout settles, shows black for ever rather than late.
+       */
+      element.setAttribute("visible", "always");
+      element.style.width = "100%";
+      element.style.height = "100%";
+      element.style.display = "block";
+
+      /**
+       * The nested canvas the renderer paints into, and it is REQUIRED.
+       *
+       * `<moq-watch>` finds its render target by querying its own children. With
+       * no canvas there is no target, so the renderer is never visible, so
+       * `video.in.enabled` stays false and the decoder never subscribes. Every
+       * symptom of this is silent: the connection is established, the catalog
+       * arrives with the video rendition, the config resolves, and the relay
+       * shows only a `catalog.json` subscription and never a `video` one.
+       */
+      const canvas = document.createElement("canvas");
+      canvas.style.width = "100%";
+      canvas.style.height = "100%";
+      canvas.style.display = "block";
+      element.appendChild(canvas);
+
+      // A relay that refuses the ticket, or a broadcast that is not there,
+      // surfaces as an error event rather than a throw: the element owns its
+      // own reconnect loop and never rejects the caller.
+      element.addEventListener("error", () => {
+        onFailedRef.current("the relay connection failed");
+      });
+
+      host.replaceChildren(element);
+    };
+
+    void mount();
+
+    return () => {
+      cancelled = true;
+      // `replaceChildren()` disconnects the element, and its
+      // `disconnectedCallback` closes the connection and the decoders. Leaving
+      // it attached would keep a QUIC session and a decode pipeline alive for a
+      // stage the viewer has already left.
+      host.replaceChildren();
+      element = undefined;
+    };
+  }, [url, name, muted]);
+
+  return <div ref={hostRef} className="h-full w-full bg-black" />;
+}