@forgecart/cli 2.202608221935.0 → 2.202609190800.0

package/templates/storefront/src/lib/locale/middleware-plan.ts

@@ -0,0 +1,107 @@
+import { isUnprefixedPath, parseLocalePath } from './grammar';
+
+/**
+ * What the middleware does with a request path (#1346, epic launch#54 W1-8 /
+ * S1) — the edge stage's whole locale decision, as a value.
+ *
+ * PURE BY CONTRACT, for the same two reasons `grammar.ts` is: it runs on every
+ * request under the edge runtime, and `tool/storefront-template-spec` imports
+ * it directly from outside the scaffold. `middleware.ts` itself can never be
+ * pinned by that project — it imports `next/server` — so the decision lives
+ * here and the middleware is left as dispatch.
+ */
+
+/** The edge stage's decision for one request path. */
+export type LocaleRewritePlan =
+  | { kind: 'pass' }
+  | { kind: 'rewrite'; locale: string; routePath: string };
+
+/**
+ * Plan the locale stage for `pathname`.
+ *
+ *  - `pass` — no locale prefix (the default-language majority of traffic), or
+ *    a prefix worn over a store-wide route.
+ *  - `rewrite` — serve `routePath` in `locale`.
+ *
+ * The `pass` on a prefixed infrastructure route is the load-bearing one.
+ * `/ping` never reaches middleware, but `/de/ping` does: the matcher's
+ * negative lookahead is anchored at the start of the path, so it is a
+ * whole-path prefix test. Rewriting that onto the real readiness probe would
+ * give it 676 two-letter spellings that answer 200 — each with a `Set-Cookie`
+ * attached, on a route whose contract is to be byte-stable and cacheable —
+ * where every one of them previously 404'd. Passing leaves the path whole, so
+ * it reaches a route tree that has no such route.
+ *
+ * The candidate is NOT validated here — that needs the channel's languages,
+ * and this stage is zero-fetch by contract. An unknown locale still plans a
+ * `rewrite`; `decideRequestLocale` turns it into a 404 at request time.
+ *
+ * Canonicalization is deliberately absent: Next's own `/:path+/` → `/:path+`
+ * redirect and its repeated-slash normalization are ordered BEFORE middleware
+ * in `resolve-routes.js`, so a non-canonical path has already been 308'd by
+ * the time this runs. The grammar still normalizes, which makes this total for
+ * any input, but there is no canonicalizing branch here because there is no
+ * request that would reach it.
+ */
+export function planLocaleRewrite(pathname: string): LocaleRewritePlan {
+  const { localeCandidate, pathname: routePath } = parseLocalePath(pathname);
+  if (localeCandidate === null) return { kind: 'pass' };
+  if (isUnprefixedPath(routePath)) return { kind: 'pass' };
+
+  return { kind: 'rewrite', locale: localeCandidate, routePath };
+}
+
+/**
+ * Headers the middleware puts ON the request for the render to read. They are
+ * SERVER-AUTHORED and the render trusts them completely, which is exactly why
+ * an inbound copy is an attack rather than input.
+ *
+ * `ROUTE_PATH` and `SEARCH` exist because the render sees the REWRITTEN path
+ * and cannot reconstruct the original — the layout needs both to build the
+ * canonical target when it redirects a default-locale prefix.
+ */
+export const LOCALE_REQUEST_HEADER = 'x-forgecart-locale';
+export const ROUTE_PATH_REQUEST_HEADER = 'x-forgecart-route-path';
+export const SEARCH_REQUEST_HEADER = 'x-forgecart-search';
+
+const SERVER_AUTHORED_HEADERS: readonly string[] = [
+  LOCALE_REQUEST_HEADER,
+  ROUTE_PATH_REQUEST_HEADER,
+  SEARCH_REQUEST_HEADER,
+];
+
+/**
+ * Whether a request arrived wearing a header only the server may set.
+ *
+ * A client sending `x-forgecart-locale: de` to `/products` would otherwise get
+ * a German render at the canonical English URL — content negotiation by request
+ * header, at a URL whose entire contract is that the URL is the only locale
+ * selector. The middleware uses this to decide whether a `pass` needs
+ * sanitizing at all, so clean traffic keeps the untouched fast path.
+ */
+export function hasServerAuthoredHeaders(headers: Headers): boolean {
+  return SERVER_AUTHORED_HEADERS.some((name) => headers.has(name));
+}
+
+/**
+ * The headers the render should see: every inbound copy of the server-authored
+ * set removed, then the real values written when there is a locale to forward.
+ *
+ * Strip-then-set, always in that order and unconditionally — a `pass` must be
+ * left carrying none of them, or a forged value survives into the render on
+ * exactly the paths that have no locale of their own.
+ */
+export function localeRequestHeaders(
+  headers: Headers,
+  plan: LocaleRewritePlan,
+  search: string,
+): Headers {
+  const sanitized = new Headers(headers);
+  for (const name of SERVER_AUTHORED_HEADERS) sanitized.delete(name);
+  if (plan.kind !== 'rewrite') return sanitized;
+
+  sanitized.set(LOCALE_REQUEST_HEADER, plan.locale);
+  sanitized.set(ROUTE_PATH_REQUEST_HEADER, plan.routePath);
+  sanitized.set(SEARCH_REQUEST_HEADER, search);
+  return sanitized;
+}

