@forgecart/cli 2.202608221935.0 → 2.202609190800.0

package/templates/storefront/src/lib/seo/sitemap-cache.ts

@@ -0,0 +1,114 @@
+/**
+ * The XML sitemap's 60s window (#1347, epic launch#54 W1-9).
+ *
+ * Unlike every page route, this document is not per-visitor and not per-locale:
+ * one deployment has exactly one of it, and building it walks the whole catalog
+ * — up to fifty backend reads for a large store, against a merchant's own pod.
+ * A crawler that fetches it repeatedly would otherwise multiply that walk by
+ * however often it asks. Caching a shared, visitor-independent document is
+ * therefore not the same decision as caching a page, and it is why this is the
+ * one route in the template that holds a window.
+ *
+ * A TTL, deliberately, and NOT Next's `revalidate`: ISR pre-renders the first
+ * response at BUILD time, which is the same frozen-builder-environment failure
+ * `sitemap.ts` sets `force-dynamic` to avoid, wearing a TTL as a disguise. This
+ * window lives entirely inside the running server, so it can only ever hold a
+ * document that a configured process actually produced.
+ *
+ * The clock is injected so the window is exercised by vectors instead of by
+ * waiting on wall time — the same seam `createChannelLocalesCache` uses.
+ */
+
+export interface SitemapCache<T> {
+  get(): Promise<T>;
+}
+
+export interface SitemapCacheOptions {
+  /**
+   * The window, read PER ACCESS rather than captured once.
+   *
+   * A getter, not a number, because an env-tuned window read at import time
+   * freezes at whatever the first module load saw — the same snapshot bug the
+   * endurance-window getters elsewhere in the repo exist to avoid.
+   */
+  ttlMs?: () => number;
+  /** Injected clock — the specs drive time instead of sleeping through it. */
+  now?: () => number;
+}
+
+/** The window #1347 fixes for the XML sitemap. */
+export const SITEMAP_TTL_MS = 60_000;
+
+/**
+ * The window this deployment actually uses.
+ *
+ * Tunable so a harness can shrink it instead of waiting it out: an integration
+ * check that a newly scaffolded page reaches the sitemap otherwise has to
+ * sleep through a real minute, which is both slow and the kind of wall-clock
+ * dependency that turns into a flake on a loaded machine. The BEHAVIOUR at the
+ * bound is what such a check proves; the production VALUE is pinned by a
+ * vector here.
+ *
+ * A missing, unparseable or negative value falls back to the default rather
+ * than disabling the window — a typo in an env var must not quietly turn every
+ * sitemap request into a full catalog walk.
+ */
+export function sitemapWindowMs(): number {
+  // Emptiness is checked BEFORE the number conversion, because `Number('')`
+  // and `Number('  ')` are both 0 — so an env var present but blank, which is
+  // what `FORGECART_SITEMAP_TTL_MS=` in a `.env` produces, would otherwise
+  // read as an explicit "no window" and turn every sitemap request into a full
+  // catalog walk against the merchant's backend.
+  const raw = process.env.FORGECART_SITEMAP_TTL_MS?.trim();
+  if (!raw) return SITEMAP_TTL_MS;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : SITEMAP_TTL_MS;
+}
+
+export function createSitemapCache<T>(
+  load: () => Promise<T>,
+  options: SitemapCacheOptions = {},
+): SitemapCache<T> {
+  const windowMs = options.ttlMs ?? (() => SITEMAP_TTL_MS);
+  const now = options.now ?? Date.now;
+
+  let snapshot: { value: T } | null = null;
+  let loadedAt = 0;
+  /**
+   * The load in progress, shared by everyone who arrives during it. Without
+   * it, a cold process meeting a crawler's parallel fetches would run the
+   * whole catalog walk once per request — precisely the amplification this
+   * window exists to remove.
+   */
+  let inFlight: Promise<T> | null = null;
+
+  async function reload(): Promise<T> {
+    if (inFlight) return inFlight;
+    inFlight = load();
+    try {
+      const loaded = await inFlight;
+      snapshot = { value: loaded };
+      loadedAt = now();
+      return loaded;
+    } finally {
+      // Cleared on failure too, so one bad read does not pin a rejected
+      // promise as the permanent answer for every request that follows.
+      inFlight = null;
+    }
+  }
+
+  async function get(): Promise<T> {
+    if (snapshot !== null && now() - loadedAt < windowMs()) return snapshot.value;
+    if (snapshot === null) return reload();
+
+    // Expired WITH a previous document: a refresh failure serves the last one
+    // rather than propagating. Those URLs existed a minute ago, which makes a
+    // slightly stale sitemap the most truthful answer available — and strictly
+    // better than the alternatives, since an empty document asserts the
+    // catalog is gone and a 5xx invites the crawler straight back.
+    const previous = snapshot.value;
+    return reload().catch(() => previous);
+  }
+
+  return { get };
+}

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

