@startsimpli/billing 0.4.24 → 0.4.25

package/src/components/SubscriptionManager.test.tsx

@@ -376,12 +376,15 @@ describe("SubscriptionManager", () => {
       expect(screen.getByTestId("available-plans")).toBeDefined();
     });
 
-    // Click Enterprise upgrade option
+    // Click Enterprise upgrade option: already paying, so it asks first.
     const enterpriseButton = screen.getByTestId("upgrade-cta-enterprise-monthly");
     await userEvent.click(enterpriseButton);
+    expect(onPlanChange).not.toHaveBeenCalled();
+    await userEvent.click(await screen.findByTestId("plan-change-confirm-button"));
 
     expect(onPlanChange).toHaveBeenCalledWith(
-      expect.objectContaining({ slug: "enterprise-monthly" })
+      expect.objectContaining({ slug: "enterprise-monthly" }),
+      null,
     );
   });
 
@@ -655,8 +658,10 @@ describe("SubscriptionManager", () => {
 
     await waitFor(() => expect(screen.getByTestId("available-plans")).toBeDefined());
 
-    // Click the Free card's CTA (slug "starter-monthly", isFree=true)
-    (await screen.findByTestId("upgrade-cta-starter-monthly")).click();
+    // Click the Free card's CTA (slug "starter-monthly", isFree=true), then
+    // confirm: leaving a paid plan is never one click (crochet_patterns-lr7mj).
+    await userEvent.click(await screen.findByTestId("upgrade-cta-starter-monthly"));
+    await userEvent.click(await screen.findByTestId("plan-change-confirm-button"));
 
     // subscribe-free is hit (server fetcher saw the POST)
     await waitFor(() => {
@@ -830,10 +835,12 @@ describe("SubscriptionManager", () => {
         cardSlug: "pro-monthly",
         expectedCta: /current plan/i, shouldBeDisabled: true,
         shouldShowCurrentBadge: true, shouldShowTrialCopy: false },
-      { label: "pro · Enterprise card → upgrade CTA, trial copy if applicable",
+      // Already paying: an upgrade changes the plan in place, so it says so
+      // instead of the new-buyer pitch (crochet_patterns-anw61).
+      { label: "pro · Enterprise card → 'Upgrade to Enterprise', no trial copy",
         subscription: mockSubscriptionActive,
         cardSlug: "enterprise-monthly",
-        expectedCta: /contact sales/i, shouldBeDisabled: false,
+        expectedCta: /upgrade to enterprise/i, shouldBeDisabled: false,
         shouldShowCurrentBadge: false, shouldShowTrialCopy: false },
 
       // TRIALING Pro current sub
@@ -965,8 +972,10 @@ describe("SubscriptionManager", () => {
       </Wrapper>
     );
 
-    // Banner renders
-    await waitFor(() => expect(screen.getByTestId("status-banner-success")).toBeDefined());
+    // No subscription found yet: "Activating…", never "activated" beside
+    // Free (crochet_patterns-nag60).
+    await waitFor(() => expect(screen.getByTestId("status-banner-activating")).toBeDefined());
+    expect(screen.queryByTestId("status-banner-success")).toBeNull();
 
     // success-sync was hit
     await waitFor(() => {
@@ -993,7 +1002,10 @@ describe("SubscriptionManager", () => {
       </Wrapper>
     );
 
-    await waitFor(() => expect(screen.getByTestId("status-banner-success")).toBeDefined());
+    await waitFor(() => {
+      const calls = (fetcher as ReturnType<typeof vi.fn>).mock.calls.map((c) => c[0] as string);
+      expect(calls.some((u) => u.includes("/billing/success-sync/"))).toBe(true);
+    });
     rerender(
       <Wrapper>
         <SubscriptionManager productId="raise-simpli" returnUrl="https://t/s" statusMessage="success" />

package/src/components/SubscriptionManager.tsx

@@ -12,15 +12,26 @@
  *   />
  */
 
-import React, { useEffect, useRef } from "react";
+import React, { useCallback, useEffect, useRef, useState } from "react";
 import { useSubscription } from "../hooks/useSubscription";
 import { useProduct } from "../hooks/useProduct";
 import { usePortal } from "../hooks/usePortal";
 import { useCheckout } from "../hooks/useCheckout";
 import { useUsage } from "../hooks/useUsage";
 import { useSuccessSync } from "../hooks/useSuccessSync";
-import type { OfferFeature, ProductOffer } from "../types";
+import { usePlanChange } from "../hooks/usePlanChange";
+import type { OfferFeature, PlanChangePreview, ProductOffer } from "../types";
 import { CurrentPlanCard } from "./CurrentPlanCard";
+import { PlanChangeConfirm } from "./PlanChangeConfirm";
+import {
+  isPayingSubscription,
+  isUnlistedOffer,
+  planCtaLabel,
+  planDirection,
+  trialApplies,
+  TRIAL_NOTE_FEATURE_KEY,
+  type PlanDirection,
+} from "../utils/plan";
 import { AnnualNote, IntervalToggle, OfferPrice, useIntervalOffers } from "./IntervalToggle";
 import { formatFeatureLabel } from "../utils/format";
 
@@ -31,13 +42,26 @@ export interface SubscriptionManagerProps {
   /** URL to return to after portal session */
   returnUrl: string;
 
-  /** Called when user clicks an available plan's CTA button */
-  onPlanChange?: (offer: ProductOffer) => void;
+  /** Does a paid plan change once the viewer has chosen (and, when they
+   * already pay, confirmed) it — typically a checkout via useCheckout. Gets
+   * the backend's preview when one was made. Return "navigating" after
+   * sending the browser away; throw to show an error. */
+  onPlanChange?: (offer: ProductOffer, preview?: PlanChangePreview | null) => unknown;
 
-  /** Optional status message to display (e.g., after checkout redirect) */
-  statusMessage?: "success" | "cancelled" | "activating" | null;
+  /** Optional status message to display (e.g., after checkout redirect).
+   * "success" shows "Activating…" until the paid plan is actually found;
+   * "scheduled" is a change that takes effect at period end. */
+  statusMessage?: "success" | "cancelled" | "activating" | "scheduled" | null;
+
+  /** The checkout session id from the success URL ({CHECKOUT_SESSION_ID}),
+   * passed to success-sync so it reads the checkout that was paid. */
+  checkoutSessionId?: string | null;
 }
 
+/** How long to keep looking for a just-paid subscription before saying so. */
+const ACTIVATION_POLLS = 5;
+const ACTIVATION_POLL_MS = 2000;
+
 /** Render one OfferFeature row. Skips boolean-false (the plan _doesn't_ have
  * that feature so we don't pretend it does). Numeric limits surface as
  * "Unlimited X" (-1) / "Up to N X" / "X" (no limit attribute).
@@ -57,11 +81,12 @@ function FeatureRow({ feature }: { feature: OfferFeature }) {
   );
 }
 
-function PlanFeatureList({ features }: { features: OfferFeature[] }) {
+function PlanFeatureList({ features, showTrialNote = true }: { features: OfferFeature[]; showTrialNote?: boolean }) {
   if (!features || features.length === 0) return null;
+  const shown = showTrialNote ? features : features.filter((f) => f.key !== TRIAL_NOTE_FEATURE_KEY);
   return (
     <ul data-testid="plan-features" className="space-y-1.5 mb-4">
-      {features.map((f) => <FeatureRow key={f.key} feature={f} />)}
+      {shown.map((f) => <FeatureRow key={f.key} feature={f} />)}
     </ul>
   );
 }
@@ -167,6 +192,7 @@ export function SubscriptionManager({
   returnUrl,
   onPlanChange,
   statusMessage,
+  checkoutSessionId = null,
 }: SubscriptionManagerProps) {
   const { subscription, loading: subLoading, error: subError, refetch: refetchSubscription } = useSubscription(productId);
   const { product, loading: productLoading, error: productError, refetch: refetchProduct } = useProduct(productId);
@@ -179,24 +205,58 @@ export function SubscriptionManager({
     subscription?.offer?.id ?? null,
   );
 
+  // Free offers → POST /billing/subscribe-free/ then refetch (no Stripe
+  // round-trip for $0 plans — startsim-6vk). Paid offers → the app's
+  // onPlanChange (a checkout). Either way only after the viewer has confirmed
+  // a change to a plan they already have (crochet_patterns-lr7mj).
+  const proceed = useCallback(
+    async (offer: ProductOffer, preview: PlanChangePreview | null) => {
+      if (offer.isFree) {
+        await subscribeFree(offer.id);
+        await refetchSubscription();
+        return;
+      }
+      return onPlanChange?.(offer, preview);
+    },
+    [subscribeFree, refetchSubscription, onPlanChange],
+  );
+  const planChange = usePlanChange(proceed);
+
   // startsim-ngw — when the user lands on ?status=success (just back from
   // Stripe checkout), POST /billing/success-sync/ ONCE to populate the cache
   // from Stripe so the UI flips to Trialing/Active without waiting for the
   // webhook, then refetch the subscription. The ref guard prevents the effect
   // re-firing on React StrictMode double-invokes.
   const successSyncedRef = useRef(false);
+  // "syncing" until the paid plan is found or we have looked long enough.
+  // The banner said "activated" from the URL alone, beside "You're on the
+  // Free plan" when the sync had not found it (crochet_patterns-nag60).
+  const [activation, setActivation] = useState<"idle" | "syncing" | "done">("idle");
+  const planFoundRef = useRef(false);
+  // Back from a checkout (session id in the URL): only a paid row is the
+  // plan just bought. Otherwise any row the change produced counts.
+  planFoundRef.current = !!subscription?.offer && (!checkoutSessionId || !subscription.offer.isFree);
   useEffect(() => {
     if (statusMessage === "success" && !successSyncedRef.current) {
       successSyncedRef.current = true;
+      setActivation("syncing");
       (async () => {
         try {
-          await successSync();
-        } finally {
+          await successSync({ sessionId: checkoutSessionId, productSlug: productId });
+        } catch {
+          /* the refetch below still tells us what the backend has */
+        }
+        const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+        for (let i = 0; i < ACTIVATION_POLLS; i++) {
           await refetchSubscription();
+          await sleep(50); // let the refetched row render before reading it
+          if (planFoundRef.current) break;
+          if (i < ACTIVATION_POLLS - 1) await sleep(ACTIVATION_POLL_MS);
         }
+        setActivation("done");
       })();
     }
-  }, [statusMessage, successSync, refetchSubscription]);
+  }, [statusMessage, successSync, refetchSubscription, checkoutSessionId, productId]);
 
   // startsim-z6f: skeleton matching the final layout (current-plan box +
   // 2-card grid) so the transition from loading → loaded doesn't reflow.
@@ -246,53 +306,17 @@ export function SubscriptionManager({
   // for the chosen interval. The card matching their current plan gets a
   // "Current plan" badge + disabled CTA. startsim-1f1, crochet_patterns-34n7.
 
-  /** Per-card direction relative to the current subscription:
-   * - "current"   → user is on this exact offer → "Current Plan" badge, no action
-   * - "upgrade"   → card is a higher tier (paid vs current free, or higher sortOrder)
-   * - "downgrade" → card is a lower tier (free when current is paid, or lower sortOrder)
-   * startsim-21f. */
-  type Direction = "current" | "upgrade" | "downgrade" | "switch";
-  function directionFor(cardOffer: ProductOffer): Direction {
-    if (!currentOffer) return "upgrade"; // plan still unknown → every card is an upgrade
-    if (cardOffer.id === currentOffer.id) return "current";
-    // Same plan, other billing interval (Lite ↔ Lite Annual).
-    const tierKey = tierKeyOf(cardOffer.id);
-    if (tierKey !== null && tierKey === tierKeyOf(currentOffer.id)) return "switch";
-    // Free vs Paid: paid is always an upgrade, free is always a downgrade.
-    if (cardOffer.isFree && !currentOffer.isFree) return "downgrade";
-    if (!cardOffer.isFree && currentOffer.isFree) return "upgrade";
-    // Both paid → compare sortOrder (apps order their tiers low → high).
-    return cardOffer.sortOrder > currentOffer.sortOrder ? "upgrade" : "downgrade";
-  }
-
-  /** Visible CTA label for the card, branching on direction. The default
-   * `offer.ctaText` (e.g. "Start Free Trial") is for UPGRADE only — using it
-   * on a Free card when a Pro user is looking is the bug startsim-21f closes. */
-  function ctaLabelFor(cardOffer: ProductOffer, direction: Direction): string {
-    if (direction === "current") return "Current plan";
-    if (direction === "switch") return cardOffer.intervalUnit === "year" ? "Switch to annual" : "Switch to monthly";
-    if (direction === "downgrade") return `Downgrade to ${cardOffer.name}`;
-    return cardOffer.ctaText || `Upgrade to ${cardOffer.name}`;
-  }
+  // Direction and label per card, shared with /pricing (utils/plan):
+  // startsim-21f, crochet_patterns-anw61.
+  const paying = isPayingSubscription(usableSubscription);
+  const onUnlistedPlan = !!product && isUnlistedOffer(product.offers, usableSubscription?.offer);
+  const directionFor = (cardOffer: ProductOffer): PlanDirection =>
+    planDirection(cardOffer, currentOffer, tierKeyOf);
 
-  // Branch the offer CTA internally so apps don't reinvent it:
-  // - Free offers → POST /billing/subscribe-free/ then refetch subscription
-  //   (no Stripe round-trip needed for $0 plans — startsim-6vk).
-  // - Paid offers → app-supplied onPlanChange (typically a Stripe checkout
-  //   redirect via useCheckout).
-  const handleOfferClick = async (offer: ProductOffer) => {
+  const handleOfferClick = (offer: ProductOffer) => {
     // Non-owner viewers can SEE the plans but can't change them — startsim-wo9.
     if (subscription?.viewerIsOwner === false) return;
-    if (offer.isFree) {
-      try {
-        await subscribeFree(offer.id);
-        await refetchSubscription();
-      } catch {
-        /* Error captured by hook state — banner not added here yet. */
-      }
-      return;
-    }
-    onPlanChange?.(offer);
+    void planChange.choose(offer, { paying, leavingUnlisted: onUnlistedPlan, currentOffer });
   };
 
   // The "Upgrade" CTA on the current-plan card points at the NEXT tier above
@@ -326,7 +350,7 @@ export function SubscriptionManager({
 
   return (
     <div data-testid="subscription-manager" className="max-w-3xl mx-auto px-6 py-12 space-y-8">
-      {statusMessage === "success" && (
+      {statusMessage === "success" && activation === "done" && planFoundRef.current && (
         <div data-testid="status-banner-success" className="rounded-xl bg-green-50 border border-green-200 p-4 flex items-center gap-3">
           <svg className="w-5 h-5 text-green-600 shrink-0" fill="none" viewBox="0 0 24 24" stroke="currentColor" strokeWidth={2}>
             <path strokeLinecap="round" strokeLinejoin="round" d="M5 13l4 4L19 7" />
@@ -344,7 +368,32 @@ export function SubscriptionManager({
         </div>
       )}
 
-      {statusMessage === "activating" && (
+      {statusMessage === "success" && activation === "done" && !planFoundRef.current && (
+        <div data-testid="status-banner-pending" role="status" className="rounded-xl bg-amber-50 border border-amber-200 p-4">
+          <p className="text-sm font-medium text-amber-900">
+            We haven&apos;t received the payment confirmation yet. It can take a minute; refresh this page to check again. Please don&apos;t pay a second time.
+          </p>
+        </div>
+      )}
+
+      {statusMessage === "scheduled" && (
+        <div data-testid="status-banner-scheduled" role="status" className="rounded-xl bg-blue-50 border border-blue-200 p-4">
+          <p className="text-sm font-medium text-blue-900">
+            Your plan change is scheduled.
+            {usableSubscription?.currentPeriodEnd
+              ? <> You keep your current plan until {new Date(usableSubscription.currentPeriodEnd).toLocaleDateString("en-US", { month: "long", day: "numeric", year: "numeric", timeZone: "UTC" })}.</>
+              : <> You keep your current plan until the end of this billing period.</>}
+          </p>
+        </div>
+      )}
+
+      {planChange.error && !planChange.pending && (
+        <div data-testid="plan-change-error" role="alert" className="rounded-xl bg-red-50 border border-red-200 p-4">
+          <p className="text-sm text-red-700">{planChange.error}</p>
+        </div>
+      )}
+
+      {(statusMessage === "activating" || (statusMessage === "success" && activation !== "done")) && (
         <div data-testid="status-banner-activating" className="rounded-xl bg-blue-50 border border-blue-200 p-4 flex items-center gap-3">
           <svg className="w-5 h-5 text-blue-600 shrink-0 animate-spin" fill="none" viewBox="0 0 24 24">
             <circle className="opacity-25" cx="12" cy="12" r="10" stroke="currentColor" strokeWidth="4"></circle>
@@ -380,7 +429,8 @@ export function SubscriptionManager({
               usableSubscription.viewerIsOwner !== false && usableSubscription.offer.isFree && featuredPaidOffer ? (
                 <button
                   data-testid="upgrade-cta-current-plan"
-                  onClick={() => handleOfferClick(featuredPaidOffer)}
+                  onClick={() => !planChange.busy && handleOfferClick(featuredPaidOffer)}
+                  disabled={planChange.busy}
                   className="inline-flex items-center gap-2 px-5 py-2.5 text-sm font-bold rounded-xl bg-blue-600 text-white hover:bg-blue-700 cursor-pointer transition-colors"
                 >
                   Upgrade to {featuredPaidOffer.name} →
@@ -389,7 +439,7 @@ export function SubscriptionManager({
             }
           />
         </>
-      ) : onFreeByDefault && freeOffer ? (
+      ) : statusMessage === "success" && activation !== "done" ? null : onFreeByDefault && freeOffer ? (
         <div data-testid="free-by-default" className="text-center py-8">
           <p className="text-lg text-gray-600">You&apos;re on the {freeOffer.name} plan</p>
           <p className="text-sm text-gray-400 mt-1">Choose a plan below to upgrade.</p>
@@ -446,7 +496,8 @@ export function SubscriptionManager({
               const direction = directionFor(offer);
               const isCurrent = direction === "current";
               const isDowngrade = direction === "downgrade" || direction === "switch";
-              const ctaLabel = ctaLabelFor(offer, direction);
+              const ctaLabel = planCtaLabel(offer, direction, paying);
+              const showTrial = trialApplies(offer, direction, paying);
 
               // Border: current = solid ring; featured upgrade = blue; else gray.
               const cardBorder =
@@ -491,13 +542,14 @@ export function SubscriptionManager({
                   {/* Trial copy is for prospective trialers only — once the
                       user is on this offer or moving downward, drop the
                       "14-day free trial" sales pitch. */}
-                  {direction === "upgrade" && <TrialCopy trialDays={offer.trialDays} />}
-                  <PlanFeatureList features={offer.features} />
+                  {showTrial && <TrialCopy trialDays={offer.trialDays} />}
+                  <PlanFeatureList features={offer.features} showTrialNote={showTrial || !(offer.trialDays > 0)} />
                   <button
                     data-testid={`upgrade-cta-${offer.slug}`}
-                    onClick={() => !isCurrent && !isViewerNonOwner && handleOfferClick(offer)}
-                    disabled={isCurrent || isViewerNonOwner}
-                    aria-disabled={isCurrent || isViewerNonOwner || undefined}
+                    onClick={() => !isCurrent && !isViewerNonOwner && !planChange.busy && handleOfferClick(offer)}
+                    disabled={isCurrent || isViewerNonOwner || planChange.busy}
+                    aria-disabled={isCurrent || isViewerNonOwner || planChange.busy || undefined}
+                    aria-busy={planChange.busy && planChange.pending?.offer.id === offer.id ? true : undefined}
                     title={isViewerNonOwner ? "Only the team owner can change the plan" : undefined}
                     className={`w-full py-2.5 px-4 text-sm font-bold rounded-xl transition-colors ${ctaClass} ${isViewerNonOwner ? "opacity-60 cursor-not-allowed" : ""}`}
                   >
@@ -532,6 +584,14 @@ export function SubscriptionManager({
           </button>
         </div>
       )}
+
+      <PlanChangeConfirm
+        state={planChange.pending}
+        confirming={planChange.confirming}
+        error={planChange.pending ? planChange.error : null}
+        onConfirm={planChange.confirm}
+        onCancel={planChange.cancel}
+      />
     </div>
   );
 }

package/src/components/UpgradeModal.tsx

@@ -11,17 +11,31 @@
 
 import React, { useEffect, useRef, useCallback } from "react";
 import { useProduct } from "../hooks/useProduct";
-import type { ProductOffer } from "../types";
+import type { PlanChangePreview, ProductOffer } from "../types";
 import { FeatureIcon } from "./FeatureIcon";
 import { formatFeatureLabel } from "../utils/format";
-import { resolveCurrentOfferId, type CurrentPlanState } from "../utils/plan";
+import {
+  isPayingSubscription,
+  isUnlistedOffer,
+  planCtaLabel,
+  planDirection,
+  resolveCurrentOffer,
+  trialApplies,
+  TRIAL_NOTE_FEATURE_KEY,
+  type CurrentPlanState,
+} from "../utils/plan";
+import { usePlanChange } from "../hooks/usePlanChange";
+import { PlanChangeConfirm } from "./PlanChangeConfirm";
 import { AnnualNote, IntervalToggle, OfferPrice, useIntervalOffers } from "./IntervalToggle";
 
 export interface UpgradeModalProps {
   productId: string;
   open: boolean;
   onClose: () => void;
-  onSelectOffer?: (offer: ProductOffer) => void;
+  /** Does the purchase / change. For a viewer who already pays it runs only
+   * after they confirm the charge (crochet_patterns-anw61). Return
+   * "navigating" after sending the browser away; throw to show an error. */
+  onSelectOffer?: (offer: ProductOffer, preview?: PlanChangePreview | null) => unknown;
 
   /** The viewer's plan, so their card reads "Current plan" and is disabled.
    * Omit on signed-out pages. crochet_patterns-34n7. */
@@ -36,10 +50,23 @@ export function UpgradeModal({
   currentPlan,
 }: UpgradeModalProps) {
   const { product, loading, error } = useProduct(productId);
+  const currentOffer = resolveCurrentOffer(product?.offers ?? [], currentPlan);
   const { interval, setInterval, hasChoice, entries } = useIntervalOffers(
     product?.offers ?? [],
-    resolveCurrentOfferId(product?.offers ?? [], currentPlan),
+    currentOffer?.id ?? null,
   );
+  const planChange = usePlanChange(async (offer, preview) => onSelectOffer?.(offer, preview));
+  const paying = !!currentOffer && isPayingSubscription(currentPlan?.subscription);
+  const onUnlistedPlan = isUnlistedOffer(product?.offers ?? [], currentOffer);
+  const tierKeyOf = (offerId: string) =>
+    entries.find(({ tier }) => tier.monthly?.id === offerId || tier.annual?.id === offerId)?.tier.key ?? null;
+  const select = (offer: ProductOffer) => {
+    if (!currentOffer) {
+      onSelectOffer?.(offer);
+      return;
+    }
+    void planChange.choose(offer, { paying, leavingUnlisted: onUnlistedPlan, currentOffer });
+  };
   const modalRef = useRef<HTMLDivElement>(null);
   const previousFocusRef = useRef<HTMLElement | null>(null);
 
@@ -143,7 +170,12 @@ export function UpgradeModal({
             {entries.map((entry) => {
               const { offer, tier } = entry;
               const isFeatured = offer.isFeatured;
-              const isCurrent = offer.id === resolveCurrentOfferId(product.offers, currentPlan);
+              const direction = currentOffer ? planDirection(offer, currentOffer, tierKeyOf) : null;
+              const isCurrent = direction === "current";
+              const trial = direction ? trialApplies(offer, direction, paying) : offer.trialDays > 0;
+              const features = trial || !(offer.trialDays > 0)
+                ? offer.features
+                : offer.features.filter((f) => f.key !== TRIAL_NOTE_FEATURE_KEY);
               return (
                 <div
                   key={offer.id}
@@ -167,15 +199,15 @@ export function UpgradeModal({
                     <AnnualNote entry={entry} className="mt-1" />
                   </div>
 
-                  {offer.trialDays > 0 && (
-                    <span className="inline-block bg-blue-50 text-blue-700 text-xs font-semibold px-2.5 py-0.5 rounded-md mb-3 w-fit">
+                  {trial && (
+                    <span data-testid={`trial-pill-${offer.slug}`} className="inline-block bg-blue-50 text-blue-700 text-xs font-semibold px-2.5 py-0.5 rounded-md mb-3 w-fit">
                       {offer.trialDays}-day free trial
                     </span>
                   )}
 
-                  {offer.features.length > 0 && (
+                  {features.length > 0 && (
                     <ul className="list-none p-0 m-0 mb-4 flex-1 space-y-0">
-                      {offer.features.map((f) => (
+                      {features.map((f) => (
                         <li key={f.key} className="flex items-center gap-1.5 py-1 text-sm text-gray-600">
                           <FeatureIcon value={f.value} size="w-3.5 h-3.5" />
                           <span>{formatFeatureLabel(f)}</span>
@@ -185,10 +217,10 @@ export function UpgradeModal({
                   )}
 
                   <button
-                    onClick={() => !isCurrent && onSelectOffer?.(offer)}
+                    onClick={() => !isCurrent && !planChange.busy && select(offer)}
                     data-testid={`upgrade-cta-${offer.slug}`}
-                    disabled={isCurrent}
-                    aria-disabled={isCurrent || undefined}
+                    disabled={isCurrent || planChange.busy}
+                    aria-disabled={isCurrent || planChange.busy || undefined}
                     className={`
                       w-full py-2.5 px-4 text-sm font-bold rounded-lg transition-colors
                       ${isCurrent
@@ -199,14 +231,26 @@ export function UpgradeModal({
                       }
                     `}
                   >
-                    {isCurrent ? "Current plan" : offer.ctaText}
+                    {isCurrent ? "Current plan" : direction ? planCtaLabel(offer, direction, paying) : offer.ctaText}
                   </button>
                 </div>
               );
             })}
           </div>
         )}
+        {planChange.error && !planChange.pending && (
+          <p data-testid="plan-change-error" role="alert" className="mt-4 rounded-lg bg-red-50 border border-red-200 p-3 text-sm text-red-700">
+            {planChange.error}
+          </p>
+        )}
       </div>
+      <PlanChangeConfirm
+        state={planChange.pending}
+        confirming={planChange.confirming}
+        error={planChange.pending ? planChange.error : null}
+        onConfirm={planChange.confirm}
+        onCancel={planChange.cancel}
+      />
     </div>
   );
 }

package/src/components/index.ts

@@ -16,3 +16,5 @@ export { CurrentPlanCard } from "./CurrentPlanCard";
 export type { CurrentPlanCardProps } from "./CurrentPlanCard";
 export { LimitNudge } from "./LimitNudge";
 export type { LimitNudgeProps } from "./LimitNudge";
+export { PlanChangeConfirm, planChangeCopy } from "./PlanChangeConfirm";
+export type { PlanChangeConfirmProps } from "./PlanChangeConfirm";

package/src/hooks/index.ts

@@ -6,3 +6,5 @@ export { usePortal } from "./usePortal";
 export { useSubscription } from "./useSubscription";
 export { useSuccessSync } from "./useSuccessSync";
 export { useUsage, notifyUsageChanged, USAGE_CHANGED_EVENT } from "./useUsage";
+export { usePlanChange } from "./usePlanChange";
+export type { PlanChangeContext, PlanChangeConfirmState, PlanChangeProceed, UsePlanChangeResult } from "./usePlanChange";