package/templates/storefront/src/lib/locale/request-binding.ts

@@ -0,0 +1,80 @@
+import 'server-only';
+
+import { cache } from 'react';
+import { headers } from 'next/headers';
+
+import { resolveChannelLocales } from './channel-locales-loader';
+import { decideRequestLocale } from './request-locale';
+import type { LocaleDecision } from './request-locale';
+import type { LocaleBinding } from './localized-path';
+import {
+  LOCALE_REQUEST_HEADER,
+  ROUTE_PATH_REQUEST_HEADER,
+  SEARCH_REQUEST_HEADER,
+} from './middleware-plan';
+
+/**
+ * The request's locale, resolved once and shared (#1346, W1-8 / S1+S2).
+ *
+ * This is the reader for the headers the middleware authored, and the only
+ * place the four-case decision is taken. A layout cannot pass props to a page
+ * — pages arrive as opaque `children` — so every server component that needs
+ * the locale calls this rather than receiving it, and React's `cache()` makes
+ * that one resolution per request no matter how many callers there are. The
+ * same primitive already backs `getVariant`'s request-scoped visitor id.
+ *
+ * Server-only by construction as well as by declaration: `headers()` throws in
+ * a client component, and `cache()` is an unmemoized pass-through in the
+ * client build. Client components receive the locale as a PROP instead — see
+ * `localized-path.ts` for why reading it from `usePathname()` cannot work
+ * under the rewrite.
+ */
+
+export interface RequestLocale {
+  /** What the layout must do with this request. */
+  decision: LocaleDecision;
+  /** What every link needs: the rendering locale and the channel default. */
+  binding: LocaleBinding;
+  /** The channel's languages, for the switcher. */
+  languageCodes: readonly string[];
+  /** The merchant's shop name, for the title suffix (#1347). Null when unset. */
+  shopName: string | null;
+  /**
+   * Whether the channel behind this render was actually established (#1347).
+   *
+   * Surfaced here rather than read from the loader directly because every
+   * `generateMetadata` in the template already awaits this resolution: the
+   * fact costs nothing to carry, and a route that has to fetch it separately
+   * is a route that will forget to.
+   */
+  channelResolved: boolean;
+  /** The pre-rewrite path and query, for building a canonical redirect. */
+  routePath: string;
+  search: string;
+}
+
+export const getRequestLocale = cache(async (): Promise<RequestLocale> => {
+  const requestHeaders = await headers();
+  const candidate = requestHeaders.get(LOCALE_REQUEST_HEADER);
+  const routePath = requestHeaders.get(ROUTE_PATH_REQUEST_HEADER) ?? '/';
+  const search = requestHeaders.get(SEARCH_REQUEST_HEADER) ?? '';
+
+  const { channel, offered } = await resolveChannelLocales(candidate);
+  const decision = decideRequestLocale({ candidate, routePath, channel, offered, search });
+
+  return {
+    decision,
+    // A redirect or a 404 never reaches a link, but the binding is built
+    // unconditionally so callers never have to branch: the channel default is
+    // the only honest locale for a request that is not being rendered.
+    binding: {
+      locale: decision.kind === 'render' ? decision.locale : channel.defaultLanguageCode,
+      defaultLocale: channel.defaultLanguageCode,
+    },
+    languageCodes: channel.languageCodes,
+    shopName: channel.shopName,
+    channelResolved: channel.resolved,
+    routePath,
+    search,
+  };
+});

