create-ailk 0.18.0 → 0.19.0

package/templates/apps/web/app/[locale]/(authed)/account/profile-actions.ts

@@ -0,0 +1,116 @@
+"use server";
+
+/**
+ * account/profile-actions.ts — User settings › General's two member writes
+ * (#8232, spec docs/specs/8232-member-settings-account-general-and-spec.md
+ * D6; the writes are #8170's).
+ *
+ *   - `saveProfile` — the member's name and photo, `member.updateProfile`
+ *     (`PATCH /v1/member/profile`). On a spoke the hub-session cookie is then
+ *     re-sealed from the hub's `/me` (`resealHubSession`, D11), so the new
+ *     name shows on the next render.
+ *   - `requestAccountDeletion` — `member.requestDeletion`
+ *     (`POST /v1/member/deletion-request`). The API files it with the
+ *     deployment that holds the account (8170 D9) and answers which operator
+ *     it went to, so nothing here tests the topology.
+ *
+ * Both send `forwardedCookieInit()`'s init: on a single site the session
+ * cookie plus the request's `Origin`, which `apps/api`'s cookie CSRF check
+ * needs; on a hub-mode spoke the hub credential. Neither takes an identity
+ * argument — who comes from the forwarded credential alone (8170 D1).
+ *
+ * Not a `*.actions.ts` file and no `*Action`-suffixed export: these writes
+ * have no MCP twin by decision (8170's header), and apps/mcp's parity test
+ * reads that suffix. `resealHubSession` is imported by its own path, never
+ * through `lib/hub-session/index.ts`: `sync-routes` never overwrites a
+ * scaffold's existing `index.ts`, so an import through it would not compile
+ * there (D13). Logs carry a status or `err.name` only — never a name, a
+ * link, an email or a credential.
+ */
+
+import { member } from "@working-theory/api-client";
+
+import { resealHubSession } from "../../../../lib/hub-session/reseal";
+import { forwardedCookieInit } from "../../../../lib/server-api";
+
+/** PII-safe error identity for logs (the `checkout.actions.ts` idiom: `err.name` only). */
+function errorName(err: unknown): string {
+  return err instanceof Error ? err.name : "unknown";
+}
+
+/** The `error.code` of a member write's refusal body, when it has one. */
+function errorCode(body: unknown): string | null {
+  if (typeof body !== "object" || body === null) return null;
+  const error = (body as { error?: unknown }).error;
+  if (typeof error !== "object" || error === null) return null;
+  const code = (error as { code?: unknown }).code;
+  return typeof code === "string" ? code : null;
+}
+
+export type SaveProfileResult =
+  | { ok: true; name: string | null; image: string | null }
+  | { ok: false; reason: "required" | "photo" | "unverified" | "unavailable" | "failed" };
+
+/**
+ * Saves the member's name, and their photo when `image` is present:
+ * `null` (or a blank link) clears it, and an absent key leaves it as it is.
+ */
+export async function saveProfile(input: {
+  name: string;
+  image?: string | null;
+}): Promise<SaveProfileResult> {
+  // Action input is untrusted: a hand-built call may send anything.
+  const { name: rawName, image } = (typeof input === "object" && input !== null ? input : {}) as {
+    name?: unknown;
+    image?: unknown;
+  };
+  const name = typeof rawName === "string" ? rawName.trim() : "";
+  if (!name) return { ok: false, reason: "required" };
+  // Anything but a string or null is refused, never read as "clear the photo".
+  if (image !== undefined && image !== null && typeof image !== "string") {
+    return { ok: false, reason: "photo" };
+  }
+  const body = image === undefined ? { name } : { name, image: image?.trim() || null };
+
+  try {
+    const res = await member.updateProfile(body, await forwardedCookieInit());
+    if (res.ok) {
+      if ((await resealHubSession()) === "failed") {
+        console.error("[profile-actions] saveProfile reseal=failed");
+      }
+      return { ok: true, name: res.body.name, image: res.body.image };
+    }
+    console.error(`[profile-actions] saveProfile status=${res.status}`);
+    if (res.status === 400 && errorCode(res.body) === "link_not_https") {
+      return { ok: false, reason: "photo" };
+    }
+    if (res.status === 403) return { ok: false, reason: "unverified" };
+    if (res.status === 404 || res.status === 503) return { ok: false, reason: "unavailable" };
+    return { ok: false, reason: "failed" };
+  } catch (err) {
+    console.error(`[profile-actions] saveProfile errName=${errorName(err)}`);
+    return { ok: false, reason: "failed" };
+  }
+}
+
+export type AccountDeletionResult =
+  | { ok: true; sentTo: "site-operator" | "hub-operator" }
+  | { ok: false; reason: "unverified" | "unavailable" | "failed" };
+
+/**
+ * Asks the operator who holds the account to delete it. The body is empty,
+ * so the API's own subject and message go to the operator.
+ */
+export async function requestAccountDeletion(): Promise<AccountDeletionResult> {
+  try {
+    const res = await member.requestDeletion({}, await forwardedCookieInit());
+    if (res.ok) return { ok: true, sentTo: res.body.sentTo };
+    console.error(`[profile-actions] requestAccountDeletion status=${res.status}`);
+    if (res.status === 403) return { ok: false, reason: "unverified" };
+    if (res.status === 404 || res.status === 503) return { ok: false, reason: "unavailable" };
+    return { ok: false, reason: "failed" };
+  } catch (err) {
+    console.error(`[profile-actions] requestAccountDeletion errName=${errorName(err)}`);
+    return { ok: false, reason: "failed" };
+  }
+}

