create-ailk 0.5.0 → 0.6.0

package/templates/apps/web/app/[locale]/(auth)/sign-in/sign-in-card.tsx

@@ -0,0 +1,125 @@
+"use client"; // Better Auth's client calls (signIn.social / signIn.email) + error state
+
+/**
+ * SignInCard — the /sign-in page's client island (#4984).
+ *
+ * Composes the shipped `AuthCard` block (`intent="sign-in"`, `footer="none"`)
+ * and wires its provider buttons / password form to the Better Auth client
+ * via the shared `useAuthCardFlow` hook (#6018 AC-3) — the same hook
+ * `SignUpCard` next door uses, using the SAME `createAuthClient()` idiom the
+ * `(authed)` group's `SignInGate` uses. The page (RSC) decides providers +
+ * method from auth-env and hands them in; this component never reads env
+ * itself.
+ *
+ * The brand mark is the SHELL's since #5963 — this island renders no `logo`,
+ * or it would appear twice on the page.
+ *
+ * No sign-up affordance anywhere: `footer="none"` drops the "Not a member?
+ * Create an account" cross-link (Better Auth `emailAndPassword.disableSignUp`
+ * posture).
+ *
+ * Password path: `apps/web/auth.ts` does not enable `emailAndPassword` today,
+ * so `signIn.email` is wired but inert (Better Auth answers with an error)
+ * until an operator enables it server-side — the page only selects
+ * `method="password"` when auth-env reports the "email" provider.
+ *
+ * Zero providers (method sso, providers []): the card renders in its inert
+ * state — heading + `notConfiguredSubhead`, no buttons, no form. Never a
+ * fabricated session.
+ *
+ * Error surface: AuthCard's `errors` prop is per-field. A failed provider
+ * launch lands on `errors.email` — the social row sits inside the password
+ * form beside the email field, so it renders there. The SSO body has no
+ * fields at all, so for `method="sso"` the same message is rendered as an
+ * `Alert` above the card instead.
+ *
+ * `forgot` (#6018 AC-1): the page passes `forgot="none"` when
+ * `isResetAvailable()` is false, so the "Forgot password?" link never renders
+ * a dead end — AuthCard's own default (`"link"`) assumes reset is wired.
+ */
+
+import { AuthCard, type AuthCardLabels } from "@working-theory/ui/blocks";
+import { Alert, AlertDescription } from "@working-theory/ui/primitives";
+import type { ReactElement } from "react";
+
+import { authClient, useAuthCardFlow } from "../use-auth-card-flow";
+
+/** The OAuth providers this page can launch — a subset of AuthCard's. */
+export type SignInProvider = "google" | "github";
+
+export interface SignInCardProps {
+  /** Active OAuth providers, exactly as auth-env reports them. */
+  providers: SignInProvider[];
+  /** "password" when the email provider is active; otherwise "sso". */
+  method: "sso" | "password";
+  /** Sanitised post-sign-in path (see `next-path.ts`). */
+  next: string;
+  /** Href for the card's "Forgot password?" link (#5963). */
+  forgotHref?: string;
+  /** "link" (AuthCard's default) unless password reset is unavailable (#6018). */
+  forgot?: "link" | "none";
+  /** Translated AuthCard labels (resolved server-side by the page). */
+  labels: AuthCardLabels;
+  /** Subhead shown when no provider is configured. */
+  notConfiguredSubhead: string;
+  /** Translated error copy. */
+  errorLabels: { signInFailed: string; providerFailed: string };
+}
+
+export function SignInCard({
+  providers,
+  method,
+  next,
+  forgotHref,
+  forgot,
+  labels,
+  notConfiguredSubhead,
+  errorLabels,
+}: SignInCardProps): ReactElement {
+  const { errors, providerError, launchProvider, submitPassword } =
+    useAuthCardFlow(next, {
+      providerFailed: errorLabels.providerFailed,
+      passwordFailed: errorLabels.signInFailed,
+    });
+
+  const notConfigured = method === "sso" && providers.length === 0;
+
+  return (
+    /*
+     * No page framing of its own (#5963): AuthShell owns the brand row, the
+     * 400px column and the vertical rhythm. The `min-h-screen items-center
+     * justify-center` wrapper this used to carry is exactly the "card centered
+     * in empty space, first input at 470px" defect the auth route group fixes.
+     */
+    <div className="flex flex-col gap-4" data-testid="sign-in-page">
+      {method === "sso" && providerError ? (
+        <Alert variant="error" data-testid="sign-in-provider-error">
+          <AlertDescription>{providerError}</AlertDescription>
+        </Alert>
+      ) : null}
+      <AuthCard
+        intent="sign-in"
+        method={method}
+        footer="none"
+        {...(forgotHref !== undefined ? { forgotHref } : {})}
+        {...(forgot !== undefined ? { forgot } : {})}
+        {...(notConfigured ? { subhead: notConfiguredSubhead } : {})}
+        providers={providers.map((provider) => ({
+          provider,
+          onClick: () => void launchProvider(provider),
+        }))}
+        onSubmit={(data) =>
+          void submitPassword(
+            authClient.signIn.email({
+              email: data.email,
+              password: data.password ?? "",
+              callbackURL: next,
+            }),
+          )
+        }
+        errors={errors}
+        labels={labels}
+      />
+    </div>
+  );
+}

