@usequeek/theme-kit 0.1.21 → 0.1.22

package/types/media.ts

@@ -1,21 +1,20 @@
 /**
- * The srcset-ready tier map emitted by the backend's MediaVariantMap
- * (queek_backend: app/Services/Media/MediaVariantMap.php). Sits BESIDE the
- * existing collapsed url fields (media.image, vendor.logo, collection.image, …),
- * which are unchanged — this is purely additive.
+ * The srcset-ready tier map emitted by the API. Sits BESIDE the existing
+ * collapsed url fields (media.image, vendor.logo, collection.image, …), which
+ * are unchanged — this is purely additive.
  *
- * Contract (enforced backend-side, relied on here):
+ * Contract (enforced API-side, relied on here):
  *  1. All 5 keys are ALWAYS present when the map itself is non-null.
  *  2. A tier that doesn't exist is the WHOLE VALUE null — never a partial
  *     object, never a fallback url. Skip it; never synthesize a filename.
  *  3. `original` is never null when the map is non-null. Modeled as
  *     `ImageVariantTier | null` anyway rather than a type-level invariant:
- *     making it non-nullable would buy zero runtime safety against a backend
+ *     making it non-nullable would buy zero runtime safety against an API
  *     regression while forcing every consumer through a `!` or a cast. The
  *     invariant is documented, not encoded.
  *  4. `w`/`h` are `min(tier_cap, original.width)` and the proportional height —
  *     so on a small original SEVERAL TIERS LEGITIMATELY SHARE A WIDTH. That is
- *     correct backend behavior, and the reason resolveImageSources() dedupes
+ *     correct API behavior, and the reason resolveImageSources() dedupes
  *     srcset candidates by width (duplicate `w` descriptors make a srcset
  *     non-deterministic).
  *  5. `thumb` ALWAYS has `w: null, h: null` — it's a legacy 150→240px tier with
@@ -25,7 +24,7 @@
  *     url, SVG, some legacy uploads). Consumers fall back to the existing
  *     collapsed field, exactly as today.
  *
- * Tier caps (queek_backend config/media.php `variant_widths`):
+ * Tier caps (px):
  *   thumb ~240 (uncapped/legacy) · card 480 · card2x 800 · view 1600 · original raw
  */
 export interface ImageVariantTier {
@@ -44,7 +43,7 @@ export type ImageVariants = {
 
 /**
  * The flat url→variants sidecar on a Page/Post response
- * (StorePageResource::toArray → 'media_index'). Keyed by the EXACT raw url
+ * (the `media_index` field). Keyed by the EXACT raw url
  * string as it appears in that same response's `content[]` block JSON —
  * block schemas were not changed, so a consumer looks up
  * `mediaIndex[url] ?? null` per raw url it finds in block content.

package/types/product.ts

@@ -29,8 +29,7 @@ export interface ProductShop {
 }
 
 /**
- * One entry of the ordered `images` list (backend
- * `CustomerProductMedia::orderedImages()`): primary first,
+ * One entry of the ordered `images` list: primary first,
  * `{id, url, alt, variants}`. The listing payload caps the list
  * (`media.listing.images_limit`); detail/PDP carries the full list.
  */
@@ -53,11 +52,9 @@ export interface ProductMedia {
   primary_variant_image?: string | null;
   video_url?: string | null;
   /** Falls back to `image` server-side when the vendor hasn't set an explicit
-   *  poster (ProductResource::resolveVideoPosterUrl) — always a usable value
-   *  whenever video_url is set. */
+   *  poster — always a usable value whenever video_url is set. */
   video_poster_url?: string | null;
-  /** Srcset tier map for `image` (ProductResource::buildBaseMediaPayload /
-   *  buildDetailMediaPayload — present on BOTH list and detail responses).
+  /** Srcset tier map for `image` (present on BOTH list and detail responses).
    *  null when the primary image isn't Media-backed. */
   image_variants?: ImageVariants | null;
   /** Sibling to `primary_variant_image`, same contract. */
@@ -268,9 +265,8 @@ export interface LegacyProductLike {
   vendor_id?: string;
   thumbnail?: string | null;
   image?: string | null;
-  // Sibling top-level fields on the real backend payload (ProductResource::
-  // buildBasePayload) — NOT nested under `media` server-side, unlike
-  // image/thumbnail which are sent in both places.
+  // Sibling top-level fields on the real API payload — NOT nested under
+  // `media` server-side, unlike image/thumbnail which are sent in both places.
   video_url?: string | null;
   video_poster_url?: string | null;
   stock?: number;
@@ -296,9 +292,9 @@ export interface LegacyProductLike {
       // also send it as a {optionName: value} map (normalizeVariantOptionValues handles both) —
       // intersecting the two types directly collapses to an unsatisfiable type, hence the Omit.
       option_values?: ProductVariantOptionValue[] | Record<string, string>;
-      // The backend sends a variant's own price/stock as FLAT fields (see
-      // ProductResource::resolveShopVariants), never nested under pricing/inventory —
-      // those nested keys only exist if some other caller pre-shapes the payload.
+      // The API sends a variant's own price/stock as FLAT fields, never nested
+      // under pricing/inventory — those nested keys only exist if some other
+      // caller pre-shapes the payload.
       price?: number;
       discount_price?: number;
       compare_at_price?: number | null;

package/types/theme.ts

@@ -254,9 +254,8 @@ export interface ThemeManifestVariant {
    * in vendor.ts) this variant's rendered markup actually consumes via CSS
    * vars, i.e. which controls a per-section `block.tokens` override on THIS
    * variant will visibly change. Authored next to the component/CSS that
-   * consumes the vars so it can't drift — flows verbatim through
-   * generate-theme-registry.ts → registry.json → Laravel's Theme.variants →
-   * ThemeManifestService (mirrors `fields`).
+   * consumes the vars so it can't drift — flows verbatim from the manifest
+   * through the theme registry to the API (mirrors `fields`).
    *
    * Granular per sub-control, NOT per parent dimension — `'shape'` is not a
    * valid entry; declare `'shape.radius'` and/or `'shape.border_weight'`
@@ -269,19 +268,17 @@ export interface ThemeManifestVariant {
    *
    * No back-compat default: an omitted `editable` (or an omitted leaf) means
    * NOT stylable for that control — every variant in every theme has an
-   * explicit, audited array as of the 2026-08-03 granular pass.
+   * explicit, audited array.
    */
   editable?: DesignTokenAxisPath[];
   /**
-   * Business buckets this variant is a strong fit for, as
-   * `config/category_packs.php` keys ONLY (queek_backend): food | supermarket |
-   * product | pharmacy | laundry | delivery | service | gas-refill |
-   * local_market. Omitted = universal. Authored next to the component (same
-   * anti-drift placement as `fields`/`editable`) and flows verbatim through
-   * generate-theme-registry.ts -> registry.json -> Laravel's Theme.variants ->
-   * ThemeManifestService, where BuildHomepageTool's scored resolver boosts a
-   * bucket match when auto-building a store. The backend matches buckets with
-   * `_`/`-` treated as equivalent.
+   * Business buckets this variant is a strong fit for, as category-pack keys
+   * ONLY: food | supermarket | product | pharmacy | laundry | delivery |
+   * service | gas-refill | local_market. Omitted = universal. Authored next to
+   * the component (same anti-drift placement as `fields`/`editable`) and flows
+   * verbatim through the theme registry to the API, where the AI store builder
+   * boosts a bucket match when auto-building a store. The API matches buckets
+   * with `_`/`-` treated as equivalent.
    */
   best_for?: string[];
   /**
@@ -342,13 +339,11 @@ export interface ThemeManifest {
   features?: string[];
   images?: Record<string, ThemeImageSpec>;
   /**
-   * Theme's default semantic design-token set (design-token-contract.md,
-   * queek_backend `.agent/.tmp/`) — the theme's current look expressed as
-   * tokens. Surfaced via `ThemeManifestService`/registry.json as the
-   * baseline the backend resolver layers vendor `tokens` overrides onto
-   * (theme defaults ← legacy fields ← vendor overrides). Optional during
-   * the pilot rollout — themes without it fall back to the storefront
-   * injector's own hardcoded defaults (`lib/core/utils/brand.ts`).
+   * Theme's default semantic design-token set — the theme's current look
+   * expressed as tokens. Surfaced through the theme registry as the baseline
+   * the API resolver layers vendor `tokens` overrides onto (theme defaults ←
+   * legacy fields ← vendor overrides). Optional — themes without it fall back
+   * to the token injector's own hardcoded defaults (`utils/brand.ts`).
    */
   tokens?: DesignTokens;
   /**
@@ -358,19 +353,25 @@ export interface ThemeManifest {
    * Same shape as the kit core English default
    * (nested objects by dot-path, or flat dotted keys; CLDR plural maps
    * allowed); keys follow the shared grammar (dotted lowercase, <= 40
-   * chars) because the backend overlay stores `<theme-slug>.<key>` in a
-   * varchar(64).
+   * chars) because merchant overrides are stored as `<theme-slug>.<key>` in a
+   * 64-character field.
    *
    * The kit layers it between the host-loaded locale dictionaries and the
    * kit core English, so ANY host that mounts the theme (vendor layout,
    * theme preview, CLI dev preview) renders the theme's English with zero
    * host cooperation — a host that passes nothing still shows English,
    * never empty labels. ENGLISH ONLY: non-English packs stay host-loaded
-   * per locale and are never bundled into the theme. Optional during the
-   * migration — a manifest without it behaves exactly as before (kit core
-   * English, then `''` for unknown keys).
+   * per locale and are never bundled into the theme. Optional — a manifest
+   * without it falls back to the kit core English, then `''` for unknown keys.
    */
   strings?: ThemeStringsDictionary;
+  /**
+   * Set to `'theme'` when the theme places the kit's `LanguageSwitcher`
+   * itself. The storefront then does not render its own floating language
+   * control, so the shopper sees exactly one. Optional — a manifest without
+   * it keeps the storefront's control for multi-language stores.
+   */
+  languageSwitcher?: 'theme';
 }
 
 /**

package/types/vendor.ts

@@ -7,13 +7,11 @@ export interface BrandFont {
 }
 
 /**
- * Semantic design-token shapes — the FROZEN contract
- * (`.agent/.tmp/design-token-contract.md` in queek_backend). Backend resolves
- * theme defaults ← legacy vendor fields ← vendor `tokens` overrides and
- * returns this object under `StorefrontConfig.tokens`. Every field is
- * optional: during the transition many vendors have no `tokens` at all, and
- * the storefront injector (`lib/core/utils/brand.ts`) fills every gap with a
- * sane default so it can never crash or omit a CSS var.
+ * Semantic design-token shapes. The API resolves theme defaults ← legacy
+ * vendor fields ← vendor `tokens` overrides and returns this object under
+ * `StorefrontConfig.tokens`. Every field is optional: many vendors have no
+ * `tokens` at all, and the token injector (`utils/brand.ts`) fills every gap
+ * with a sane default so it can never crash or omit a CSS var.
  */
 export type DesignColorScheme = 'light' | 'dark';
 export type DesignScaleRatio = 1.125 | 1.2 | 1.25 | 1.333;
@@ -94,9 +92,9 @@ export type DesignTokenAxis = keyof DesignTokens;
  * container's radius is a hardcoded literal, or a button's border reads
  * `--border-weight` while its radius doesn't. Declaring only the dimension name
  * (e.g. `'shape'`) would show a dead sub-dial next to a live one — this is the
- * exact 2026-08-03 gap found in Allure's products/carousel section (Image radius
- * and Corner radius dead, Image fit/filter and Border weight live, all under the
- * same 'shape'/'image' bundle). `type`/`elevation`/`motion` have no UI sub-controls
+ * exact gap of a products/carousel section whose Image radius and Corner radius
+ * were dead while Image fit/filter and Border weight were live, all under the
+ * same 'shape'/'image' bundle. `type`/`elevation`/`motion` have no UI sub-controls
  * today, so they stay bare (no `.field` suffix) — add one here the day a sub-dial
  * is added for them.
  */
@@ -185,7 +183,7 @@ export interface StorefrontConfig {
     heading?: string;
     body?: string;
   };
-  /** Resolved semantic design tokens (see design-token-contract.md). Absent for stores not yet migrated. */
+  /** Resolved semantic design tokens. Absent for stores that have none. */
   tokens?: DesignTokens | null;
   menus?: {
     header?: Menu;
@@ -235,7 +233,7 @@ export interface StorefrontConfig {
       heading?: string;
       tagline?: string;
       cta?: string;
-      /** `modal` variant only — when it should pop up. Backend field pending; defaults to 'scroll' when unset. */
+      /** `modal` variant only — when it should pop up. Defaults to 'scroll' when unset. */
       trigger?: 'immediate' | 'delay' | 'scroll';
     };
   };

package/utils/announcement.ts

@@ -1,9 +1,9 @@
 /**
- * The announcement bar is ONE text field on the backend
+ * The announcement bar is ONE text field on the API
  * (`header.announcement.text`). A vendor writes several messages into it
  * separated by `|` or a line break and the bar rotates them; a single
- * message renders static. Roast's masthead set the convention; the merchant
- * editor and Qee teach it. Split here, once, so every theme rotates the same
+ * message renders static. The merchant editor and Qee teach this convention.
+ * Split here, once, so every theme rotates the same
  * list — a theme-local split meant the other themes showed the literal pipes
  * after a switch.
  */

package/utils/benefit-icon.tsx

@@ -1,13 +1,12 @@
 import type { JSX } from 'react';
 /**
- * Shared icon-keyword vocabulary for "benefit row" content blocks (glow's
- * `trust-badges`, any theme's `features-columns`, and similar icon+title+text
- * item lists). qee generates a short keyword per item (e.g. "star", "truck"),
+ * Shared icon-keyword vocabulary for "benefit row" content blocks (a theme's
+ * `trust-badges` or `features-columns`, and similar icon+title+text item
+ * lists). Qee generates a short keyword per item (e.g. "star", "truck"),
  * never raw SVG markup — themes render that keyword through this resolver
- * instead of each theme re-declaring its own switch (glow and allure both
- * had one, independently, before this was extracted) or a theme trying to
- * `dangerouslySetInnerHTML` the keyword directly (renders as literal text,
- * not an icon — the bug that prompted this).
+ * instead of each theme re-declaring its own switch, or trying to
+ * `dangerouslySetInnerHTML` the keyword directly (that renders as literal
+ * text, not an icon).
  *
  * `currentColor` throughout — the caller controls color via CSS `color` on
  * an ancestor, same convention every existing usage already followed.
@@ -88,8 +87,8 @@ const PATHS: Record<BenefitIconKey, JSX.Element> = {
   ),
 };
 
-// Synonyms qee has actually generated in practice for a key in BENEFIT_ICON_KEYS
-// (confirmed live: "truck" for a shipping/delivery benefit) — the AI is given
+// Synonyms Qee is known to generate for a key in BENEFIT_ICON_KEYS (for example
+// "truck" for a shipping/delivery benefit) — the AI is given
 // the canonical keyword list in the manifest/prompt, but a close synonym
 // should still resolve to the right icon instead of silently falling back.
 const ALIASES: Record<string, BenefitIconKey> = {
@@ -103,8 +102,7 @@ const ALIASES: Record<string, BenefitIconKey> = {
   quality: 'star',
   payment: 'wallet',
   price: 'wallet',
-  // Carried over from glow's pre-shared TrustIcon switch — real demo data
-  // and, presumably, real qee-generated pages already use this word.
+  // Already used by existing demo data and generated pages.
   sustainability: 'leaf',
 };
 

package/utils/brand.ts

@@ -20,10 +20,8 @@ import type {
 
 /**
  * Storefront design-token injector — turns the resolved semantic `tokens`
- * object (design-token-contract.md, queek_backend `.agent/.tmp/`) into the
- * full CSS custom-property set every theme reads. Replaces the old
- * `getBrandCssVariables`, which only ever emitted ~12 of the 24 color roles
- * (the bug this fixes).
+ * object into the full CSS custom-property set every theme reads, covering
+ * all 24 color roles.
  *
  * `expandDesignTokens` is the pure, unit-tested core: given ANY partial (or
  * absent) token object it fills every gap with a sane default and always
@@ -34,7 +32,7 @@ import type {
  * legacy `config.colors` / `brand.colors` / `brand.font` ← defaults) and
  * hands them to `expandDesignTokens`, then layers on the handful of
  * chrome vars (`--brand-footer-*`, explicit legacy button overrides) that
- * live outside the token contract so existing stores render identically.
+ * live outside the token set so existing stores render identically.
  */
 
 const DEFAULT_COLOR: Required<DesignTokenColor> = {
@@ -120,7 +118,7 @@ const CASE_MAP: Record<DesignHeadingCase, string> = {
 
 /**
  * Deliberately its OWN fixed scale, not a reference into RADIUS_SCALE/
- * shape.radius. Live-caught (15/8/26): when `--image-radius` pointed at
+ * shape.radius. When `--image-radius` pointed at
  * `var(--radius-sm/md/lg)`, a vendor on the (very common) 'sharp' global
  * Shape preset saw EVERY image-radius choice — sharp, soft, AND rounded —
  * collapse to the same 0px, since 'sharp' flattens the whole sm/md/lg
@@ -215,8 +213,7 @@ function contrastRatio(hexA: string, hexB: string): number | null {
 }
 
 /** WCAG AA body-text minimum. Below this, `accent`/`on_accent` reads as
- *  the same color rather than text-on-a-surface (the Taylor/glow incident:
- *  a vendor's legacy `colors.accent` override went to near-black while
+ *  the same color rather than text-on-a-surface (for example, a vendor's legacy `colors.accent` override went to near-black while
  *  `on_accent` silently kept the theme's own default — also near-black,
  *  since it was tuned to pair with THAT theme's accent, not the vendor's). */
 const MIN_ON_ACCENT_CONTRAST = 4.5;
@@ -474,7 +471,7 @@ function legacyTokensFromConfig(brand?: Brand | null, config?: StorefrontConfig
 }
 
 /**
- * Resolution order per the contract: `config.tokens` (per-group) ←
+ * Resolution order: `config.tokens` (per-group) ←
  * legacy fields ← (handled by `expandDesignTokens`'s own defaults).
  */
 function resolveEffectiveTokens(brand?: Brand | null, config?: StorefrontConfig | null): DesignTokens {
@@ -497,7 +494,7 @@ function resolveEffectiveTokens(brand?: Brand | null, config?: StorefrontConfig
 /**
  * Resolve brand CSS variables for the `provider.tsx` wrapper. Emits the
  * full token-derived var set (see `expandDesignTokens`), then layers on
- * the legacy chrome/override vars that sit outside the token contract:
+ * the legacy chrome/override vars that sit outside the token set:
  * footer colors and an explicit `config.colors.button(_text)` override
  * (pre-tokens stores could set a button color independent of `primary`).
  */

package/utils/format.ts

@@ -4,11 +4,10 @@
  * down to 0, so it silently truncated EVERY fractional-naira amount to a
  * whole number, everywhere in the storefront. A ₦0.28 balance (e.g. a tiny
  * residual left after a near-100% discount) displayed as "₦0" — the customer
- * saw a free checkout, then got asked to actually pay something. POS already
- * shows real money correctly (lib/currency.ts: minimumFractionDigits: 2,
- * maximumFractionDigits: 2, always).
+ * saw a free checkout, then got asked to actually pay something. The POS
+ * always shows two decimals.
  *
- * Deliberately NOT matching POS's always-2-decimals contract here: the
+ * Deliberately NOT matching the POS's always-2-decimals format here: the
  * overwhelming majority of storefront prices are whole naira, and putting
  * ".00" on every single one would be a large, unrequested visual change
  * across every theme. `minimumFractionDigits: 0, maximumFractionDigits: 2`
@@ -51,8 +50,7 @@ function displayTagFor(
 /**
  * A date for display (default "14 Feb 2026"), identical on server and browser.
  * '' if unparseable. The locale parameter is routed through the canonical
- * mapping (founder 2/10/26: English is British/Nigerian order, never US
- * order), so even an explicit 'en'/'en-US' renders "15 February 2026" — no
+ * mapping (English is British/Nigerian order, never US order), so even an explicit 'en'/'en-US' renders "15 February 2026" — no
  * exported formatter lets an 'en*' tag reach Intl unmapped.
  */
 export function formatDisplayDate(
@@ -137,7 +135,7 @@ export const PLATFORM_DEFAULT_CURRENCY = 'NGN';
  * The ONE currency-code resolver: trims/uppercases the item or vendor code,
  * accepts it when it is a 3-letter code, and returns the platform default
  * otherwise. List-level `meta.currency` is never consulted — it stamps the
- * platform default even on non-NGN stores (api-currency-contract-fix).
+ * platform default even on non-NGN stores.
  */
 export function normalizeCurrencyCode(value: unknown, fallback: string = PLATFORM_DEFAULT_CURRENCY): string {
   const code = typeof value === 'string' ? value.trim().toUpperCase() : '';

package/utils/image-srcset.ts

@@ -22,10 +22,10 @@ export interface ResolvedImageSources {
 
 const NONE: ResolvedImageSources = { src: undefined, srcSet: undefined, sizes: undefined };
 
-/** Ascending by cap. `thumb` is excluded by contract rule 5; `original` is
+/** Ascending by cap. `thumb` is excluded because it has no width; `original` is
  *  excluded on purpose — it is uncapped and unoptimized (raw jpg/png, possibly
  *  6000px), so letting a browser pick it off a srcset is the exact regression
- *  this whole effort exists to remove. `original` survives only as a last-resort
+ *  the tier map exists to prevent. `original` survives only as a last-resort
  *  `src` for the `raw` intent and as the onError step-2 retry. */
 const SRCSET_TIERS = ['card', 'card2x', 'view'] as const;
 type SrcSetTier = (typeof SRCSET_TIERS)[number];

package/utils/locale-switch.ts

@@ -0,0 +1,208 @@
+/**
+ * Language-switch URL rules — pure (no `next/*`, no React) so the hook, the
+ * component and any node tooling share one implementation.
+ *
+ * Routing shape of a storefront with several languages:
+ *
+ * - The store's DEFAULT language is served at the store root (`path_prefix`
+ *   is `''`).
+ * - Every other language — English included when it is not the default —
+ *   lives under its bare lower-case code: `/fr`, `/en`, `/zh-cn`.
+ * - Slugs are never translated, so a page keeps the same path under every
+ *   prefix.
+ * - `StorefrontProvider`'s `basePath` already carries the ACTIVE language
+ *   prefix (`/store/fr` on a path-based host, `/fr` on a store domain), so
+ *   links built from it stay in the shopper's language. `localeHref` takes
+ *   that into account.
+ */
+
+/** One language a store serves — the row shape the locales endpoint returns. */
+export interface StoreLocale {
+  /** Language code, e.g. `en`, `fr`, `zh-CN`. */
+  locale: string;
+  /** English name, e.g. `French`. */
+  name: string;
+  /** The language's own name, e.g. `Français`. */
+  native_name: string;
+  /** The store's content (source) language. */
+  is_primary: boolean;
+  /** Served at the store root. Exactly one language is the default. */
+  is_default: boolean;
+  /** URL prefix: `''` on the default language, the bare lower-case code otherwise. */
+  path_prefix: string;
+  hreflang: string;
+  html_lang: string;
+  /** `'rtl'` or `'ltr'`. */
+  dir: string;
+}
+
+/**
+ * What `StorefrontProvider` accepts for `locales`: a `StoreLocale` list as
+ * the storefront already holds it, or an older payload that lacks
+ * `is_default` (then the primary language is the default). Extra fields are
+ * tolerated and dropped.
+ */
+export interface StoreLocaleInput {
+  locale: string;
+  name?: string;
+  native_name?: string;
+  is_primary?: boolean;
+  is_default?: boolean;
+  path_prefix?: string;
+  hreflang?: string;
+  html_lang?: string;
+  dir?: string;
+}
+
+const FALLBACK_LOCALE_CODE = 'en';
+
+/**
+ * Validates and normalises a locales payload into `StoreLocale` rows.
+ *
+ * - Rows without a string `locale` are dropped; a repeated code keeps its
+ *   first row.
+ * - `is_default` missing (older backend) is derived from `is_primary`.
+ * - Exactly one row stays default: the first flagged one, else the primary,
+ *   else the first row. It sorts first (others keep their order) and its
+ *   prefix is forced to `''`; every other prefix is lower-cased, and an
+ *   empty one becomes the bare lower-case code.
+ * - Nothing usable → `[]`, which the hook and component read as "single
+ *   language: no switcher".
+ */
+export function normalizeStoreLocales(input: readonly StoreLocaleInput[] | null | undefined): StoreLocale[] {
+  if (!Array.isArray(input)) return [];
+
+  const seen = new Set<string>();
+  const rows: StoreLocale[] = [];
+  for (const row of input as readonly StoreLocaleInput[]) {
+    if (!row || typeof row.locale !== 'string' || row.locale.length === 0) continue;
+    const key = row.locale.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+
+    const isPrimary = row.is_primary === true;
+    rows.push({
+      locale: row.locale,
+      name: typeof row.name === 'string' && row.name ? row.name : row.locale,
+      native_name: typeof row.native_name === 'string' && row.native_name ? row.native_name : (typeof row.name === 'string' && row.name ? row.name : row.locale),
+      is_primary: isPrimary,
+      is_default: typeof row.is_default === 'boolean' ? row.is_default : isPrimary,
+      path_prefix: typeof row.path_prefix === 'string' ? row.path_prefix.toLowerCase() : '',
+      hreflang: typeof row.hreflang === 'string' && row.hreflang ? row.hreflang : row.locale,
+      html_lang: typeof row.html_lang === 'string' && row.html_lang ? row.html_lang : row.locale,
+      dir: row.dir === 'rtl' ? 'rtl' : 'ltr',
+    });
+  }
+  if (rows.length === 0) return [];
+
+  const defaultRow = rows.find((row) => row.is_default) ?? rows.find((row) => row.is_primary) ?? rows[0];
+  const normalized = rows.map((row) => {
+    const isDefault = row === defaultRow;
+    return {
+      ...row,
+      is_default: isDefault,
+      path_prefix: isDefault ? '' : row.path_prefix || row.locale.toLowerCase(),
+    };
+  });
+  return [...normalized.filter((row) => row.is_default), ...normalized.filter((row) => !row.is_default)];
+}
+
+/**
+ * The store's default language — the one served at the root. Falls back to
+ * the primary, then the first row, then English for an empty list.
+ */
+export function defaultStoreLocale(locales: readonly StoreLocale[]): StoreLocale {
+  return (
+    locales.find((locale) => locale.is_default) ??
+    locales.find((locale) => locale.is_primary) ??
+    locales[0] ?? {
+      locale: FALLBACK_LOCALE_CODE,
+      name: 'English',
+      native_name: 'English',
+      is_primary: true,
+      is_default: true,
+      path_prefix: '',
+      hreflang: FALLBACK_LOCALE_CODE,
+      html_lang: FALLBACK_LOCALE_CODE,
+      dir: 'ltr',
+    }
+  );
+}
+
+/**
+ * The language a request renders in. `localeCode` is the request locale the
+ * provider holds (`null` on the default language). An unknown code resolves
+ * to the default — never an error.
+ */
+export function resolveActiveLocale(locales: readonly StoreLocale[], localeCode: string | null | undefined): StoreLocale {
+  if (localeCode) {
+    const code = localeCode.toLowerCase();
+    const match = locales.find((locale) => locale.locale.toLowerCase() === code);
+    if (match) return match;
+  }
+  return defaultStoreLocale(locales);
+}
+
+/** `/a/b` starts with segment path `/a` (whole segments only). */
+function hasSegmentPrefix(path: string, prefix: string): boolean {
+  return path === prefix || path.startsWith(`${prefix}/`);
+}
+
+function hasSegmentSuffix(path: string, segment: string): boolean {
+  return path === `/${segment}` || path.endsWith(`/${segment}`);
+}
+
+function withMark(value: string | undefined, mark: '?' | '#'): string {
+  if (!value || value === mark) return '';
+  return value.startsWith(mark) ? value : `${mark}${value}`;
+}
+
+export interface LocaleHrefInput {
+  /** The current path as the browser shows it, e.g. `/store/fr/shop`. */
+  pathname: string;
+  /** Query string, with or without the leading `?`. Kept as is. */
+  search?: string;
+  /** Hash, with or without the leading `#`. Kept as is. */
+  hash?: string;
+  /** The provider's `basePath` (already carries the active language prefix). */
+  basePath?: string;
+  /** The language the page renders in now. */
+  active: StoreLocale;
+  /** The language to switch to. */
+  target: StoreLocale;
+}
+
+/**
+ * The same page in another language: the path moves under the target's
+ * prefix (or to the root for the default language), the query string and
+ * hash are kept, and a trailing slash is kept.
+ *
+ * Only the ACTIVE prefix is removed from the current path, and only as a
+ * whole segment — `/french-press` is a page, not the `fr` language.
+ */
+export function localeHref({ pathname, search, hash, basePath = '', active, target }: LocaleHrefInput): string {
+  const activePrefix = active.path_prefix.toLowerCase();
+  const current = pathname || '/';
+  const lowerBase = basePath.toLowerCase();
+
+  let vendorBase = basePath;
+  let bare = current;
+
+  if (activePrefix && hasSegmentSuffix(lowerBase, activePrefix)) {
+    // `basePath` is the localized one: removing it removes the language too.
+    vendorBase = basePath.slice(0, basePath.length - activePrefix.length - 1);
+    if (hasSegmentPrefix(current.toLowerCase(), lowerBase)) bare = current.slice(basePath.length) || '/';
+  } else {
+    if (basePath && hasSegmentPrefix(current, basePath)) bare = current.slice(basePath.length) || '/';
+    if (activePrefix && hasSegmentPrefix(bare.toLowerCase(), `/${activePrefix}`)) {
+      bare = bare.slice(activePrefix.length + 1) || '/';
+    }
+  }
+  if (!bare.startsWith('/')) bare = `/${bare}`;
+
+  const targetPrefix = target.is_default ? '' : target.path_prefix.toLowerCase() || target.locale.toLowerCase();
+  const rest = bare === '/' ? '' : bare;
+  const path = `${vendorBase}${targetPrefix ? `/${targetPrefix}` : ''}${rest}` || '/';
+
+  return `${path}${withMark(search, '?')}${withMark(hash, '#')}`;
+}

package/utils/locale.ts

@@ -1,10 +1,9 @@
 /**
- * Storefront locale transport — the kit side of the translations plan.
+ * Storefront locale transport.
  *
- * Contract (translations-core.md, decisions closed): the backend accepts
- * `?locale=<code>` on every customer-facing read and answers translated text
- * (unknown/unpublished locale → source text, no error). The storefront proxy
- * sets `x-queek-locale` on the incoming request for published NON-primary
+ * The API accepts `?locale=<code>` on every customer-facing read and answers
+ * translated text (unknown/unpublished locale → source text, no error). The
+ * storefront proxy sets `x-queek-locale` on the incoming request for published NON-primary
  * locales only — the header is ABSENT on the primary locale — and suffixes
  * revalidation tags as `<tag>:locale:<code>`.
  *
@@ -23,17 +22,17 @@
  * English display locale — the ONE Intl tag every English shopper sees dates,
  * numbers and money in. `en-NG`, not `en-GB`: both print dates identically
  * ("2 October 2026", "14 Feb 2026"), but only `en-NG` renders NGN with the
- * naira sign the stores already show (`₦12,500` vs `en-GB`'s `NGN 12,500` —
- * verified on Node 22, full ICU, 2/10/26). `DISPLAY_LOCALE` in
- * `utils/format.ts` aliases this, so the value lives in exactly one place.
+ * naira sign the stores already show (`₦12,500` vs `en-GB`'s `NGN 12,500`, on
+ * Node 22 with full ICU). `DISPLAY_LOCALE` in `utils/format.ts` aliases this, so
+ * the value lives in exactly one place.
  */
 export const ENGLISH_DISPLAY_LOCALE = 'en-NG';
 
 /**
  * THE single canonical mapping from a storefront locale code to the Intl
- * locale dates/numbers/relative time are formatted in (founder 2/10/26:
- * shopper's locale, English in the British/Nigerian style so English stores
- * do not change visibly — "2 October 2026", never US "October 2, 2026").
+ * locale dates/numbers/relative time are formatted in: the shopper's locale,
+ * with English in the British/Nigerian style ("2 October 2026", never US
+ * "October 2, 2026").
  *
  * - Missing/invalid/unknown-structure codes and EVERY English variant (`en`,
  *   `en-GB`, `en-NG`, `en-US`, …) become `ENGLISH_DISPLAY_LOCALE`. In