@tribe-nest/forge 3.59.0 → 3.61.0

package/src/ui/headless/siteApp/appPrompts.ts

@@ -0,0 +1,229 @@
+/**
+ * When the site app asks to be installed, and when it offers notifications.
+ * Contract: docs/proposals/site-app-and-website-menu.md, section 8.
+ *
+ * Install is asked at a moment the person just got something worth coming back
+ * to (they joined, bought, booked, accepted an invite), worded for that moment.
+ * Notifications are offered once, on the first launch of the installed app.
+ *
+ * The decisions are pure functions; the storage around them is guarded,
+ * because private mode and blocked storage throw on access.
+ */
+
+import { shareRuntimeValue } from "../../../runtime/registry";
+
+// ---- Install requests --------------------------------------------------------
+
+export const APP_INSTALL_CONTEXTS = ["joined_community", "purchase", "booking", "invite_accepted"] as const;
+
+export type AppInstallContext = (typeof APP_INSTALL_CONTEXTS)[number];
+
+export interface AppInstallRequest {
+  context: AppInstallContext;
+  /** Epoch ms. */
+  at: number;
+}
+
+/** Remembered "Not now": the prompt stays away this long. */
+export const APP_INSTALL_SNOOZE_MS = 14 * 24 * 60 * 60 * 1000;
+
+/**
+ * How long a request waits for a page that can show it. A success usually
+ * navigates (into the community, back from a payment), so the request rides
+ * the session to the next page; a stale one is not shown out of nowhere.
+ */
+export const APP_INSTALL_REQUEST_TTL_MS = 30 * 60 * 1000;
+
+export const APP_INSTALL_DISMISSED_KEY = "forge-app-install-dismissed-at";
+export const APP_INSTALL_PENDING_KEY = "forge-app-install-pending";
+export const APP_PUSH_ANSWER_KEY = "forge-app-push-answer";
+
+/**
+ * The waiting request and who is listening, shared through the runtime
+ * registry: the success that asks (a hosted page, or the site's own checkout)
+ * and the prompt that shows it may sit in different copies of Forge.
+ */
+const shared = () =>
+  shareRuntimeValue<{ pending: AppInstallRequest | null; listeners: Set<() => void> }>("state:app-install-request", () => ({
+    pending: null,
+    listeners: new Set(),
+  }));
+
+function isContext(value: unknown): value is AppInstallContext {
+  return typeof value === "string" && (APP_INSTALL_CONTEXTS as readonly string[]).includes(value);
+}
+
+function readStorage(kind: "local" | "session", key: string): string | null {
+  try {
+    const store = kind === "local" ? window.localStorage : window.sessionStorage;
+    return store.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function writeStorage(kind: "local" | "session", key: string, value: string | null): void {
+  try {
+    const store = kind === "local" ? window.localStorage : window.sessionStorage;
+    if (value === null) store.removeItem(key);
+    else store.setItem(key, value);
+  } catch {
+    /* private mode or blocked storage: the prompt is best effort */
+  }
+}
+
+/**
+ * Ask the site app to offer itself, worded for `context`. Call it from a
+ * success: a community joined, a purchase confirmed, a booking made, an invite
+ * accepted. Safe to call anywhere, any number of times; the app decides whether
+ * a prompt is shown (never when installed, never when the creator turned it
+ * off, never within 14 days of "Not now").
+ */
+export function requestAppInstall(context: AppInstallContext): void {
+  if (typeof window === "undefined" || !isContext(context)) return;
+  const request: AppInstallRequest = { context, at: Date.now() };
+  shared().pending = request;
+  writeStorage("session", APP_INSTALL_PENDING_KEY, JSON.stringify(request));
+  shared().listeners.forEach((listener) => listener());
+}
+
+/** The request waiting to be shown, if one is fresh. */
+export function readPendingAppInstall(now: number = Date.now()): AppInstallRequest | null {
+  let request = shared().pending;
+  if (!request && typeof window !== "undefined") {
+    const raw = readStorage("session", APP_INSTALL_PENDING_KEY);
+    if (raw) {
+      try {
+        const parsed = JSON.parse(raw) as Partial<AppInstallRequest>;
+        if (isContext(parsed.context) && typeof parsed.at === "number") request = { context: parsed.context, at: parsed.at };
+      } catch {
+        request = null;
+      }
+    }
+  }
+  if (!request || now - request.at > APP_INSTALL_REQUEST_TTL_MS || request.at > now + 60_000) return null;
+  return request;
+}
+
+/** The request was shown or turned down: forget it. */
+export function clearPendingAppInstall(): void {
+  shared().pending = null;
+  if (typeof window !== "undefined") writeStorage("session", APP_INSTALL_PENDING_KEY, null);
+  shared().listeners.forEach((listener) => listener());
+}
+
+/** Be told when a request arrives or is cleared. */
+export function subscribeAppInstallRequests(listener: () => void): () => void {
+  shared().listeners.add(listener);
+  return () => {
+    shared().listeners.delete(listener);
+  };
+}
+
+/** When "Not now" was last pressed, or null. */
+export function readInstallDismissedAt(): number | null {
+  if (typeof window === "undefined") return null;
+  const raw = readStorage("local", APP_INSTALL_DISMISSED_KEY);
+  const value = raw ? Number(raw) : NaN;
+  return Number.isFinite(value) ? value : null;
+}
+
+export function rememberInstallDismissed(now: number = Date.now()): void {
+  if (typeof window !== "undefined") writeStorage("local", APP_INSTALL_DISMISSED_KEY, String(now));
+}
+
+export type AppInstallMode = "native" | "ios";
+
+/**
+ * Whether to offer the install, and how. Pure.
+ *
+ * - `installPrompt` is the website's setting; anything but `true` (off, or not
+ *   known yet) is no.
+ * - Running installed is no: there is nothing to install.
+ * - "Not now" within the last 14 days is no.
+ * - A held native prompt (Android, desktop Chromium) is `native`; iPhone and
+ *   iPad Safari, which have none, get the two `ios` steps. Anything else is no.
+ */
+export function decideAppInstall(input: {
+  installPrompt: boolean | null | undefined;
+  isStandalone: boolean;
+  isIOS: boolean;
+  hasNativePrompt: boolean;
+  dismissedAt: number | null;
+  now: number;
+}): AppInstallMode | null {
+  if (input.installPrompt !== true) return null;
+  if (input.isStandalone) return null;
+  if (input.dismissedAt !== null && input.now - input.dismissedAt < APP_INSTALL_SNOOZE_MS) return null;
+  if (input.hasNativePrompt) return "native";
+  if (input.isIOS) return "ios";
+  return null;
+}
+
+// ---- Notifications on first launch ------------------------------------------------
+
+export type AppPushAnswer = "accepted" | "declined";
+
+export function readPushAnswer(): AppPushAnswer | null {
+  if (typeof window === "undefined") return null;
+  const raw = readStorage("local", APP_PUSH_ANSWER_KEY);
+  return raw === "accepted" || raw === "declined" ? raw : null;
+}
+
+export function rememberPushAnswer(answer: AppPushAnswer): void {
+  if (typeof window !== "undefined") writeStorage("local", APP_PUSH_ANSWER_KEY, answer);
+}
+
+/**
+ * Whether to offer notifications now. Pure.
+ *
+ * Only in the installed app (standalone), only when the website's `pushPrompt`
+ * is on, only to someone signed in (a subscription belongs to an account), only
+ * where the browser can do push, only while the browser has not been asked
+ * (`default`: granted needs no asking, denied cannot be asked again), and only
+ * once: any earlier answer here ends it.
+ */
+export function decideAppPush(input: {
+  pushPrompt: boolean | null | undefined;
+  isStandalone: boolean;
+  isSignedIn: boolean;
+  isSupported: boolean;
+  permission: NotificationPermission | null;
+  answer: AppPushAnswer | null;
+}): boolean {
+  return (
+    input.pushPrompt === true &&
+    input.isStandalone &&
+    input.isSignedIn &&
+    input.isSupported &&
+    input.permission === "default" &&
+    input.answer === null
+  );
+}
+
+/**
+ * The push categories offered on first launch, each the notification types it
+ * switches (`<type>.push` in the member's preference matrix). A category is
+ * offered only when the server's matrix knows at least one of its types.
+ */
+export const APP_PUSH_CATEGORIES = [
+  { key: "messages", types: ["dm", "mention", "reply", "chat_message", "client_message"] },
+  { key: "community", types: ["new_post", "new_community_post", "reaction", "mod"] },
+  { key: "events", types: ["event_reminder", "stream_live"] },
+] as const;
+
+export type AppPushCategoryKey = (typeof APP_PUSH_CATEGORIES)[number]["key"];
+
+/** The preference patch for the chosen categories: every known type of each offered category, on or off. */
+export function pushPreferencePatch(
+  chosen: Readonly<Record<AppPushCategoryKey, boolean>>,
+  knownTypes: ReadonlySet<string>,
+): Record<string, boolean> {
+  const patch: Record<string, boolean> = {};
+  for (const category of APP_PUSH_CATEGORIES) {
+    for (const type of category.types) {
+      if (knownTypes.has(type)) patch[`${type}.push`] = chosen[category.key];
+    }
+  }
+  return patch;
+}

package/src/ui/headless/siteApp/index.ts

@@ -0,0 +1,58 @@
+// The site app (one installable app per website): the bar model, the home
+// sections, and the install and notification prompts.
+export {
+  APP_BAR_HREFS,
+  buildAppBar,
+  isAppBarItemActive,
+  normaliseBarItems,
+  type AppBarItem,
+  type AppBarKey,
+  type AppBarModel,
+} from "./appBar";
+export {
+  APP_HOME_LIST_LIMIT,
+  APP_PORTAL_TILES,
+  attentionAction,
+  buildAppHomeSections,
+  buildPortalTiles,
+  courseProgress,
+  greetingPart,
+  isSafeLinkHref,
+  pickLearningCourse,
+  pickNextCall,
+  pickNextTicket,
+  upcomingEvents,
+  type AppAttentionAction,
+  type AppCommunityCard,
+  type AppCourseProgress,
+  type AppHomeData,
+  type AppHomeSectionView,
+  type AppLearningCourse,
+  type AppNextCall,
+  type AppNextTicket,
+  type AppPortalTile,
+  type AppPortalTileKey,
+} from "./appHome";
+export { useAppHome, useAppCommunityUnread, type UseAppHomeResult } from "./useAppHome";
+export { useAppInstallRequest } from "./useAppInstallRequest";
+export {
+  APP_INSTALL_CONTEXTS,
+  APP_INSTALL_SNOOZE_MS,
+  APP_PUSH_CATEGORIES,
+  clearPendingAppInstall,
+  decideAppInstall,
+  decideAppPush,
+  pushPreferencePatch,
+  readInstallDismissedAt,
+  readPendingAppInstall,
+  readPushAnswer,
+  rememberInstallDismissed,
+  rememberPushAnswer,
+  requestAppInstall,
+  subscribeAppInstallRequests,
+  type AppInstallContext,
+  type AppInstallMode,
+  type AppInstallRequest,
+  type AppPushAnswer,
+  type AppPushCategoryKey,
+} from "./appPrompts";

package/src/ui/headless/siteApp/useAppHome.ts

@@ -0,0 +1,210 @@
+import { useContext, useMemo } from "react";
+import { useQuery } from "@tanstack/react-query";
+import { useForge } from "../../../provider/ForgeProvider";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import {
+  SITE_APP_DEFAULT_SECTIONS,
+  useSiteApp,
+  type SiteAppHomeSection,
+  type SiteAppSectionKey,
+} from "../../../data/queries/useSiteApp";
+import { useMyCommunityMemberships, usePublicCommunities } from "../../../data/queries/useCommunities";
+import { communityKeys } from "../../../data/queries/useCommunity";
+import { useMyBookings } from "../../../data/queries/useMyBookings";
+import { useMyTickets } from "../../../data/queries/useMyTickets";
+import { useMyCourses } from "../../../data/queries/useMyCourses";
+import { useCourseAccess } from "../../../data/queries/useCourseAccess";
+import { useGetCourses } from "../../../data/queries/useCourses";
+import { useGetProducts } from "../../../data/queries/useProducts";
+import { membershipCallKeys, type MyMembershipCall } from "../../../data/queries/useMembershipCalls";
+import type { IEvent } from "../../../types/models";
+import { internalPath } from "../../../runtime/pages";
+import { getMembershipAccess } from "../../../utils/membershipAccess";
+import { usePortalSummary } from "../portal/usePortal";
+import { communityAboutPath, communityHomePath } from "../communities/paths";
+import {
+  buildAppHomeSections,
+  buildPortalTiles,
+  courseProgress,
+  pickLearningCourse,
+  pickNextCall,
+  pickNextTicket,
+  upcomingEvents,
+  type AppCommunityCard,
+  type AppHomeSectionView,
+  type AppLearningCourse,
+} from "./appHome";
+
+export interface UseAppHomeResult {
+  /** The settings or the account are still being read: draw a loading state. */
+  isLoading: boolean;
+  /** Signed out: the home is the sign-in screen. */
+  isSignedIn: boolean;
+  /** The app's name (the website's, unless the creator renamed the app). */
+  appName: string | null;
+  iconUrl: string | null;
+  /** The member's first name, for the greeting. */
+  firstName: string | null;
+  /** The sections to draw, in order. Empty while loading. */
+  sections: AppHomeSectionView[];
+}
+
+/**
+ * The data behind the site app's home (`/i/app`).
+ *
+ * Reads the website's app settings, then only what the configured sections
+ * need: a section the creator hid costs no request. Signed out, nothing
+ * member-shaped is fetched at all. Built on the same public hooks the portal
+ * and the communities use, so the home never disagrees with the page a tile
+ * opens. `buildAppHomeSections` decides order, visibility and the empty-skip.
+ */
+export function useAppHome(opts: { now?: Date } = {}): UseAppHomeResult {
+  const { client, profileId } = useForge();
+  const auth = useContext(PublicAuthContext);
+  const user = auth?.user ?? null;
+  const signedIn = !!user;
+  const now = opts.now ?? new Date();
+
+  const app = useSiteApp();
+  // An unknown host (a preview) answers 404: the contract's defaults stand in.
+  const config: readonly SiteAppHomeSection[] | undefined =
+    app.data?.homeSections ?? (app.isError ? SITE_APP_DEFAULT_SECTIONS : undefined);
+  const wants = (key: SiteAppSectionKey) =>
+    !!config?.some((entry) => entry.type === "builtin" && entry.key === key && entry.visible !== false);
+
+  const summary = usePortalSummary();
+  const sectionsCount = summary.data?.sections;
+
+  const wantsCommunities = wants("communities") || wants("explore_communities");
+  const mine = useMyCommunityMemberships({ enabled: signedIn && wantsCommunities });
+  const everyCommunity = usePublicCommunities({ enabled: wantsCommunities });
+
+  const comingUp = signedIn && wants("coming_up");
+  const calls = useQuery<MyMembershipCall[]>({
+    // The member's whole call calendar, across communities and courses.
+    queryKey: [...membershipCallKeys.mine(profileId), "now", "open", "app-home", user?.id ?? null],
+    queryFn: async () =>
+      (await client.get("/public/scheduled-calls/mine", { params: { profileId, limit: 5 } })).data as MyMembershipCall[],
+    enabled: comingUp && !!profileId && !!client,
+    refetchInterval: 60_000,
+  });
+  const bookings = useMyBookings(comingUp && (sectionsCount?.bookings ?? 0) > 0 ? user?.id : undefined, 1, 20);
+  const tickets = useMyTickets(comingUp && (sectionsCount?.tickets ?? 0) > 0 ? user?.id : undefined, 1, 20);
+
+  const myCourses = useMyCourses({ accountId: user?.id, enabled: signedIn && wants("learning") });
+  const learningCourse = pickLearningCourse(myCourses.data);
+  const access = useCourseAccess(learningCourse?.accessId);
+
+  const wantsEvents = wants("events");
+  const events = useQuery<IEvent[]>({
+    queryKey: ["events", profileId],
+    queryFn: async () => (await client.get("/public/events", { params: { profileId } })).data as IEvent[],
+    enabled: wantsEvents && !!profileId && !!client,
+  });
+  const courses = useGetCourses(undefined, wants("courses"));
+  const products = useGetProducts(undefined, wants("shop"));
+
+  const sections = useMemo(() => {
+    if (!config) return [];
+    const byId = new Map((everyCommunity.data ?? []).map((community) => [community.id, community]));
+    const memberships = (mine.data ?? []).filter(
+      (row) => getMembershipAccess({ status: row.status, cancelAtPeriodEnd: !!row.cancelAtPeriodEnd }).hasAccess,
+    );
+    const joined = new Set(memberships.map((row) => row.community.id));
+    const communities: AppCommunityCard[] = memberships.map((row) => {
+      const full = byId.get(row.community.id);
+      return {
+        id: row.community.id,
+        name: row.community.name,
+        slug: row.community.slug,
+        logoUrl: full?.logoUrl ?? null,
+        coverUrl: full?.coverUrl ?? null,
+        tierName: row.tierName ?? row.membershipTier?.name ?? null,
+        memberCount: full?.memberCount ?? null,
+        href: communityHomePath(row.community.slug),
+      };
+    });
+    // Signed out, or a membership read that failed, lists nothing as "yours";
+    // explore then shows every community rather than none.
+    const explore: AppCommunityCard[] = (everyCommunity.data ?? [])
+      .filter((community) => !joined.has(community.id) && !(mine.data ?? []).some((row) => row.community.id === community.id))
+      .map((community) => ({
+        id: community.id,
+        name: community.name,
+        slug: community.slug,
+        logoUrl: community.logoUrl,
+        coverUrl: community.coverUrl,
+        tierName: null,
+        memberCount: community.memberCount,
+        href: communityAboutPath(community.slug),
+        joinMode: community.joinMode ?? "open",
+      }));
+    const learning: AppLearningCourse | null = learningCourse
+      ? {
+          accessId: learningCourse.accessId,
+          title: learningCourse.title,
+          href: internalPath("course-access/$accessId", { accessId: learningCourse.accessId }),
+          progress: courseProgress(access.data),
+        }
+      : null;
+    return buildAppHomeSections(config, {
+      attention: summary.data?.attention ?? [],
+      portalTiles: buildPortalTiles(summary.data),
+      communities,
+      nextCall: pickNextCall(calls.data, bookings.data?.data, now),
+      nextTicket: pickNextTicket(tickets.data?.data, now),
+      learning,
+      explore,
+      events: upcomingEvents(events.data, now),
+      courses: courses.data?.data ?? [],
+      products: products.data?.data ?? [],
+    });
+    // `now` is read per render on purpose; the inputs below are what change the answer.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    config,
+    everyCommunity.data,
+    mine.data,
+    learningCourse,
+    access.data,
+    summary.data,
+    calls.data,
+    bookings.data,
+    tickets.data,
+    events.data,
+    courses.data,
+    products.data,
+  ]);
+
+  const authReady = auth ? auth.isInitialized !== false : true;
+  const isLoading = !config || !authReady || (signedIn && summary.isLoading);
+
+  return {
+    isLoading,
+    isSignedIn: signedIn,
+    appName: app.data?.appName ?? null,
+    iconUrl: app.data?.iconUrl ?? null,
+    firstName: user?.firstName?.trim() || null,
+    sections: isLoading ? [] : sections,
+  };
+}
+
+/**
+ * Unread notifications in one community, for its card on the app home. The
+ * same request and cache entry as the community's own bell, so opening the
+ * community and coming back shows the same number.
+ */
+export function useAppCommunityUnread(communityId: string | undefined, enabled = true) {
+  const { client, profileId } = useForge();
+  return useQuery<number>({
+    queryKey: communityKeys.unread(communityId),
+    queryFn: async () => {
+      const res = await client.get("/public/community/notifications", {
+        params: { profileId, communityId, page: 1, limit: 1, unreadOnly: true },
+      });
+      return res.data.unreadCount as number;
+    },
+    enabled: enabled && !!profileId && !!communityId && !!client,
+    refetchInterval: 30_000,
+  });
+}

package/src/ui/headless/siteApp/useAppInstallRequest.ts

@@ -0,0 +1,16 @@
+import { useEffect, useRef } from "react";
+import { requestAppInstall, type AppInstallContext } from "./appPrompts";
+
+/**
+ * Ask for the app install once, the first time `ready` is true (a payment
+ * confirmed, a booking confirmed). For a success that is a callback rather
+ * than a state, call `requestAppInstall` directly.
+ */
+export function useAppInstallRequest(ready: boolean, context: AppInstallContext): void {
+  const asked = useRef(false);
+  useEffect(() => {
+    if (!ready || asked.current) return;
+    asked.current = true;
+    requestAppInstall(context);
+  }, [ready, context]);
+}

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

@@ -7,6 +7,8 @@ export {
   useWorkTaskAttachments,
   useWorkInvite,
   useAcceptWorkInvite,
+  rememberSignupEmail,
+  SIGNUP_EMAIL_PREFILL_KEY,
   useWorkProjectInvoices,
   useWorkSharedDocuments,
   useWorkOpenSharedDocument,

package/src/ui/headless/work/useWorkPortal.ts

@@ -129,25 +129,19 @@ export interface WorkInviteContext {
   email: string;
   firstName: string | null;
   /**
-   * The invited address already has an account, so the invite grants portal
-   * access but cannot set a credential: render "sign in", not a password
-   * form (C10).
+   * The invited address has no account yet. The invite never creates one: the
+   * page sends the person through the normal signup (which verifies the
+   * address with an emailed code) and back.
    */
+  needsAccount: boolean;
+  /** The complement of `needsAccount`: sign in, then come back. */
   requiresExistingLogin?: boolean;
 }
 
+/** POST /public/work/invite/accept, made as the signed-in invited account. */
 export interface WorkInviteAcceptResult {
-  /**
-   * True when the invited address already has an account: the invite granted
-   * portal access but issued NO session, and the person signs in normally
-   * (C10). `token` is absent in that case.
-   */
-  requiresLogin?: boolean;
-  token?: string;
-  /** Rotating refresh token for the portal session (backend §7). Persist it. */
-  refreshToken?: string;
+  accepted: true;
   projectId: string;
-  account: { id: string; email: string; firstName: string | null; lastName: string | null };
 }
 
 // ── Query keys ───────────────────────────────────────────────────────────────
@@ -410,22 +404,23 @@ export function useUploadWorkDocument(projectId: string) {
   });
 }
 
-// ── Client invite accept (public, no auth) ───────────────────────────────────
+// ── Client invite accept ─────────────────────────────────────────────────────
 
 /**
  * Fetch the branded context for an invite link (GET /public/work/invite).
- * Public: no bearer token needed; the link's token IS the credential.
- * `null`/errored when the token or project is missing/invalid/expired.
+ * Public: no bearer token needed. Sends the site's `profileId`, so a token for
+ * another tenant's project is refused here. Errors when the token or project is
+ * missing, invalid, expired or already used.
  */
 export function useWorkInvite(
   token: string | undefined,
   projectId: string | undefined,
 ): UseQueryResult<WorkInviteContext> {
-  const { client } = useForge();
+  const { client, profileId } = useForge();
   return useQuery<WorkInviteContext>({
-    queryKey: ["work-invite", token, projectId],
+    queryKey: ["work-invite", token, projectId, profileId],
     queryFn: async () => {
-      const res = await client.get(`/public/work/invite`, { params: { token, projectId } });
+      const res = await client.get(`/public/work/invite`, { params: { token, projectId, profileId } });
       return res.data as WorkInviteContext;
     },
     enabled: !!client && !!token && !!projectId,
@@ -434,20 +429,36 @@ export function useWorkInvite(
 }
 
 /**
- * Accept an invite (POST /public/work/invite/accept): set a password and
- * receive a fresh portal session token. The caller persists the token +
- * navigates. Public: no bearer token needed.
+ * Accept an invite (POST /public/work/invite/accept) as the SIGNED-IN account.
+ * The account's email must be the invited address; nothing is created and no
+ * password is involved.
  */
 export function useAcceptWorkInvite() {
-  const { client } = useForge();
-  return useMutation<WorkInviteAcceptResult, unknown, { token: string; projectId: string; password: string }>({
-    mutationFn: async ({ token, projectId, password }) => {
-      const res = await client.post(`/public/work/invite/accept`, { token, projectId, password });
+  const { client, profileId } = useForge();
+  return useMutation<WorkInviteAcceptResult, unknown, { token: string; projectId: string }>({
+    mutationFn: async ({ token, projectId }) => {
+      const res = await client.post(`/public/work/invite/accept`, { token, projectId, profileId });
       return res.data as WorkInviteAcceptResult;
     },
   });
 }
 
+/** Session-storage key the signup form reads its prefilled email from. */
+export const SIGNUP_EMAIL_PREFILL_KEY = "forge:signup-email";
+
+/**
+ * Hand an email to the next signup form in this tab, without putting it in a
+ * URL (where analytics would record it). Read once by `useSignupForm`.
+ */
+export function rememberSignupEmail(email: string | null | undefined) {
+  if (!email || typeof window === "undefined") return;
+  try {
+    window.sessionStorage.setItem(SIGNUP_EMAIL_PREFILL_KEY, email);
+  } catch {
+    // Storage unavailable: the person types it.
+  }
+}
+
 // ── Presentational helpers ───────────────────────────────────────────────────
 
 /** Major-unit amount → display string using the project currency symbol. */