@usequeek/theme-kit 0.1.20 → 0.1.22

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,17 +4,22 @@
  * 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`
  * shows decimals only when the amount genuinely has them — ₦5,000 stays
  * ₦5,000, ₦0.28 now correctly shows as ₦0.28.
  */
+import {
+  ENGLISH_DISPLAY_LOCALE,
+  resolveIntlLocale,
+  resolveSupportedLocale,
+} from './locale';
+
 /**
  * The locale and zone every date/number the kit DISPLAYS is formatted in.
  * Fixed on purpose: storefront pages render on the server first, and a runtime
@@ -22,11 +27,32 @@
  * browser (Africa/Lagos, en-NG/en-GB) — "Feb 14, 2026" vs "14 Feb 2026". React
  * then fails hydration and re-renders the whole page on the client. Queek's
  * stores and shoppers are Nigerian, so that is the one answer both sides give.
+ *
+ * Aliases `ENGLISH_DISPLAY_LOCALE` (`utils/locale.ts`) — the value lives in
+ * exactly one place. `resolveIntlLocale` maps every English storefront code
+ * here, so English output is byte-identical with or without a locale.
  */
-export const DISPLAY_LOCALE = 'en-NG';
+export const DISPLAY_LOCALE: string = ENGLISH_DISPLAY_LOCALE;
 export const DISPLAY_TIME_ZONE = 'Africa/Lagos';
 
-/** A date for display (default "14 Feb 2026"), identical on server and browser. '' if unparseable. */
+/**
+ * Pick the Intl tag for one formatting call: the storefront locale through
+ * the canonical mapping, or English when the runtime's ICU lacks the locale.
+ * Never throws.
+ */
+function displayTagFor(
+  locale: string | null | undefined,
+  supportedLocalesOf: (locales: string[]) => readonly string[],
+): string {
+  return resolveSupportedLocale(resolveIntlLocale(locale), supportedLocalesOf);
+}
+
+/**
+ * A date for display (default "14 Feb 2026"), identical on server and browser.
+ * '' if unparseable. The locale parameter is routed through the canonical
+ * 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(
   value: string | number | Date,
   options: Intl.DateTimeFormatOptions = { day: 'numeric', month: 'short', year: 'numeric' },
@@ -34,12 +60,66 @@ export function formatDisplayDate(
 ): string {
   const date = value instanceof Date ? value : new Date(value);
   if (Number.isNaN(date.getTime())) return '';
-  return date.toLocaleDateString(locale, { ...options, timeZone: DISPLAY_TIME_ZONE });
+  return date.toLocaleDateString(resolveIntlLocale(locale), {
+    ...options,
+    timeZone: DISPLAY_TIME_ZONE,
+  });
+}
+
+/**
+ * A date for display in the SHOPPER's locale: `formatDisplayDate` with the
+ * storefront locale (from `useStorefrontLocale()`) already resolved through
+ * the canonical mapping. English renders exactly as `formatDisplayDate`
+ * ("14 Feb 2026"); `fr` renders "14 févr. 2026", and so on. Time zone and
+ * invalid-date handling are `formatDisplayDate`'s. Never throws.
+ */
+export function formatShopperDate(
+  value: string | number | Date,
+  locale: string | null | undefined,
+  options: Intl.DateTimeFormatOptions = { day: 'numeric', month: 'short', year: 'numeric' },
+): string {
+  return formatDisplayDate(
+    value,
+    options,
+    displayTagFor(locale, (l) => Intl.DateTimeFormat.supportedLocalesOf(l)),
+  );
 }
 
 /** A count for display ("1,234"), identical on server and browser. */
-export function formatCount(value: number): string {
-  return value.toLocaleString(DISPLAY_LOCALE);
+export function formatCount(value: number, locale?: string | null): string {
+  const tag = displayTagFor(locale, (l) => Intl.NumberFormat.supportedLocalesOf(l));
+  try {
+    return value.toLocaleString(tag);
+  } catch {
+    return value.toLocaleString(DISPLAY_LOCALE);
+  }
+}
+
+/**
+ * Relative time for display ("yesterday", "il y a 3 jours") in the shopper's
+ * locale — `numeric: 'auto'` so whole days read as words where the language
+ * has them. Falls back to English on a missing ICU locale or a bad unit;
+ * never throws.
+ */
+export function formatRelativeTime(
+  value: number,
+  unit: Intl.RelativeTimeFormatUnit = 'day',
+  locale?: string | null,
+  options?: Intl.RelativeTimeFormatOptions,
+): string {
+  const tag = displayTagFor(locale, (l) => Intl.RelativeTimeFormat.supportedLocalesOf(l));
+  try {
+    return new Intl.RelativeTimeFormat(tag, { numeric: 'auto', ...options }).format(value, unit);
+  } catch {
+    try {
+      return new Intl.RelativeTimeFormat(DISPLAY_LOCALE, { numeric: 'auto', ...options }).format(
+        value,
+        unit,
+      );
+    } catch {
+      return `${value} ${unit}`;
+    }
+  }
 }
 
 /**
@@ -55,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() : '';
@@ -64,16 +144,22 @@ export function normalizeCurrencyCode(value: unknown, fallback: string = PLATFOR
   return /^[A-Z]{3}$/.test(cleanFallback) ? cleanFallback : PLATFORM_DEFAULT_CURRENCY;
 }
 
-export function formatMoney(amount: number, currency = PLATFORM_DEFAULT_CURRENCY): string {
+export function formatMoney(
+  amount: number,
+  currency = PLATFORM_DEFAULT_CURRENCY,
+  locale?: string | null,
+): string {
+  const code = normalizeCurrencyCode(currency);
+  const tag = displayTagFor(locale, (l) => Intl.NumberFormat.supportedLocalesOf(l));
   try {
-    return new Intl.NumberFormat('en-NG', {
+    return new Intl.NumberFormat(tag, {
       style: 'currency',
-      currency,
+      currency: code,
       minimumFractionDigits: 0,
       maximumFractionDigits: 2,
     }).format(amount);
   } catch {
-    return `${currency} ${amount.toLocaleString(DISPLAY_LOCALE)}`;
+    return `${code} ${amount.toLocaleString(DISPLAY_LOCALE)}`;
   }
 }
 

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, '#')}`;
+}