package/templates/apps/web/app/[locale]/(auth)/sign-up/page.tsx

@@ -0,0 +1,96 @@
+/**
+ * `/[locale]/sign-up` — the site's sign-up page (#5963).
+ *
+ * RSC. Branches on `isSignUpOpen()`:
+ *   - open   → the sign-up form island, wired to Better Auth exactly as
+ *              `/sign-in`'s island is (providers + method from auth-env).
+ *   - closed → AuthCard's `invitation` intent: copy only, with the footer's
+ *              "Back to sign in" link. This is the DEFAULT — `apps/web/auth.ts`
+ *              does not enable `emailAndPassword`, so a scaffold offers no
+ *              public sign-up and the page must not advertise one.
+ *
+ * `AuthShell` (the (auth) group's layout) owns the brand mark and the 400px
+ * column, so this page passes no `logo` and no framing of its own.
+ */
+
+import { localeHref } from "@working-theory/ui";
+import { AuthCard, type AuthCardLabels } from "@working-theory/ui/blocks";
+import type { Metadata } from "next";
+import { getTranslations } from "next-intl/server";
+import type { ReactElement } from "react";
+
+import { getActiveProviderIds, isSignUpOpen } from "../../../../lib/auth-env";
+
+import { SignUpCard, type SignUpProvider } from "./sign-up-card";
+
+interface Props {
+  params: Promise<{ locale: string }>;
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "auth" });
+  return { title: t("signUpTitle"), description: t("signUpDescription") };
+}
+
+export default async function SignUpPage({
+  params,
+}: Props): Promise<ReactElement> {
+  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "auth" });
+  const signInHref = localeHref(locale, "/sign-in");
+
+  if (!isSignUpOpen()) {
+    const closedLabels: AuthCardLabels = {
+      invitationHeading: t("invitationHeading"),
+      invitationSubhead: t("invitationSubhead"),
+      invitationBody: t("invitationBody"),
+      backToSignIn: t("backToSignIn"),
+    };
+    return (
+      <div className="flex flex-col gap-4" data-testid="sign-up-page">
+        <AuthCard
+          intent="invitation"
+          signInHref={signInHref}
+          labels={closedLabels}
+        />
+      </div>
+    );
+  }
+
+  const active = getActiveProviderIds();
+  // Exactly the OAuth providers auth-env reports — never a default set.
+  const providers = active.filter(
+    (id): id is SignUpProvider => id === "google" || id === "github",
+  );
+  const method = active.includes("email") ? "password" : "sso";
+
+  const labels: AuthCardLabels = {
+    signUpHeading: t("signUpHeading"),
+    signUpSubhead: t("signUpSubhead"),
+    signUpSubmit: t("signUpSubmit"),
+    signUpFooterPrompt: t("signUpFooterPrompt"),
+    signUpFooterLink: t("signUpFooterLink"),
+    ssoPrefix: t("ssoPrefix"),
+    google: t("google"),
+    github: t("github"),
+    email: t("email"),
+    password: t("password"),
+    orContinue: t("orContinue"),
+  };
+
+  return (
+    <SignUpCard
+      providers={providers}
+      method={method}
+      next={localeHref(locale, "/account")}
+      signInHref={signInHref}
+      labels={labels}
+      notConfiguredSubhead={t("signUpNotConfiguredSubhead")}
+      errorLabels={{
+        signUpFailed: t("signUpFailed"),
+        providerFailed: t("providerFailed"),
+      }}
+    />
+  );
+}