package/templates/apps/web/app/[locale]/(authed)/account/security/page.tsx

@@ -0,0 +1,80 @@
+/**
+ * /[locale]/account/security — User settings › Security (#8339 D8, NEW).
+ *
+ * RSC, inside the account layout's SignedInShell with the rail visible, in
+ * the member's four-tab settings frame (D7). Holds the former Sign-in
+ * section's content, moved here verbatim from General (#8339 C6): how this
+ * member signs in (`signInMethod()`, #8232 D7) — the hub line (named or
+ * unnamed), the configured methods, or none.
+ */
+
+import { AccountSettingsFrame, AccountSettingsPane } from "@working-theory/templates/account";
+import { DescriptionList } from "@working-theory/ui/blocks";
+import { Text } from "@working-theory/ui/primitives";
+import type { Metadata } from "next";
+import { getTranslations } from "next-intl/server";
+import type { ReactElement } from "react";
+
+import { accountSession } from "../account-data";
+import { memberSettingsFrame, type Translate } from "../settings-frame";
+import { signInMethod, type SignInMethodId } from "../sign-in-method";
+
+interface Props {
+  params: Promise<{ locale: string }>;
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "account" });
+  return { title: t("settings.security.title"), description: t("settings.signIn.lead") };
+}
+
+/** Each sign-in method's label key. */
+const METHOD_KEYS = {
+  google: "settings.signIn.methods.google",
+  github: "settings.signIn.methods.github",
+  "magic-link": "settings.signIn.methods.magicLink",
+  email: "settings.signIn.methods.password",
+} as const satisfies Record<SignInMethodId, string>;
+
+export default async function AccountSecurityPage({ params }: Props): Promise<ReactElement> {
+  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "account" });
+  const session = await accountSession(locale);
+  const frame = memberSettingsFrame(locale, t as unknown as Translate, "security");
+  const name = session?.ctx.user.name || session?.ctx.user.email || "";
+
+  const signIn = signInMethod();
+
+  return (
+    <AccountSettingsFrame {...frame} name={name}>
+      <AccountSettingsPane
+        id="account-settings-security"
+        title={t("settings.security.title")}
+        lead={t("settings.signIn.lead")}
+      >
+        <div data-testid="account-signin-method">
+          {signIn.kind === "hub" ? (
+            <Text as="p" variant="body-sm" tone="muted">
+              {signIn.hubHost !== null
+                ? t("settings.signIn.viaHub", { hub: signIn.hubHost })
+                : t("settings.signIn.viaHubUnnamed")}
+            </Text>
+          ) : signIn.methods.length > 0 ? (
+            <DescriptionList
+              items={signIn.methods.map((id) => ({
+                label: t(METHOD_KEYS[id]),
+                value: t("settings.signIn.available"),
+                "data-testid": `account-signin-${id}`,
+              }))}
+            />
+          ) : (
+            <Text as="p" variant="body-sm" tone="muted">
+              {t("settings.signIn.none")}
+            </Text>
+          )}
+        </div>
+      </AccountSettingsPane>
+    </AccountSettingsFrame>
+  );
+}

package/templates/apps/web/app/[locale]/(authed)/account/settings/page.tsx

