@tribe-nest/forge 3.60.0 → 3.63.0

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

@@ -0,0 +1,102 @@
+import { internalPath } from "../../../runtime/pages";
+import {
+  SITE_APP_BAR_KEYS,
+  SITE_APP_BAR_MAX_ITEMS,
+  SITE_APP_DEFAULT_BAR,
+  type SiteAppBarKey,
+} from "../../../data/queries/useSiteApp";
+
+/**
+ * The site app's bottom bar: Home, then the creator's chosen items (at most
+ * three), then More, which opens a sheet with every other destination. Kept
+ * apart from how it is drawn so the bar, the sheet and a spec can never
+ * disagree about what goes where (the same split as `buildMemberHomeBar`).
+ */
+
+export type AppBarKey = "home" | SiteAppBarKey;
+
+export interface AppBarItem {
+  key: AppBarKey;
+  href: string;
+  active: boolean;
+}
+
+export interface AppBarModel {
+  /** Home first, then the configured items. More is not an item: it is always drawn last. */
+  bar: AppBarItem[];
+  /** Every destination not in the bar, in the canonical order. */
+  more: AppBarItem[];
+  /** The page being shown lives in the sheet, so More is the highlighted button. */
+  moreActive: boolean;
+}
+
+/** Where each destination goes. Inbox is the member's notifications. */
+export const APP_BAR_HREFS: Readonly<Record<SiteAppBarKey, string>> = {
+  communities: internalPath("communities"),
+  portal: internalPath("account"),
+  inbox: internalPath("account/notifications"),
+  events: internalPath("events"),
+  courses: internalPath("courses"),
+  shop: internalPath("store"),
+};
+
+/**
+ * The configured keys made safe: unknown keys and repeats dropped, at most
+ * three. A missing or empty list is the contract's default.
+ */
+export function normaliseBarItems(items: readonly string[] | null | undefined): SiteAppBarKey[] {
+  if (!items || items.length === 0) return [...SITE_APP_DEFAULT_BAR];
+  const known = new Set<string>(SITE_APP_BAR_KEYS);
+  const out: SiteAppBarKey[] = [];
+  for (const key of items) {
+    if (!known.has(key) || out.includes(key as SiteAppBarKey)) continue;
+    out.push(key as SiteAppBarKey);
+    if (out.length === SITE_APP_BAR_MAX_ITEMS) break;
+  }
+  return out;
+}
+
+/** Strip a query and hash, and a trailing slash, so `/i/events/` and `/i/events?x=1` compare equal. */
+function clean(path: string): string {
+  const bare = path.split(/[?#]/)[0] ?? "";
+  return bare.length > 1 ? bare.replace(/\/+$/, "") : bare;
+}
+
+/**
+ * Is `currentPath` this destination? Home matches only itself; the others match
+ * their own page and anything below it, except that the portal does not claim
+ * the inbox, which lives under it.
+ */
+export function isAppBarItemActive(key: AppBarKey, href: string, currentPath: string | null | undefined): boolean {
+  if (!currentPath) return false;
+  const here = clean(currentPath);
+  const target = clean(href);
+  if (key === "home") return here === target;
+  if (key === "portal" && isAppBarItemActive("inbox", APP_BAR_HREFS.inbox, here)) return false;
+  return here === target || here.startsWith(`${target}/`);
+}
+
+/**
+ * Decide what sits in the bar and what goes behind More. Pure.
+ *
+ * Every destination appears exactly once, in the bar or in the sheet.
+ */
+export function buildAppBar({
+  barItems,
+  homeHref,
+  currentPath,
+}: {
+  barItems: readonly string[] | null | undefined;
+  homeHref: string;
+  currentPath?: string | null;
+}): AppBarModel {
+  const chosen = normaliseBarItems(barItems);
+  const item = (key: AppBarKey, href: string): AppBarItem => ({
+    key,
+    href,
+    active: isAppBarItemActive(key, href, currentPath),
+  });
+  const bar = [item("home", homeHref), ...chosen.map((key) => item(key, APP_BAR_HREFS[key]))];
+  const more = SITE_APP_BAR_KEYS.filter((key) => !chosen.includes(key)).map((key) => item(key, APP_BAR_HREFS[key]));
+  return { bar, more, moreActive: more.some((entry) => entry.active) };
+}

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

@@ -0,0 +1,344 @@
+import { internalPath } from "../../../runtime/pages";
+import { bookingCallWindow } from "../../media/bookingWindow";
+import { SITE_APP_SECTION_KEYS, type SiteAppHomeSection, type SiteAppSectionKey } from "../../../data/queries/useSiteApp";
+import type { PortalAttentionItem, PortalSectionKey, PortalSummary } from "../portal/usePortal";
+import type { MyBooking } from "../../../data/queries/useMyBookings";
+import type { MyTicket } from "../../../data/queries/useMyTickets";
+import type { MyCourse } from "../../../data/queries/useMyCourses";
+import type { MyMembershipCall } from "../../../data/queries/useMembershipCalls";
+import type { CourseAccessData, IEvent, IPublicProduct, PublicCourse } from "../../../types/models";
+
+/**
+ * The site app's home (`/i/app`): the sections the creator configured, in their
+ * order, each drawn only when it has something to show. The portal is the one
+ * exception: it is always drawn, because it is where everything a member owns
+ * lives. Everything here is pure, so the order, the visibility and the
+ * empty-skip are decided in one place a spec can read.
+ */
+
+// ---- Portal tiles -------------------------------------------------------------------
+
+export type AppPortalTileKey = "projects" | "bookings" | "invoices" | "documents" | "courses" | "orders" | "tickets" | "saved" | "settings";
+
+export interface AppPortalTile {
+  key: AppPortalTileKey;
+  href: string;
+  /** How many things in this section need the person (the tile's badge). 0 draws none. */
+  attention: number;
+}
+
+/** The tiles, in the order the grid draws them, each with the summary count that decides it. */
+export const APP_PORTAL_TILES: ReadonlyArray<{ key: Exclude<AppPortalTileKey, "settings">; countKey: PortalSectionKey; href: string }> = [
+  { key: "projects", countKey: "projects", href: internalPath("account/projects") },
+  { key: "bookings", countKey: "bookings", href: internalPath("account/bookings") },
+  { key: "invoices", countKey: "invoices", href: internalPath("account/invoices") },
+  { key: "documents", countKey: "documents", href: internalPath("account/documents") },
+  { key: "courses", countKey: "courses", href: internalPath("account/courses") },
+  { key: "orders", countKey: "orders", href: internalPath("account/orders") },
+  { key: "tickets", countKey: "tickets", href: internalPath("account/tickets") },
+  { key: "saved", countKey: "saved", href: internalPath("account/saved") },
+];
+
+const ATTENTION_TILE: Record<PortalAttentionItem["kind"], AppPortalTileKey | null> = {
+  invoice_due: "invoices",
+  invoice_overdue: "invoices",
+  document_to_sign: "documents",
+  approval_requested: "projects",
+  membership_payment_failed: null,
+  message_unread: null,
+};
+
+/**
+ * The portal grid: a tile for each section the person has anything in, then
+ * Settings so a new fan's grid is never empty and a full one is exactly eight.
+ */
+export function buildPortalTiles(summary: PortalSummary | null | undefined): AppPortalTile[] {
+  const attention: Partial<Record<AppPortalTileKey, number>> = {};
+  for (const item of summary?.attention ?? []) {
+    const tile = ATTENTION_TILE[item.kind];
+    if (tile) attention[tile] = (attention[tile] ?? 0) + 1;
+  }
+  const tiles: AppPortalTile[] = APP_PORTAL_TILES.filter((tile) => (summary?.sections?.[tile.countKey] ?? 0) > 0).map(
+    (tile) => ({ key: tile.key, href: tile.href, attention: attention[tile.key] ?? 0 }),
+  );
+  if (tiles.length < APP_PORTAL_TILES.length) {
+    tiles.push({ key: "settings", href: internalPath("account/settings"), attention: 0 });
+  }
+  return tiles;
+}
+
+// ---- Needs you ----------------------------------------------------------------------
+
+export interface AppAttentionAction {
+  item: PortalAttentionItem;
+  /** Which verb the button says. */
+  action: "pay" | "review" | "reply" | "update";
+  href: string;
+}
+
+/** Where each portal attention item is acted on: the exact thing, one tap away. */
+export function attentionAction(item: PortalAttentionItem): AppAttentionAction {
+  switch (item.kind) {
+    case "invoice_due":
+    case "invoice_overdue":
+      return { item, action: "pay", href: internalPath("invoice/$invoiceId", { invoiceId: item.id }) };
+    case "approval_requested":
+      return {
+        item,
+        action: "review",
+        href: `${internalPath("account/projects/$projectId", { projectId: item.projectId })}#approvals`,
+      };
+    case "document_to_sign":
+      return { item, action: "review", href: internalPath("documents/$token", { token: item.token }) };
+    case "message_unread":
+      return { item, action: "reply", href: internalPath("account/messages") };
+    case "membership_payment_failed":
+      return { item, action: "update", href: internalPath("communities/$slug/home", { slug: item.communitySlug }) };
+  }
+}
+
+// ---- Coming up ----------------------------------------------------------------------
+
+export interface AppNextCall {
+  id: string;
+  title: string;
+  startsAt: string;
+  /** The call is open right now. */
+  joinable: boolean;
+  /** The room when joinable, else where the session is listed. */
+  href: string;
+  /** Who it is with: the audience label of a member call, or null for a booked session. */
+  context: string | null;
+}
+
+export interface AppNextTicket {
+  id: string;
+  title: string;
+  startsAt: string;
+  /** Passes on the order, at least 1. */
+  count: number;
+  href: string;
+}
+
+/**
+ * The next call: a member call or a booked session, whichever comes first and
+ * has not ended. An open one is joinable.
+ */
+export function pickNextCall(
+  calls: readonly MyMembershipCall[] | null | undefined,
+  bookings: readonly MyBooking[] | null | undefined,
+  now: Date,
+): AppNextCall | null {
+  const candidates: AppNextCall[] = [];
+  for (const call of calls ?? []) {
+    if (Date.parse(call.endsAt) < now.getTime()) continue;
+    const joinable = call.isOpen && !!call.callPublicId;
+    candidates.push({
+      id: `call:${call.id}`,
+      title: call.title,
+      startsAt: call.startsAt,
+      joinable,
+      // The call page itself says when the room opens, so it is the link either way.
+      href: call.callPublicId ? internalPath("video-calls/$callId", { callId: call.callPublicId }) : internalPath("account"),
+      context: call.audiences?.[0]?.label ?? null,
+    });
+  }
+  for (const booking of bookings ?? []) {
+    if (booking.status !== "confirmed") continue;
+    if (Date.parse(booking.sessionEndTime) < now.getTime()) continue;
+    const joinable = bookingCallWindow(booking, now).isOpen && !!booking.videoCallId;
+    candidates.push({
+      id: `booking:${booking.id}`,
+      title: booking.coachingProductTitle,
+      startsAt: booking.sessionStartTime,
+      joinable,
+      href: joinable ? internalPath("video-calls/$callId", { callId: booking.videoCallId! }) : internalPath("account/bookings"),
+      context: null,
+    });
+  }
+  candidates.sort((a, b) => Date.parse(a.startsAt) - Date.parse(b.startsAt));
+  return candidates[0] ?? null;
+}
+
+/** The next event the person holds a ticket for. Cancelled and refunded orders do not count. */
+export function pickNextTicket(tickets: readonly MyTicket[] | null | undefined, now: Date): AppNextTicket | null {
+  const upcoming = (tickets ?? [])
+    .filter((ticket) => !ticket.selfCancelledAt && ticket.status !== "cancelled" && ticket.status !== "refunded")
+    .filter((ticket) => Date.parse(ticket.eventEndDateTime ?? ticket.eventDateTime) >= now.getTime())
+    .sort((a, b) => Date.parse(a.eventDateTime) - Date.parse(b.eventDateTime));
+  const next = upcoming[0];
+  if (!next) return null;
+  const count = (next.items ?? []).reduce((sum, item) => sum + (Number(item.quantity) || 0), 0);
+  return {
+    id: next.id,
+    title: next.eventTitle,
+    startsAt: next.eventDateTime,
+    count: Math.max(1, count),
+    href: internalPath("account/tickets"),
+  };
+}
+
+// ---- Continue learning -------------------------------------------------------------
+
+/** The course to carry on with: one started and not finished, else the newest not finished. */
+export function pickLearningCourse(courses: readonly MyCourse[] | null | undefined): MyCourse | null {
+  const open = (courses ?? []).filter((course) => !course.completedAt);
+  return open.find((course) => !!course.currentLessonId) ?? open[0] ?? null;
+}
+
+export interface AppCourseProgress {
+  done: number;
+  total: number;
+  /** 0 to 1. */
+  ratio: number;
+}
+
+/** Lessons done out of lessons released, from the classroom read. Null when there are no lessons. */
+export function courseProgress(access: CourseAccessData | null | undefined): AppCourseProgress | null {
+  if (!access) return null;
+  const lessons = (access.course?.modules ?? []).flatMap((module) => module.lessons ?? []);
+  if (lessons.length === 0) return null;
+  const completed = new Set((access.progress ?? []).filter((row) => row.isCompleted).map((row) => row.lessonId));
+  const done = lessons.filter((lesson) => completed.has(lesson.id) || lesson.progress?.isCompleted).length;
+  return { done, total: lessons.length, ratio: done / lessons.length };
+}
+
+export interface AppLearningCourse {
+  accessId: string;
+  title: string;
+  href: string;
+  progress: AppCourseProgress | null;
+}
+
+// ---- Communities ---------------------------------------------------------------------
+
+export interface AppCommunityCard {
+  id: string;
+  name: string;
+  slug: string;
+  logoUrl: string | null;
+  coverUrl: string | null;
+  tierName: string | null;
+  memberCount: number | null;
+  href: string;
+  /** Explore only: how a visitor gets in, which names the button. */
+  joinMode?: "open" | "application" | "invite";
+}
+
+// ---- The sections ---------------------------------------------------------------------
+
+/** Everything the home can show, already fetched and shaped. Missing means none. */
+export interface AppHomeData {
+  attention?: readonly PortalAttentionItem[];
+  portalTiles?: readonly AppPortalTile[];
+  communities?: readonly AppCommunityCard[];
+  nextCall?: AppNextCall | null;
+  nextTicket?: AppNextTicket | null;
+  learning?: AppLearningCourse | null;
+  explore?: readonly AppCommunityCard[];
+  events?: readonly IEvent[];
+  courses?: readonly PublicCourse[];
+  products?: readonly IPublicProduct[];
+}
+
+export type AppHomeSectionView =
+  | { kind: "needs_you"; key: "needs_you"; actions: AppAttentionAction[] }
+  | { kind: "portal"; key: "portal"; tiles: AppPortalTile[] }
+  | { kind: "communities"; key: "communities"; communities: AppCommunityCard[] }
+  | { kind: "coming_up"; key: "coming_up"; call: AppNextCall | null; ticket: AppNextTicket | null }
+  | { kind: "learning"; key: "learning"; course: AppLearningCourse }
+  | { kind: "explore_communities"; key: "explore_communities"; communities: AppCommunityCard[] }
+  | { kind: "events"; key: "events"; events: IEvent[] }
+  | { kind: "courses"; key: "courses"; courses: PublicCourse[] }
+  | { kind: "shop"; key: "shop"; products: IPublicProduct[] }
+  | { kind: "link"; key: string; label: string; href: string };
+
+/** How many items a list section shows before "See all". */
+export const APP_HOME_LIST_LIMIT = { explore: 3, events: 4, courses: 3, products: 4 } as const;
+
+const KNOWN = new Set<string>(SITE_APP_SECTION_KEYS);
+
+/** A link section's address: a site path, or an absolute http(s) URL. Anything else is not drawn. */
+export function isSafeLinkHref(href: string | null | undefined): boolean {
+  const value = href?.trim() ?? "";
+  if (value.startsWith("/")) return !value.startsWith("//") && !value.startsWith("/\\");
+  return /^https?:\/\/[^\s]+$/i.test(value);
+}
+
+/**
+ * The sections to draw, in the configured order. Pure.
+ *
+ * Hidden entries, unknown keys, repeats and broken links are skipped. A
+ * section with nothing to show is skipped too, except the portal.
+ */
+export function buildAppHomeSections(
+  config: readonly SiteAppHomeSection[] | null | undefined,
+  data: AppHomeData,
+): AppHomeSectionView[] {
+  const out: AppHomeSectionView[] = [];
+  const seen = new Set<string>();
+  for (const entry of config ?? []) {
+    if (!entry || entry.visible === false) continue;
+    if (entry.type === "link") {
+      const label = entry.label?.trim();
+      if (!label || !isSafeLinkHref(entry.href) || seen.has(`link:${entry.id}`)) continue;
+      seen.add(`link:${entry.id}`);
+      out.push({ kind: "link", key: entry.id, label, href: entry.href.trim() });
+      continue;
+    }
+    if (entry.type !== "builtin" || !KNOWN.has(entry.key) || seen.has(entry.key)) continue;
+    seen.add(entry.key);
+    const view = builtinView(entry.key, data);
+    if (view) out.push(view);
+  }
+  return out;
+}
+
+function builtinView(key: SiteAppSectionKey, data: AppHomeData): AppHomeSectionView | null {
+  switch (key) {
+    case "needs_you": {
+      const actions = (data.attention ?? []).map(attentionAction);
+      return actions.length ? { kind: key, key, actions } : null;
+    }
+    case "portal":
+      // Always drawn: it is where everything the member owns lives.
+      return { kind: key, key, tiles: [...(data.portalTiles ?? buildPortalTiles(null))] };
+    case "communities":
+      return data.communities?.length ? { kind: key, key, communities: [...data.communities] } : null;
+    case "coming_up":
+      return data.nextCall || data.nextTicket
+        ? { kind: key, key, call: data.nextCall ?? null, ticket: data.nextTicket ?? null }
+        : null;
+    case "learning":
+      return data.learning ? { kind: key, key, course: data.learning } : null;
+    case "explore_communities":
+      return data.explore?.length
+        ? { kind: key, key, communities: data.explore.slice(0, APP_HOME_LIST_LIMIT.explore) }
+        : null;
+    case "events":
+      return data.events?.length ? { kind: key, key, events: data.events.slice(0, APP_HOME_LIST_LIMIT.events) } : null;
+    case "courses":
+      return data.courses?.length
+        ? { kind: key, key, courses: data.courses.slice(0, APP_HOME_LIST_LIMIT.courses) }
+        : null;
+    case "shop":
+      return data.products?.length
+        ? { kind: key, key, products: data.products.slice(0, APP_HOME_LIST_LIMIT.products) }
+        : null;
+  }
+}
+
+/** Events still to come, soonest first. Cancelled, completed and archived ones are left out. */
+export function upcomingEvents(events: readonly IEvent[] | null | undefined, now: Date): IEvent[] {
+  return (events ?? [])
+    .filter((event) => event.status !== "cancelled" && event.status !== "completed" && event.status !== "draft")
+    .filter((event) => !event.cancelledAt && !event.archivedAt)
+    .filter((event) => Date.parse(event.endDateTime ?? event.dateTime) >= now.getTime())
+    .sort((a, b) => Date.parse(a.dateTime) - Date.parse(b.dateTime));
+}
+
+/** The time-of-day part of the greeting. */
+export function greetingPart(now: Date): "morning" | "afternoon" | "evening" {
+  const hour = now.getHours();
+  return hour < 12 ? "morning" : hour < 18 ? "afternoon" : "evening";
+}

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;
+}