package/templates/storefront/src/lib/locale/request-locale.ts

@@ -0,0 +1,66 @@
+import type { ChannelLocales } from './channel-locales';
+
+/**
+ * The request-time locale decision (#1346, epic launch#54 W1-8 / S1).
+ *
+ * The middleware cannot make this call — it is zero-fetch by contract — so it
+ * rewrites on a CANDIDATE and the real decision happens in the layout's
+ * request-time hole, where the channel's languages are reachable.
+ *
+ * This module is deliberately PURE and deliberately does not import
+ * `next/navigation`. Returning a decision instead of calling `notFound()` /
+ * `permanentRedirect()` is what keeps the interesting logic — which of four
+ * outcomes a request gets — inside the seam the template spec project can
+ * import. The layout performs the dispatch, and dispatch is the part with
+ * nothing left to get wrong.
+ */
+
+/** What the layout should do with this request. */
+export type LocaleDecision =
+  | { kind: 'render'; locale: string }
+  | { kind: 'redirect'; to: string }
+  | { kind: 'notFound' };
+
+export interface RequestLocaleInput {
+  /** The two-letter first segment the middleware stripped, if there was one. */
+  candidate: string | null;
+  /** The path AFTER the prefix was stripped — what the route tree serves. */
+  routePath: string;
+  /** The channel's advertised languages. */
+  channel: ChannelLocales;
+  /**
+   * Whether the channel offers `candidate`, already resolved through
+   * `channel-locales` (which reloads once on a miss, so a language added a
+   * moment ago answers `true` here on its first request).
+   */
+  offered: boolean;
+  /** The original query string, `''` or leading `?` — preserved on redirect. */
+  search?: string;
+}
+
+/**
+ * Decide the outcome for a request whose locale prefix has already been parsed.
+ *
+ * The four cases, in the order they must be tested:
+ *
+ *  1. No prefix at all → render in the channel's default language. This is the
+ *     canonical shape for the default locale.
+ *  2. The prefix names the DEFAULT language → permanent redirect to the
+ *     unprefixed path. `/en/products` and `/products` would otherwise be two
+ *     URLs serving one page, which is the duplicate-content split the whole
+ *     grammar exists to avoid. Tested BEFORE `offered`, because the default
+ *     language is always offered and would otherwise render prefixed.
+ *  3. The prefix names a language the channel does not offer → 404. Not a
+ *     redirect: silently rewriting an unknown locale to the default would tell
+ *     a crawler that `/zz/x` is a real page.
+ *  4. Otherwise → render in that language.
+ */
+export function decideRequestLocale(input: RequestLocaleInput): LocaleDecision {
+  const { candidate, routePath, channel, offered } = input;
+  if (candidate === null) return { kind: 'render', locale: channel.defaultLanguageCode };
+  if (candidate === channel.defaultLanguageCode) {
+    return { kind: 'redirect', to: `${routePath}${input.search ?? ''}` };
+  }
+  if (!offered) return { kind: 'notFound' };
+  return { kind: 'render', locale: candidate };
+}

package/templates/storefront/src/lib/marketing-params.ts