@@ -1,367 +1,26 @@
 /**
- * /[locale]/account/settings — User settings (#7430, spec 7423 U4 · D10,
- * D10a; DESIGN.md §5.12a's section content).
+ * /[locale]/account/settings — redirects to User settings › General (#8232,
+ * spec docs/specs/8232-member-settings-account-general-and-spec.md D8).
  *
- * RSC, inside the account layout's SignedInShell with the rail visible
- * (D10a — a member's rail has one row, so a separate no-rail frame would add
- * a step for nothing). One page of anchored sections — the For-you items
- * link to `#general` and `#billing`:
+ * Settings is four tabs since #8339 — General · Security · Notifications ·
+ * Billing — and this one-page, anchored route (#7430) only forwards. A URL
+ * fragment never reaches the server, so `#billing` cannot be redirected
+ * here: the browser carries it across this redirect, and General's
+ * `BillingAnchor` sends it on to Billing; `#general` lands on General as it
+ * is. The hub's authorize step still sends an unverified person here
+ * (`VERIFY_EMAIL_PATH`), and this redirect carries them on.
  *
- *   - General — color mode (only when the site's theme defines more than
- *     one mode), the email read-only, and the name the member sets and edits
- *     (an accepted applicant arrives with none, #7418).
- *   - Security — the sign-in methods this site has configured; a Password
- *     row only when the password method is on.
- *   - Notifications — a note until a preference store exists.
- *   - Privacy — the cookie settings (`/privacy#cookie-settings`, since the
- *     account area carries no consent Banner, D4) and "Request account
- *     deletion", which files a Support request of kind `deletion`.
- *   - Billing — only when `subscription.me()` answers a status or an
- *     available portal; absent on `status: null` + no portal, and on any
- *     401/403/404 (the commerce-disabled build answers 404).
- *   - Then any section a module contributes (`accountSettingsSections`).
- *
- * On a spoke that signs in through its hub (`SIGN_IN_PROVIDER === "hub"`,
- * #7894 D10) the account belongs to the hub: the name is a read-only row,
- * Security says sign-in happens on the hub, and both the name edit and the
- * deletion request are a link to the hub's own account settings — so a
- * request about a hub account never lands in this spoke's inbox
- * (SEC-7894-11). Billing is absent there because its read answers 404.
- *
- * No Credentials, Scope, Organizations or Credits section: those are an
- * agent's or an operator's (§5.12a), never a member's.
+ * The directory keeps the one file General reuses unchanged: `theme-modes.ts`.
  */
 
-import { subscription, type SubscriptionMeResponse } from "@working-theory/api-client";
 import { localeHref } from "@working-theory/ui";
-import { DescriptionList } from "@working-theory/ui/blocks";
-import { Button, Heading, Link, Text } from "@working-theory/ui/primitives";
-import type { Metadata } from "next";
-import { getTranslations } from "next-intl/server";
-import type { ReactElement, ReactNode } from "react";
-
-import { accountSettingsSections } from "../../../../../lib/account-config";
-import { getActiveProviderIds } from "../../../../../lib/auth-env";
-import { hubSessionConfig } from "../../../../../lib/hub-session/config";
-import { SIGN_IN_PROVIDER } from "../../../../../lib/topology.generated";
-import { accountSession, logReadFailure } from "../account-data";
-import { openBillingPortal } from "../actions";
-
-import { ColorModeSetting } from "./color-mode";
-import { DeletionRequest } from "./deletion-request";
-import { NameForm } from "./name-form";
-import { siteThemeModeCount } from "./theme-modes";
+import { redirect } from "next/navigation";
 
 interface Props {
   params: Promise<{ locale: string }>;
 }
 
