@usequeek/theme-kit 0.1.21 → 0.1.23

package/sdk/client.ts

@@ -5,8 +5,9 @@ import { getActivePlatform } from './platform';
 export const API_BASE_URL = process.env.QUEEK_API_URL ?? process.env.NEXT_PUBLIC_QUEEK_API_URL ?? 'http://127.0.0.1:8000/api/v1';
 // BROWSER-side only (createBrowserClient below, "for client components/hooks").
 // Hardcoded relative on purpose, same reasoning as queek-client.ts's
-// API_BASE_URL: next.config.ts's rewrite already proxies /api/v1/client/:path*
-// to the backend server-side, so the browser never needs the real host. This
+// API_BASE_URL: the host app's `next.config` rewrite already proxies
+// /api/v1/client/:path* to the API server-side, so the browser never needs the
+// real host. This
 // used to read NEXT_PUBLIC_QUEEK_API_URL directly — when that's set to the
 // same absolute value as the server-side QUEEK_API_URL, every hook built on
 // createBrowserClient (products, shop, categories, reviews, related products,
@@ -35,7 +36,7 @@ export interface RequestCachePolicy {
  * eventually releases, not to enforce an SLA on a shopper's mobile connection.
  *
  * A write gets far more room than a read, and `request()` NEVER retries: an
- * aborted POST may already have reached the backend, so re-sending it could
+ * aborted POST may already have reached the API, so re-sending it could
  * duplicate an order or a payment.
  */
 const BROWSER_GET_TIMEOUT_MS = 15_000;
@@ -44,8 +45,8 @@ const BROWSER_POST_TIMEOUT_MS = 25_000;
 /**
  * Carries the HTTP status so callers can tell a genuine "this does not exist"
  * (404) apart from an infrastructure failure (5xx, timeout, network). That
- * distinction is load-bearing in `app/[vendor]/layout.tsx`: 404 must render
- * not-found, while a backend blip must NOT — a 404 on every URL of a live store
+ * distinction is load-bearing in a host's vendor layout: 404 must render
+ * not-found, while an API blip must NOT — a 404 on every URL of a live store
  * is how storefronts get deindexed.
  */
 export class ApiRequestError extends Error {
@@ -85,7 +86,7 @@ export class ApiTimeoutError extends Error {
  * For fetchers whose caller renders not-found on a null result.
  *
  * Returns null ONLY for a real 404 and rethrows everything else. A bare
- * `catch { return null }` there turns a backend timeout or 5xx into a 404 for a
+ * `catch { return null }` there turns an API timeout or 5xx into a 404 for a
  * product/page that exists — which is what deindexes a store's highest-value
  * URLs during a blip, and became far more likely once SSR fetches gained an
  * abort budget.
@@ -114,7 +115,7 @@ function withQuery(path: string, query?: RequestOptions['query']): string {
       continue;
     }
 
-    // Laravel's query parser only builds a real array from bracket notation
+    // The API's query parser only builds a real array from bracket notation
     // (`key[]=a&key[]=b`) — a plain comma-joined `key=a,b` (URLSearchParams'
     // default for an array via String()) arrives server-side as a single
     // string, failing an `array` validation rule outright.
@@ -134,11 +135,11 @@ function withQuery(path: string, query?: RequestOptions['query']): string {
 }
 
 export async function request<T>(baseUrl: string, path: string, options: RequestOptions & { credentials?: RequestCredentials } = {}, extraHeaders?: Record<string, string>): Promise<T> {
-  // HARD RULE: the storefront only ever calls the `/v1/client/*` scope. That scope's
-  // ResolveClientContext middleware resolves the vendor AND forces the platform
-  // (storefront/instore_qr), so prices are always the storefront's (no marketplace
-  // commission). Legacy v1 routes (/products, /vendors/*, /categories) bypass that
-  // middleware → wrong platform → wrong price. Never call them from here.
+  // HARD RULE: the storefront only ever calls the `/v1/client/*` scope. That scope
+  // resolves the vendor AND forces the platform (storefront/instore_qr), so prices
+  // are always the storefront's (no marketplace commission). Legacy v1 routes
+  // (/products, /vendors/*, /categories) skip that resolution → wrong platform →
+  // wrong price. Never call them from here.
   if (!path.startsWith('/client/')) {
     throw new Error(`Storefront may only call /v1/client/* routes — got "${path}". Use createServerStoreClient / createBrowserClient (which prefix /client/store).`);
   }

package/sdk/error-handler.ts

@@ -7,7 +7,7 @@ import { isReauthSuppressed } from './reauth-guard';
 
 /**
  * Returns true if the caught error is an unauthenticated (401) error
- * from the backend or SDK token layer.
+ * from the API or SDK token layer.
  */
 export function isUnauthenticatedError(err: unknown): boolean {
   if (err instanceof QueekSdkError) {

package/sdk/platform.ts

@@ -2,7 +2,7 @@
  * Active API platform holder.
  *
  * Every API request the storefront makes carries an `X-Platform` header so the
- * backend can resolve the right config + fees. Most of the site runs on the
+ * API can resolve the right config + fees. Most of the site runs on the
  * `storefront` channel; the in-core QR ordering page (`/qr`) runs on `instore_qr`.
  *
  * The two client factories (`createBrowserClient`, `getQueekClient`) and the
@@ -18,8 +18,8 @@
  * `server-store-client`'s `X-Platform` header non-deterministic.
  *
  * SSR therefore always reads `storefront`, which is correct: server-side fetches
- * only ever load storefront-channel content, and the backend's
- * ResolveClientContext re-derives and forces the platform regardless.
+ * only ever load storefront-channel content, and the API re-derives and forces
+ * the platform regardless.
  */
 export type Platform = 'storefront' | 'instore_qr';
 
@@ -46,11 +46,9 @@ export function setActivePlatform(platform: Platform): void {
  * simply invisible to `/qr` and vice versa — no in-memory state to keep in
  * sync, no risk of one flow reading the other's leftovers.
  *
- * This is what a stale, non-QR `deliveryMode` (e.g. "pickup", picked earlier
- * on the ordinary storefront) reaching a `/qr` dine-in checkout and getting
- * its packaging wrongly enforced would have been caught by (production
- * incident 30/8/26 — Kili Foods "Nkwobi"; see DeliveryModePicker's own fix
- * for that specific symptom). Apply this to every persisted store/key a `/qr`
+ * Without it, a stale non-QR `deliveryMode` (e.g. "pickup", picked earlier on
+ * the ordinary storefront) could reach a `/qr` dine-in checkout and have its
+ * packaging wrongly enforced. Apply this to every persisted store/key a `/qr`
  * flow touches EXCEPT auth (`queek-storefront-user`, the access/refresh
  * tokens in `queek-client.ts`) — a signed-in customer must stay signed in
  * across both.

package/sdk/queek-client.ts

@@ -5,13 +5,13 @@ import { triggerReauth } from './error-handler';
 import { getActivePlatform } from './platform';
 
 // This file is 'use client' — every export here only ever runs in the browser.
-// ALWAYS same-origin-relative, on purpose: next.config.ts's rewrite already
-// proxies /api/v1/client/:path* to the real backend server-side, so the
-// browser never needs (or should have) the backend's actual host. Reading
+// ALWAYS same-origin-relative, on purpose: the host app's `next.config` rewrite
+// already proxies /api/v1/client/:path* to the real API server-side, so the
+// browser never needs (or should have) the API's actual host. Reading
 // NEXT_PUBLIC_QUEEK_API_URL here would let a misconfigured env var (e.g. the
 // same absolute value used for the SERVER-side QUEEK_API_URL) leak
-// api.usequeek.com straight into every client-side request — confirmed live,
-// visible in the browser Network tab for autocomplete/resolve/fees/couriers/
+// api.usequeek.com straight into every client-side request, visible in the
+// browser Network tab for autocomplete/resolve/fees/couriers/
 // addresses. No such var read = structurally impossible to leak it from here.
 export const API_BASE_URL = '/api/v1';
 export const QUEEK_AUTH_URL = process.env.NEXT_PUBLIC_QUEEK_AUTH_URL ?? 'https://auth.usequeek.com';
@@ -45,12 +45,11 @@ const platformFetch: typeof fetch = (input, init) => {
 };
 
 /**
- * Every API response carries a backend request id. The SDK's `request()` returns
- * only the parsed body, so this wrapper — the one place every SDK call's raw
- * Response passes through — is where it can be read at all. Kept as the last-seen
- * value: the storefront has no error-reporting integration (no Sentry), so the
- * only consumer today is the checkout failure log, which is exactly the report a
- * customer support ticket needs to be traceable to a backend request.
+ * Every API response carries a request id. The SDK's `request()` returns only
+ * the parsed body, so this wrapper — the one place every SDK call's raw Response
+ * passes through — is where it can be read at all. Kept as the last-seen value:
+ * the only consumer is the checkout failure log, which is exactly the report a
+ * customer support ticket needs to be traceable to an API request.
  */
 const REQUEST_ID_HEADERS = ['x-request-id', 'x-correlation-id', 'request-id'];
 
@@ -68,7 +67,7 @@ function captureRequestId(response: Response): Response {
   return response;
 }
 
-/** The backend request id of the most recent SDK call, when it sent one. */
+/** The API request id of the most recent SDK call, when it sent one. */
 export function getLastRequestId(): string | null {
   return lastRequestId;
 }

package/sdk/server-store-client.ts

@@ -5,7 +5,7 @@ import { API_BASE_URL, request, type RequestCachePolicy, type RequestOptions } f
 import { getActivePlatform } from './platform';
 
 /**
- * Origin of the incoming storefront request, forwarded to the backend so it
+ * Origin of the incoming storefront request, forwarded to the API so it
  * resolves the vendor exactly as it does for a real browser request (subdomain,
  * apex/path and custom-domain storefronts all work with zero configuration).
  *
@@ -26,9 +26,7 @@ export async function getRequestOrigin(): Promise<string | undefined> {
  * for the subdomain-vs-path `basePath` resolution (subdomain/custom-domain
  * storefronts serve at the bare origin; path-based access serves under
  * `/vendor-slug`). Every canonical URL, sitemap entry, and JSON-LD `url` field
- * must derive from this instead of re-deriving `basePath` inline — see
- * `app/[vendor]/layout.tsx` and `app/[vendor]/products/[slug]/page.tsx`, which
- * used to duplicate this logic before it was extracted here.
+ * must derive from this instead of re-deriving `basePath` inline.
  */
 export async function resolveStoreBaseUrl(vendor: string): Promise<string | null> {
   const origin = await getRequestOrigin();
@@ -56,7 +54,7 @@ export async function resolveStoreBaseUrl(vendor: string): Promise<string | null
  * Abort budget for SSR reads. Sized above the observed p99 of the slowest
  * bootstrap call (`/theme`, ~4.4s) with headroom, so it never fails a legitimate
  * slow response — its job is to stop in-flight renders accumulating without
- * bound when the backend hangs, not to enforce an SLA.
+ * bound when the API hangs, not to enforce an SLA.
  */
 const SSR_TIMEOUT_MS = 8_000;
 
@@ -70,7 +68,7 @@ const SSR_TIMEOUT_MS = 8_000;
  *
  * Tags are per vendor so one store's edit never flushes another's. The TTL is a
  * safety net, not the primary mechanism — `POST /api/revalidate?tag=…` from the
- * backend is what makes an edit show up immediately.
+ * API is what makes an edit show up immediately.
  */
 function resolveCachePolicy(vendorSlug: string, path: string): RequestCachePolicy | null {
   const vendor = `v:${vendorSlug}`;
@@ -80,15 +78,13 @@ function resolveCachePolicy(vendorSlug: string, path: string): RequestCachePolic
   });
 
   // `/config` is deliberately NOT here: nothing fetches it server-side today, and
-  // its response varies by platform (VendorConfigRequest), so allowlisting it
+  // its response varies by platform, so allowlisting it
   // would let a future SSR caller that omits `platform` collapse two platforms
   // onto one cached entry.
   if (path === '/info') return policy(300, 'profile');
-  // Combines /theme + /menus + /pages-chrome into one backend round trip (see
-  // StoreContentController::bootstrapForClient). Tagged with all three resource
-  // suffixes so a merchant edit to any one of them busts this entry — the
-  // existing observers (MenuObserver, PostObserver, VendorConfigObserver)
-  // already emit exactly these suffixes, no backend change needed.
+  // Combines /theme + /menus + /pages-chrome into one API round trip. Tagged
+  // with all three resource suffixes so a merchant edit to any one of them busts
+  // this entry.
   if (path === '/bootstrap') return { revalidate: 300, tags: [vendor, `${vendor}:theme`, `${vendor}:menus`, `${vendor}:pages`] };
   if (path === '/blog-categories') return policy(300, 'posts');
   if (/^\/pages(\/[^/]+)?$/.test(path)) return policy(300, 'pages');
@@ -99,7 +95,7 @@ function resolveCachePolicy(vendorSlug: string, path: string): RequestCachePolic
   if (/^\/collections(\/[^/]+\/products)?$/.test(path)) return policy(300, 'collections');
 
   // Shorter, because price and stock live here: a stale card that a shopper then
-  // cannot buy at the shown price is a trust problem, even though the backend
+  // cannot buy at the shown price is a trust problem, even though the API
   // recomputes both at order time.
   if (path === '/products') return policy(60, 'products');
 
@@ -127,14 +123,14 @@ function resolveCachePolicy(vendorSlug: string, path: string): RequestCachePolic
  * storefront with `?preview=true&id=<vendorId>`. Set by `proxy.ts`, which is the only
  * place that can see query params before the fetch layer runs.
  *
- * A preview render MUST bypass the cache outright rather than rely on the backend's
+ * A preview render MUST bypass the cache outright rather than rely on the API's
  * invalidation call. Invalidation is a distributed handshake — it needs two env vars
- * to match across two repos and a live HTTP round trip — and when any part of that
+ * to match across two services and a live HTTP round trip — and when any part of that
  * is wrong it fails SILENTLY, leaving a merchant staring at an unchanged store for
  * the full TTL. The editor is the one surface where "eventually" is not acceptable,
  * and it already knows it is the editor, so it should not have to ask anyone.
  *
- * The backend still flushes tags on save; that is what keeps the PUBLIC store fresh.
+ * The API still flushes tags on save; that is what keeps the PUBLIC store fresh.
  * This just removes the editor's dependence on it.
  */
 async function isPreviewRender(): Promise<boolean> {
@@ -147,7 +143,7 @@ async function isPreviewRender(): Promise<boolean> {
  * Validated locale of the incoming storefront request, or null for the
  * primary rendering. The proxy sets `x-queek-locale` for published
  * non-primary locales ONLY (absent on the primary); anything else is
- * ignored, mirroring the backend's unknown-locale → source-text rule.
+ * ignored, mirroring the API's unknown-locale → source-text rule.
  *
  * THE single header-parsing site — every server fetcher resolves its locale
  * through here (directly or via `resolveRequestLocale`), never by reading

package/shared-blocks/metaobjects.tsx

@@ -15,7 +15,7 @@ export interface CoreMetaobjectsBlockProps extends MetaobjectsResolved {
  * `EntryCard` a product's linked-entry metafields render. Renders nothing
  * when the type is unknown, hidden, or has no active entries (the server
  * seeds `entries: []` for all three cases — see `hydrateProductBlocks` in
- * the storefront). Each card links to `/{type}/{handle}` only when the
+ * the host app). Each card links to `/{type}/{handle}` only when the
  * definition opted into entry pages (`has_pages`); otherwise it's inert.
  */
 export function CoreMetaobjectsBlock({

package/stores/cart-store.ts

@@ -59,8 +59,8 @@ export const useCartStore = create<CartState>()(
       },
       addItemWithAddons: (product, quantity = 1, addons = [], variant = null) => {
         // A variant-enabled product has no valid "no selection" line: the cart
-        // save fails server-side (DiscountService's VariantSelectionException),
-        // so persisting one only moves the failure to checkout. Themes gate
+        // save fails server-side, so persisting one only moves the failure to
+        // checkout. Themes gate
         // their add button too, but a theme is presentation — correctness
         // cannot depend on all seven, or on the next one, getting it right.
         if (!variant && productRequiresVariant(product)) {

package/stores/checkout-store.ts

@@ -66,7 +66,7 @@ interface CheckoutState {
   isEditingAddress: boolean;
   /** The customer's saved address (CustomerAddress uuid) currently selected for
    *  delivery, when they picked one from their address book instead of
-   *  searching a fresh address. Lets the backend reuse the cached courier
+   *  searching a fresh address. Lets the API reuse the cached courier
    *  geocode. Null whenever the address came from a fresh Google search. */
   savedAddressId: string | null;
 

package/stores/edit-preview-store.ts

@@ -21,15 +21,14 @@ interface EditPreviewState {
  * Draft page content streamed live from the merchant editor, so a section edit
  * renders immediately instead of waiting for a network round trip.
  *
- * Before this, every field change took the long way: 900ms debounce → PUT the
- * draft → postMessage 'refresh' → router.refresh() → RSC fetch → backend
- * render, and the preview showed the OLD content the whole time. The merchant
+ * Without it, every field change would take the long way: 900ms debounce → PUT
+ * the draft → postMessage 'refresh' → router.refresh() → RSC fetch → API render,
+ * and the preview would show the OLD content the whole time. The merchant
  * already holds the edited section in its own state; sending it costs nothing
  * and removes both network hops from the interactive path.
  *
- * Design tokens have worked this way all along (design-token-preview.tsx) — this
- * is the same idea applied to section content, which is the thing merchants
- * actually spend their time editing.
+ * Design tokens work the same way (design-token-preview.tsx) — this applies the
+ * idea to section content, which is what merchants spend their time editing.
  *
  * The server stays authoritative: PageRenderer drops this override the moment a
  * fresh server payload arrives, so the debounced save still reconciles and a

package/stores/user-store.ts

@@ -11,7 +11,7 @@ export interface StorefrontUser {
   email: string | null;
   phone: string;
   avatar: string | null;
-  /** Backend flag: false for social/email signups that still lack a real phone. */
+  /** API flag: false for social/email signups that still lack a real phone. */
   profile_complete?: boolean;
   delivery_info?: {
     map_lat: number;
@@ -22,10 +22,9 @@ export interface StorefrontUser {
 
 /**
  * A signed-in customer whose account is missing the details we require to
- * fulfil an order. The backend's `profile_complete` is itself derived purely
- * from phone+name presence (`ClientAuthUserResource`: `phone !== null && name
- * !== ''`), so both it and the raw `!user.phone` check are gated by
- * `requiresPhone` together — there's no case where one applies without the
+ * fulfil an order. The API's `profile_complete` is itself derived purely from
+ * phone+name presence (`phone !== null && name !== ''`), so both it and the raw
+ * `!user.phone` check are gated by `requiresPhone` together — there's no case where one applies without the
  * other.
  *
  * `requiresPhone` — defaults true (delivery/pickup orders need a real number

package/strings/pseudo-locale.ts

@@ -1,8 +1,8 @@
 /**
- * Pseudo-locale QA (slice: typed keys + pseudo-locale QA helper).
+ * Pseudo-locale QA helper.
  *
  * PURE AND SERVER-SAFE: this module imports nothing from `next/*` and nothing
- * from React, so server components, Node tooling (theme-check), tests and the
+ * from React, so server components, Node tooling (such as the theme check), tests and the
  * browser all share it (precedent: `utils/locale.ts`, `strings/theme-strings.ts`).
  * Keep it that way.
  *
@@ -19,8 +19,7 @@
  *    (un-wrapped) string. Never ship pseudo to shoppers.
  *  - Tests: render a component with the pseudo dictionary, then run the
  *    English-leak scan (`findEnglishLeaks` / `assertNoEnglishLeak`) over the
- *    HTML. That scan is the reusable primitive theme tests (and the
- *    storefront, and theme-tools) import.
+ *    HTML. That scan is the reusable primitive theme tests import.
  *
  * English safety: this module never changes an English value — pseudo
  * dictionaries are built on demand in dev/test and never enter a bundle.

package/strings/theme-strings.ts

@@ -1,12 +1,13 @@
 /**
- * Theme strings — the kit's Shopify-shaped UI-string mechanism (slice K0).
+ * Theme strings — the kit's UI-string mechanism: dotted keys, `{var}`
+ * interpolation, CLDR plurals and per-locale dictionaries.
  *
  * PURE AND SERVER-SAFE: this module imports nothing from `next/*` and nothing
  * from React, so server components, Node tooling and the browser all share it
  * (precedent: `utils/locale.ts`). Keep it that way — `tests/theme-strings*`
  * fails a build that adds either import here.
  *
- * Two surfaces (plan decision 4):
+ * Two surfaces:
  *  - Server: `createThemeStrings({ locale, loaders })` returns a bound `t`
  *    that a server component receives via props/closure. NO provider in the
  *    tree. The host supplies the loaders (per-locale dynamic imports) so the
@@ -15,15 +16,16 @@
  *    `useThemeStrings()` returns the same bound `t`. Absent prop = English
  *    defaults, byte-identical to the old hardcoded literals.
  *
- * Fallback (plan decision 3): the caller supplies an ordered list of
+ * Fallback: the caller supplies an ordered list of
  * dictionaries (merchant override, theme locale, kit core locale) and `t`
  * returns the FIRST hit. The LAST entry is always the English default value —
  * never the raw dotted key, never "translation missing". A key absent
  * everywhere returns `''` (and warns once per key in development only).
  *
  * Key budget: dotted lowercase `scope.thing.state`, total length <= 40 chars.
- * The backend overlay stores `<theme-slug>.<key>` in a varchar(64), so 40 for
- * the key leaves 23 for the slug plus the dot separator. Values <= 1000 chars.
+ * Merchant overrides are stored as `<theme-slug>.<key>` in a 64-character
+ * field, so 40 for the key leaves 23 for the slug plus the dot separator.
+ * Values <= 1000 chars.
  */
 
 import {
@@ -84,11 +86,11 @@ const PLURAL_FORMS = ['one', 'two', 'few', 'many', 'other'] as const;
  * US-order Intl tag (`February 15, 2026`). NEVER pass its result to
  * `Intl.DateTimeFormat` / `Intl.NumberFormat` / `Intl.RelativeTimeFormat`,
  * `toLocale*`, or any date/number/money/relative-time formatter — that would
- * reintroduce the US-order defect the founder banned for English stores.
+ * reintroduce US date order (`February 15, 2026`) for English stores.
  * Formatters must route through `resolveIntlLocale` (en* → en-NG) instead.
  *
  * Unknown/unparseable codes become English, mirroring `parseLocaleCode` (and
- * the backend's unknown-locale rule). A well-formed code the runtime's ICU
+ * the API's unknown-locale rule). A well-formed code the runtime's ICU
  * does not know also becomes English, so plural selection never silently
  * follows the wrong language.
  */

package/tests/auth-email-errors.test.tsx

@@ -1,10 +1,10 @@
 /**
- * Auth error English pins (checkout / auth slice) — S4 drift guard.
+ * Auth error English pins.
  *
  * `mapEmailError` maps SDK failure codes to `t('auth.error.*')` strings, and
  * three more error keys are set directly in the provider. Every English value
  * below is resolved through the REAL default dictionary, so renaming a key or
- * changing any English value fails here. S7 proof included.
+ * changing any English value fails here.
  */
 import { describe, expect, it } from 'vitest';
 import { QueekSdkError } from '@queekai/client-sdk';

package/tests/currency-contract.test.ts

@@ -6,13 +6,12 @@ import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
 import { useCartStore } from '../stores/cart-store';
 
 /**
- * Slice 2 of api-currency-contract-fix: client readers off `meta.currency`.
- * List-level `meta.currency` stamps the PLATFORM default (NGN) even on
+ * Client readers do not use `meta.currency`. List-level `meta.currency` stamps the PLATFORM default (NGN) even on
  * non-NGN stores, so the item's own `currency` code is the source and the
  * vendor's currency is the store-wide source. Missing codes fall back to the
  * platform default as a LAST resort, in exactly one place.
  */
-describe('currency contract (Slice 2)', () => {
+describe('currency resolution', () => {
   it('exposes NGN as the platform default last resort', () => {
     expect(PLATFORM_DEFAULT_CURRENCY).toBe('NGN');
   });

package/tests/display-format.test.ts

@@ -25,9 +25,9 @@ describe('display formatting is the same on the server and in the browser', () =
     // browser (Lagos) used to print different days for this review.
     expect(formatDisplayDate('2026-02-14T23:30:00Z')).toBe('15 Feb 2026');
     expect(formatDisplayDate('2026-02-14', {})).toBe('14/02/2026');
-    // Founder 2/10/26: English is British/Nigerian order, never US order — the
-    // locale parameter is routed through resolveIntlLocale, so even an explicit
-    // 'en'/'en-US' renders "15 February 2026" (was "February 15, 2026" before).
+    // English is British/Nigerian order, never US order — the locale parameter
+    // is routed through resolveIntlLocale, so even an explicit 'en'/'en-US'
+    // renders "15 February 2026", not "February 15, 2026".
     expect(formatDisplayDate('2026-02-14T23:30:00Z', { year: 'numeric', month: 'long', day: 'numeric' }, 'en-US')).toBe('15 February 2026');
     expect(formatDisplayDate('2026-02-14T23:30:00Z', { year: 'numeric', month: 'long', day: 'numeric' }, 'en')).toBe('15 February 2026');
     expect(formatDisplayDate('not a date')).toBe('');
@@ -55,9 +55,8 @@ describe('display formatting is the same on the server and in the browser', () =
 });
 
 /**
- * Founder 2/10/26: dates and numbers follow the SHOPPER's locale, with
- * English in the British/Nigerian style so English stores do not change
- * visibly ("2 October 2026", never US "October 2, 2026").
+ * Dates and numbers follow the SHOPPER's locale, with English in the
+ * British/Nigerian style ("2 October 2026", never US "October 2, 2026").
  */
 describe('canonical locale mapping (shopper locale -> Intl locale)', () => {
   const LONG_LAGOS = { year: 'numeric', month: 'long', day: 'numeric', timeZone: 'Africa/Lagos' } as const;
@@ -147,7 +146,7 @@ describe('shopper locales format through real Intl output', () => {
     }
   };
 
-  // Observed on Node 22 (full ICU) 2/10/26; each row falls back to the
+  // Expected output on Node 22 with full ICU; each row falls back to the
   // English style when the runtime's ICU lacks the locale.
   it.each([
     ['fr', '15 février 2026'],
@@ -319,15 +318,11 @@ describe("no exported formatter lets an 'en*' tag reach Intl unmapped", () => {
   });
 });
 
-describe('English money before/after (S7 table, measured on old vs new code)', () => {
-  // BEFORE (f7ee395, scratch worktree run): formatMoney was hardcoded 'en-NG';
-  // formatThemeMoney used bare 'en' via canonicalThemeLocale. AFTER: both use
-  // en-NG. Decision: en-NG ('US$') wins because live English stores already
-  // render formatMoney — the only money helper any theme imports (atelier
-  // blocks/components import it; ZERO themes import formatThemeMoney, so the
-  // old bare-'en' '$5,000.00' never reached a live store). GBP/EUR symbols are
-  // identical under 'en' vs 'en-NG'; only the helper decimal contract differs
-  // (formatMoney: decimals only when present; formatThemeMoney: K0 2-decimals).
+describe('English money output', () => {
+  // formatMoney and formatThemeMoney both render English through en-NG, so USD
+  // prints 'US$'. GBP/EUR symbols are identical under 'en' and 'en-NG'; the
+  // helpers differ only in decimals (formatMoney: decimals only when present;
+  // formatThemeMoney: always the currency's default decimals).
   it.each([
     ['NGN', '₦5,000', '₦5,000.00'],
     ['USD', 'US$5,000', 'US$5,000.00'],
@@ -346,15 +341,12 @@ describe('English money before/after (S7 table, measured on old vs new code)', (
   });
 });
 
-describe('malformed currency before/after (normalize-then-format is intended)', () => {
-  // BEFORE (f7ee395): formatMoney passed the raw value to Intl — an invalid
-  // code threw RangeError internally and the fallback echoed the RAW token
-  // (' ngn  5,000', 'null 5,000'). AFTER: normalizeCurrencyCode runs first, so
-  // fixable/invalid codes resolve to the platform default instead of echoing
-  // raw input into shopper-facing money. Already-valid inputs are unchanged:
-  // 'usd' (Intl is case-insensitive) and 'XXX' (real ISO 4217 code) render
-  // byte-identical to before. formatThemeMoney already normalized at base —
-  // its malformed handling is untouched by this slice.
+describe('malformed currency (normalize-then-format)', () => {
+  // normalizeCurrencyCode runs first, so fixable/invalid codes resolve to the
+  // platform default instead of echoing raw input (' ngn  5,000', 'null 5,000')
+  // into shopper-facing money. Already-valid inputs render as Intl prints them:
+  // 'usd' (Intl is case-insensitive) and 'XXX' (a real ISO 4217 code).
+  // formatThemeMoney normalizes at its base as well.
   it.each([
     ['usd', 'US$5,000'],
     [' ngn ', '₦5,000'],

package/tests/fixtures/external-theme.tsx

@@ -1,5 +1,5 @@
 // A real theme, written the way an external developer would, against the
-// PUBLISHED package only — no access to the storefront repo.
+// PUBLISHED package only — no access to any host app.
 import type { JSX } from 'react';
 import type { ThemeModule, HeaderProps, FooterProps } from '@usequeek/theme-kit/types/theme';
 import type { Product } from '@usequeek/theme-kit/types/product';
@@ -9,6 +9,9 @@ import { useStorefront } from '@usequeek/theme-kit/provider';
 import { useHref } from '@usequeek/theme-kit/hooks/use-href';
 import { formatMoney } from '@usequeek/theme-kit/utils/format';
 import { Image } from '@usequeek/theme-kit/components/image';
+import { LanguageSwitcher } from '@usequeek/theme-kit/components/language-switcher';
+import { useLocales } from '@usequeek/theme-kit/hooks/use-locales';
+import type { StoreLocale } from '@usequeek/theme-kit/utils/locale-switch';
 import { ThemeMount } from '@usequeek/theme-kit/theme-mount';
 
 export function Header({ menu, showCart }: HeaderProps): JSX.Element {
@@ -21,12 +24,30 @@ export function Header({ menu, showCart }: HeaderProps): JSX.Element {
       <a href={href('/')}>{vendor?.name}</a>
       {menu.map((item) => <a key={item.label} href={item.ref ?? '#'}>{item.label}</a>)}
       {showCart ? <span>{items.length}</span> : null}
+      <LanguageSwitcher className="header-language" />
     </header>
   );
 }
 
 export function Footer({ copyright }: FooterProps): JSX.Element {
-  return <footer>{copyright}</footer>;
+  const { hasMultiple, locales, hrefFor } = useLocales();
+  const label = (l: StoreLocale): string => l.native_name;
+
+  return (
+    <footer>
+      {copyright}
+      <LanguageSwitcher variant="inline-list" showCode />
+      <LanguageSwitcher variant="menu" side="top" align="start" showCode />
+      <LanguageSwitcher variant="menu">
+        {({ active, displayName, open, setOpen }) => (
+          <button type="button" aria-expanded={open} onClick={() => setOpen(!open)}>
+            {displayName(active)}
+          </button>
+        )}
+      </LanguageSwitcher>
+      {hasMultiple ? locales.map((l) => <a key={l.locale} href={hrefFor(l)}>{label(l)}</a>) : null}
+    </footer>
+  );
 }
 
 export function ProductCard({ product }: { product: Product }): JSX.Element {