@@ -0,0 +1,213 @@
+/**
+ * The marketing signals a landing URL carries (#1596).
+ *
+ * A shopper arriving from an ad brings the entire attribution story in the
+ * query string and nowhere else: the platform's CLICK ID identifies that exact
+ * click to the platform's conversion API, and the UTM tags say which campaign
+ * paid for it. Both are gone the moment the visitor reaches a second page — no
+ * cookie, no header and no backend record carries them — so they are read on
+ * landing or they are lost.
+ *
+ * This module only READS them. It turns a query string into what it found;
+ * WHERE those values go — the identity mutation for the click IDs, the track
+ * event for the UTM tags — is the caller's decision, taken somewhere that has a
+ * session and can talk to the backend. Keeping the two apart is what lets the
+ * reading rules be a table of vectors rather than a browser scenario.
+ *
+ * PURE by construction, and that is a requirement rather than a preference: it
+ * imports nothing, touches no browser global and reads no environment. This
+ * template tree sits outside the repository's lint, typecheck and test graph
+ * (`eslint.config.mts` ignores it, `package/cli/tsconfig.lib.json` excludes it)
+ * and is copied verbatim into every merchant's store, so
+ * `tool/storefront-template-spec` — which imports modules like this one by
+ * relative path — is the only thing standing between this file and production.
+ * A module that stops being pure stops being testable from there, which is an
+ * alarm rather than an inconvenience.
+ */
+
+/** A captured click ID, shaped for the backend's `MarketingIdentifierInput`. */
+export interface MarketingIdentifier {
+  /** The registered identifier key this value is stored under. */
+  key: string;
+  /** The click ID exactly as the ad platform wrote it into the URL. */
+  value: string;
+}
+
+/**
+ * The captured UTM tags, shaped to be spread straight into `TrackEventInput`.
+ *
+ * Every field is optional and an absent tag is OMITTED rather than set to an
+ * empty string, because those are different claims: the backend treats a
+ * present `''` as a blank dimension and writes it to ClickHouse, where it can
+ * no longer be told apart from a campaign that genuinely has no medium.
+ */
+export interface UtmParams {
+  utmSource?: string;
+  utmMedium?: string;
+  utmCampaign?: string;
+  utmTerm?: string;
+  utmContent?: string;
+}
+
+/**
+ * What a landing URL turned out to carry.
+ *
+ * A discriminated union rather than a pair of possibly-empty collections,
+ * because "this visitor came from an ad" and "this visitor typed the address"
+ * are different situations and the second is by far the common one. The union
+ * makes the empty case impossible to walk past: nothing can reach `identifiers`
+ * or `utm` without answering the question first, so a visitor with no query
+ * parameters produces exactly the tracking behaviour that existed before this
+ * module — no extra request, no blank row.
+ *
+ * The `captured` arm carries at least one signal, though not necessarily both:
+ * an ad link with a click ID and no tags yields an empty `utm`, and a
+ * hand-written newsletter link yields empty `identifiers`. A caller skips the
+ * empty side rather than sending it.
+ */
+export type MarketingParams =
+  | { kind: 'none' }
+  | { kind: 'captured'; identifiers: readonly MarketingIdentifier[]; utm: UtmParams };
+
+/** One click ID: what the platform appends, and what we store it as. */
+interface ClickIdParam {
+  /** The parameter name an ad platform writes into the landing URL. */
+  readonly param: string;
+  /** The backend identifier key it is stored under. */
+  readonly key: string;
+}
+
+/** One UTM tag: the URL parameter, and the field it becomes. */
+interface UtmParam {
+  readonly param: string;
+  readonly field: keyof UtmParams;
+}
+
+/**
+ * The click IDs this storefront captures.
+ *
+ * Each `key` is byte-identical to one the backend pre-registers, in
+ * `package/core/src/marketing-identity/marketing-identity.module.ts:85`, and
+ * that exactness is load-bearing: the shop mutation looks the key up and
+ * REJECTS an unknown one — reporting it in `rejected` rather than failing — so
+ * a single typo here loses the attribution silently, behind a response that
+ * still looks accepted.
+ *
+ * Three of the six registered click IDs appear below. The other three
+ * (`msclkid`, `liClickId`, `impact_click_id`) are registered backend-side, but
+ * an identifier's KEY and its URL-parameter spelling are two separate facts,
+ * and for those three they are not the same string — two are not even
+ * URL-shaped. Guessing the missing spellings would buy nothing and could cost
+ * real data: a guess that never matches is dead code, and a guess that happens
+ * to match another platform's parameter writes a foreign click's value into a
+ * real shopper's identity. Capturing one of them later is one row here, which
+ * is why the two spellings are held apart even where they coincide.
+ */
+const CLICK_ID_PARAMS: readonly ClickIdParam[] = [
+  { param: 'gclid', key: 'gclid' },
+  { param: 'fbclid', key: 'fbclid' },
+  { param: 'ttclid', key: 'ttclid' },
+];
+
+/**
+ * All five UTM tags, not the three everyone names.
+ *
+ * `utm_term` and `utm_content` are the two dropped as an afterthought, and
+ * dropping them here would be a pure loss for zero saving: the chain downstream
+ * already carries five, from `TrackEventInput` through the relay's allowlist in
+ * `src/app/__fc/track/route.ts` to the ClickHouse columns and the
+ * `MarketingTouchpoint` row. They are also what tells two ads in one ad group
+ * apart, which is the granularity a merchant actually optimises at.
+ */
+const UTM_PARAMS: readonly UtmParam[] = [
+  { param: 'utm_source', field: 'utmSource' },
+  { param: 'utm_medium', field: 'utmMedium' },
+  { param: 'utm_campaign', field: 'utmCampaign' },
+  { param: 'utm_term', field: 'utmTerm' },
+  { param: 'utm_content', field: 'utmContent' },
+];
+
+/**
+ * Unicode control characters (C0, DEL, C1), stripped from every value.
+ *
+ * The same expression the server applies in
+ * `package/core/src/marketing-event/service/marketing-event.service.ts:38`.
+ * Repeating it here is not belt-and-braces — it is what keeps the value SENT
+ * identical to the value STORED, so the two can never be reported differently.
+ */
+const CONTROL_CHARS_REGEX = /\p{Cc}/gu;
+
+/**
+ * The cap the server applies to every UTM value (that same service, line 39),
+ * mirrored here so a tag cannot change shape in transit. These land in
+ * `LowCardinality(String)` ClickHouse columns, where the cap is what stops
+ * client garbage from inflating the column dictionary; truncating at the same
+ * boundary means the campaign name a merchant reads in a report is the one this
+ * module sent.
+ */
+export const UTM_VALUE_MAX_LENGTH = 128;
+
+/**
+ * The cap for a click ID — deliberately NOT the UTM one.
+ *
+ * There is nothing to mirror here: an identifier value lands in an unbounded
+ * `varchar` and the identity path validates the KEY while storing the value
+ * exactly as given, so this bound is a garbage fence rather than a truncation
+ * the server would reproduce. It therefore has to sit well clear of every real
+ * click ID: Meta's `fbclid` routinely runs past 128 characters, and a click ID
+ * short by even one character matches nothing at the platform that issued it.
+ * That failure is silent — the conversion simply never attributes — and
+ * preventing it is the reason this module exists.
+ */
+export const CLICK_ID_VALUE_MAX_LENGTH = 512;
+
+/**
+ * Read the marketing signals out of a landing URL's query string.
+ *
+ * Accepts the string with or without its leading `?`, so `window.location.
+ * search` and a hand-built query read alike. Never throws: this runs on the
+ * first render of every page a visitor can land on, and an unreadable query is
+ * a reason to capture nothing, never a reason to fail the page the shopper came
+ * for.
+ *
+ * A repeated parameter keeps its FIRST occurrence. `?gclid=a&gclid=b` has no
+ * honest reading — one of the two belongs to somebody else's click — and the
+ * first is the one the ad platform appended before any later redirect had the
+ * chance to add its own.
+ */
+export function parseMarketingParams(search: string): MarketingParams {
+  const params = new URLSearchParams(search);
+
+  const identifiers: MarketingIdentifier[] = [];
+  for (const { param, key } of CLICK_ID_PARAMS) {
+    const value = sanitize(params.get(param), CLICK_ID_VALUE_MAX_LENGTH);
+    if (value === undefined) continue;
+    identifiers.push({ key, value });
+  }
+
+  const utm: UtmParams = {};
+  for (const { param, field } of UTM_PARAMS) {
+    const value = sanitize(params.get(param), UTM_VALUE_MAX_LENGTH);
+    if (value === undefined) continue;
+    utm[field] = value;
+  }
+
+  if (identifiers.length === 0 && Object.keys(utm).length === 0) return { kind: 'none' };
+  return { kind: 'captured', identifiers, utm };
+}
+
+/**
+ * Clean one raw parameter value, or report it absent.
+ *
+ * The order matters and matches the server's `sanitizeLowCardinalityValue`
+ * (`marketing-event.service.ts:343`): strip control characters, trim, drop what
+ * remains if it is empty, and only then cap. Capping first would let trailing
+ * whitespace eat the budget, and treating a blank as present would send
+ * `?utm_source=` upstream as a campaign whose source is the empty string.
+ */
+function sanitize(raw: string | null, maxLength: number): string | undefined {
+  if (raw === null) return undefined;
+  const stripped = raw.replace(CONTROL_CHARS_REGEX, '').trim();
+  if (stripped.length === 0) return undefined;
+  return stripped.slice(0, maxLength);
+}

