@tribe-nest/forge 3.37.0 → 3.39.0

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

@@ -0,0 +1,189 @@
+import type { ConnectionState, DisconnectCause, ProducerEntry, RoomState } from "@tribe-nest/media-client";
+
+/**
+ * Which stage a live broadcast plays on, as pure functions.
+ *
+ * A v2 broadcast can be watched two ways. The platform's own media plane
+ * carries it over WebRTC in well under a second, and HLS carries it to
+ * everybody else six to ten seconds behind. The plane is the better picture and
+ * it is also the one with a hard cap on it (`STREAM_V2_REALTIME_VIEWER_CAP`,
+ * 100 by default), so being turned away from it is an ORDINARY outcome rather
+ * than an error, and the viewer who is turned away must simply end up watching
+ * the stream.
+ *
+ * That is the whole reason this is a pure function in its own file. The choice
+ * is made from four independent signals arriving at four different times (what
+ * the broadcast advertises, what the token endpoint answered, what the SDK is
+ * doing, and whether the room is still open), and a rule assembled inline out
+ * of four `if`s inside a component is a rule nobody can test and everybody
+ * edits. `callState.ts` splits the call screen's decisions out for the same
+ * reason.
+ *
+ * ## The bias, stated once
+ *
+ * Every uncertain state resolves to `hls`. A viewer on HLS is watching the
+ * broadcast a few seconds late; a viewer left on a realtime stage that is not
+ * going to connect is watching a black rectangle. Those are not comparable
+ * failures, so the ambiguity is spent in the direction that always shows a
+ * picture.
+ */
+
+/** `realtime` is the media plane. `hls` is the stream everybody can always watch. */
+/**
+ * Which stage the player shows.
+ *
+ * `pending` is the state between "this broadcast offers realtime" and knowing
+ * whether this viewer gets it. It draws nothing on purpose: the alternative
+ * 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";
+
+/**
+ * The viewer-token endpoint said no.
+ *
+ * `409` is the designed refusal (the room is full, realtime is off, or nothing
+ * is live) and it is not special-cased below: a refusal is a refusal, and a
+ * network failure with no status at all falls back exactly the same way. The
+ * status is carried so a caller can log which one happened, never so this
+ * function can treat one as recoverable.
+ */
+export type BroadcastCredentialsError = {
+  /** The HTTP status when the server answered at all. Absent on a network failure. */
+  status?: number;
+  message?: string;
+};
+
+/** What the SDK says about the live room. Absent until the provider is mounted. */
+export type BroadcastRoomState = {
+  connectionState: ConnectionState;
+  /** The ROOM's phase. `closed` means the node said so, on a socket still open. */
+  phase: RoomState["phase"];
+  /**
+   * Is another attempt actually booked?
+   *
+   * `connectionState` is `reconnecting` both while the SDK is coming back and
+   * after its policy has given up, so without this a broadcast whose room died
+   * would sit on a frozen frame for ever rather than falling back.
+   */
+  recovering: boolean;
+  error?: DisconnectCause;
+};
+
+export type BroadcastStageInput = {
+  /** `broadcast.realtime.available`, as the public read reported it. */
+  realtimeAvailable: boolean;
+  /** A viewer credential has been minted. Nothing is mounted before it has. */
+  credentialsReady: boolean;
+  /** The refusal, when the fetch failed. `null` while it has not. */
+  credentialsError: BroadcastCredentialsError | null;
+  roomState?: BroadcastRoomState;
+};
+
+/**
+ * Is the realtime attempt over, as opposed to merely in progress?
+ *
+ * A drop that the SDK is recovering from is NOT over: it holds the last frame
+ * for a second or two and comes back, and tearing the room down to swap in an
+ * HLS player would turn a blink into a restart. A drain is the same, as long as
+ * the move is really happening. Everything else on this list is finished:
+ * refused, the room closed, the socket closed for good, or the reconnect policy
+ * exhausted with nothing booked.
+ */
+function realtimeIsOver(roomState: BroadcastRoomState | undefined): boolean {
+  if (!roomState) return false;
+  if (roomState.phase === "closed") return true;
+  if (roomState.connectionState === "closed") return true;
+  if (roomState.error?.type === "refused") return true;
+  if (roomState.error?.type === "room_closed") return true;
+  return roomState.connectionState === "reconnecting" && !roomState.recovering;
+}
+
+/**
+ * The stage to render right now.
+ *
+ * Read in order, and the order is the safety property: nothing reaches the
+ * realtime branch until the broadcast has offered it, a credential has actually
+ * been minted, and the room is still alive.
+ */
+export function chooseBroadcastStage(input: BroadcastStageInput): BroadcastStage {
+  if (!input.realtimeAvailable) return "hls";
+  if (input.credentialsError) return "hls";
+  // PENDING, not "hls". Answering "hls" here mounted the HLS engine for the
+  // moment the ticket was in flight, and an HLS engine does not idle: it
+  // fetched the playlist and started pulling segments for a stage that was
+  // 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";
+  if (realtimeIsOver(input.roomState)) return "hls";
+  return "realtime";
+}
+
+/**
+ * Did this viewer come DOWN to HLS, or were they always going to be here?
+ *
+ * The distinction is the whole content of the line the player shows. A
+ * broadcast that never offered realtime has nothing to explain, and a page that
+ * says "watching the standard stream" on every ordinary stream is a page that
+ * has taught its viewers to ignore the one time it matters.
+ *
+ * A token fetch still in flight is deliberately NOT a fallback. It resolves in
+ * a moment, and announcing a fallback that is about to be withdrawn is a line
+ * that flickers on every single load.
+ */
+export function broadcastFellBack(input: BroadcastStageInput): boolean {
+  if (!input.realtimeAvailable) return false;
+  if (input.credentialsError) return true;
+  if (!input.credentialsReady) return false;
+  return realtimeIsOver(input.roomState);
+}
+
+/** The one program feed, split into the elements that carry it. */
+export type BroadcastProgramTracks = {
+  /** Attach with `useRemoteTrack`. Absent means no video has arrived yet. */
+  videoProducerId?: string;
+  /** The publisher paused it at source. Their choice, not a failure. */
+  videoPaused: boolean;
+  /** The one program soundtrack. An array because it may legitimately be empty. */
+  audioProducerIds: readonly string[];
+};
+
+/**
+ * What to render out of the producers this viewer may actually receive.
+ *
+ * The live room holds exactly one publisher, `program:<broadcastId>`, with one
+ * video producer and one audio producer, and a viewer token's subscribe rule
+ * names that identity and nothing else. So there is no filtering to do here and
+ * deliberately none attempted: re-deriving the identity in the browser would
+ * give a second answer to a question the node has already answered, and the
+ * wrong answer is a black stage on a broadcast that is playing perfectly.
+ *
+ * The FIRST video is taken rather than the last. A studio that briefly
+ * republishes leaves two announced for a frame or two, and picking the newer
+ * one would swap the element's stream under a viewer mid-sentence.
+ *
+ * Audio is returned as a list rather than as one id because the cost of being
+ * wrong is asymmetric: a spare `<audio>` with no track attached does nothing at
+ * all, and a missed one is a broadcast with no sound.
+ */
+export function programTracks(producers: readonly ProducerEntry[]): BroadcastProgramTracks {
+  const video = producers.find((producer) => producer.kind === "video");
+  const audio = producers.filter((producer) => producer.kind === "audio");
+  return {
+    ...(video ? { videoProducerId: video.producerId } : {}),
+    videoPaused: video?.paused ?? false,
+    // ONE, deliberately, not every audio producer in the room.
+    //
+    // A broadcast has a single soundtrack: the studio's mix, published once by
+    // the program feed. If the room ever holds two (a republish after a
+    // reconnect racing the old producer's teardown), playing both is never the
+    // right answer, so the newer publication wins and the stale one is dropped
+    // rather than mixed in.
+    //
+    // This is a guard, not the fix for the doubled audio that was reported
+    // during the build: THAT was the player mounting the HLS stage while the
+    // viewer ticket was still in flight, so the same broadcast arrived twice,
+    // seconds apart, over two transports. See `chooseBroadcastStage`.
+    audioProducerIds: audio.length > 0 ? [audio[audio.length - 1]!.producerId] : [],
+  };
+}