@@ -0,0 +1,321 @@
+import { buildAlternates, staticPathsByLocale } from './alternates';
+import type { LocaleBinding } from '../locale/localized-path';
+
+/**
+ * The XML sitemap's contents (#1347, epic launch#54 W1-9).
+ *
+ * Say "XML sitemap" — the bare word "sitemap" is the visual editor's route
+ * board, and the two are different things (D12).
+ *
+ * Every URL here is built through `buildAlternates`, the same function the
+ * pages use for their canonical and hreflang. That is deliberate: a sitemap
+ * that disagreed with the pages it lists is worse than no sitemap, because a
+ * crawler reconciles the two and trusts neither. Sharing the builder makes
+ * disagreement impossible rather than unlikely.
+ */
+
+/** A route the template ships, as opposed to a catalog entity. */
+export interface StaticRoute {
+  path: string;
+  /**
+   * Whether the route belongs in the XML sitemap.
+   *
+   * Kept as data rather than derived from `NOINDEX_PATHS` so a scaffolded page
+   * can join this table with its own answer (#1347's
+   * `storefront-page-creation.service` append). A unit vector pins the two
+   * against each other so they cannot drift.
+   */
+  indexable: boolean;
+}
+
+/**
+ * Every non-entity route the storefront serves.
+ *
+ * Non-indexable routes stay listed: this table is the single source of truth
+ * for what routes EXIST, and dropping them would make "is this route missing
+ * or merely unlisted?" unanswerable when a page is scaffolded into it.
+ */
+export const STATIC_ROUTES: readonly StaticRoute[] = [
+  { path: '/', indexable: true },
+  { path: '/products', indexable: true },
+  { path: '/cart', indexable: false },
+  { path: '/checkout', indexable: false },
+  // The account-link routes (#1472). Listed-but-suppressed rather than absent,
+  // for this table's stated reason: a page scaffolded at `/verify` later must
+  // find the route already claimed and non-indexable, instead of adding a
+  // fragment that submits a token page for indexing.
+  { path: '/verify', indexable: false },
+  { path: '/reset-password', indexable: false },
+  // 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 directory a scaffolded page drops its row into (#1347).
+ *
+ * One file per page rather than an append to the table above, and that is the
+ * whole reason it is a directory: two pages scaffolded at once would both read
+ * the table, both append, and the second write would erase the first. Separate
+ * files cannot lose each other's writes, and re-scaffolding the same page
+ * rewrites its own file instead of adding a duplicate row.
+ */
+export const SCAFFOLDED_ROUTES_DIR = 'src/seo/routes.d';
+
+/**
+ * One fragment as it arrives from disk — untrusted, because it is written by
+ * another process and editable by hand.
+ *
+ * Rejected as null rather than repaired: a fragment naming `cart` instead of
+ * `/cart`, or carrying no `indexable`, is a bug in whatever wrote it, and
+ * guessing what it meant would publish a URL nobody chose.
+ */
+export function parseScaffoldedRoute(raw: unknown): StaticRoute | null {
+  if (typeof raw !== 'object' || raw === null) return null;
+  const { path, indexable } = raw as { path?: unknown; indexable?: unknown };
+  if (typeof path !== 'string' || !path.startsWith('/')) return null;
+  if (typeof indexable !== 'boolean') return null;
+  return { path, indexable };
+}
+
+/**
+ * The template's own routes plus whatever has been scaffolded since.
+ *
+ * The base table WINS every collision, and that is load-bearing rather than a
+ * tie-break: `/cart` is non-indexable because this template decided so, and a
+ * fragment claiming otherwise — stale, hand-edited, or written for a route
+ * that later became structural — must not be able to submit the checkout
+ * funnel for indexing. A scaffolded page can add a route; it cannot overrule
+ * one.
+ *
+ * Ordering is deterministic (base order, then scaffolded by path) so the
+ * document does not reshuffle between reads for no reason.
+ */
+export function mergeScaffoldedRoutes(
+  base: readonly StaticRoute[],
+  scaffolded: readonly StaticRoute[],
+): StaticRoute[] {
+  const claimed = new Set(base.map((route) => route.path));
+  const added = new Map<string, StaticRoute>();
+  for (const route of scaffolded) {
+    if (claimed.has(route.path) || added.has(route.path)) continue;
+    added.set(route.path, route);
+  }
+  return [...base, ...[...added.values()].sort((a, b) => a.path.localeCompare(b.path))];
+}
+
+/**
+ * Where ACF page routes are mounted (#1934, #1035 D3).
+ *
+ * The shop API stores a page's route UNMOUNTED — a bare slug, no prefix
+ * (launch#50) — because the mount is the renderer's decision, and this template
+ * makes it exactly once, here. `app/pages/[slug]` serves the same prefix; a
+ * second spelling of it is a sitemap that names URLs the router does not have.
+ */
+export const PAGE_ROUTE_PREFIX = '/pages';
+
+/**
+ * The merchant's published ACF pages as sitemap routes (#1934).
+ *
+ * They join the STATIC route table rather than getting a feed of their own, and
+ * that is the whole design: `staticSitemapUrls` then gives each page its
+ * per-language URL and the full hreflang cluster for free — identical treatment
+ * to `/products`, which is what a page IS from the sitemap's point of view (one
+ * address per language, no per-language slug). The alternative, a second
+ * URL-building path, is precisely the disagreement this module opens by saying
+ * it exists to prevent.
+ *
+ * `indexable: true` unconditionally: the input is the set of routes the shop
+ * API says it currently SERVES, so an unpublished page never reaches here —
+ * membership, not a flag, is what takes a page out of the document. Per-page
+ * indexability is the SEO sidecar's job and has no storage yet.
+ *
+ * No `lastModified`: `StaticRoute` carries none, and widening it for a value
+ * whose real source (the per-page SEO sidecar) has not landed would put a
+ * guess into the document. An omitted `<lastmod>` is a hint withheld; a wrong
+ * one is a claim.
+ */
+export function pageSitemapRoutes(routes: readonly string[]): StaticRoute[] {
+  return routes.map((route) => ({ path: `${PAGE_ROUTE_PREFIX}/${route}`, indexable: true }));
+}
+
+/** One `<url>` of the XML sitemap, in Next's `MetadataRoute.Sitemap` shape. */
+export interface SitemapUrl {
+  url: string;
+  lastModified?: string;
+  alternates?: { languages: Record<string, string> };
+}
+
+/** One catalog entry as `seoEntries` returns it. */
+export interface SeoEntry {
+  /** ISO 8601 by contract — the API's `DateTime` scalar serializes `toISOString()`. */
+  updatedAt: string;
+  /**
+   * One path per language that HAS a translation row. The backend omits the
+   * rest and never synthesizes them, so this is already the "real content"
+   * set — no filtering is needed or wanted here.
+   */
+  paths: readonly { languageCode: string; slug: string }[];
+}
+
+/** One page of the feed, as the shop API returns it. */
+export interface SeoEntryPage {
+  items: readonly SeoEntry[];
+  totalItems: number;
+}
+
+/** The API's own per-request ceiling on `take` (`SeoEntriesInput`). */
+export const SEO_ENTRY_PAGE_SIZE = 1000;
+
+/**
+ * The sitemap protocol's limit on a single document.
+ *
+ * A sitemap is a HINT, and the protocol says so — omitting URLs costs their
+ * discovery through this channel and nothing else. Exceeding the limit is a
+ * different thing entirely: the document is rejected whole, so every URL in it
+ * loses that channel, including the ones that fit. Truncating is therefore
+ * strictly better than overflowing, which is why the budget is enforced here
+ * rather than left to chance.
+ */
+export const MAX_SITEMAP_URLS = 50_000;
+
+/**
+ * The point at which an operator has to hear about the budget — deliberately
+ * BELOW the cap, so the warning arrives while there is still room to act
+ * rather than once coverage is already being lost.
+ */
+export const SITEMAP_URL_WARN_THRESHOLD = 40_000;
+
+/**
+ * What this document owes its operator, or null when it owes nothing.
+ *
+ * A cap that silently stops listing pages would be the worst possible failure
+ * for this feature specifically: the thing whose job is getting pages indexed,
+ * quietly not indexing them, while every check stays green. Crossing the
+ * budget has to be audible.
+ *
+ * The two states are kept apart because they call for different urgency —
+ * "coverage is being lost right now" is not the same message as "act before
+ * it is". Neither carries the channel token: it is a credential, and this
+ * string goes to the pod's stdout.
+ */
+export function sitemapBudgetWarning(urlCount: number): string | null {
+  if (urlCount >= MAX_SITEMAP_URLS) {
+    return `[sitemap] TRUNCATED at ${MAX_SITEMAP_URLS} URLs — the catalog is larger than one XML sitemap may hold, so URLs beyond the cap are NOT being submitted for indexing. A sitemap index is the fix.`;
+  }
+  if (urlCount >= SITEMAP_URL_WARN_THRESHOLD) {
+    return `[sitemap] ${urlCount} URLs, approaching the ${MAX_SITEMAP_URLS} per-document limit — past it, URLs stop being submitted for indexing. A sitemap index is the fix, and there is still room to build one.`;
+  }
+  return null;
+}
+
+/**
+ * One `<url>` per (route × language), each carrying the cluster's full
+ * alternate set.
+ *
+ * Per language rather than per route because each locale's URL is a distinct
+ * address a crawler must discover; the shared alternate set is what tells it
+ * they are one page in several languages rather than several pages.
+ */
+export function staticSitemapUrls(
+  languageCodes: readonly string[],
+  defaultLocale: string,
+  publicOrigin: string,
+  routes: readonly StaticRoute[] = STATIC_ROUTES,
+): SitemapUrl[] {
+  const urls: SitemapUrl[] = [];
+  for (const route of routes) {
+    if (!route.indexable) continue;
+    const pathsByLocale = staticPathsByLocale(languageCodes, route.path);
+    for (const languageCode of languageCodes) {
+      const alternates = buildAlternates({
+        binding: { locale: languageCode, defaultLocale },
+        pathsByLocale,
+        publicOrigin,
+      });
+      if (alternates) {
+        urls.push({ url: alternates.canonical, alternates: { languages: alternates.languages } });
+      }
+    }
+  }
+  return urls;
+}
+
+/**
+ * The catalog's URLs, one per (entry × translated language).
+ *
+ * `lastModified` comes straight from the entry: the backend computes it as
+ * GREATEST(product, MAX(translation)), so a slug RENAME moves it too — which
+ * is the case a naive `product.updatedAt` would miss, leaving the new URL
+ * looking stale on the day it appeared.
+ */
+export function productSitemapUrls(
+  entries: readonly SeoEntry[],
+  defaultLocale: string,
+  publicOrigin: string,
+): SitemapUrl[] {
+  const urls: SitemapUrl[] = [];
+  for (const entry of entries) {
+    const pathsByLocale: Record<string, string> = {};
+    for (const path of entry.paths) {
+      pathsByLocale[path.languageCode] = `/products/${path.slug}`;
+    }
+    for (const languageCode of Object.keys(pathsByLocale)) {
+      const binding: LocaleBinding = { locale: languageCode, defaultLocale };
+      const alternates = buildAlternates({ binding, pathsByLocale, publicOrigin });
+      if (alternates) {
+        urls.push({
+          url: alternates.canonical,
+          lastModified: entry.updatedAt,
+          alternates: { languages: alternates.languages },
+        });
+      }
+    }
+  }
+  return urls;
+}
+
+/**
+ * The whole catalog's URLs, read page by page until the feed or the budget
+ * runs out.
+ *
+ * The loader is injected so the loop — the one part of this module that can
+ * hang, over-fetch, or stop early — is exercised by vectors instead of by a
+ * running backend, the same seam `createChannelLocalesCache` uses for the
+ * channel read.
+ *
+ * Termination is bounded three ways, and all three are load-bearing: the
+ * budget caps the work, a short page ends the feed, and an EMPTY page ends it
+ * unconditionally. The last one is what makes a backend that miscounts
+ * `totalItems` cost one wasted request rather than an unbounded loop inside a
+ * request — `totalItems` is a separate query from the page (see
+ * `SeoEntryService`), so the two can legitimately disagree under a concurrent
+ * write and neither is authoritative about the other.
+ */
+export async function collectProductSitemapUrls(
+  loadPage: (skip: number, take: number) => Promise<SeoEntryPage>,
+  defaultLocale: string,
+  publicOrigin: string,
+  maxUrls: number,
+): Promise<SitemapUrl[]> {
+  const urls: SitemapUrl[] = [];
+  let skip = 0;
+
+  while (urls.length < maxUrls) {
+    const page = await loadPage(skip, SEO_ENTRY_PAGE_SIZE);
+    if (page.items.length === 0) break;
+
+    urls.push(...productSitemapUrls(page.items, defaultLocale, publicOrigin));
+    skip += page.items.length;
+
+    if (page.items.length < SEO_ENTRY_PAGE_SIZE) break;
+    if (skip >= page.totalItems) break;
+  }
+
+  // Trimmed at the end rather than per page: an entry's languages belong to
+  // one cluster, and cutting inside one would publish a URL whose alternates
+  // name siblings the document does not contain. The trim can still split a
+  // cluster, but only at the very edge of a 50,000-URL document, where the
+  // alternative is having no document at all.
+  return urls.length > maxUrls ? urls.slice(0, maxUrls) : urls;
+}

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

@@ -4,6 +4,12 @@ import 'server-only';
 
 import { cookies } from 'next/headers';
 
+import {
+  SESSION_COOKIE,
+  SESSION_COOKIE_ATTRIBUTES,
+  SESSION_MIRROR_COOKIE,
+} from './session-cookies';
+
 /**
  * Session custody glue for the PROGRESSIVE stack.
  *
@@ -19,13 +25,15 @@ import { cookies } from 'next/headers';
  * The mirror is deliberately not httpOnly: the session token is the
  *shopper's own low-privilege shop session (channel-scoped; the admin secret
  * never reaches the browser), and the client socket cannot exist without
- * reading it. Both cookies always carry the same value — this action is the
- * single writer.
+ * reading it. Both cookies always carry the same value — and this action is the
+ * single REPLACING writer.
+ *
+ * It is not the only writer: on a cookie-less first touch the `__fc` relays
+ * ESTABLISH the same pair (`session-cookies.ts`, which owns both names and the
+ * attributes all of them write), and they never replace what they find. So the
+ * pair moves as a pair no matter which writer moved it.
  */
 
-const SESSION_COOKIE = 'forgecart-session';
-const SESSION_MIRROR_COOKIE = 'forgecart-session-client';
-const SESSION_MAX_AGE = 60 * 60 * 24 * 30;
 /** Session tokens are opaque but bounded — reject junk before it hits a header. */
 const MAX_TOKEN_LENGTH = 512;
 
@@ -48,7 +56,6 @@ export async function syncShopSession(token: string | null): Promise<void> {
   ) {
     return;
   }
-  const shared = { sameSite: 'lax' as const, path: '/', maxAge: SESSION_MAX_AGE };
-  store.set(SESSION_COOKIE, token, { ...shared, httpOnly: true });
-  store.set(SESSION_MIRROR_COOKIE, token, { ...shared, httpOnly: false });
+  store.set(SESSION_COOKIE, token, { ...SESSION_COOKIE_ATTRIBUTES, httpOnly: true });
+  store.set(SESSION_MIRROR_COOKIE, token, { ...SESSION_COOKIE_ATTRIBUTES, httpOnly: false });
 }

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

