@tribe-nest/forge 3.54.0 → 3.58.0

package/src/ui/media/panels/CallBreakoutsPanel.tsx

@@ -0,0 +1,395 @@
+import { useState, type CSSProperties } from "react";
+import { DoorOpen, Undo2 } from "lucide-react";
+
+import type { ForgeT } from "../../../i18n";
+import { CallHelpHint } from "../CallHelpHint";
+import type { BreakoutParticipant, BreakoutRoomSummary, CallStageBreakouts } from "../callBreakouts";
+import type { StageTokens } from "../stage/stageTheme";
+
+/**
+ * The rooms rail: breakout rooms, as the host runs them and as everyone else
+ * sees them.
+ *
+ * Everything this panel touches arrives through the `CallStageBreakouts`
+ * adapter, never a client: the stage serves three differently-authenticated
+ * surfaces and the admin dashboard mounts no `ForgeProvider`. The one thing
+ * the panel does NOT do itself is move the viewer: a self-move is the stage's
+ * flow (write the assignment, then `room.moveTo()`), so the Join and Return
+ * buttons call `onSelfMove` and the stage owns the reconnect.
+ *
+ * Copy: explanations live behind a `?`; what stays visible is state (where you
+ * are, who is where), errors, and the one warning a host has to read before
+ * closing every room.
+ */
+export function CallBreakoutsPanel({
+  breakouts,
+  myIdentity,
+  onSelfMove,
+  movePending,
+  moveError,
+  tokens,
+  t,
+}: {
+  breakouts: CallStageBreakouts;
+  myIdentity: string | null;
+  onSelfMove: (roomPublicId: string | null) => void;
+  /** The stage's own self-move is in flight. */
+  movePending: boolean;
+  /** The stage's own self-move failed, verbatim from the server when it said why. */
+  moveError: string | null;
+  tokens: StageTokens;
+  t: ForgeT;
+}) {
+  const [error, setError] = useState<string | null>(null);
+  const busy = breakouts.pending || movePending;
+
+  // Every adapter call reports the same way: the server's sentence when it
+  // gave one, else our own. Visible, because an error is never help.
+  const run = (action: () => Promise<void>) => {
+    setError(null);
+    void action().catch((cause: unknown) => {
+      const message = cause instanceof Error && cause.message ? cause.message : t("forge.call_stage.breakouts.error");
+      setError(message);
+    });
+  };
+
+  return (
+    <div
+      data-testid="call-breakouts-panel"
+      style={{
+        flex: 1,
+        minHeight: 0,
+        overflowY: "auto",
+        display: "flex",
+        flexDirection: "column",
+        gap: "0.75rem",
+        padding: "0.75rem",
+        fontSize: "0.8125rem",
+      }}
+    >
+      {!breakouts.ready && <span style={{ color: tokens.stageMuted }}>{t("forge.call_stage.breakouts.loading")}</span>}
+
+      {breakouts.ready && breakouts.canManage && (
+        <HostView breakouts={breakouts} myIdentity={myIdentity} onSelfMove={onSelfMove} busy={busy} run={run} tokens={tokens} t={t} />
+      )}
+      {breakouts.ready && !breakouts.canManage && (
+        <AttendeeView breakouts={breakouts} onSelfMove={onSelfMove} busy={busy} tokens={tokens} t={t} />
+      )}
+
+      {(error || moveError) && (
+        <span role="alert" data-testid="breakouts-error" style={{ color: tokens.stageText }}>
+          {error ?? moveError}
+        </span>
+      )}
+    </div>
+  );
+}
+
+const panelButton = (tokens: StageTokens, primary: boolean, busy: boolean, danger = false): CSSProperties => ({
+  display: "inline-flex",
+  alignItems: "center",
+  gap: "0.3rem",
+  padding: "0.3rem 0.65rem",
+  borderRadius: tokens.cornerRadius,
+  border: `1px solid ${danger ? tokens.danger : primary ? tokens.accent : tokens.stageBorder}`,
+  backgroundColor: primary ? tokens.accent : "transparent",
+  color: primary ? tokens.accentText : tokens.stageText,
+  cursor: busy ? "progress" : "pointer",
+  opacity: busy ? 0.6 : 1,
+  font: "inherit",
+  fontSize: "0.75rem",
+  whiteSpace: "nowrap",
+});
+
+const fieldStyle = (tokens: StageTokens): CSSProperties => ({
+  padding: "0.3rem 0.45rem",
+  borderRadius: tokens.cornerRadius,
+  border: `1px solid ${tokens.stageBorder}`,
+  backgroundColor: tokens.stageBg,
+  color: tokens.stageText,
+  font: "inherit",
+  fontSize: "0.8125rem",
+});
+
+const labelStyle: CSSProperties = { display: "flex", alignItems: "center", gap: "0.35rem", color: "inherit" };
+
+const roomHeading = (tokens: StageTokens): CSSProperties => ({
+  display: "flex",
+  alignItems: "center",
+  gap: "0.5rem",
+  fontWeight: 600,
+  color: tokens.stageText,
+});
+
+const nameOf = (person: BreakoutParticipant): string => person.name?.trim() || person.identity;
+
+/**
+ * Everyone who belongs to a room, arrived or not. Live presence first (the
+ * plane's own account), then anybody assigned who has not landed yet, so a
+ * host sees the person they just sent to Room 2 listed there before the
+ * reconnect completes rather than vanishing for a second.
+ */
+function roster(room: Pick<BreakoutRoomSummary, "participants" | "assigned">): (BreakoutParticipant & { arrived: boolean })[] {
+  const rows = room.participants.map((person) => ({ ...person, arrived: true }));
+  const seen = new Set(rows.map((person) => person.identity));
+  for (const person of room.assigned) {
+    if (seen.has(person.identity)) continue;
+    seen.add(person.identity);
+    rows.push({ ...person, arrived: false });
+  }
+  return rows;
+}
+
+function HostView({
+  breakouts,
+  myIdentity,
+  onSelfMove,
+  busy,
+  run,
+  tokens,
+  t,
+}: {
+  breakouts: CallStageBreakouts;
+  myIdentity: string | null;
+  onSelfMove: (roomPublicId: string | null) => void;
+  busy: boolean;
+  run: (action: () => Promise<void>) => void;
+  tokens: StageTokens;
+  t: ForgeT;
+}) {
+  const [count, setCount] = useState(2);
+  const [assign, setAssign] = useState<"auto" | "manual">("auto");
+  const [confirmingClose, setConfirmingClose] = useState(false);
+
+  if (!breakouts.active) {
+    const validCount = Number.isInteger(count) && count >= 1 && count <= 20;
+    return (
+      <form
+        data-testid="breakouts-create"
+        onSubmit={(event) => {
+          event.preventDefault();
+          if (!validCount) return;
+          run(() => breakouts.create({ count, assign }));
+        }}
+        style={{ display: "flex", flexDirection: "column", gap: "0.625rem" }}
+      >
+        <div style={roomHeading(tokens)}>
+          {t("forge.call_stage.breakouts.create_title")}
+          <CallHelpHint label={t("forge.call_stage.breakouts.help_create_label")}>{t("forge.call_stage.breakouts.help_create")}</CallHelpHint>
+        </div>
+        <label style={labelStyle}>
+          <span style={{ flex: 1 }}>{t("forge.call_stage.breakouts.count_label")}</span>
+          <input
+            type="number"
+            min={1}
+            max={20}
+            step={1}
+            value={count}
+            onChange={(event) => setCount(Number(event.target.value))}
+            style={{ ...fieldStyle(tokens), width: "4.5rem" }}
+          />
+        </label>
+        <label style={labelStyle}>
+          <span style={{ flex: 1 }}>{t("forge.call_stage.breakouts.assign_label")}</span>
+          <select value={assign} onChange={(event) => setAssign(event.target.value as "auto" | "manual")} style={fieldStyle(tokens)}>
+            <option value="auto">{t("forge.call_stage.breakouts.assign_auto")}</option>
+            <option value="manual">{t("forge.call_stage.breakouts.assign_manual")}</option>
+          </select>
+        </label>
+        <button type="submit" disabled={busy || !validCount} aria-busy={busy} style={{ ...panelButton(tokens, true, busy), alignSelf: "flex-start" }}>
+          <DoorOpen width={14} height={14} aria-hidden="true" />
+          {t("forge.call_stage.breakouts.create")}
+        </button>
+      </form>
+    );
+  }
+
+  const roomOptions = [{ value: "", label: t("forge.call_stage.breakouts.main_room") }, ...breakouts.rooms.map((room) => ({ value: room.publicId, label: room.name }))];
+
+  const rows = (room: Pick<BreakoutRoomSummary, "participants" | "assigned">, here: string | null) =>
+    roster(room).map((person) => {
+      const mine = person.identity === myIdentity;
+      return (
+        <div key={person.identity} style={{ display: "flex", alignItems: "center", gap: "0.5rem", padding: "0.2rem 0" }}>
+          <span style={{ flex: 1, minWidth: 0, overflow: "hidden", textOverflow: "ellipsis", whiteSpace: "nowrap" }}>
+            {nameOf(person)}
+            {mine && <span style={{ color: tokens.stageMuted }}> {t("forge.call_stage.you_suffix")}</span>}
+            {!person.arrived && <span style={{ color: tokens.stageMuted }}> {t("forge.call_stage.breakouts.assigned_not_arrived")}</span>}
+          </span>
+          {!mine && (
+            <select
+              aria-label={t("forge.call_stage.breakouts.move_to_label", { name: nameOf(person) })}
+              value={here ?? ""}
+              disabled={busy}
+              onChange={(event) => run(() => breakouts.assign(person.identity, event.target.value || null))}
+              style={{ ...fieldStyle(tokens), fontSize: "0.75rem", padding: "0.15rem 0.3rem" }}
+            >
+              {roomOptions.map((option) => (
+                <option key={option.value} value={option.value}>
+                  {option.label}
+                </option>
+              ))}
+            </select>
+          )}
+        </div>
+      );
+    });
+
+  const joinButton = (roomPublicId: string | null) => {
+    const here = (breakouts.current?.publicId ?? null) === roomPublicId;
+    return here ? (
+      <span style={{ fontSize: "0.6875rem", color: tokens.stageMuted }}>{t("forge.call_stage.breakouts.current_marker")}</span>
+    ) : (
+      <button
+        type="button"
+        data-testid={roomPublicId ? `breakouts-join-${roomPublicId}` : "breakouts-join-main"}
+        onClick={() => onSelfMove(roomPublicId)}
+        disabled={busy}
+        aria-busy={busy}
+        style={{ ...panelButton(tokens, false, busy), marginLeft: "auto" }}
+      >
+        {roomPublicId ? t("forge.call_stage.breakouts.join") : t("forge.call_stage.breakouts.return_to_main")}
+      </button>
+    );
+  };
+
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "0.75rem" }}>
+      <div style={roomHeading(tokens)}>
+        {t("forge.call_stage.breakouts.create_title")}
+        <CallHelpHint label={t("forge.call_stage.breakouts.help_join_label")}>{t("forge.call_stage.breakouts.help_join")}</CallHelpHint>
+      </div>
+
+      <section data-testid="breakouts-room-main" style={{ display: "flex", flexDirection: "column", gap: "0.25rem" }}>
+        <div style={roomHeading(tokens)}>
+          <span>{t("forge.call_stage.breakouts.main_room")}</span>
+          <span style={{ fontWeight: 400, color: tokens.stageMuted }}>
+            {t("forge.call_stage.breakouts.participant_count", { count: breakouts.main.participantCount })}
+          </span>
+          {joinButton(null)}
+        </div>
+        {breakouts.main.participants.length === 0 && <span style={{ color: tokens.stageMuted }}>{t("forge.call_stage.breakouts.empty_room")}</span>}
+        {rows({ participants: breakouts.main.participants, assigned: [] }, null)}
+      </section>
+
+      {breakouts.rooms.map((room) => (
+        <section key={room.publicId} data-testid={`breakouts-room-${room.publicId}`} style={{ display: "flex", flexDirection: "column", gap: "0.25rem" }}>
+          <div style={roomHeading(tokens)}>
+            <span>{room.name}</span>
+            <span style={{ fontWeight: 400, color: tokens.stageMuted }}>
+              {t("forge.call_stage.breakouts.participant_count", { count: room.participantCount })}
+            </span>
+            {joinButton(room.publicId)}
+          </div>
+          {room.participants.length === 0 && room.assigned.length === 0 && (
+            <span style={{ color: tokens.stageMuted }}>{t("forge.call_stage.breakouts.empty_room")}</span>
+          )}
+          {rows(room, room.publicId)}
+        </section>
+      ))}
+
+      {confirmingClose ? (
+        <div
+          role="group"
+          aria-label={t("forge.call_stage.breakouts.close_all")}
+          style={{
+            display: "flex",
+            flexDirection: "column",
+            gap: "0.5rem",
+            padding: "0.625rem",
+            borderRadius: tokens.cornerRadius,
+            border: `1px solid ${tokens.danger}`,
+          }}
+        >
+          {/* A warning about what a control is about to do must be read, so it
+              is content here, never a `?` hint. */}
+          <span>{t("forge.call_stage.breakouts.close_confirm_body")}</span>
+          <div style={{ display: "flex", gap: "0.5rem" }}>
+            <button
+              type="button"
+              data-testid="breakouts-close-confirm"
+              disabled={busy}
+              onClick={() => {
+                setConfirmingClose(false);
+                run(() => breakouts.closeAll());
+              }}
+              style={panelButton(tokens, false, busy, true)}
+            >
+              {t("forge.call_stage.breakouts.close_confirm")}
+            </button>
+            <button type="button" onClick={() => setConfirmingClose(false)} style={panelButton(tokens, false, false)}>
+              {t("forge.call_stage.breakouts.close_cancel")}
+            </button>
+          </div>
+        </div>
+      ) : (
+        <button
+          type="button"
+          data-testid="breakouts-close-all"
+          onClick={() => setConfirmingClose(true)}
+          disabled={busy}
+          style={{ ...panelButton(tokens, false, busy, true), alignSelf: "flex-start" }}
+        >
+          {t("forge.call_stage.breakouts.close_all")}
+        </button>
+      )}
+    </div>
+  );
+}
+
+function AttendeeView({
+  breakouts,
+  onSelfMove,
+  busy,
+  tokens,
+  t,
+}: {
+  breakouts: CallStageBreakouts;
+  onSelfMove: (roomPublicId: string | null) => void;
+  busy: boolean;
+  tokens: StageTokens;
+  t: ForgeT;
+}) {
+  return (
+    <div style={{ display: "flex", flexDirection: "column", gap: "0.75rem" }}>
+      <div style={roomHeading(tokens)}>
+        {/* Where you are is STATE, and stays visible. */}
+        <span data-testid="breakouts-where">
+          {breakouts.current
+            ? t("forge.call_stage.breakouts.you_are_in", { room: breakouts.current.name })
+            : t("forge.call_stage.breakouts.you_are_in_main")}
+        </span>
+        <CallHelpHint label={t("forge.call_stage.breakouts.help_attendee_label")}>{t("forge.call_stage.breakouts.help_attendee")}</CallHelpHint>
+      </div>
+
+      <ul style={{ listStyle: "none", margin: 0, padding: 0, display: "flex", flexDirection: "column", gap: "0.25rem" }}>
+        <li style={{ display: "flex", gap: "0.5rem" }}>
+          <span>{t("forge.call_stage.breakouts.main_room")}</span>
+          {!breakouts.current && <span style={{ color: tokens.stageMuted }}>{t("forge.call_stage.breakouts.current_marker")}</span>}
+        </li>
+        {breakouts.rooms.map((room) => (
+          <li key={room.publicId} style={{ display: "flex", gap: "0.5rem" }}>
+            <span>{room.name}</span>
+            {breakouts.current?.publicId === room.publicId && (
+              <span style={{ color: tokens.stageMuted }}>{t("forge.call_stage.breakouts.current_marker")}</span>
+            )}
+          </li>
+        ))}
+      </ul>
+
+      {breakouts.current && (
+        <button
+          type="button"
+          data-testid="breakouts-return-main"
+          onClick={() => onSelfMove(null)}
+          disabled={busy}
+          aria-busy={busy}
+          style={{ ...panelButton(tokens, true, busy), alignSelf: "flex-start" }}
+        >
+          <Undo2 width={14} height={14} aria-hidden="true" />
+          {t("forge.call_stage.breakouts.return_to_main_room")}
+        </button>
+      )}
+    </div>
+  );
+}

