@forgecart/cli 2.202610141948.0 → 2.202610150140.0

package/templates/storefront/src/components/account/RegisterForm.tsx

@@ -3,14 +3,10 @@
 import { useState } from 'react';
 
 import { AccountMessage, type AccountMessageTone } from './AccountMessage';
+import { VerificationResend } from './VerificationResend';
 import { LocaleLink } from '../LocaleLink';
-import { submitVerificationRequest } from '../../lib/account-actions';
 import { registerCustomerAccount } from '../../lib/account-session';
-import {
-  registerState,
-  type RegisterState,
-  type VerificationResendState,
-} from '../../lib/account/register-state';
+import { registerState, type RegisterState } from '../../lib/account/register-state';
 import type { LocaleBinding } from '../../lib/locale/localized-path';
 
 /**
@@ -26,8 +22,8 @@ import type { LocaleBinding } from '../../lib/locale/localized-path';
  * The submit runs on the shopper's OWN websocket rather than through a Server
  * Action, because the API's protection against a double-clicked submit is
  * scoped to their session — `lib/account-session.ts` carries the full
- * argument. The RESEND below is a Server Action, because it needs nothing but
- * an address.
+ * argument. The RESEND (`VerificationResend`) is a Server Action, because it
+ * needs nothing but an address.
  *
  * Which screen an outcome produces is decided in
  * `lib/account/register-state.ts`; this component renders it.
@@ -56,39 +52,13 @@ const PROMPTS: Readonly<
   },
 };
 
-/**
- * What a SUBMITTED resend says. `idle` has no entry because it is the
- * pre-submit state and renders nothing.
- *
- * `sent` is worded so it is true for every address a shopper can type — one
- * with a pending account, one with none, and one the platform's throttle
- * silently swallowed. That is the same neutrality the reset-request form
- * carries, and `verificationResendState` is where it is decided.
- */
-const RESEND_MESSAGES: Readonly<
-  Record<'sent' | 'failed', { tone: AccountMessageTone; title: string; body: string }>
-> = {
-  sent: {
-    tone: 'success',
-    title: 'On its way',
-    body: 'If that address is waiting to be confirmed, a link is on its way to it. A mail we sent a moment ago still works, so it is worth checking for that one too.',
-  },
-  failed: {
-    tone: 'error',
-    title: 'We could not send that e-mail',
-    body: 'Something went wrong on our side and nothing has been sent. Please try again in a few minutes.',
-  },
-};
-
 export function RegisterForm({ locale }: { locale: LocaleBinding }) {
   const [firstName, setFirstName] = useState('');
   const [lastName, setLastName] = useState('');
   const [emailAddress, setEmailAddress] = useState('');
   const [password, setPassword] = useState('');
   const [state, setState] = useState<RegisterState>('form');
-  const [resend, setResend] = useState<VerificationResendState>('idle');
   const [pending, setPending] = useState(false);
-  const [resendPending, setResendPending] = useState(false);
 
   /**
    * The guard is the FIRST half of #1471's double-submit fix: the button is
@@ -115,19 +85,6 @@ export function RegisterForm({ locale }: { locale: LocaleBinding }) {
     setState(registerState(outcome));
   }
 
-  /**
-   * Same guard, and it matters more here: this button triggers a MAIL, so a
-   * re-entrant click is a mail a shopper did not ask for. The platform throttles
-   * it too — silently, which is why a refused resend still renders as sent.
-   */
-  async function requestAnotherMail(): Promise<void> {
-    if (resendPending) return;
-    setResendPending(true);
-    const next = await submitVerificationRequest(emailAddress);
-    setResendPending(false);
-    setResend(next);
-  }
-
   if (state === 'signed-in-already') {
     return (
       <div className="space-y-6" data-fc-account-mode="register" data-fc-account-state={state}>
@@ -135,8 +92,8 @@ export function RegisterForm({ locale }: { locale: LocaleBinding }) {
           This address is already confirmed, so there is nothing left to do here — you can sign in
           with it whenever you like.
         </AccountMessage>
-        <LocaleLink href="/" locale={locale} className="btn btn-primary">
-          Continue shopping
+        <LocaleLink href="/account" locale={locale} className="btn btn-primary">
+          Sign in
         </LocaleLink>
       </div>
     );
@@ -144,32 +101,17 @@ export function RegisterForm({ locale }: { locale: LocaleBinding }) {
 
   if (state === 'verify-your-email' || state === 'already-registered') {
     const prompt = PROMPTS[state];
-    const resendMessage = resend === 'idle' ? null : RESEND_MESSAGES[resend];
     return (
       <div className="space-y-6" data-fc-account-mode="register" data-fc-account-state={state}>
         <AccountMessage tone={prompt.tone} title={prompt.title}>
           {prompt.body}
         </AccountMessage>
 
-        {resendMessage && (
-          <AccountMessage tone={resendMessage.tone} title={resendMessage.title}>
-            {resendMessage.body}
-          </AccountMessage>
-        )}
-
-        <div className="flex flex-wrap gap-3">
-          <button
-            type="button"
-            className="btn btn-primary"
-            disabled={resendPending}
-            onClick={() => void requestAnotherMail()}
-          >
-            {resendPending ? 'Sending…' : 'Send the confirmation e-mail again'}
-          </button>
+        <VerificationResend emailAddress={emailAddress}>
           <LocaleLink href="/" locale={locale} className="btn btn-ghost">
             Continue shopping
           </LocaleLink>
-        </div>
+        </VerificationResend>
       </div>
     );
   }
@@ -278,6 +220,13 @@ export function RegisterForm({ locale }: { locale: LocaleBinding }) {
       <button type="submit" className="btn btn-primary" disabled={pending}>
         {pending ? 'Creating your account…' : 'Create account'}
       </button>
+
+      <p className="text-sm text-base-content/60">
+        Already have an account?{' '}
+        <LocaleLink href="/account" locale={locale} className="link link-hover">
+          Sign in
+        </LocaleLink>
+      </p>
     </form>
   );
 }

package/templates/storefront/src/components/account/ResetPasswordForm.tsx

@@ -77,8 +77,8 @@ export function ResetPasswordForm({ token, locale }: { token: string; locale: Lo
         <AccountMessage tone="success" title="Your password has been changed">
           You can sign in with your new password from now on.
         </AccountMessage>
-        <LocaleLink href="/" locale={locale} className="btn btn-primary">
-          Continue shopping
+        <LocaleLink href="/account" locale={locale} className="btn btn-primary">
+          Sign in
         </LocaleLink>
       </div>
     );

package/templates/storefront/src/components/account/VerificationResend.tsx

@@ -0,0 +1,96 @@
+'use client';
+
+import { useState, type ReactNode } from 'react';
+
+import { AccountMessage, type AccountMessageTone } from './AccountMessage';
+import { submitVerificationRequest } from '../../lib/account-actions';
+import type { VerificationResendState } from '../../lib/account/register-state';
+
+/**
+ * Send the confirmation e-mail again (#1471, #1093) — the one key an UNCONFIRMED
+ * account's owner has. Rendered wherever such an account stops a shopper: the
+ * register prompt, for the address they just registered, and the sign-in form,
+ * after the API refused a sign-in NOT_VERIFIED. Without it that shopper has
+ * nowhere to go: the mail they lost is the only way to confirm the account.
+ *
+ * A Server Action rather than the shopper's socket: the resend needs nothing but
+ * an address, so it runs on the anonymous channel singleton like the reset
+ * request (`lib/account-actions.ts`).
+ *
+ * Renders the resend's answer, then a row holding the button and whatever the
+ * caller passes as `children` — its own next step beside it.
+ */
+
+/**
+ * What a SUBMITTED resend says. `idle` has no entry because it is the
+ * pre-submit state and renders nothing.
+ *
+ * `sent` is worded so it is true for every address a shopper can type — one
+ * with a pending account, one with none, and one the platform's throttle
+ * silently swallowed. That is the same neutrality the reset-request form
+ * carries, and `verificationResendState` is where it is decided.
+ */
+const RESEND_MESSAGES: Readonly<
+  Record<'sent' | 'failed', { tone: AccountMessageTone; title: string; body: string }>
+> = {
+  sent: {
+    tone: 'success',
+    title: 'On its way',
+    body: 'If that address is waiting to be confirmed, a link is on its way to it. A mail we sent a moment ago still works, so it is worth checking for that one too.',
+  },
+  failed: {
+    tone: 'error',
+    title: 'We could not send that e-mail',
+    body: 'Something went wrong on our side and nothing has been sent. Please try again in a few minutes.',
+  },
+};
+
+export function VerificationResend({
+  emailAddress,
+  children,
+}: {
+  /** The address the confirmation mail goes to. */
+  emailAddress: string;
+  /** The caller's own next step, rendered beside the button. */
+  children?: ReactNode;
+}) {
+  const [resend, setResend] = useState<VerificationResendState>('idle');
+  const [pending, setPending] = useState(false);
+
+  /**
+   * This button triggers a MAIL, so a re-entrant click is a mail a shopper did
+   * not ask for: `pending` refuses one even before `disabled` has painted. The
+   * platform throttles it too — silently, which is why a refused resend still
+   * renders as sent.
+   */
+  async function requestAnotherMail(): Promise<void> {
+    if (pending) return;
+    setPending(true);
+    const next = await submitVerificationRequest(emailAddress);
+    setPending(false);
+    setResend(next);
+  }
+
+  const message = resend === 'idle' ? null : RESEND_MESSAGES[resend];
+  return (
+    <>
+      {message && (
+        <AccountMessage tone={message.tone} title={message.title}>
+          {message.body}
+        </AccountMessage>
+      )}
+
+      <div className="flex flex-wrap gap-3">
+        <button
+          type="button"
+          className="btn btn-primary"
+          disabled={pending}
+          onClick={() => void requestAnotherMail()}
+        >
+          {pending ? 'Sending…' : 'Send the confirmation e-mail again'}
+        </button>
+        {children}
+      </div>
+    </>
+  );
+}

package/templates/storefront/src/lib/account/account-state.ts

@@ -0,0 +1,152 @@
+import type { AccountCallOutcome } from './account-link';
+
+/**
+ * What `/account` renders, as a value (#1093).
+ *
+ * PURE BY CONTRACT, for the reasons `account-link.ts` states. The panel owns the
+ * COPY; this module owns which view a given answer of the shop API IS, so every
+ * decision the sign-in surface makes is a table of vectors and the panel is a
+ * render.
+ *
+ * The page is a static shell and the session lives on the shopper's own socket,
+ * so nothing here is known at render time: the server paints `loading`, and the
+ * panel asks the socket who is signed in once the cart provider has armed it.
+ */
+
+/** The shopper a signed-in session belongs to, as the account page greets them. */
+export interface SignedInCustomer {
+  readonly firstName: string;
+  readonly lastName: string;
+  readonly emailAddress: string;
+}
+
+/**
+ * What the shop API answered when asked who this socket's session belongs to.
+ *
+ * `customer: null` is an ordinary answer, not an error: a socket carrying no
+ * session, and an anonymous cart session, both belong to nobody.
+ */
+export type ActiveCustomerOutcome =
+  | { kind: 'ok'; customer: SignedInCustomer | null }
+  | { kind: 'error'; code: string };
+
+/** The call a refusal answered — what the panel says went wrong. */
+export type AccountStep = 'greeting' | 'sign-in' | 'sign-out';
+
+/** A refusal the panel renders, with the call it answered. */
+export interface AccountRefusal {
+  readonly step: AccountStep;
+  readonly code: string;
+}
+
+/**
+ * The views of the account page — each `state` is the `data-fc-account-state`
+ * the panel stamps.
+ *
+ *  - `loading`    — the server render, and every client render until the
+ *                   socket has been asked. A skeleton, never the form: a
+ *                   returning customer must land on their greeting without a
+ *                   flash of the sign-in form first.
+ *  - `signed-out` — the sign-in form, with the refusal that put it there, if
+ *                   any.
+ *  - `signed-in`  — the greeting and the way out.
+ */
+export type AccountView =
+  | { readonly state: 'loading' }
+  | { readonly state: 'signed-out'; readonly refusal: AccountRefusal | null }
+  | { readonly state: 'signed-in'; readonly customer: SignedInCustomer };
+
+/** The view the server renders. */
+export const LOADING_VIEW: AccountView = { state: 'loading' };
+
+/**
+ * The codes that mean the session the socket presented is OVER: the API holds
+ * no session for the token (`SESSION_NOT_FOUND`), or the request carried none
+ * it could use (`UNAUTHORIZED` — the guard's answer for a token that resolves
+ * to no session).
+ *
+ * A session that is over is a shopper who is signed out, not a fault: the
+ * greeting renders the form without a message, and a sign-out that finds the
+ * session already gone has done what it was asked.
+ */
+const SESSION_GONE_CODES: ReadonlySet<string> = new Set(['UNAUTHORIZED', 'SESSION_NOT_FOUND']);
+
+/**
+ * The refusal of a sign-in whose session greets nobody: the credentials were
+ * accepted, but the session belongs to no customer of THIS store — the code
+ * `/verify`'s `wrong-store` state reads for the same situation.
+ */
+const NO_CUSTOMER_CODE = 'CUSTOMER_NOT_FOUND';
+
+/** The refusal that a confirmation mail answers. */
+const NOT_VERIFIED_CODE = 'NOT_VERIFIED';
+
+/** Whether a refusal says the session it was asked about no longer exists. */
+export function isSessionGone(code: string): boolean {
+  return SESSION_GONE_CODES.has(code);
+}
+
+/**
+ * The view the page lands in when it asks who is signed in on arrival.
+ *
+ * A session that greets nobody — none on the socket, an anonymous cart session,
+ * or one that is over — is the sign-in form with nothing to apologise for. Any
+ * other refusal is shown: the form still renders, because a shopper who cannot
+ * be greeted can still try to sign in.
+ */
+export function greetingView(outcome: ActiveCustomerOutcome): AccountView {
+  if (outcome.kind === 'ok' && outcome.customer !== null) {
+    return { state: 'signed-in', customer: outcome.customer };
+  }
+  if (outcome.kind === 'ok' || isSessionGone(outcome.code)) {
+    return { state: 'signed-out', refusal: null };
+  }
+  return { state: 'signed-out', refusal: { step: 'greeting', code: outcome.code } };
+}
+
+/**
+ * The view an ACCEPTED sign-in lands in, from the greeting asked right after it.
+ *
+ * Unlike {@link greetingView}, "nobody is signed in" is never a silent answer
+ * here: the shopper has just been told yes, so a session that greets nobody is
+ * a failed sign-in and is rendered as one. A session that is gone the moment it
+ * was minted is the #1089 signature — a socket still speaking for the session
+ * it opened with — and is shown with its code rather than folded away.
+ */
+export function signInView(outcome: ActiveCustomerOutcome): AccountView {
+  if (outcome.kind === 'error') {
+    return { state: 'signed-out', refusal: { step: 'sign-in', code: outcome.code } };
+  }
+  if (outcome.customer === null) {
+    return { state: 'signed-out', refusal: { step: 'sign-in', code: NO_CUSTOMER_CODE } };
+  }
+  return { state: 'signed-in', customer: outcome.customer };
+}
+
+/** The view a REFUSED sign-in lands in. */
+export function signInRefusedView(code: string): AccountView {
+  return { state: 'signed-out', refusal: { step: 'sign-in', code } };
+}
+
+/**
+ * The view a sign-out lands in. Always `signed-out` — the session helper has
+ * left this tab without a session whatever the API answered — and a refusal is
+ * shown only when the API could not confirm the session ended.
+ */
+export function signedOutView(outcome: AccountCallOutcome): AccountView {
+  if (outcome.kind === 'ok') return { state: 'signed-out', refusal: null };
+  return { state: 'signed-out', refusal: { step: 'sign-out', code: outcome.code } };
+}
+
+/**
+ * Whether the view offers to send the confirmation mail again: only after a
+ * sign-in the API refused because the account was never confirmed. Without it
+ * that shopper has nowhere to go — the mail they lost is the only key.
+ */
+export function offersVerificationResend(view: AccountView): boolean {
+  return (
+    view.state === 'signed-out' &&
+    view.refusal?.step === 'sign-in' &&
+    view.refusal.code === NOT_VERIFIED_CODE
+  );
+}

package/templates/storefront/src/lib/account-session.ts

@@ -1,16 +1,19 @@
 'use client';
 
-import type { RegisterCustomerInput } from '@forgecart/sdk/shop';
+import type { NativeAuthInput, RegisterCustomerInput } from '@forgecart/sdk/shop';
 
+import type { AccountCallOutcome } from './account/account-link';
+import { isSessionGone, type ActiveCustomerOutcome } from './account/account-state';
 import type { RegisterOutcome } from './account/register-state';
-import { runSessionOp } from './shop-session';
+import { replaceShopSession, runSessionOp } from './shop-session';
 
 /**
- * Registering, on the shopper's OWN websocket (#1471).
+ * The account calls that run on the shopper's OWN websocket: registering
+ * (#1471), and signing in and out (#1093).
  *
  * Every other unauthenticated account call in this template is a Server Action
- * running on the anonymous channel singleton (`lib/account-actions.ts`). This
- * one is not, and the placement is the design rather than a preference:
+ * running on the anonymous channel singleton (`lib/account-actions.ts`). These
+ * are not, and the placement is the design rather than a preference:
  *
  *  1. CORRECTNESS. `lib/forgecart.ts` memoizes ONE client per language for the
  *     whole Next process, so every visitor's Server Action shares it — and
@@ -18,19 +21,26 @@ import { runSessionOp } from './shop-session';
  *     SESSION-scoped (a session holds one registration claim, which is what
  *     turns a double-clicked submit into one account and one prompt instead of
  *     a refusal), so running it on a shared session would answer one shopper
- *     with another shopper's pending state. The guarantee is only sound on a
- *     session that belongs to one person.
+ *     with another shopper's pending state. A sign-in on that client would be
+ *     worse still: it would sign EVERY visitor in as whoever signed in last.
+ *     These calls are only sound on a session that belongs to one person.
  *  2. INTENT. Registering starts the shopper relationship, and the anonymous
- *     session this socket holds IS the cart identity that logging in later
- *     promotes — so the cart someone filled before registering follows them
- *     into their account.
+ *     session this socket holds IS the cart identity that signing in later
+ *     promotes — so the cart someone filled before registering, or before
+ *     signing in, follows them into their account.
  *
  * That is the opposite placement from `/verify` and `/reset-password`, and
  * deliberately so: those act on a one-shot token out of a mail, where opening a
  * session for a visitor who has not shopped yet would attach a cart identity to
- * a password reset. The verification RESEND on this page is in that second
- * category too — it needs nothing but an address — so it stays a Server Action.
+ * a password reset. The verification RESEND is in that second category too — it
+ * needs nothing but an address — so it stays a Server Action.
+ *
+ * Like `runSessionOp`, none of these throws: a refusal is a typed code in the
+ * outcome, which is the ordinary case (a mistyped password, an address already
+ * registered), and the pure state tables in `lib/account/` stay the only things
+ * that read an ErrorCode.
  */
+
 export async function registerCustomerAccount(
   input: RegisterCustomerInput,
 ): Promise<RegisterOutcome> {
@@ -38,10 +48,67 @@ export async function registerCustomerAccount(
     async (client) =>
       (await client.customer.registerCustomerAccount({ input })).registerCustomerAccount,
   );
-  // `runSessionOp` never throws — a refusal arrives as a typed code, which is
-  // the ordinary case here (the address may already be registered) and the form
-  // renders it. The envelope is flattened into the pure outcome union so the
-  // state table stays the only thing that reads an ErrorCode.
   if (!result.ok) return { kind: 'error', code: result.error.code };
   return { kind: 'ok', verificationPending: result.data.verificationPending };
 }
+
+/**
+ * Sign the shopper in.
+ *
+ * Resolves only once this tab's socket AND the session cookies carry the
+ * session the sign-in minted (`replaceShopSession`), so the caller's very next
+ * operation — the greeting — runs as the signed-in shopper. Before #1093 every
+ * storefront hand-rolled this, and the one that did not rotate the socket had
+ * its next operation refused UNAUTHORIZED and reported a failed sign-in (#1089).
+ *
+ * A refusal resolves with its code — `INVALID_CREDENTIALS`, `NOT_VERIFIED`, … —
+ * and changes nothing: the socket keeps the session it had, cart included.
+ */
+export async function loginCustomer(input: NativeAuthInput): Promise<AccountCallOutcome> {
+  const result = await runSessionOp(async (client) => (await client.auth.login({ input })).login);
+  if (!result.ok) return { kind: 'error', code: result.error.code };
+  await replaceShopSession(result.data.token);
+  return { kind: 'ok' };
+}
+
+/**
+ * Sign the shopper out.
+ *
+ * Asks the shop API to end the session, then leaves this tab without one —
+ * the socket replaced by one that carries no session, both cookies cleared —
+ * WHATEVER the API answered: signing out is first a promise about this device,
+ * and a shopper on a shared computer who pressed the button must not stay
+ * signed in because the network blinked. The outcome reports the API's half:
+ * `ok` when the session is over (a session the API no longer holds included),
+ * the refusal's code when the API could not confirm it.
+ */
+export async function logoutCustomer(): Promise<AccountCallOutcome> {
+  const ended = await runSessionOp(async (client) => (await client.auth.logout()).logout);
+  await replaceShopSession(null);
+  if (ended.ok || isSessionGone(ended.error.code)) return { kind: 'ok' };
+  return { kind: 'error', code: ended.error.code };
+}
+
+/**
+ * Who this tab's session belongs to.
+ *
+ * A socket carrying no session is answered without a request — a visitor who
+ * has never shopped, or one who just signed out, belongs to nobody — and so is
+ * every page load that finds no mirror cookie, since the socket boots its
+ * session from it. Otherwise the shop API is asked, and an anonymous cart
+ * session answers `null` too.
+ */
+export async function findSignedInCustomer(): Promise<ActiveCustomerOutcome> {
+  const result = await runSessionOp(async (client) => {
+    if (client.getAuthToken() === null) return null;
+    const customer = (await client.customer.activeCustomer()).activeCustomer ?? null;
+    if (customer === null) return null;
+    return {
+      firstName: customer.firstName,
+      lastName: customer.lastName,
+      emailAddress: customer.emailAddress,
+    };
+  });
+  if (!result.ok) return { kind: 'error', code: result.error.code };
+  return { kind: 'ok', customer: result.data };
+}

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

@@ -1,24 +1,118 @@
 import type { ExtractedError } from '@forgecart/sdk/shop';
 
 /**
- * Shopper-facing messages for the typed checkout error codes.
+ * Shopper-facing copy for the typed error codes a storefront call can meet.
  *
  * The shop API's error contract ships CODES, never prose — `message` on an
  * extracted error is the code string itself, and resolving human copy is the
  * frontend's job (error-handling contract). A raw enum leaking into the UI is
  * a defect (the address step rendered SHIPPING_ADDRESS_PHONE_REQUIRED
  * verbatim, 2026-08-09).
+ *
+ * Two families live here. The checkout's address codes, and every refusal a
+ * customer ACCOUNT call can meet (#1093): signing in and out, registering, a
+ * verification or reset link, a password or e-mail change. The account family
+ * is swept against the shop's own `ErrorCode` enum by
+ * `tool/storefront-template-spec` — every member of its `Auth - Self-Service`
+ * and `Auth - Service` blocks, plus the sign-in refusal, the anonymous
+ * socket's refusal and the taken address — so a refusal added to the platform
+ * reddens that sweep until it has copy here. Before #1093 this map held the
+ * three address codes alone, and every refused sign-in rendered as the
+ * generic line: indistinguishable from the platform faults it was masking.
+ *
+ * `SHOP_API_UNREACHABLE` is not a platform code but this template's own
+ * (`lib/action-result.ts`): the answer when the API could not be asked at all,
+ * which is the one failure the generic line's "check your details" is wrong
+ * about.
+ *
+ * A Map rather than an object literal: a lookup keyed by an API-supplied
+ * string must not be able to land on `Object.prototype` (`constructor`,
+ * `toString`) and render a function as copy.
  */
-const SHOPPER_MESSAGES: Record<string, string> = {
-  SHIPPING_ADDRESS_PHONE_REQUIRED: 'A phone number is required for delivery updates.',
-  SHIPPING_ADDRESS_COUNTRY_REQUIRED: 'Please select a country.',
-  SHIPPING_ADDRESS_COUNTRY_INVALID: 'We can’t ship to the selected country yet.',
-};
+const SHOPPER_MESSAGES: ReadonlyMap<string, string> = new Map([
+  ['SHIPPING_ADDRESS_PHONE_REQUIRED', 'A phone number is required for delivery updates.'],
+  ['SHIPPING_ADDRESS_COUNTRY_REQUIRED', 'Please select a country.'],
+  ['SHIPPING_ADDRESS_COUNTRY_INVALID', 'We can’t ship to the selected country yet.'],
+  [
+    'INVALID_CREDENTIALS',
+    'That e-mail address and password do not match. Check both and try again.',
+  ],
+  ['UNAUTHORIZED', 'You are not signed in, or your session has ended. Please sign in again.'],
+  [
+    'EMAIL_ADDRESS_CONFLICT',
+    'That e-mail address already has an account. Sign in with it, or reset its password.',
+  ],
+  [
+    'IDENTIFIER_ALREADY_EXISTS',
+    'That e-mail address already has an account. Sign in with it, or reset its password.',
+  ],
+  [
+    'NOT_VERIFIED',
+    'This account is not confirmed yet. Open the link in the confirmation e-mail we sent you, then sign in.',
+  ],
+  [
+    'VERIFICATION_TOKEN_INVALID',
+    'This confirmation link is not valid — it may have been used already. Ask for a new confirmation e-mail.',
+  ],
+  [
+    'VERIFICATION_TOKEN_EXPIRED',
+    'This confirmation link has expired. Ask for a new confirmation e-mail and open the newest link.',
+  ],
+  [
+    'PASSWORD_RESET_TOKEN_INVALID',
+    'This password reset link is not valid — it may have been used already. Ask for a new one.',
+  ],
+  [
+    'PASSWORD_RESET_TOKEN_EXPIRED',
+    'This password reset link has expired. Ask for a new one and open the newest link.',
+  ],
+  [
+    'PASSWORD_VALIDATION_FAILED',
+    'That password does not meet the store’s requirements. Please choose a different one.',
+  ],
+  [
+    'PASSWORD_CHANGE_FAILED',
+    'Your password could not be changed. Check your current password and try again.',
+  ],
+  [
+    'IDENTIFIER_CHANGE_TOKEN_INVALID',
+    'This e-mail change link is not valid — it may have been used already. Ask for the change again.',
+  ],
+  [
+    'IDENTIFIER_CHANGE_TOKEN_EXPIRED',
+    'This e-mail change link has expired. Ask for the change again and open the newest link.',
+  ],
+  [
+    'CUSTOMER_NOT_FOUND',
+    'That account does not shop at this store. Sign in with the address you registered here.',
+  ],
+  ['SESSION_NOT_FOUND', 'Your session has ended. Please sign in again.'],
+  [
+    'SESSION_CACHE_READ_FAILED',
+    'We could not check your session just now. Please try again in a moment.',
+  ],
+  [
+    'SESSION_CACHE_WRITE_FAILED',
+    'We could not save your session just now. Please try again in a moment.',
+  ],
+  [
+    'SHOP_API_UNREACHABLE',
+    'We could not reach the store just now. Please check your connection and try again.',
+  ],
+]);
 
 const FALLBACK_MESSAGE = 'Something went wrong. Please check your details and try again.';
 
-/** Human copy for a typed error — never the raw enum, never undefined. */
+/**
+ * Human copy for a typed error — never undefined.
+ *
+ * A code this map has no copy for renders the generic line WITH the code
+ * appended in parentheses: an unmodelled refusal must stay distinguishable
+ * from a platform fault, by the shopper who reports it and by the merchant —
+ * or their agent — who reads the report. Only an error carrying no code at all
+ * renders the generic line bare.
+ */
 export function shopperMessage(error: Pick<ExtractedError, 'code'> | null | undefined): string {
   if (!error?.code) return FALLBACK_MESSAGE;
-  return SHOPPER_MESSAGES[error.code] ?? FALLBACK_MESSAGE;
+  return SHOPPER_MESSAGES.get(error.code) ?? `${FALLBACK_MESSAGE} (${error.code})`;
 }