-export async function generateMetadata({ params }: Props): Promise<Metadata> {
-  const { locale } = await params;
-  const t = await getTranslations({ locale, namespace: "account" });
-  return { title: t("settings.title"), description: t("settings.lead") };
-}
-
-/** The section role DESIGN.md §5.12 names: a title, a muted subtitle, then the fields. */
-function Section({
-  id,
-  title,
-  lead,
-  children,
-}: {
-  id: string;
-  title: string;
-  lead?: string;
-  children: ReactNode;
-}): ReactElement {
-  return (
-    <section
-      id={id}
-      aria-labelledby={`${id}-title`}
-      className="flex scroll-mt-8 flex-col gap-4 border-t border-(--color-border) pt-8"
-      data-testid={`account-settings-${id}`}
-    >
-      <div>
-        <Heading level={2} visual={4} id={`${id}-title`}>
-          {title}
-        </Heading>
-        {lead ? (
-          <Text as="p" variant="body-sm" tone="muted" className="mt-1">
-            {lead}
-          </Text>
-        ) : null}
-      </div>
-      {children}
-    </section>
-  );
-}
-
-/** The sign-in methods this deployment has configured, as message keys. */
-const METHOD_KEYS: Record<string, string> = {
-  google: "settings.security.google",
-  github: "settings.security.github",
-  "magic-link": "settings.security.magicLink",
-  email: "settings.security.password",
-};
-
-/** The hub's own account settings page, on a spoke that signs in through it. */
-function hubSettingsHref(): string | null {
-  const config = hubSessionConfig();
-  return config === null ? null : new URL("/account/settings", config.hubOrigin).toString();
-}
-
-/** A link to the hub's account settings, in place of a control that would act on the spoke. */
-function HubSettingsLink({
-  href,
-  label,
-  testId,
-}: {
-  href: string;
-  label: string;
-  testId: string;
-}): ReactElement {
-  return (
-    <div>
-      <Link href={href} className="inline-flex min-h-6 items-center" data-testid={testId}>
-        {label}
-      </Link>
-    </div>
-  );
-}
-
-/** The statuses with a message key; any other renders as the API sent it. */
-const KNOWN_STATUSES: ReadonlySet<string> = new Set(["trialing", "active", "past_due", "canceled"]);
-
-/**
- * Billing's read: `null` on any non-2xx — 401/403/404 by D10 — and a failed
- * read leaves the section out rather than failing the whole page. A failure
- * other than those three is logged, so it is not silent to the operator.
- */
-async function readSubscription(
-  init: { headers: Record<string, string> },
-): Promise<SubscriptionMeResponse | null> {
-  try {
-    const res = await subscription.me(init);
-    if (res.ok) return res.body;
-    if (![401, 403, 404].includes(res.status)) {
-      console.error(`[account] read failed source=billing status=${res.status}`);
-    }
-    return null;
-  } catch (err) {
-    logReadFailure("billing", err);
-    return null;
-  }
-}
-
-export default async function AccountSettingsPage({ params }: Props): Promise<ReactElement> {
+export default async function AccountSettingsPage({ params }: Props): Promise<never> {
   const { locale } = await params;
-  const t = await getTranslations({ locale, namespace: "account" });
-  const session = await accountSession(locale);
-
-  // Unreachable behind the (authed) gate; a session that expired between
-  // the layout and the page renders the heading alone.
-  if (!session) {
-    return (
-      <div className="max-w-3xl py-8" data-testid="account-settings">
-        <Heading level={1} visual={2}>
-          {t("settings.title")}
-        </Heading>
-      </div>
-    );
-  }
-
-  const { ctx } = session;
-  const sub = await readSubscription(ctx.init);
-  const showBilling = sub !== null && (sub.status !== null || sub.portalAvailable);
-  const methods = getActiveProviderIds().filter((id) => id in METHOD_KEYS);
-  const viaHub = SIGN_IN_PROVIDER === "hub";
-  const hubHref = viaHub ? hubSettingsHref() : null;
-
-  return (
-    <div className="flex max-w-3xl flex-col gap-8 py-8" data-testid="account-settings">
-      <div>
-        <Heading level={1} visual={2}>
-          {t("settings.title")}
-        </Heading>
-        <Text as="p" variant="body-sm" tone="muted" className="mt-block-tight">
-          {t("settings.lead")}
-        </Text>
-      </div>
-
-      <Section id="general" title={t("settings.general.title")} lead={t("settings.general.lead")}>
-        {siteThemeModeCount() > 1 ? (
-          <div className="flex flex-col items-start gap-2">
-            <Text as="p" variant="body-sm" className="font-medium">
-              {t("settings.general.colorMode")}
-            </Text>
-            <ColorModeSetting
-              labels={{
-                title: t("settings.general.colorMode"),
-                light: t("settings.general.light"),
-                auto: t("settings.general.auto"),
-                dark: t("settings.general.dark"),
-              }}
-            />
-          </div>
-        ) : null}
-        <DescriptionList
-          items={[
-            {
-              label: t("settings.general.email"),
-              value: ctx.user.email,
-              "data-testid": "account-settings-email",
-            },
-            ...(viaHub && ctx.user.name
-              ? [
-                  {
-                    label: t("settings.general.name"),
-                    value: ctx.user.name,
-                    "data-testid": "account-settings-name",
-                  },
-                ]
-              : []),
-          ]}
-        />
-        {viaHub ? (
-          hubHref !== null ? (
-            <HubSettingsLink
-              href={hubHref}
-              label={t("settings.general.manageOnHub")}
-              testId="account-settings-manage-on-hub"
-            />
-          ) : null
-        ) : (
-          <NameForm
-            initialName={ctx.user.name ?? ""}
-            labels={{
-              name: t("settings.general.name"),
-              placeholder: t("settings.general.namePlaceholder"),
-              save: t("settings.general.save"),
-              saving: t("settings.general.saving"),
-              saved: t("settings.general.saved"),
-              unsaved: t("settings.general.unsaved"),
-              clean: t("settings.general.clean"),
-              required: t("settings.general.nameRequired"),
-              error: t("settings.general.saveError"),
-            }}
-          />
-        )}
-      </Section>
-
-      <Section id="security" title={t("settings.security.title")} lead={t("settings.security.lead")}>
-        {viaHub ? (
-          <Text as="p" variant="body-sm" tone="muted">
-            {t("settings.security.viaHub")}
-          </Text>
-        ) : methods.length > 0 ? (
-          <div className="flex flex-col gap-2">
-            <Text as="p" variant="body-sm" className="font-medium">
-              {t("settings.security.methods")}
-            </Text>
-            <DescriptionList
-              items={methods.map((id) => ({
-                label: ctx.t(METHOD_KEYS[id]!),
-                value: t("settings.security.available"),
-                "data-testid": `account-signin-${id}`,
-              }))}
-            />
-          </div>
-        ) : (
-          <Text as="p" variant="body-sm" tone="muted">
-            {t("settings.security.none")}
-          </Text>
-        )}
-      </Section>
-
-      <Section
-        id="notifications"
-        title={t("settings.notifications.title")}
-        lead={t("settings.notifications.lead")}
-      >
-        <Text as="p" variant="body-sm" tone="muted">
-          {t("settings.notifications.placeholder")}
-        </Text>
-      </Section>
-
-      <Section id="privacy" title={t("settings.privacy.title")} lead={t("settings.privacy.lead")}>
-        <div>
-          <Link
-            href={localeHref(locale, "/privacy#cookie-settings")}
-            className="inline-flex min-h-6 items-center"
-            data-testid="account-cookie-settings"
-          >
-            {t("settings.privacy.cookies")}
-          </Link>
-        </div>
-        {viaHub ? (
-          hubHref !== null ? (
-            <HubSettingsLink
-              href={hubHref}
-              label={t("settings.general.manageOnHub")}
-              testId="account-privacy-manage-on-hub"
-            />
-          ) : null
-        ) : (
-          <div className="flex flex-col gap-2">
-            <Text as="p" variant="body-sm" tone="muted">
-              {t("settings.privacy.deletionLead")}
-            </Text>
-            <DeletionRequest
-              labels={{
-                action: t("settings.privacy.deletion"),
-                subject: t("settings.privacy.deletionSubject"),
-                message: t("settings.privacy.deletionMessage"),
-                sent: t("settings.privacy.deletionSent"),
-                error: t("settings.privacy.deletionError"),
-              }}
-            />
-          </div>
-        )}
-      </Section>
-
-      {showBilling ? (
-        <Section id="billing" title={t("settings.billing.title")} lead={t("settings.billing.lead")}>
-          {sub.status !== null || sub.accessRevokesAt ? (
-            <DescriptionList
-              items={[
-                ...(sub.status !== null
-                  ? [
-                      {
-                        label: t("settings.billing.status"),
-                        value: KNOWN_STATUSES.has(sub.status)
-                          ? ctx.t(`settings.billing.statuses.${sub.status}`)
-                          : sub.status,
-                      },
-                    ]
-                  : []),
-                ...(sub.accessRevokesAt
-                  ? [
-                      {
-                        label: t("settings.billing.accessRevokesAt"),
-                        value: new Intl.DateTimeFormat(locale, { dateStyle: "medium" }).format(
-                          new Date(sub.accessRevokesAt),
-                        ),
-                      },
-                    ]
-                  : []),
-              ]}
-            />
-          ) : null}
-          {sub.portalAvailable ? (
-            <form action={openBillingPortal}>
-              <Button type="submit" variant="secondary" data-testid="account-billing-manage">
-                {t("settings.billing.manage")}
-              </Button>
-            </form>
-          ) : null}
-        </Section>
-      ) : null}
-
-      {accountSettingsSections.map((section) => (
-        <Section key={section.id} id={section.id} title={ctx.t(section.title)}>
-          {section.render(ctx)}
-        </Section>
-      ))}
-    </div>
-  );
+  redirect(localeHref(locale, "/account/general"));
 }

package/templates/apps/web/app/[locale]/(authed)/account/settings-frame.tsx

@@ -0,0 +1,108 @@
+/**
+ * settings-frame.tsx — User settings' four tabs, General · Security ·
+ * Notifications · Billing (#8339 D7; builds on #8232 D1).
+ *
+ * `memberSettingsFrame` supplies the member's half of the shared
+ * `AccountSettingsFrame` (@working-theory/templates/account, spec 8339 D2):
+ * `standalone: false` (the member area already renders inside AppShell's
+ * own `<main>`), Back to the Inbox, and the four tabs in the reference's
+ * order. Every member settings page calls it and renders the result through
+ * `AccountSettingsFrame` (General, via the shared `AccountSettings`) or
+ * directly (Security, Notifications, Billing).
+ *
+ * `SettingsSection` stays as it is: contributed sections
+ * (`accountSettingsSections`, `accountBillingSections`) still use it, as do
+ * General's and Billing's own trailing content.
+ */
+
+import type { AccountSettingsFrameProps, AccountSettingsTab } from "@working-theory/templates/account";
+import { localeHref } from "@working-theory/ui";
+import { Heading, Icon, Text } from "@working-theory/ui/primitives";
+import { Bell, CreditCard, ShieldCheck, UserRound } from "lucide-react";
+import type { ReactElement, ReactNode } from "react";
+
+/** The `next-intl` translator General/Security/Notifications/Billing each
+ * hold. Widened from `getTranslations`'s own literal-key-checked type (the
+ * `AccountTranslate` idiom, `account-data.ts`) — a settings page's own
+ * string keys are static, but the function is shared across four route
+ * files with four different generic instantiations. Call sites cast their
+ * own `t` with `as unknown as Translate`. */
+export type Translate = (key: string, values?: Record<string, unknown>) => string;
+
+/** The member's half of `AccountSettingsFrameProps` — every settings page's
+ * `frame` prop, less `name` (the caller's own session) and `children`. */
+export function memberSettingsFrame(
+  locale: string,
+  t: Translate,
+  active: "general" | "security" | "notifications" | "billing",
+): Omit<AccountSettingsFrameProps, "name" | "children"> {
+  const tabs: readonly AccountSettingsTab[] = [
+    {
+      key: "general",
+      label: t("settings.general.title"),
+      href: localeHref(locale, "/account/general"),
+      icon: <Icon icon={UserRound} size="sm" decorative className="shrink-0" />,
+    },
+    {
+      key: "security",
+      label: t("settings.security.title"),
+      href: localeHref(locale, "/account/security"),
+      icon: <Icon icon={ShieldCheck} size="sm" decorative className="shrink-0" />,
+    },
+    {
+      key: "notifications",
+      label: t("settings.notifications.title"),
+      href: localeHref(locale, "/account/notifications"),
+      icon: <Icon icon={Bell} size="sm" decorative className="shrink-0" />,
+    },
+    {
+      key: "billing",
+      label: t("settings.billing.title"),
+      href: localeHref(locale, "/account/billing"),
+      icon: <Icon icon={CreditCard} size="sm" decorative className="shrink-0" />,
+    },
+  ];
+
+  return {
+    standalone: false,
+    back: { label: t("settings.back"), href: localeHref(locale, "/account") },
+    railLabel: t("settings.title"),
+    accountLabel: t("settings.account"),
+    tabs,
+    active,
+  };
+}
+
+/** The section role DESIGN.md §5.12 names: a title, a muted subtitle, then the fields. */
+export function SettingsSection({
+  id,
+  title,
+  lead,
+  children,
+}: {
+  id: string;
+  title: string;
+  lead?: string;
+  children: ReactNode;
+}): ReactElement {
+  return (
+    <section
+      id={id}
+      aria-labelledby={`${id}-title`}
+      className="flex scroll-mt-8 flex-col gap-4 border-t border-(--color-border) pt-8"
+      data-testid={`account-settings-${id}`}
+    >
+      <div>
+        <Heading level={2} visual={4} id={`${id}-title`}>
+          {title}
+        </Heading>
+        {lead ? (
+          <Text as="p" variant="body-sm" tone="muted" className="mt-1">
+            {lead}
+          </Text>
+        ) : null}
+      </div>
+      {children}
+    </section>
+  );
+}