@carrierllc/mcp 0.13.40 → 0.13.47

package/templates/storefront/src/components/landing/TierPlanBoard.tsx

@@ -0,0 +1,237 @@
+"use client";
+
+import { useState } from "react";
+import Link from "next/link";
+import { formatDataAllowance, formatPrice, formatValidity } from "@/vendor/geo";
+import {
+  TIER_HELP_COPY,
+  combinations,
+  dataChoices,
+  presentTierCatalog,
+  skuFor,
+  tierChoiceSku,
+  tierEmptyCopy,
+  validityChoices,
+  type SpeedTier,
+} from "@/vendor/carrier/tiers";
+import type { SkuTemplate } from "@/vendor/carrier/types";
+import { cn } from "@/vendor/ui/cn";
+
+interface TierPlanBoardProps {
+  plans: SkuTemplate[];
+  mode: "select" | "link";
+  /** Per-tenant Lightning switch. Off unless the tenant configured it. */
+  lightningEnabled?: boolean;
+  selectedId?: string | null;
+  /** Tier radio. Selects the current data and validity, including a single plan. */
+  onSelect?: (plan: SkuTemplate) => void;
+  /** Data or validity radio. Does not select a tier and does not scroll. */
+  onAdjust?: (plan: SkuTemplate) => void;
+}
+
+const secondary = "text-sand-700 dark:text-sand-200";
+
+export function TierPlanBoard({
+  plans,
+  mode,
+  lightningEnabled = false,
+  selectedId,
+  onSelect,
+  onAdjust,
+}: TierPlanBoardProps) {
+  const view = presentTierCatalog(plans, { lightningEnabled });
+
+  return (
+    <div role="radiogroup" aria-label="Speed tier" className="grid grid-cols-1 gap-8 lg:grid-cols-3">
+      {view.tiers.map((group) => (
+        <TierCard
+          key={group.tier}
+          tier={group.tier}
+          plans={group.plans}
+          featured={group.tier === "Cruise" && group.plans.length > 0}
+          mode={mode}
+          selectedId={selectedId}
+          onSelect={onSelect}
+          onAdjust={onAdjust}
+        />
+      ))}
+    </div>
+  );
+}
+
+function TierCard({
+  tier,
+  plans,
+  featured,
+  mode,
+  selectedId,
+  onSelect,
+  onAdjust,
+}: {
+  tier: SpeedTier;
+  plans: SkuTemplate[];
+  featured: boolean;
+  mode: "select" | "link";
+  selectedId?: string | null;
+  onSelect?: (plan: SkuTemplate) => void;
+  onAdjust?: (plan: SkuTemplate) => void;
+}) {
+  const first = combinations(plans)[0];
+  const [dataGb, setDataGb] = useState(first?.dataGb ?? 0);
+  const [validityDays, setValidityDays] = useState(first?.validityDays ?? 0);
+  const sku = skuFor(plans, dataGb, validityDays);
+  const selected = sku !== null && sku.id === selectedId;
+
+  function chooseData(next: number) {
+    const days = validityChoices(plans, next);
+    const validity = days.includes(validityDays) ? validityDays : days[0];
+    if (validity === undefined) return;
+    setDataGb(next);
+    setValidityDays(validity);
+    const nextSku = skuFor(plans, next, validity);
+    if (nextSku) onAdjust?.(nextSku);
+  }
+
+  function chooseValidity(next: number) {
+    setValidityDays(next);
+    const nextSku = skuFor(plans, dataGb, next);
+    if (nextSku) onAdjust?.(nextSku);
+  }
+
+  function selectTier() {
+    const choice = sku ?? tierChoiceSku(plans);
+    if (choice) onSelect?.(choice);
+  }
+
+  return (
+    <article
+      data-tier={tier}
+      className={cn(
+        "relative flex flex-col gap-4 rounded-2xl border p-6",
+        selected && "border-[var(--brand-accent)]",
+        featured
+          ? "border-[var(--brand-accent)] bg-[color-mix(in_srgb,var(--brand-accent)_6%,white)] dark:bg-[color-mix(in_srgb,var(--brand-accent)_12%,#0F0E0A)]"
+          : "border-sand-200 bg-white dark:border-sand-700 dark:bg-sand-900",
+      )}
+    >
+      {featured ? (
+        <span
+          className="absolute left-1/2 top-0 -translate-x-1/2 -translate-y-1/2 rounded-full px-3 py-0.5 text-xs font-semibold"
+          style={{ background: "var(--brand-accent)", color: "var(--brand-on-accent)" }}
+        >
+          Most popular
+        </span>
+      ) : null}
+      <div>
+        <h3 className="font-semibold text-sand-900 dark:text-sand-50">{tier}</h3>
+        <p className={cn("mt-0.5 text-sm", secondary)}>{plans.length === 0 ? tierEmptyCopy(tier) : TIER_HELP_COPY}</p>
+      </div>
+
+      {plans.length === 0 ? null : (
+        <>
+          {mode === "select" ? (
+            <label className={cn("inline-flex min-h-11 cursor-pointer items-center gap-2 text-base font-semibold text-sand-900 dark:text-sand-50")}>
+              <input
+                type="radio"
+                name="speed-tier"
+                value={tier}
+                checked={selected}
+                aria-checked={selected}
+                onChange={selectTier}
+              />
+              <span>{selected ? "Selected" : `Select ${tier}`}</span>
+              {selected ? (
+                <span aria-hidden="true" className="text-[var(--brand-accent-text)]">
+                  ✓
+                </span>
+              ) : null}
+            </label>
+          ) : null}
+          <ChoiceGroup
+            legend="Data"
+            name={`${tier}-data`}
+            value={dataGb}
+            options={dataChoices(plans).map((amount) => ({
+              value: amount,
+              label: formatDataAllowance(amount, plans.find((plan) => plan.dataGb === amount)?.unlimited),
+            }))}
+            onChange={chooseData}
+          />
+          <ChoiceGroup
+            legend="Validity"
+            name={`${tier}-validity`}
+            value={validityDays}
+            options={validityChoices(plans, dataGb).map((days) => ({
+              value: days,
+              label: formatValidity(days),
+            }))}
+            onChange={chooseValidity}
+          />
+          {sku ? (
+            sku.price_unavailable ? (
+              <p className="text-3xl font-bold text-sand-900 dark:text-sand-50" data-sku={sku.id} aria-live="polite">
+                Unavailable
+              </p>
+            ) : (
+              <p
+                className="text-3xl font-bold text-sand-900 dark:text-sand-50"
+                data-unit-amount={sku.price_cents}
+                data-currency={sku.currency}
+                data-sku={sku.id}
+                aria-live="polite"
+              >
+                {formatPrice(sku.price_cents, sku.currency)}
+              </p>
+            )
+          ) : null}
+          {mode === "link" && sku && sku.price_unavailable !== true ? (
+            <Link
+              href={`/checkout/${sku.id}`}
+              className="mt-auto inline-flex min-h-11 items-center justify-center rounded-full px-6 text-center text-base font-semibold"
+              style={{ background: "var(--brand-accent)", color: "var(--brand-on-accent)" }}
+            >
+              Select plan
+            </Link>
+          ) : null}
+        </>
+      )}
+    </article>
+  );
+}
+
+function ChoiceGroup({
+  legend,
+  name,
+  value,
+  options,
+  onChange,
+}: {
+  legend: string;
+  name: string;
+  value: number;
+  options: Array<{ value: number; label: string }>;
+  onChange: (value: number) => void;
+}) {
+  return (
+    <fieldset className="space-y-2">
+      <legend className={cn("text-xs font-semibold uppercase tracking-widest", secondary)}>{legend}</legend>
+      <div className="flex flex-wrap gap-2">
+        {options.map((option) => (
+          <label
+            key={option.value}
+            className="inline-flex min-h-11 cursor-pointer items-center gap-2 rounded-full border border-sand-300 px-3 text-base text-sand-900 dark:border-sand-600 dark:text-sand-50"
+          >
+            <input
+              type="radio"
+              name={name}
+              value={option.value}
+              checked={option.value === value}
+              onChange={() => onChange(option.value)}
+            />
+            {option.label}
+          </label>
+        ))}
+      </div>
+    </fieldset>
+  );
+}