package/templates/apps/web/app/[locale]/(auth)/sign-up/sign-up-card.tsx

@@ -0,0 +1,101 @@
+"use client"; // Better Auth's client calls (signUp.email / signIn.social) + error state
+
+/**
+ * SignUpCard — the /sign-up page's client island (#5963).
+ *
+ * The sign-in island's twin: composes `AuthCard` (`intent="sign-up"`) and
+ * wires its provider buttons / password form to the Better Auth client via
+ * the shared `useAuthCardFlow` hook (#6018 AC-3) — the same hook
+ * `SignInCard` next door uses. The page (RSC) decides providers + method from
+ * auth-env and hands them in; this component never reads env.
+ *
+ * Inert until an operator enables `emailAndPassword` server-side — the same
+ * documented posture the sign-in island already carries for its password
+ * path. The page only renders this island at all when `isSignUpOpen()`.
+ *
+ * The brand mark is the shell's: no `logo` is passed, or it would render twice.
+ *
+ * Error surface: `AuthCard`'s `errors` prop is per-field, so a failed provider
+ * launch lands on `errors.email` (the social row sits inside the password form
+ * beside the email field). The SSO body has no fields, so the same message is
+ * rendered as an `Alert` above the card for `method="sso"`.
+ */
+
+import { AuthCard, type AuthCardLabels } from "@working-theory/ui/blocks";
+import { Alert, AlertDescription } from "@working-theory/ui/primitives";
+import type { ReactElement } from "react";
+
+import { authClient, useAuthCardFlow } from "../use-auth-card-flow";
+
+/** The OAuth providers this page can launch — a subset of AuthCard's. */
+export type SignUpProvider = "google" | "github";
+
+export interface SignUpCardProps {
+  /** Active OAuth providers, exactly as auth-env reports them. */
+  providers: SignUpProvider[];
+  /** "password" when the email provider is active; otherwise "sso". */
+  method: "sso" | "password";
+  /** Post-sign-up path. */
+  next: string;
+  /** Href for the footer's "Sign in" cross-link. */
+  signInHref: string;
+  /** Translated AuthCard labels (resolved server-side by the page). */
+  labels: AuthCardLabels;
+  /** Subhead shown when no provider is configured. */
+  notConfiguredSubhead: string;
+  /** Translated error copy. */
+  errorLabels: { signUpFailed: string; providerFailed: string };
+}
+
+export function SignUpCard({
+  providers,
+  method,
+  next,
+  signInHref,
+  labels,
+  notConfiguredSubhead,
+  errorLabels,
+}: SignUpCardProps): ReactElement {
+  const { errors, providerError, launchProvider, submitPassword } =
+    useAuthCardFlow(next, {
+      providerFailed: errorLabels.providerFailed,
+      passwordFailed: errorLabels.signUpFailed,
+    });
+
+  const notConfigured = method === "sso" && providers.length === 0;
+
+  return (
+    <div className="flex flex-col gap-4" data-testid="sign-up-page">
+      {method === "sso" && providerError ? (
+        <Alert variant="error" data-testid="sign-up-provider-error">
+          <AlertDescription>{providerError}</AlertDescription>
+        </Alert>
+      ) : null}
+      <AuthCard
+        intent="sign-up"
+        method={method}
+        signInHref={signInHref}
+        {...(notConfigured ? { subhead: notConfiguredSubhead } : {})}
+        providers={providers.map((provider) => ({
+          provider,
+          onClick: () => void launchProvider(provider),
+        }))}
+        onSubmit={(data) =>
+          // Better Auth requires a `name` on email sign-up; this card collects
+          // none, so the address doubles as the display name until the person
+          // sets one.
+          void submitPassword(
+            authClient.signUp.email({
+              email: data.email,
+              password: data.password ?? "",
+              name: data.email,
+              callbackURL: next,
+            }),
+          )
+        }
+        errors={errors}
+        labels={labels}
+      />
+    </div>
+  );
+}