@@ -0,0 +1,98 @@
+import type { NextResponse } from 'next/server';
+
+/**
+ * The shopper session's two homes — one identity, one contract.
+ *
+ *   - `forgecart-session`        httpOnly — the server-readable original, and
+ *                                the only presence signal server code may
+ *                                trust.
+ *   - `forgecart-session-client` the JS-readable mirror — what the browser's
+ *                                shop socket boots its auth from
+ *                                (`shop-session.ts`).
+ *
+ * Three writers share that contract: the two `__fc` relays, which ESTABLISH the
+ * pair on a cookie-less first touch, and `session-actions.ts#syncShopSession`,
+ * which REPLACES it whenever the client captures a new token. They write through
+ * different APIs — a relay owns a `NextResponse`, the action owns the
+ * request-scoped `cookies()` store — so what lives here is the part that must
+ * never drift between them: the names, the attributes, and the rule that
+ * establishment writes BOTH homes or neither.
+ *
+ * That rule is why this module exists. `document.cookie` cannot see an httpOnly
+ * cookie, so a session written into the original alone is invisible to the
+ * browser: the shop socket boots unauthenticated, its first operation mints a
+ * RIVAL session, `syncShopSession` overwrites both cookies with it, and
+ * everything recorded against the first one — the landing touch, an ad click's
+ * identifiers — is stranded on a session no attribution read resolves to.
+ * Nothing errors, and no session merge exists to repair it afterwards (#1733).
+ *
+ * No `secure` on either half, unlike the VISITOR pair in `middleware.ts`.
+ * `secure` is honored on https and on localhost; browsers may drop it on the
+ * other plain-http dev hosts — the `*.127.0.0.1.nip.io` preview hostnames a
+ * merchant looks at first. `middleware.ts` accepts that loss for the visitor id
+ * (a production concern, not a preview one); the session cannot, because losing
+ * it on a preview loses the cart the preview exists to demo. The cost is taken
+ * deliberately: the pair rides plain http wherever a deployed host answers on
+ * it. Setting it on one half only would be worse still — the pair would split
+ * precisely there.
+ *
+ * Writers are not the only importers. The server-side READERS of the original
+ * (`lib/experiments.ts`, `server/runner.ts`) take its name from here too, so
+ * the literal lives in one place. And this module is deliberately NOT
+ * `server-only`, unlike `session-actions.ts`: the mirror's name is a CLIENT
+ * fact as well — `lib/shop-session.ts` reads it from `document.cookie` — so
+ * client code must stay able to import it. That file still carries its own copy
+ * of the name while it sits in the #1136 refresh partition; it is the last
+ * duplicate.
+ */
+
+/** The httpOnly copy — the server-readable original of the shopper's session. */
+export const SESSION_COOKIE = 'forgecart-session';
+
+/**
+ * The JS-readable mirror. Never read as AUTHORITY server-side: it is DERIVED
+ * from the original and written only beside it, and being client-writable it
+ * must never be what decides whether a request is carrying a session — the same
+ * posture the visitor pair's mirror keeps in `middleware.ts`, which reads its
+ * own mirror only to detect drift and re-sync it, never to decide.
+ */
+export const SESSION_MIRROR_COOKIE = 'forgecart-session-client';
+
+/** 30 days — the shopper session's window, in both homes. */
+const SESSION_COOKIE_MAX_AGE_SECONDS = 60 * 60 * 24 * 30;
+
+/**
+ * Everything the two cookies share. `httpOnly` is the ONLY attribute that may
+ * differ between them, and the single `maxAge` is deliberate: cookies that
+ * expired apart would leave a half-present pair that no writer could tell from
+ * a first touch.
+ */
+export const SESSION_COOKIE_ATTRIBUTES = {
+  sameSite: 'lax',
+  path: '/',
+  maxAge: SESSION_COOKIE_MAX_AGE_SECONDS,
+} as const;
+
+/**
+ * Establish the shopper identity on a relay response: both homes, one token,
+ * one lifetime.
+ *
+ * Establishment, never replacement — a caller guards on the httpOnly original
+ * being ABSENT (`if (!incomingSession && token)`) and calls this only then.
+ * Replacing a live session would vanish the cart it holds (the first-touch
+ * double-mint race), and adopting a stale session's re-mint belongs to the cart
+ * path, whose SDK capture and `syncShopSession` own it.
+ *
+ * That guard reads the ORIGINAL alone on purpose. It is the authoritative copy;
+ * the mirror is client-writable, so letting it answer "a session is present"
+ * would let a tampered cookie suppress establishment entirely. And because the
+ * pair is always written together with one lifetime, a mirror without its
+ * original is not a state this storefront can produce.
+ */
+export function establishSessionCookies(response: NextResponse, token: string): void {
+  response.cookies.set(SESSION_COOKIE, token, { ...SESSION_COOKIE_ATTRIBUTES, httpOnly: true });
+  response.cookies.set(SESSION_MIRROR_COOKIE, token, {
+    ...SESSION_COOKIE_ATTRIBUTES,
+    httpOnly: false,
+  });
+}