package/templates/storefront/src/lib/money.ts

@@ -0,0 +1,50 @@
+/**
+ * Minor-unit money arithmetic — the one place the ISO-4217 exponent is decided.
+ *
+ * ForgeCart prices are integers in the currency's smallest denomination, and
+ * the divisor is NOT always a hundred: 2500 is $25.00 (two-decimal cents) but
+ * ¥2,500 (zero-decimal yen) and BHD 2.500 (three-decimal fils). A hardcoded
+ * hundred is therefore wrong for real currencies, silently, and only for
+ * merchants outside the two-decimal world.
+ *
+ * It lives here rather than inside the price formatter because there are now
+ * two consumers with different output: the shopper-facing string
+ * (`lib/format.ts`) and the machine-readable `Offer.price` a crawler reads
+ * (`lib/seo/json-ld.ts`). Those two disagreeing about what 2500 means would
+ * publish one price to people and another to search engines — a discrepancy
+ * that reads as deceptive pricing, and one nothing in the template would
+ * report. One derivation, two consumers, no room to drift.
+ *
+ * Pure by construction — no SDK types, no `next` — so it is a table of vectors
+ * rather than something only a rendered page can exercise.
+ */
+
+/**
+ * The currency's fraction digits, from the same CLDR data that renders it.
+ *
+ * Derived rather than tabulated: a hand-maintained exponent table is a second
+ * source of truth that goes stale silently. The fallback of 2 covers a
+ * formatter that resolves no digits at all (an unknown code), which is the
+ * only case CLDR cannot answer.
+ */
+export function currencyExponent(currency: string): number {
+  const formatter = new Intl.NumberFormat('en-US', { style: 'currency', currency });
+  return formatter.resolvedOptions().maximumFractionDigits ?? 2;
+}
+
+/** A minor-unit integer as its major-unit value — 2500 USD → 25, 2500 JPY → 2500. */
+export function toMajorUnits(minorUnits: number, currency: string): number {
+  return minorUnits / 10 ** currencyExponent(currency);
+}
+
+/**
+ * A minor-unit integer as the decimal string schema.org wants for a price.
+ *
+ * Fixed to the currency's own digit count, deliberately: `25` and `25.00` are
+ * the same number but not the same claim to a price parser, and a
+ * zero-decimal currency must not acquire cents it does not have.
+ */
+export function toPriceString(minorUnits: number, currency: string): string {
+  const exponent = currencyExponent(currency);
+  return (minorUnits / 10 ** exponent).toFixed(exponent);
+}