package/templates/apps/web/app/[locale]/(auth)/use-auth-card-flow.ts

@@ -0,0 +1,102 @@
+"use client"; // useState + the Better Auth client's browser-side calls
+
+/**
+ * useAuthCardFlow — the provider-launch + password-submit boilerplate shared
+ * by SignInCard and SignUpCard (#6018 AC-3).
+ *
+ * Both cards wire an `AuthCard`'s provider buttons and password form to the
+ * same two moves: launch a Better Auth OAuth provider (a failed launch lands
+ * the shared `providerFailed` message on the email field, and — for an
+ * SSO-only card with no fields — as a banner above the card) and submit the
+ * password form (a failed submit lands a caller-named message on the
+ * password field).
+ *
+ * What differs between sign-in and sign-up is the underlying Better Auth CALL
+ * itself — `signIn.email(...)` vs `signUp.email(...)`, the latter needing a
+ * `name` — so `submitPassword` takes the call's own promise as an argument
+ * rather than owning the choice of which Better Auth method to invoke. The
+ * single shared `authClient` this module exports is what each card's
+ * `onSubmit` calls that method on.
+ */
+
+import { createAuthClient } from "better-auth/react";
+import { useState } from "react";
+
+export const authClient = createAuthClient();
+
+/** The OAuth providers either card can launch. */
+export type AuthProvider = "google" | "github";
+
+export interface AuthCardFlowErrorLabels {
+  /** Shown on a failed OAuth provider launch (shared by both cards). */
+  providerFailed: string;
+  /** Shown on a failed password submit — signInFailed or signUpFailed, caller-named. */
+  passwordFailed: string;
+}
+
+interface FieldErrors {
+  email?: string;
+  password?: string;
+}
+
+/** The shape every Better Auth client call this hook awaits resolves to. */
+type AuthResult = { error?: unknown } | null | undefined;
+
+export interface AuthCardFlow {
+  /** Per-field form errors, in `AuthCard`'s `errors` prop shape. */
+  errors: FieldErrors;
+  /** The SSO-body error banner text, or null when none is pending. */
+  providerError: string | null;
+  /** Launches an OAuth provider via `signIn.social`. */
+  launchProvider: (provider: AuthProvider) => Promise<void>;
+  /**
+   * Awaits the caller's own Better Auth call (`signIn.email(...)` or
+   * `signUp.email(...)`) and surfaces a `{ error }` result — or a rejection —
+   * on the password field.
+   */
+  submitPassword: (action: Promise<AuthResult>) => Promise<void>;
+}
+
+/**
+ * @param next - the post-auth `callbackURL` every provider launch uses.
+ * @param errorLabels - translated copy for the two failure cases.
+ */
+export function useAuthCardFlow(
+  next: string,
+  errorLabels: AuthCardFlowErrorLabels,
+): AuthCardFlow {
+  const [errors, setErrors] = useState<FieldErrors>({});
+  const [providerError, setProviderError] = useState<string | null>(null);
+
+  const launchProvider = async (provider: AuthProvider): Promise<void> => {
+    setProviderError(null);
+    // Better Auth reports a failed launch as `{ error }`; a network/runtime
+    // failure rejects. Both land on the same providerFailed message.
+    const failed = await authClient.signIn
+      .social({ provider, callbackURL: next })
+      .then(
+        (res: AuthResult) => Boolean(res?.error),
+        () => true,
+      );
+    if (failed) {
+      setProviderError(errorLabels.providerFailed);
+      setErrors((prev) => ({ ...prev, email: errorLabels.providerFailed }));
+    }
+  };
+
+  const submitPassword = async (action: Promise<AuthResult>): Promise<void> => {
+    setErrors({});
+    // Mirrors launchProvider's own resilience: a `{ error }` result AND a
+    // rejected promise both land on the same passwordFailed message, so a
+    // network/runtime failure from the caller's signIn.email/signUp.email
+    // call surfaces in the form rather than becoming an unhandled rejection
+    // (code review, #6018).
+    const failed = await action.then(
+      (res) => Boolean(res?.error),
+      () => true,
+    );
+    if (failed) setErrors({ password: errorLabels.passwordFailed });
+  };
+
+  return { errors, providerError, launchProvider, submitPassword };
+}