package/src/ui/styled/work/WorkProjectDocuments.tsx

@@ -0,0 +1,224 @@
+import { useRef, useState } from "react";
+import { FileText, Paperclip, Upload } from "lucide-react";
+import { useThemeTokens } from "../../theme/ForgeThemeProvider";
+import {
+  formatWorkDate,
+  useUploadWorkDocument,
+  useWorkOpenSharedDocument,
+  useWorkSharedDocuments,
+  type WorkSharedDocument,
+} from "../../headless/work/useWorkPortal";
+
+export interface WorkProjectDocumentsProps {
+  /** The client project id. */
+  projectId: string;
+  /** Hide the upload control. The list still renders. Defaults to `true`. */
+  allowUpload?: boolean;
+}
+
+const humanSize = (size: number | null | undefined): string => {
+  if (!size || size <= 0) return "";
+  const units = ["B", "KB", "MB", "GB"];
+  let n = size;
+  let i = 0;
+  while (n >= 1024 && i < units.length - 1) {
+    n /= 1024;
+    i += 1;
+  }
+  return `${n.toFixed(n >= 10 || i === 0 ? 0 : 1)} ${units[i]}`;
+};
+
+const errorMessage = (error: unknown): string =>
+  (error as { response?: { data?: { message?: string } } })?.response?.data?.message ||
+  "The upload didn't go through. Please try again.";
+
+/**
+ * The documents on a client's project: what the firm shared with them, and
+ * what they sent in themselves, with an upload control for the latter.
+ *
+ * A file opens through a short-lived signed read fetched on the click, never
+ * from an address held in the page. Built on `useWorkSharedDocuments`,
+ * `useWorkOpenSharedDocument` and `useUploadWorkDocument`; theme tokens only.
+ *
+ * Unlike the invoices block this renders even when the list is empty, because
+ * the empty state is where the upload control lives.
+ */
+export function WorkProjectDocuments({ projectId, allowUpload = true }: WorkProjectDocumentsProps) {
+  const t = useThemeTokens();
+  const { data: documents, isLoading } = useWorkSharedDocuments(projectId);
+  const open = useWorkOpenSharedDocument(projectId);
+  const upload = useUploadWorkDocument(projectId);
+  const fileInputRef = useRef<HTMLInputElement>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [opening, setOpening] = useState<string | null>(null);
+
+  if (isLoading) return null;
+
+  const onFiles = async (files: FileList | null) => {
+    if (!files || files.length === 0) return;
+    setError(null);
+    // One at a time, in order: each is its own signed PUT and its own row, and
+    // a failure names the file that failed rather than the whole batch.
+    for (const file of Array.from(files)) {
+      try {
+        await upload.mutateAsync({ file });
+      } catch (err) {
+        setError(`${file.name}: ${errorMessage(err)}`);
+        return;
+      }
+    }
+  };
+
+  const openDocument = async (doc: WorkSharedDocument) => {
+    if (!doc.file) return;
+    setOpening(doc.id);
+    try {
+      const { url } = await open.mutateAsync(doc.id);
+      window.open(url, "_blank", "noopener");
+    } catch (err) {
+      setError(errorMessage(err));
+    } finally {
+      setOpening(null);
+    }
+  };
+
+  const list = documents ?? [];
+
+  return (
+    <div
+      data-testid="work-project-documents"
+      style={{
+        border: `1px solid ${t.border}`,
+        borderRadius: t.cornerRadius,
+        background: t.surface,
+        padding: 20,
+        color: t.text,
+        fontFamily: t.fontFamily,
+      }}
+    >
+      <div
+        style={{
+          display: "flex",
+          alignItems: "center",
+          justifyContent: "space-between",
+          gap: 12,
+          flexWrap: "wrap",
+          marginBottom: 14,
+        }}
+      >
+        <h2 style={{ fontSize: 16, fontWeight: 800, margin: 0 }}>Documents</h2>
+        {allowUpload && (
+          <>
+            <input
+              ref={fileInputRef}
+              type="file"
+              multiple
+              hidden
+              data-testid="work-document-file-input"
+              onChange={(e) => {
+                void onFiles(e.target.files);
+                e.target.value = "";
+              }}
+            />
+            <button
+              type="button"
+              data-testid="work-document-upload"
+              onClick={() => fileInputRef.current?.click()}
+              disabled={upload.isPending}
+              style={{
+                display: "inline-flex",
+                alignItems: "center",
+                gap: 8,
+                padding: "8px 16px",
+                borderRadius: t.cornerRadius,
+                border: "none",
+                background: t.primary,
+                color: t.textPrimary,
+                fontWeight: 700,
+                fontSize: 13,
+                cursor: upload.isPending ? "wait" : "pointer",
+                opacity: upload.isPending ? 0.7 : 1,
+              }}
+            >
+              <Upload size={14} />
+              {upload.isPending ? "Uploading…" : "Upload a document"}
+            </button>
+          </>
+        )}
+      </div>
+
+      {error && (
+        <p
+          data-testid="work-document-error"
+          role="alert"
+          style={{ margin: "0 0 12px", fontSize: 13, color: "#ef4444" }}
+        >
+          {error}
+        </p>
+      )}
+
+      {list.length === 0 ? (
+        <p data-testid="work-project-documents-empty" style={{ margin: 0, fontSize: 13, color: t.muted }}>
+          {allowUpload
+            ? "Nothing here yet. Upload a document to add it to this project."
+            : "Nothing has been shared with you yet."}
+        </p>
+      ) : (
+        <ul style={{ listStyle: "none", margin: 0, padding: 0, display: "flex", flexDirection: "column", gap: 8 }}>
+          {list.map((doc) => (
+            <li
+              key={doc.id}
+              data-testid={`work-document-${doc.id}`}
+              style={{
+                display: "flex",
+                alignItems: "center",
+                justifyContent: "space-between",
+                gap: 12,
+                flexWrap: "wrap",
+                padding: "10px 14px",
+                border: `1px solid ${t.border}`,
+                borderRadius: t.cornerRadius,
+              }}
+            >
+              <div style={{ display: "flex", alignItems: "center", gap: 10, minWidth: 0 }}>
+                {doc.file ? (
+                  <Paperclip size={14} style={{ color: t.muted, flexShrink: 0 }} />
+                ) : (
+                  <FileText size={14} style={{ color: t.muted, flexShrink: 0 }} />
+                )}
+                <div style={{ display: "flex", flexDirection: "column", gap: 2, minWidth: 0 }}>
+                  <span style={{ fontWeight: 700, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+                    {doc.title}
+                  </span>
+                  <span style={{ fontSize: 12, color: t.muted }}>
+                    {formatWorkDate(doc.sharedAt)}
+                    {doc.file?.size ? ` · ${humanSize(doc.file.size)}` : ""}
+                  </span>
+                </div>
+              </div>
+              {doc.file && (
+                <button
+                  type="button"
+                  data-testid={`work-document-open-${doc.id}`}
+                  onClick={() => void openDocument(doc)}
+                  disabled={opening === doc.id}
+                  style={{
+                    background: "transparent",
+                    border: "none",
+                    padding: 0,
+                    color: t.primary,
+                    fontSize: 13,
+                    textDecoration: "underline",
+                    cursor: opening === doc.id ? "wait" : "pointer",
+                  }}
+                >
+                  {opening === doc.id ? "Opening…" : "Open"}
+                </button>
+              )}
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/ui/styled/work/WorkProjectReport.tsx

@@ -3,6 +3,7 @@ import { Loading } from "../Loading";
 import { useWorkProjectReport } from "../../headless/work/useWorkPortal";
 import { WorkReportBody } from "./WorkReportBody";
 import { WorkProjectInvoices } from "./WorkProjectInvoices";
+import { WorkProjectDocuments } from "./WorkProjectDocuments";
 
 export interface WorkProjectReportProps {
   /** The client project id (from the route). */
@@ -17,7 +18,7 @@ export interface WorkProjectReportProps {
 }
 
 /**
- * The authenticated client's read-only project report — milestones, task list
+ * The authenticated client's read-only project report: milestones, task list
  * and the billable-only time report. Each task links to its detail/comments
  * page. Built on `useWorkProjectReport`; theme tokens only.
  */
@@ -55,11 +56,12 @@ export function WorkProjectReport({ projectId, taskHref, onOpenTask }: WorkProje
         ? undefined
         : (taskHref ?? ((taskId: string) => `/i/work/projects/${projectId}/tasks/${taskId}`));
 
-  // The invoices section is authed-only (not part of the login-free token
-  // share, which renders WorkReportBody directly).
+  // The documents and invoices sections are authed-only (not part of the
+  // login-free token share, which renders WorkReportBody directly).
   return (
     <div style={{ display: "flex", flexDirection: "column", gap: 24 }}>
       <WorkReportBody report={report} taskHref={resolvedTaskHref} onOpenTask={onOpenTask} />
+      <WorkProjectDocuments projectId={projectId} />
       <WorkProjectInvoices projectId={projectId} />
     </div>
   );

package/src/ui/styled/work/index.ts

@@ -8,3 +8,4 @@ export { WorkTaskAttachments, type WorkTaskAttachmentsProps } from "./WorkTaskAt
 export { WorkTaskDetail, type WorkTaskDetailProps } from "./WorkTaskDetail";
 export { WorkInviteAccept, type WorkInviteAcceptProps } from "./WorkInviteAccept";
 export { WorkProjectInvoices, type WorkProjectInvoicesProps } from "./WorkProjectInvoices";
+export { WorkProjectDocuments, type WorkProjectDocumentsProps } from "./WorkProjectDocuments";