package/templates/storefront/src/components/nav/StorefrontNav.tsx

@@ -8,6 +8,7 @@ import { SignedIn, SignedOut, UserButton } from "@clerk/nextjs";
 import { cn } from "@/vendor/ui/cn";
 import brand from "@/brand.config";
 import { ThemeToggle } from "@/components/theme/ThemeToggle";
+import { filledAccentClass } from "@/lib/tap-target";
 
 const NAV_LINKS = [
   { label: "Plans", href: "/shop" },
@@ -35,9 +36,9 @@ export function StorefrontNav() {
                 key={link.href}
                 href={link.href}
                 className={cn(
-                  "text-sm transition-colors",
+                  "inline-flex min-h-11 items-center text-base transition-colors",
                   active
-                    ? "font-medium text-[var(--brand-accent)]"
+                    ? "font-medium text-[var(--brand-accent-text)]"
                     : "text-sand-600 hover:text-sand-900 dark:text-sand-400 dark:hover:text-sand-50",
                 )}
               >
@@ -52,22 +53,18 @@ export function StorefrontNav() {
           <SignedOut>
             <Link
               href="/sign-in"
-              className="hidden text-sm text-sand-600 hover:text-sand-900 dark:text-sand-400 dark:hover:text-sand-50 sm:inline"
+              className="hidden min-h-11 items-center text-base text-sand-600 hover:text-sand-900 dark:text-sand-400 dark:hover:text-sand-50 sm:inline-flex"
             >
               Sign in
             </Link>
-            <Link
-              href="/shop"
-              className="rounded-full px-4 py-1.5 text-sm font-semibold text-white transition-opacity hover:opacity-90"
-              style={{ background: "var(--brand-accent)" }}
-            >
+            <Link href="/shop" className={filledAccentClass}>
               Get connected
             </Link>
           </SignedOut>
           <SignedIn>
             <Link
               href="/dashboard"
-              className="hidden text-sm text-sand-600 hover:text-sand-900 dark:text-sand-400 dark:hover:text-sand-50 sm:inline"
+              className="hidden min-h-11 items-center text-base text-sand-600 hover:text-sand-900 dark:text-sand-400 dark:hover:text-sand-50 sm:inline-flex"
             >
               Dashboard
             </Link>
@@ -75,7 +72,7 @@ export function StorefrontNav() {
           </SignedIn>
           <button
             type="button"
-            className="inline-flex size-9 items-center justify-center rounded-full border border-sand-200 text-sand-800 md:hidden dark:border-sand-700 dark:text-sand-100"
+            className="inline-flex size-11 min-h-11 min-w-11 items-center justify-center rounded-full border border-sand-200 text-sand-800 md:hidden dark:border-sand-700 dark:text-sand-100"
             aria-label={open ? "Close menu" : "Open menu"}
             onClick={() => setOpen((v) => !v)}
           >
@@ -92,7 +89,7 @@ export function StorefrontNav() {
                 key={link.href}
                 href={link.href}
                 onClick={() => setOpen(false)}
-                className="text-sm font-medium text-sand-800 dark:text-sand-100"
+                className="inline-flex min-h-11 items-center text-base font-medium text-sand-800 dark:text-sand-100"
               >
                 {link.label}
               </Link>

package/templates/storefront/src/components/shop/CountrySearch.tsx

@@ -0,0 +1,94 @@
+"use client";
+
+import { useMemo, useState } from "react";
+import Link from "next/link";
+import { countryOffers, visibleCountryOffers } from "@/vendor/carrier/country-offers";
+import type { SkuTemplate } from "@/vendor/carrier/types";
+import { formatPrice } from "@/vendor/geo";
+import { fieldClass, textLinkClass } from "@/lib/tap-target";
+
+interface Props {
+  plans: SkuTemplate[];
+  /** Pre-fills the box. A two-letter code matches that country exactly. */
+  initialQuery?: string;
+}
+
+export function CountrySearch({ plans, initialQuery = "" }: Props) {
+  const [query, setQuery] = useState(initialQuery);
+  const offers = useMemo(
+    () =>
+      countryOffers(
+        plans.map((plan) => ({
+          id: plan.id,
+          priceCents: plan.price_cents,
+          currency: plan.currency,
+          regions: plan.regions,
+        })),
+      ),
+    [plans],
+  );
+  const rows = useMemo(() => visibleCountryOffers(offers, query), [offers, query]);
+  const searching = query.trim() !== "";
+
+  return (
+    <section aria-label="Countries" className="mx-auto w-full max-w-6xl min-w-0 px-4">
+      <label htmlFor="country-search" className="block text-xs font-semibold uppercase tracking-[0.18em] text-sand-500">
+        Countries
+      </label>
+      <h2 className="mt-2 text-3xl font-semibold tracking-tight text-sand-900 dark:text-sand-50">
+        Where are you going?
+      </h2>
+      <p className="mt-2 max-w-lg text-sand-600 dark:text-sand-400">
+        Search the countries this shop sells. The list updates as you type.
+      </p>
+      <input
+        id="country-search"
+        type="search"
+        enterKeyHint="search"
+        autoComplete="off"
+        placeholder="Try Germany or Japan"
+        value={query}
+        onChange={(event) => setQuery(event.target.value)}
+        aria-controls="country-list"
+        className={`${fieldClass} mt-6`}
+      />
+      <p className="mt-3 text-sm text-sand-600 dark:text-sand-400" aria-live="polite">
+        {searching
+          ? rows.length === 1
+            ? "1 country"
+            : `${rows.length} countries`
+          : "Popular countries. Type to search the rest."}
+      </p>
+      <ul id="country-list" className="mt-2 divide-y divide-sand-200 dark:divide-sand-800">
+        {rows.map((offer) => {
+          const price =
+            offer.fromCents !== null && offer.currency
+              ? formatPrice(offer.fromCents, offer.currency)
+              : null;
+          return (
+            <li key={offer.code}>
+              <Link
+                href={`/shop?country=${offer.code}`}
+                data-country={offer.code}
+                className="flex min-h-11 min-w-0 items-center justify-between gap-3 py-2 text-base text-sand-900 dark:text-sand-50"
+              >
+                <span className="min-w-0 break-words">{offer.name}</span>
+                <span className="shrink-0 font-mono text-sm text-sand-500">
+                  {price ? `From ${price}` : offer.code}
+                </span>
+              </Link>
+            </li>
+          );
+        })}
+      </ul>
+      {searching && rows.length === 0 && (
+        <p className="mt-4 text-base text-sand-700 dark:text-sand-200">
+          No countries match that search.{" "}
+          <Link href="/shop" className={textLinkClass}>
+            Browse plans
+          </Link>
+        </p>
+      )}
+    </section>
+  );
+}

package/templates/storefront/src/components/theme/BrandStyles.tsx

@@ -1,8 +1,8 @@
 import brand from "@/brand.config";
+import { brandStyleCss } from "@/components/theme/brand-style";
 
 /** Inject operator accent at runtime so editing brand.config.ts actually re-skins the shop. */
 export function BrandStyles() {
-  const { accent, accentDark, accentLight } = brand.colors;
-  const css = `:root{--brand-accent:${accent};--brand-accent-dark:${accentDark};--brand-accent-light:${accentLight};}`;
+  const css = brandStyleCss(brand.colors);
   return <style dangerouslySetInnerHTML={{ __html: css }} />;
 }

package/templates/storefront/src/components/theme/ThemeToggle.tsx

@@ -10,7 +10,7 @@ export function ThemeToggle() {
       type="button"
       onClick={toggle}
       aria-label={dark ? "Switch to light theme" : "Switch to dark theme"}
-      className="inline-flex size-9 items-center justify-center rounded-full border border-sand-200 text-sand-700 transition-colors hover:border-sand-400 hover:text-sand-900 dark:border-sand-700 dark:text-sand-200 dark:hover:border-sand-500 dark:hover:text-sand-50"
+      className="inline-flex size-11 min-h-11 min-w-11 items-center justify-center rounded-full border border-sand-200 text-sand-700 transition-colors hover:border-sand-400 hover:text-sand-900 dark:border-sand-700 dark:text-sand-200 dark:hover:border-sand-500 dark:hover:text-sand-50"
     >
       {dark ? (
         <svg viewBox="0 0 24 24" className="size-4" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden>

package/templates/storefront/src/components/theme/brand-accent-css.ts

@@ -0,0 +1,21 @@
+/**
+ * Runtime accent sheet.
+ *
+ * The dark rule is unlayered and more specific than `:root`, so it wins over
+ * both the light value and any `@layer base` copy of the light token.
+ */
+export function brandAccentStyleSheet(colors: {
+  accent: string;
+  accentDark: string;
+  accentLight: string;
+  onAccent: string;
+  accentText: string;
+  accentTextDark: string;
+}): string {
+  return (
+    `:root{--brand-accent:${colors.accent};--brand-accent-dark:${colors.accentDark};` +
+    `--brand-accent-light:${colors.accentLight};--brand-on-accent:${colors.onAccent};` +
+    `--brand-accent-text:${colors.accentText};}` +
+    `html[data-theme="dark"]{--brand-accent-text:${colors.accentTextDark};}`
+  );
+}

package/templates/storefront/src/components/theme/brand-style.ts

@@ -0,0 +1,88 @@
+/**
+ * Accent tokens for the storefront template.
+ * Emitted inside `@layer base`. Dark values apply only under `html[data-theme="dark"]`.
+ */
+
+export const FLAME = "#FF6B35";
+export const FLAME_TEXT_LIGHT = "#C2410C";
+export const FLAME_TEXT_DARK = "#FF8A5C";
+export const SAND_50 = "#FAFAF7";
+export const SAND_800 = "#2C291F";
+export const SAND_900 = "#1A1812";
+export const SAND_950 = "#0F0E0A";
+
+export interface BrandColors {
+  accent: string;
+  accentDark: string;
+  accentLight: string;
+}
+
+export function contrastRatio(foreground: string, background: string): number {
+  const lighter = Math.max(relativeLuminance(foreground), relativeLuminance(background));
+  const darker = Math.min(relativeLuminance(foreground), relativeLuminance(background));
+  return (lighter + 0.05) / (darker + 0.05);
+}
+
+export function readableOn(background: string): "#111111" | "#FFFFFF" {
+  const black = contrastRatio("#111111", background);
+  const white = contrastRatio("#FFFFFF", background);
+  if (black >= 4.5 && black >= white) return "#111111";
+  if (white >= 4.5) return "#FFFFFF";
+  return black >= white ? "#111111" : "#FFFFFF";
+}
+
+/** Accent-coloured text. Flame uses the checked pair. Any other accent is shaded until it clears 4.5:1. */
+export function accentText(accent: string, background: string, mode: "light" | "dark"): string {
+  if (accent.trim().toUpperCase() === FLAME) return mode === "light" ? FLAME_TEXT_LIGHT : FLAME_TEXT_DARK;
+  const toward = mode === "light" ? "#000000" : "#FFFFFF";
+  if (contrastRatio(accent, background) >= 4.5) return accent.trim().toUpperCase();
+  for (let step = 1; step <= 20; step += 1) {
+    const mixed = mix(accent, toward, step / 20);
+    if (contrastRatio(mixed, background) >= 4.5) return mixed;
+  }
+  return readableOn(background);
+}
+
+/** Focus ring. At least 3:1 on the background it is drawn on. */
+export function focusColor(accent: string, background: string, mode: "light" | "dark"): string {
+  const text = accentText(accent, background, mode);
+  if (contrastRatio(text, background) >= 3) return text;
+  return readableOn(background);
+}
+
+export function brandStyleCss(colors: BrandColors): string {
+  const accent = colors.accent.trim();
+  const onAccent = readableOn(accent);
+  const textLight = accentText(accent, SAND_50, "light");
+  const textDark = accentText(accent, SAND_950, "dark");
+  const focusLight = focusColor(accent, SAND_50, "light");
+  const focusDark = focusColor(accent, SAND_800, "dark");
+  const light = `:root{--brand-accent:${accent};--brand-accent-dark:${colors.accentDark};--brand-accent-light:${colors.accentLight};--brand-on-accent:${onAccent};--brand-accent-text:${textLight};--brand-focus:${focusLight};}`;
+  const dark = `--brand-accent-text:${textDark};--brand-focus:${focusDark};`;
+  return `@layer base{${light}html[data-theme="dark"]{${dark}}}`;
+}
+
+function relativeLuminance(hex: string): number {
+  const value = hex.trim().replace(/^#/, "");
+  const channel = (index: number) => {
+    const unit = Number.parseInt(value.slice(index, index + 2), 16) / 255;
+    return unit <= 0.04045 ? unit / 12.92 : ((unit + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * channel(0) + 0.7152 * channel(2) + 0.0722 * channel(4);
+}
+
+function mix(from: string, to: string, amount: number): string {
+  const left = rgb(from);
+  const right = rgb(to);
+  const channel = (index: number) => Math.round(left[index] + (right[index] - left[index]) * amount);
+  return `#${[0, 1, 2].map((index) => channel(index).toString(16).padStart(2, "0")).join("").toUpperCase()}`;
+}
+
+function rgb(hex: string): [number, number, number] {
+  const value = hex.trim().replace(/^#/, "");
+  return [
+    Number.parseInt(value.slice(0, 2), 16),
+    Number.parseInt(value.slice(2, 4), 16),
+    Number.parseInt(value.slice(4, 6), 16),
+  ];
+}

package/templates/storefront/src/components/theme/clerk-appearance.ts

@@ -1,6 +1,8 @@
 import brand from "@/brand.config";
 
 const accent = brand.colors.accent;
+const onAccent = "#111111";
+const accentText = "#C2410C";
 const sand = {
   paper: "#FAFAF7",
   card: "#FFFFFF",
@@ -33,6 +35,8 @@ export const clerkAppearance: object = {
       backgroundColor: sand.paper,
       border: `1px solid ${sand.border}`,
       color: sand.ink,
+      fontSize: "16px",
+      minHeight: "44px",
     },
     socialButtonsBlockButtonText: { color: sand.ink },
     dividerLine: { backgroundColor: sand.border },
@@ -42,8 +46,20 @@ export const clerkAppearance: object = {
       backgroundColor: sand.paper,
       border: `1px solid ${sand.border}`,
       color: sand.ink,
+      fontSize: "16px",
+      minHeight: "44px",
     },
-    footerActionLink: { color: accent },
-    identityPreviewEditButton: { color: accent },
+    formButtonPrimary: {
+      backgroundColor: accent,
+      color: onAccent,
+      fontSize: "16px",
+      minHeight: "44px",
+    },
+    footerActionLink: { color: accentText, fontSize: "16px", minHeight: "44px" },
+    formFieldAction: { color: accentText, fontSize: "16px", minHeight: "44px" },
+    identityPreviewEditButton: { color: accentText, minHeight: "44px" },
+    avatarBox: { width: "44px", height: "44px" },
+    organizationSwitcherTrigger: { display: "none" },
+    organizationListCreateOrganizationActionButton: { display: "none" },
   },
 };

package/templates/storefront/src/lib/buyer-auth-copy.ts

@@ -0,0 +1,83 @@
+/**
+ * Buyer-facing sign-in copy.
+ *
+ * The words are the same whether or not an account exists. Clerk's own
+ * error text names that difference, so it never reaches the page.
+ */
+
+export const BUYER_AUTH_COPY = {
+  rejected: "Email or password is wrong.",
+  sessionExists: "You're already signed in on this browser. Open your orders, or sign out first.",
+  resetSent: "If an account exists, we've sent a code.",
+  secondFactor:
+    "This account needs a second step this page can't finish. Use Forgot password, or contact the shop.",
+  resetRejected: "That code didn't work. Request a new one.",
+} as const;
+
+/** A finished sign-in continues. Anything else gets a clear next step, not a blank page. */
+export function signInStatusCopy(status: string | null | undefined): "complete" | "second-factor" {
+  return status === "complete" ? "complete" : "second-factor";
+}
+
+/**
+ * The reset screen after the email step.
+ *
+ * Callers use this on success and on failure. The page must not grow a
+ * second message for "no such account".
+ */
+export function resetEmailOutcome(): { step: "reset-password"; message: string } {
+  return { step: "reset-password", message: BUYER_AUTH_COPY.resetSent };
+}
+
+/**
+ * Buyer sentences for Clerk error codes.
+ *
+ * The raw `message` and `longMessage` stay off the page. An unknown code
+ * uses the caller's fallback, which is the same sentence for "no such
+ * account" and "wrong password" on sign-in.
+ */
+export const CLERK_ERROR_COPY: Record<string, string> = {
+  form_identifier_not_found: BUYER_AUTH_COPY.rejected,
+  form_password_incorrect: BUYER_AUTH_COPY.rejected,
+  form_password_pwned: "Choose a password that is harder to guess.",
+  form_password_length_too_short: "Use at least 8 characters.",
+  form_password_not_strong_enough: "Choose a stronger password.",
+  form_password_validation_failed: "That password doesn't meet the rules.",
+  form_code_incorrect: BUYER_AUTH_COPY.resetRejected,
+  form_param_format_invalid: "Check what you typed and try again.",
+  form_param_nil: "Fill in every field and try again.",
+  form_identifier_exists: "An account with that email already exists. Sign in instead.",
+  too_many_requests: "Too many attempts. Wait a moment and try again.",
+  user_locked: "This account is locked. Contact the shop.",
+  session_exists: BUYER_AUTH_COPY.sessionExists,
+  identifier_already_signed_in: BUYER_AUTH_COPY.sessionExists,
+};
+
+/** Codes that do not tell a stranger whether the account exists. */
+export const SIGN_IN_CLERK_CODES = [
+  "form_identifier_not_found",
+  "form_password_incorrect",
+  "form_param_format_invalid",
+  "too_many_requests",
+  "session_exists",
+  "identifier_already_signed_in",
+] as const;
+
+export function buyerCopyForClerkError(
+  err: unknown,
+  fallback: string,
+  allowedCodes?: readonly string[],
+): string {
+  const code = clerkErrorCode(err);
+  if (!code) return fallback;
+  if (allowedCodes && !allowedCodes.includes(code)) return fallback;
+  return CLERK_ERROR_COPY[code] ?? fallback;
+}
+
+function clerkErrorCode(err: unknown): string | undefined {
+  if (!err || typeof err !== "object") return undefined;
+  const errors = (err as { errors?: unknown }).errors;
+  if (!Array.isArray(errors)) return undefined;
+  const code = (errors[0] as { code?: unknown } | undefined)?.code;
+  return typeof code === "string" && code.trim() !== "" ? code : undefined;
+}

package/templates/storefront/src/lib/buyer-error.ts

@@ -0,0 +1,32 @@
+/**
+ * Copy a buyer may see when a dashboard or activate action fails.
+ * The kind chooses the sentence. A server string or a browser error never does.
+ */
+
+export const PLAN_UNREACHABLE =
+  "We couldn't reach your plan just now. Nothing was changed. Try again in a minute.";
+export const PHONE_UNSAVED =
+  "We couldn't save that number. Nothing else changed. Try again in a minute.";
+
+export type BuyerErrorKind = "plan" | "phone";
+
+export function buyerFacingError(kind: BuyerErrorKind, _detail?: unknown): string {
+  switch (kind) {
+    case "plan":
+      return PLAN_UNREACHABLE;
+    case "phone":
+      return PHONE_UNSAVED;
+    default: {
+      const unknown: never = kind;
+      return unknown;
+    }
+  }
+}
+
+export async function readIgnoredJson(response: Response): Promise<void> {
+  try {
+    await response.json();
+  } catch {
+    // The status already chose the copy.
+  }
+}