package/templates/apps/web/app/[locale]/(auth)/verify-email/page.tsx

@@ -0,0 +1,87 @@
+/**
+ * `/[locale]/verify-email` — the check-your-email terminus (#5963, wired by #5962).
+ *
+ * Two states, both copy-only:
+ *   - no `?error`  → the `sent` intent. What #5963 shipped: this page states
+ *                    what just happened.
+ *   - `?error=…`   → the same expired/invalid-token state `/reset-password`
+ *                    renders. Better Auth's `/verify-email` redirects to its
+ *                    callback with `?error=<code>` when the JWT is expired,
+ *                    malformed or signed with a rotated secret.
+ *
+ * The verification token's properties are NOT the reset token's, and the copy
+ * is written accordingly: it is a signed JWT rather than a row, so it is
+ * neither single-use nor revocable — the same link keeps working until it
+ * expires. That asymmetry is acceptable precisely because its blast radius is
+ * `emailVerified: true` on one row rather than a credential.
+ */
+
+import { localeHref } from "@working-theory/ui";
+import { AuthCard, type AuthCardLabels } from "@working-theory/ui/blocks";
+import type { Metadata } from "next";
+import { getTranslations } from "next-intl/server";
+import type { ReactElement } from "react";
+
+interface Props {
+  params: Promise<{ locale: string }>;
+  searchParams?: Promise<{ error?: string | string[] }>;
+}
+
+function firstValue(raw: string | string[] | undefined): string {
+  if (Array.isArray(raw)) return raw[0] ?? "";
+  return raw ?? "";
+}
+
+export async function generateMetadata({ params }: Props): Promise<Metadata> {
+  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "auth" });
+  return {
+    title: t("verifyEmailTitle"),
+    description: t("verifyEmailDescription"),
+  };
+}
+
+export default async function VerifyEmailPage({
+  params,
+  searchParams,
+}: Props): Promise<ReactElement> {
+  const { locale } = await params;
+  const t = await getTranslations({ locale, namespace: "auth" });
+  const signInHref = localeHref(locale, "/sign-in");
+
+  const query = searchParams ? await searchParams : {};
+  const error = firstValue(query.error);
+
+  if (error) {
+    const labels: AuthCardLabels = {
+      invitationHeading: t("verifyExpiredHeading"),
+      invitationSubhead: t("verifyExpiredSubhead"),
+      invitationBody: t("verifyExpiredBody"),
+      backToSignIn: t("backToSignIn"),
+    };
+    return (
+      <div className="flex flex-col gap-4" data-testid="verify-email-page">
+        <div data-testid="verify-token-error">
+          <AuthCard
+            intent="invitation"
+            signInHref={signInHref}
+            labels={labels}
+          />
+        </div>
+      </div>
+    );
+  }
+
+  const labels: AuthCardLabels = {
+    sentHeading: t("sentHeading"),
+    sentSubhead: t("sentSubhead"),
+    sentBody: t("sentBody"),
+    backToSignIn: t("backToSignIn"),
+  };
+
+  return (
+    <div className="flex flex-col gap-4" data-testid="verify-email-page">
+      <AuthCard intent="sent" signInHref={signInHref} labels={labels} />
+    </div>
+  );
+}

package/templates/apps/web/app/[locale]/(authed)/__tests__/gate.test.tsx

