@forgecart/cli 2.202610141814.0 → 2.202610142335.0

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

@@ -0,0 +1,92 @@
+'use client';
+
+import { useState, type ReactNode } from 'react';
+
+import { AccountMessage, type AccountMessageTone } from './AccountMessage';
+import { Button } from '../ui/button';
+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" disabled={pending} onClick={() => void requestAnotherMail()}>
+          {pending ? 'Sending…' : 'Send the confirmation e-mail again'}
+        </Button>
+        {children}
+      </div>
+    </>
+  );
+}

package/templates/storefront-shadcn/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-shadcn/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-shadcn/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})`;
 }

package/templates/storefront-shadcn/src/lib/seo/noindex.ts

@@ -31,6 +31,10 @@ import { getPublicOrigin } from './public-origin';
  * no content of its own, identical for every visitor, so there is nothing for a
  * search result to be about. One entry covers every language: this set is
  * matched against the locale-STRIPPED path.
+ *
+ * `/account` (#1093) is here for the same funnel reason as `/register`: the
+ * server renders a skeleton, identical for every visitor, and everything the
+ * page shows is one shopper's own — sign-in form or greeting.
  */
 export const NOINDEX_PATHS: readonly string[] = [
   '/cart',
@@ -38,6 +42,7 @@ export const NOINDEX_PATHS: readonly string[] = [
   '/verify',
   '/reset-password',
   '/register',
+  '/account',
 ];
 
 /**

package/templates/storefront-shadcn/src/lib/seo/sitemap-entries.ts

@@ -49,6 +49,8 @@ export const STATIC_ROUTES: readonly StaticRoute[] = [
   // The register page (#1471). Suppressed for the same reason `/cart` is — a
   // form with no content of its own — and listed for this table's stated one.
   { path: '/register', indexable: false },
+  // The account page (#1093): sign-in form or greeting, one shopper's own.
+  { path: '/account', indexable: false },
 ];
 
 /**

package/templates/storefront-shadcn/src/lib/shop-session.ts

@@ -29,6 +29,10 @@ import { syncShopSession } from './session-actions';
  *     it from result extensions on the first mutation) is synced back into
  *     BOTH cookies via the `syncShopSession` server action — the next SSR
  *     pass sees the cart this socket built.
+ *   - A sign-in or sign-out changes WHO the session is, and that never rides
+ *     the capture: `replaceShopSession(token)` disposes the socket, opens a
+ *     fresh one on the new session (or none) and writes both cookies before
+ *     it resolves (`lib/account-session.ts` is its caller).
  *
  * Every operation returns the same `ActionResult` envelope the old Server
  * Actions used, so calling components keep their error contract: typed
@@ -96,6 +100,24 @@ export function isSessionReady(): boolean {
   return config !== null && typeof window !== 'undefined';
 }
 
+/** A client on the channel coordinates, carrying `token` — or no session when null. */
+function openClient(coordinates: ShopSessionConfig, token: string | null): ForgeCartShopClient {
+  const opened = new ForgeCartShopClient({
+    endpoint: coordinates.apiUrl,
+    channelToken: coordinates.channelToken,
+    // Fixed at handshake — the cart, checkout and every error message on
+    // this socket answer in the language the URL resolved to.
+    languageCode: coordinates.languageCode,
+    // The visitor mirror is minted by the middleware before any page can
+    // mount the provider, so it is present on every real navigation; when
+    // it is somehow absent the client simply sends no visitor header and
+    // visitor-subject goals stay unstamped (never guess — #1079).
+    visitorId: readMirrorCookie(VISITOR_MIRROR_COOKIE) ?? undefined,
+  });
+  if (token) opened.setAuthToken(token);
+  return opened;
+}
+
 function ensureClient(): ForgeCartShopClient {
   if (!config) {
     throw new Error(
@@ -103,32 +125,63 @@ function ensureClient(): ForgeCartShopClient {
     );
   }
   if (!client) {
-    client = new ForgeCartShopClient({
-      endpoint: config.apiUrl,
-      channelToken: config.channelToken,
-      // Fixed at handshake — the cart, checkout and every error message on
-      // this socket answer in the language the URL resolved to.
-      languageCode: config.languageCode,
-      // The visitor mirror is minted by the middleware before any page can
-      // mount the provider, so it is present on every real navigation; when
-      // it is somehow absent the client simply sends no visitor header and
-      // visitor-subject goals stay unstamped (never guess — #1079).
-      visitorId: readMirrorCookie(VISITOR_MIRROR_COOKIE) ?? undefined,
-    });
     const existing = readMirrorSession();
-    if (existing) {
-      client.setAuthToken(existing);
-      syncedToken = existing;
-    }
+    client = openClient(config, existing);
+    if (existing) syncedToken = existing;
   }
   return client;
 }
 
+/**
+ * Move this tab onto another session — the ONE path an identity change takes
+ * (#1093): a sign-in hands over the session it minted, a sign-out hands over
+ * `null`.
+ *
+ * The socket is REPLACED, never re-pointed. Its identity was fixed at its
+ * handshake, and a sign-in that left the live socket speaking for the session
+ * it opened with was refused UNAUTHORIZED on its very next operation — the
+ * greeting — and rendered as a failed sign-in (#1089). So the old client is
+ * disposed, which is terminal (nothing still in flight on it can complete
+ * under the wrong identity), and a fresh one carrying `token` takes its place;
+ * its first operation handshakes as the new session. The platform now rebinds
+ * a connection that signs in, and the SDK re-handshakes on `setAuthToken`; the
+ * replacement stays regardless, so which identity every later operation runs
+ * under is a fact of this module rather than of the platform and SDK versions
+ * a workspace happens to run.
+ *
+ * A sign-out also clears the token the SDK persists in the browser's storage.
+ * A fresh client restores that token when it is constructed, so without the
+ * clear the replacement would carry the very session it was meant to leave.
+ *
+ * Both cookies are written next, and AWAITED — unlike the capture in
+ * `runSessionOp` — so a caller that resolves after this has left the next
+ * server render and the next visit's socket on the same session as this tab.
+ * A failed write is absorbed exactly as the capture absorbs one: the socket
+ * is the authority for this tab, and a lost mirror costs the next visit its
+ * session, never this interaction.
+ *
+ * Before the cart provider has armed the singleton there is no socket to
+ * replace, and only the cookies move.
+ */
+export async function replaceShopSession(token: string | null): Promise<void> {
+  client?.dispose();
+  client = config ? openClient(config, token) : null;
+  if (token === null) client?.clearAuthToken();
+  syncedToken = token;
+  try {
+    await syncShopSession(token);
+  } catch {
+    // Absorbed by design — see above: the socket already carries `token`.
+  }
+}
+
 /**
  * Run one session operation on the shopper's socket and return the typed
  * envelope. Session capture: when the operation minted or rotated the
  * session, the new token is synced into the cookies fire-and-forget —
- * a sync failure never breaks the shopper's interaction.
+ * a sync failure never breaks the shopper's interaction. An operation whose
+ * socket was replaced while it ran captures nothing: its session is no longer
+ * this tab's, and writing it would undo the replacement.
  */
 export async function runSessionOp<T>(
   op: (client: ForgeCartShopClient) => Promise<T>,
@@ -140,7 +193,7 @@ export async function runSessionOp<T>(
   try {
     const data = await op(live);
     const token = live.getAuthToken();
-    if (token && token !== syncedToken) {
+    if (token && token !== syncedToken && live === client) {
       syncedToken = token;
       void syncShopSession(token).catch(() => undefined);
     }