package/templates/storefront/src/lib/shop-config.ts

@@ -30,6 +30,13 @@ const CHANNEL_TOKEN = process.env.FORGECART_CHANNEL_TOKEN ?? '';
 export interface BrowserShopConfig {
   apiUrl: string;
   channelToken: string;
+  /**
+   * The request's resolved locale. The SDK fixes its language per CONNECTION
+   * at the socket handshake, so the shopper's session client must be built
+   * knowing it — the browser cannot re-derive it (the URL it sees is the
+   * PREFIXED one, the route it rendered is not).
+   */
+  languageCode: string;
 }
 
 /** Whether `forgecart init` has written the shop env yet (pre-warm renders without it). */
@@ -38,7 +45,7 @@ export function isShopConfigured(): boolean {
 }
 
 /** The client-socket coordinates, or null on an unconfigured scaffold. */
-export function getBrowserShopConfig(): BrowserShopConfig | null {
+export function getBrowserShopConfig(languageCode: string): BrowserShopConfig | null {
   if (!isShopConfigured()) return null;
-  return { apiUrl: SHOP_API_BROWSER_URL, channelToken: CHANNEL_TOKEN };
+  return { apiUrl: SHOP_API_BROWSER_URL, channelToken: CHANNEL_TOKEN, languageCode };
 }

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

@@ -38,28 +38,57 @@ import { syncShopSession } from './session-actions';
 export interface ShopSessionConfig {
   apiUrl: string;
   channelToken: string;
+  /** The request's resolved locale — the session speaks the page's language. */
+  languageCode: string;
 }
 
 const SESSION_MIRROR_COOKIE = 'forgecart-session-client';
 
+/**
+ * Browser-readable mirror of the httpOnly `forgecart-visitor` cookie,
+ * minted by the middleware (#1079 P1). Its value rides the SDK's
+ * `forgecart-visitor` WS connection-params header so visitor-subject
+ * experiment goals stamp server-side.
+ */
+const VISITOR_MIRROR_COOKIE = 'forgecart-visitor-client';
+
 let config: ShopSessionConfig | null = null;
 let client: ForgeCartShopClient | null = null;
 let syncedToken: string | null = null;
 
-/** Read the session mirror cookie (null outside the browser or when absent). */
-export function readMirrorSession(): string | null {
+/** Read a JS-visible mirror cookie (null outside the browser or when absent). */
+function readMirrorCookie(name: string): string | null {
   if (typeof document === 'undefined') return null;
   const entry = document.cookie
     .split('; ')
-    .find((candidate) => candidate.startsWith(`${SESSION_MIRROR_COOKIE}=`));
+    .find((candidate) => candidate.startsWith(`${name}=`));
   if (!entry) return null;
-  const value = decodeURIComponent(entry.slice(SESSION_MIRROR_COOKIE.length + 1));
+  const value = decodeURIComponent(entry.slice(name.length + 1));
   return value.length > 0 ? value : null;
 }
 
-/** Arm the singleton with the channel coordinates (idempotent; provider mount). */
+/** Read the session mirror cookie (null outside the browser or when absent). */
+export function readMirrorSession(): string | null {
+  return readMirrorCookie(SESSION_MIRROR_COOKIE);
+}
+
+/**
+ * Arm the singleton with the channel coordinates (idempotent; provider mount).
+ *
+ * A locale switch is a full document load — the switcher uses plain anchors
+ * precisely so the language cannot go stale — which resets this module and
+ * rebuilds the client at the new language. The re-sync below covers the
+ * remaining case: a client-side navigation that somehow changes the resolved
+ * locale would otherwise leave a live socket speaking the previous language
+ * for the rest of the session. `setLanguageCode` disposes and re-handshakes
+ * the socket, so it is called ONLY on an actual change.
+ */
 export function initShopSession(next: ShopSessionConfig): void {
+  const previous = config;
   config = next;
+  if (client && previous && previous.languageCode !== next.languageCode) {
+    client.setLanguageCode(next.languageCode);
+  }
 }
 
 /** Whether the session socket can exist (configured scaffold + browser). */
@@ -77,6 +106,14 @@ function ensureClient(): ForgeCartShopClient {
     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) {