@@ -26,7 +26,9 @@ const mockGetSession = jest.fn();
 // eslint-disable-next-line no-restricted-syntax -- #507: mock-internal rewrite pending; auth.ts's lazy Better-Auth singleton has no HTTP/DB boundary a unit test of the session-branch can mock without standing up Prisma.
 jest.mock("../../../../auth", () => ({
   __esModule: true,
-  auth: { api: { getSession: (...args: unknown[]) => mockGetSession(...args) } },
+  auth: {
+    api: { getSession: (...args: unknown[]) => mockGetSession(...args) },
+  },
 }));
 
 const mockGetActiveProviderIds = jest.fn();
@@ -86,6 +88,20 @@ describe("AuthedLayout — the (authed) session guard", () => {
     expect(screen.queryByTestId("sign-in-gate")).not.toBeInTheDocument();
   });
 
+  // #5953 AC-1, web half — the app profile applies to the signed-in editor
+  // surfaces only; SignInGate stays on the marketing profile.
+  it('wraps the signed-in children in a data-profile="app" root', async () => {
+    mockGetSession.mockResolvedValue({ user: { id: "user_1" } });
+    const element = await AuthedLayout({
+      params: Promise.resolve({ locale: "en" }),
+      children: <div data-testid="dashboard-content" />,
+    });
+    render(element);
+    const root = screen.getByTestId("authed-profile-root");
+    expect(root).toHaveAttribute("data-profile", "app");
+    expect(root).toContainElement(screen.getByTestId("dashboard-content"));
+  });
+
   it("ignores AILK_AUTH_REQUIRED entirely — never read by the guard", async () => {
     const original = process.env.AILK_AUTH_REQUIRED;
     process.env.AILK_AUTH_REQUIRED = "0";
@@ -114,18 +130,14 @@ describe("<SignInGate/> — the dashboard's own front door", () => {
   });
 
   it("renders AuthPanel with the active providers", () => {
-    render(
-      <SignInGate labels={GATE_LABELS} signInPath="/sign-in" />,
-    );
+    render(<SignInGate labels={GATE_LABELS} signInPath="/sign-in" />);
     expect(screen.getByTestId("sign-in-gate")).toBeInTheDocument();
     expect(screen.getByTestId("auth-panel-card")).toBeInTheDocument();
   });
 
   it("renders an EmptyState when no provider is active", () => {
     mockGetActiveProviderIds.mockReturnValue([]);
-    render(
-      <SignInGate labels={GATE_LABELS} signInPath="/sign-in" />,
-    );
+    render(<SignInGate labels={GATE_LABELS} signInPath="/sign-in" />);
     expect(screen.getByTestId("sign-in-gate-empty")).toBeInTheDocument();
     expect(screen.getByText("No providers")).toBeInTheDocument();
     expect(screen.queryByTestId("auth-panel-card")).not.toBeInTheDocument();
@@ -133,9 +145,7 @@ describe("<SignInGate/> — the dashboard's own front door", () => {
 
   it("filters an inactive/unsupported provider id out of the panel", () => {
     mockGetActiveProviderIds.mockReturnValue(["email"]);
-    render(
-      <SignInGate labels={GATE_LABELS} signInPath="/sign-in" />,
-    );
+    render(<SignInGate labels={GATE_LABELS} signInPath="/sign-in" />);
     // "email" is reported by getActiveProviderIds but is not a supported
     // AuthPanel provider (google | github) — treated as zero active providers.
     expect(screen.getByTestId("sign-in-gate-empty")).toBeInTheDocument();

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

@@ -50,10 +50,16 @@ jest.mock("../../../../../auth", () => ({
 
 const mockSignupMe = jest.fn();
 const mockCheckoutsMe = jest.fn();
+const mockSubscriptionMe = jest.fn();
+const mockSubscriptionPortalSession = jest.fn();
 jest.mock("@working-theory/api-client", () => ({
   __esModule: true,
   waitlistSignups: { me: (...args: unknown[]) => mockSignupMe(...args) },
   flowCheckouts: { me: (...args: unknown[]) => mockCheckoutsMe(...args) },
+  subscription: {
+    me: (...args: unknown[]) => mockSubscriptionMe(...args),
+    portalSession: (...args: unknown[]) => mockSubscriptionPortalSession(...args),
+  },
 }));
 
 let mockExperimentKeys: string[] = [];
@@ -139,6 +145,12 @@ beforeEach(() => {
     key === SIGNUP.experimentKey ? { ok: true, body: SIGNUP } : NOT_FOUND,
   );
   mockCheckoutsMe.mockReset().mockResolvedValue({ ok: true, body: CHECKOUTS });
+  // Default: a healthy subscriber (no banner) — commerce-disabled builds
+  // read identically (a 404), covered explicitly below (D8).
+  mockSubscriptionMe.mockReset().mockResolvedValue({
+    ok: true,
+    body: { actionRequired: false, status: null, accessRevokesAt: null, portalAvailable: false },
+  });
   mockSignOut.mockReset().mockResolvedValue(undefined);
   mockPush.mockReset();
   mockRefresh.mockReset();
@@ -258,3 +270,75 @@ describe("AccountPage — sign out", () => {
     expect(mockSignOut.mock.invocationCallOrder[0]).toBeLessThan(mockPush.mock.invocationCallOrder[0]!);
   });
 });
+
+describe("AccountPage — subscription status banner (#6038)", () => {
+  it("renders the banner for a subscriber with actionRequired: true", async () => {
+    mockSubscriptionMe.mockResolvedValue({
+      ok: true,
+      body: { actionRequired: true, status: "past_due", accessRevokesAt: null, portalAvailable: true },
+    });
+    await renderPage();
+    expect(screen.getByTestId("subscription-status-banner")).toBeInTheDocument();
+  });
+
+  it("renders no banner for a healthy subscriber — AC-1", async () => {
+    mockSubscriptionMe.mockResolvedValue({
+      ok: true,
+      body: { actionRequired: false, status: null, accessRevokesAt: null, portalAvailable: true },
+    });
+    await renderPage();
+    expect(screen.queryByTestId("subscription-status-banner")).not.toBeInTheDocument();
+  });
+
+  it("clears once the recovery lands — AC-3, no dismissal consulted", async () => {
+    mockSubscriptionMe.mockResolvedValue({
+      ok: true,
+      body: { actionRequired: false, status: null, accessRevokesAt: null, portalAvailable: true },
+    });
+    await renderPage();
+    expect(screen.queryByTestId("subscription-status-banner")).not.toBeInTheDocument();
+  });
+
+  it.each([401, 403, 404])(
+    "renders no banner and no throw on a %d read (AC-4, the existing SKIPPED_STATUSES constant)",
+    async (status) => {
+      mockSubscriptionMe.mockResolvedValue({
+        ok: false,
+        status,
+        body: { error: { code: "n/a", message: "n/a" } },
+      });
+      await renderPage();
+      expect(screen.getByTestId("account-page")).toBeInTheDocument();
+      expect(screen.queryByTestId("subscription-status-banner")).not.toBeInTheDocument();
+    },
+  );
+
+  it("rejects to the route error boundary on a 500 subscription read", async () => {
+    mockSubscriptionMe.mockResolvedValue({
+      ok: false,
+      status: 500,
+      body: { error: { code: "internal_error", message: "Boom" } },
+    });
+    await expect(Page({ params: Promise.resolve({ locale: "en" }) })).rejects.toThrow("Boom");
+  });
+
+  it("renders the action slot when portalAvailable is true", async () => {
+    mockSubscriptionMe.mockResolvedValue({
+      ok: true,
+      body: { actionRequired: true, status: "past_due", accessRevokesAt: null, portalAvailable: true },
+    });
+    await renderPage();
+    const banner = screen.getByTestId("subscription-status-banner");
+    expect(within(banner).getByRole("button")).toBeInTheDocument();
+  });
+
+  it("renders no action slot when portalAvailable is false — D3.0a", async () => {
+    mockSubscriptionMe.mockResolvedValue({
+      ok: true,
+      body: { actionRequired: true, status: "past_due", accessRevokesAt: null, portalAvailable: false },
+    });
+    await renderPage();
+    const banner = screen.getByTestId("subscription-status-banner");
+    expect(within(banner).queryByRole("button")).not.toBeInTheDocument();
+  });
+});