package/templates/storefront/src/lib/seo/alternates.ts

@@ -0,0 +1,120 @@
+import { localizedPath } from '../locale/localized-path';
+import type { LocaleBinding } from '../locale/localized-path';
+
+/**
+ * Self-canonical + reciprocal hreflang (#1347, epic launch#54 W1-9).
+ *
+ * PURE, with no env read of its own: the origin arrives as a parameter and the
+ * only caller is `metadata.ts`, which composes these claims together with the
+ * title, the robots directive and the social card. Routes do not call in here
+ * directly — five separate claims about one address, assembled separately, can
+ * disagree in ways nothing in the template would notice.
+ *
+ * Two claims, and both are claims about OTHER URLs, which is what makes them
+ * dangerous to derive loosely:
+ *
+ *  - the canonical says "this content lives at exactly this address", which
+ *    tells a crawler to collapse every other URL that serves it;
+ *  - each hreflang says "the same content exists, in that language, over
+ *    there" — and search engines require reciprocity, so an alternate pointing
+ *    at a page that does not point back is discarded, taking the whole cluster's
+ *    credibility with it.
+ *
+ * Reciprocity is therefore achieved BY CONSTRUCTION rather than by asserting
+ * it: every locale in the set is rendered from the same `pathsByLocale` map, so
+ * each page in a cluster emits an identical alternate set. Two pages built from
+ * one map cannot disagree.
+ */
+
+/** Unprefixed path per language that genuinely HAS this content. */
+export type PathsByLocale = Readonly<Record<string, string>>;
+
+export interface AlternatesInput {
+  /** The locale this page is being rendered in. */
+  binding: LocaleBinding;
+  /**
+   * Every language with real content, mapped to its own unprefixed path.
+   *
+   * Membership is the ONLY thing that decides which alternates are emitted:
+   * a language a merchant has not translated must never appear, or the cluster
+   * advertises a page that answers a fallback copy.
+   */
+  pathsByLocale: PathsByLocale;
+  /** The deployment's public origin, or null when it has none. */
+  publicOrigin: string | null;
+}
+
+/** What a page declares about its own address and its siblings. */
+export interface Alternates {
+  canonical: string;
+  languages: Record<string, string>;
+}
+
+/**
+ * The alternates for this page, or undefined when it must not make the claim.
+ *
+ * Undefined in exactly one case: this locale is not in `pathsByLocale`, which
+ * means the shopper is looking at a derived fallback copy. Such a page has no
+ * address of its own to be canonical about, and pointing hreflang at the
+ * languages that DO have the content would invite a crawler to treat the
+ * fallback as part of a reciprocal set it is not a member of. Asserting
+ * nothing is the honest answer — the same posture the preview deployment takes.
+ */
+export function buildAlternates({
+  binding,
+  pathsByLocale,
+  publicOrigin,
+}: AlternatesInput): Alternates | undefined {
+  const ownPath = pathsByLocale[binding.locale];
+  if (ownPath === undefined) return undefined;
+
+  const languages: Record<string, string> = {};
+  for (const [languageCode, path] of Object.entries(pathsByLocale)) {
+    languages[languageCode] = absolute(
+      localizedPath(path, { locale: languageCode, defaultLocale: binding.defaultLocale }),
+      publicOrigin,
+    );
+  }
+
+  // `x-default` names where an unmatched visitor should land, and the channel's
+  // default language is the only defensible answer — it is the copy served
+  // unprefixed. Emitted only when that language actually has the content:
+  // pointing x-default at a page that does not exist is worse than omitting it.
+  const defaultPath = pathsByLocale[binding.defaultLocale];
+  if (defaultPath !== undefined) {
+    languages['x-default'] = absolute(
+      localizedPath(defaultPath, { locale: binding.defaultLocale, defaultLocale: binding.defaultLocale }),
+      publicOrigin,
+    );
+  }
+
+  return { canonical: absolute(localizedPath(ownPath, binding), publicOrigin), languages };
+}
+
+/**
+ * The path map for a route that exists in EVERY language — the home page, the
+ * catalog, and any page a merchant scaffolds.
+ *
+ * Structural routes are not translated content: `/products` is the same route
+ * in every cluster, so every offered language has it and each one is a genuine
+ * alternate. That is the opposite of a product, where membership has to be
+ * earned per language (see `productPathsByLocale`).
+ */
+export function staticPathsByLocale(
+  languageCodes: readonly string[],
+  path: string,
+): Record<string, string> {
+  return Object.fromEntries(languageCodes.map((languageCode) => [languageCode, path]));
+}
+
+/**
+ * Absolute against the public origin, relative without one.
+ *
+ * A relative canonical is valid and resolves against the document's own URL, so
+ * it stays truthful on a preview host — where an absolute URL would either name
+ * an origin we do not have or invent one. Those pages are noindex anyway
+ * (`noindex.ts`), so this is belt and braces rather than the primary defence.
+ */
+function absolute(path: string, publicOrigin: string | null): string {
+  return publicOrigin === null ? path : `${publicOrigin}${path}`;
+}