package/src/ui/media/panels/CallSidePanel.tsx

@@ -2,18 +2,30 @@ import { X } from "lucide-react";
 import type { RaisedHand } from "@tribe-nest/media-client";
 
 import type { ForgeT } from "../../../i18n";
+import type { CallStageBreakouts } from "../callBreakouts";
 import type { CallStageChat } from "../callChat";
 import type { CallTile } from "../callState";
 import type { StageTokens } from "../stage/stageTheme";
+import { CallBreakoutsPanel } from "./CallBreakoutsPanel";
 import { CallChatPanel } from "./CallChatPanel";
 import { CallParticipantsPanel } from "./CallParticipantsPanel";
 
-export type SidePanelTab = "chat" | "people";
+export type SidePanelTab = "chat" | "people" | "rooms";
 
 /**
- * The right rail: one width, two tabs, the Zoom-familiar shape. Tabs rather
- * than stacked panels because the rail's width is the stage's loss, and two
- * rails would take a third of a laptop screen.
+ * Is the rooms tab drawn at all? Only when the page injected an adapter AND
+ * there is something to show: a host can always open it (to create rooms), and
+ * everyone else sees it only while rooms are open. A call where nobody creates
+ * breakouts draws the two tabs it always drew.
+ */
+export const showsRoomsTab = (breakouts: CallStageBreakouts | undefined): breakouts is CallStageBreakouts =>
+  !!breakouts && (breakouts.canManage || breakouts.active);
+
+/**
+ * The right rail: one width, two tabs (three with breakout rooms), the
+ * Zoom-familiar shape. Tabs rather than stacked panels because the rail's
+ * width is the stage's loss, and two rails would take a third of a laptop
+ * screen.
  */
 export function CallSidePanel({
   tab,
@@ -29,6 +41,10 @@ export function CallSidePanel({
   onLowerHand,
   onLowerAll,
   unread,
+  breakouts,
+  onSelfMove,
+  movePending = false,
+  moveError = null,
   fill = false,
 }: {
   tab: SidePanelTab;
@@ -44,6 +60,12 @@ export function CallSidePanel({
   onLowerHand: (identity: string) => void;
   onLowerAll: () => void;
   unread: number;
+  /** The rooms adapter. Absent, or inactive for a non-host, draws no tab. */
+  breakouts?: CallStageBreakouts | undefined;
+  /** The stage's self-move flow (assignment, then `room.moveTo()`). */
+  onSelfMove?: ((roomPublicId: string | null) => void) | undefined;
+  movePending?: boolean | undefined;
+  moveError?: string | null | undefined;
   /** Fill the parent (a full-screen overlay on a phone) instead of the fixed
    * docked width. */
   fill?: boolean;
@@ -111,6 +133,7 @@ export function CallSidePanel({
       <div style={{ display: "flex", alignItems: "center", borderBottom: `1px solid ${tokens.stageBorder}` }}>
         {chat && tabButton("chat", t("forge.call_stage.tab_chat"), tab === "chat" ? 0 : unread)}
         {tabButton("people", t("forge.call_stage.tab_people"), hands.length)}
+        {showsRoomsTab(breakouts) && tabButton("rooms", t("forge.call_stage.breakouts.tab"))}
         <button
           type="button"
           onClick={onClose}
@@ -135,6 +158,16 @@ export function CallSidePanel({
 
       {tab === "chat" && chat ? (
         <CallChatPanel chat={chat} tokens={tokens} t={t} />
+      ) : tab === "rooms" && showsRoomsTab(breakouts) ? (
+        <CallBreakoutsPanel
+          breakouts={breakouts}
+          myIdentity={myIdentity}
+          onSelfMove={onSelfMove ?? (() => undefined)}
+          movePending={movePending}
+          moveError={moveError}
+          tokens={tokens}
+          t={t}
+        />
       ) : (
         <CallParticipantsPanel
           tiles={tiles}

package/src/ui/media/stage/CallCenterNotice.tsx

@@ -25,8 +25,10 @@ export function CallCenterNotice({
   onRetry: () => void;
 }) {
   const detail = notice.detailKey ? t(notice.detailKey) : notice.detailText;
-  const busy = notice.kind === "joining";
-  const Icon = notice.kind === "joining" ? Loader2 : notice.kind === "waiting" || notice.kind === "everyone_left" ? Users : PhoneOff;
+  // A breakout move is a reconnect the person asked for (or was sent on), so
+  // it spins like joining does: something is happening, nothing is wrong.
+  const busy = notice.kind === "joining" || notice.kind === "moving";
+  const Icon = busy ? Loader2 : notice.kind === "waiting" || notice.kind === "everyone_left" ? Users : PhoneOff;
 
   return (
     <div
@@ -59,7 +61,7 @@ export function CallCenterNotice({
         color={notice.kind === "failed" ? tokens.danger : tokens.stageMuted}
         style={busy ? { animation: "forge-call-spin 1.2s linear infinite" } : undefined}
       />
-      <strong style={{ fontSize: "1.05rem" }}>{t(notice.headlineKey)}</strong>
+      <strong style={{ fontSize: "1.05rem" }}>{t(notice.headlineKey, notice.headlineVars)}</strong>
       {detail && <span style={{ fontSize: "0.875rem", color: tokens.stageMuted, maxWidth: "28rem" }}>{detail}</span>}
       {notice.canRetry && (
         <button

package/src/ui/media/stage/CallControlsBar.tsx

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState, type CSSProperties } from "react";
 import {
   Circle,
+  DoorOpen,
   Hand,
   MessageSquare,
   Mic,
@@ -10,6 +11,7 @@ import {
   PhoneOff,
   SmilePlus,
   Square,
+  Undo2,
   Users,
   Video,
   VideoOff,
@@ -73,6 +75,18 @@ export type CallControlsBarProps = {
   onTogglePeople: () => void;
   peopleOpen: boolean;
   chatOpen: boolean;
+  /**
+   * Breakout rooms. All absent by default, and then nothing here is drawn:
+   * the bar renders pixel for pixel as it did before rooms existed.
+   */
+  roomsAvailable?: boolean | undefined;
+  roomsOpen?: boolean | undefined;
+  onToggleRooms?: (() => void) | undefined;
+  /** This seat is in a breakout room, so Return to main is offered. */
+  inBreakout?: boolean | undefined;
+  onReturnToMain?: (() => void) | undefined;
+  /** The self-move is in flight. Holds the button rather than letting it be pressed twice. */
+  movePending?: boolean | undefined;
   /** Presses of any control unlock the chime AudioContext. */
   onGesture?: (() => void) | undefined;
 };
@@ -372,7 +386,39 @@ export function CallControlsBar(props: CallControlsBarProps) {
         )}
       </div>
 
+      {props.inBreakout && props.onReturnToMain && (
+        <button
+          type="button"
+          data-testid="return-to-main"
+          onClick={() => {
+            gesture();
+            props.onReturnToMain?.();
+          }}
+          disabled={props.movePending}
+          aria-busy={props.movePending}
+          style={barButton(tokens, false, props.movePending)}
+        >
+          <Undo2 width={16} height={16} aria-hidden="true" />
+          {t("forge.call_stage.breakouts.return_to_main")}
+        </button>
+      )}
+
       <span style={{ marginLeft: "auto", display: "inline-flex", gap: "0.5rem" }}>
+        {props.roomsAvailable && props.onToggleRooms && (
+          <button
+            type="button"
+            data-testid="toggle-rooms"
+            onClick={() => {
+              gesture();
+              props.onToggleRooms?.();
+            }}
+            aria-pressed={!!props.roomsOpen}
+            style={barButton(tokens, !!props.roomsOpen)}
+          >
+            <DoorOpen width={16} height={16} aria-hidden="true" />
+            {t("forge.call_stage.breakouts.button")}
+          </button>
+        )}
         {props.chatAvailable && (
           <button
             type="button"

package/src/ui/media/stage/CallTopBar.tsx

@@ -250,7 +250,7 @@ function ConnectionPill({ status, tokens, t }: { status: CallStatus; tokens: Sta
       {status.tone === "live" && (
         <span aria-hidden="true" style={{ width: 7, height: 7, borderRadius: 9999, backgroundColor: tokens.accent, display: "inline-block" }} />
       )}
-      <span style={{ fontWeight: status.tone === "failed" ? 600 : 400 }}>{t(status.headlineKey)}</span>
+      <span style={{ fontWeight: status.tone === "failed" ? 600 : 400 }}>{t(status.headlineKey, status.headlineVars)}</span>
       {detail && status.tone !== "live" && <span>{detail}</span>}
     </span>
   );

package/src/ui/payment/ForgePaymentProvider.tsx

@@ -31,6 +31,20 @@ export interface PaymentRenderProps {
    * nothing until approval. Only sent with `settlement: "deferred"`.
    */
   deferredStrategy?: DeferredChargeStrategy | null;
+  /**
+   * Set when a SetupIntent secret starts a FREE TRIAL on a paid membership
+   * rather than an application. The built-in renderer then reads "Start free
+   * trial" and says under the button that nothing is charged today, what is
+   * charged per cycle, and from which date. Ignored on a payment secret.
+   */
+  trial?: PaymentTrial | null;
+}
+
+/** The free trial a card save starts: when the first charge falls, and its cycle. */
+export interface PaymentTrial {
+  /** ISO date of the first charge. */
+  endsAt: string;
+  billingCycle: "month" | "year";
 }
 
 export type PaymentRenderer = (props: PaymentRenderProps) => ReactNode;