@usequeek/theme-kit 0.1.21 → 0.1.22

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,25 @@ 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>
+        {({ active, displayName }) => <span>{displayName(active)}</span>}
+      </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 {

package/tests/language-switcher.test.tsx

@@ -0,0 +1,350 @@
+// @vitest-environment jsdom
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { act, type ReactNode } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const nav = vi.hoisted(() => ({ pathname: '/', push: vi.fn() }));
+vi.mock('next/navigation', () => ({
+  usePathname: () => nav.pathname,
+  useRouter: () => ({ push: nav.push, replace: vi.fn(), back: vi.fn(), refresh: vi.fn() }),
+}));
+
+import { LanguageSwitcher } from '../components/language-switcher';
+import { useLocales, type LocalesState } from '../hooks/use-locales';
+import { StorefrontContext, StorefrontProvider } from '../provider';
+import type { ThemeManifest } from '../types/theme';
+import type { StoreLocaleInput } from '../utils/locale-switch';
+
+(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true;
+
+const LOCALES: StoreLocaleInput[] = [
+  { locale: 'en', name: 'English', native_name: 'English', is_primary: true, is_default: true, path_prefix: '', hreflang: 'en', html_lang: 'en', dir: 'ltr' },
+  { locale: 'fr', name: 'French', native_name: 'Français', is_primary: false, is_default: false, path_prefix: 'fr', hreflang: 'fr', html_lang: 'fr', dir: 'ltr' },
+  { locale: 'ar', name: 'Arabic', native_name: 'العربية', is_primary: false, is_default: false, path_prefix: 'ar', hreflang: 'ar', html_lang: 'ar', dir: 'rtl' },
+];
+
+interface ProviderOptions {
+  locales?: StoreLocaleInput[] | null;
+  locale?: string | null;
+  basePath?: string;
+  strings?: Record<string, unknown> | null;
+}
+
+function Provider({ options = {}, children }: { options?: ProviderOptions; children: ReactNode }) {
+  return (
+    <StorefrontProvider
+      vendor={{ id: 'v1', slug: 'acme', name: 'Acme' } as never}
+      config={{} as never}
+      menus={[]}
+      basePath={options.basePath ?? ''}
+      locale={options.locale ?? null}
+      {...(options.locales !== undefined ? { locales: options.locales } : {})}
+      {...(options.strings ? { strings: options.strings as never } : {})}
+    >
+      {children}
+    </StorefrontProvider>
+  );
+}
+
+let container: HTMLDivElement;
+let root: Root;
+
+function mount(node: ReactNode, options?: ProviderOptions): void {
+  act(() => {
+    root.render(<Provider options={options}>{node}</Provider>);
+  });
+}
+
+beforeEach(() => {
+  nav.pathname = '/shop';
+  nav.push.mockClear();
+  window.history.replaceState(null, '', '/shop');
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+});
+
+afterEach(() => {
+  act(() => root.unmount());
+  container.remove();
+});
+
+describe('useLocales', () => {
+  function capture(options?: ProviderOptions): { current: LocalesState } {
+    const ref = {} as { current: LocalesState };
+    function Probe() {
+      ref.current = useLocales();
+      return null;
+    }
+    mount(<Probe />, options);
+    return ref;
+  }
+
+  it('reports a single-language state when no locales are passed', () => {
+    const state = capture();
+    expect(state.current.hasMultiple).toBe(false);
+    expect(state.current.locales).toEqual([]);
+    expect(state.current.active.locale).toBe('en');
+    expect(state.current.defaultLocale.path_prefix).toBe('');
+  });
+
+  it('reports a single-language state for one locale', () => {
+    const state = capture({ locales: [LOCALES[0]!] });
+    expect(state.current.hasMultiple).toBe(false);
+    expect(state.current.locales).toHaveLength(1);
+  });
+
+  it('does not throw outside a provider', () => {
+    const ref = {} as { current: LocalesState };
+    function Probe() {
+      ref.current = useLocales();
+      return null;
+    }
+    act(() => root.render(<Probe />));
+    expect(ref.current.hasMultiple).toBe(false);
+  });
+
+  it('exposes locales, default and the active language from the request locale', () => {
+    const state = capture({ locales: LOCALES, locale: 'fr', basePath: '/fr' });
+    expect(state.current.hasMultiple).toBe(true);
+    expect(state.current.locales.map((l) => l.locale)).toEqual(['en', 'fr', 'ar']);
+    expect(state.current.defaultLocale.locale).toBe('en');
+    expect(state.current.active.locale).toBe('fr');
+  });
+
+  it('builds hrefFor from the pathname and picks up the query and hash after mount', () => {
+    nav.pathname = '/fr/shop';
+    window.history.replaceState(null, '', '/fr/shop?sort=new#top');
+    const state = capture({ locales: LOCALES, locale: 'fr', basePath: '/fr' });
+    expect(state.current.hrefFor('en')).toBe('/shop?sort=new#top');
+    expect(state.current.hrefFor('ar')).toBe('/ar/shop?sort=new#top');
+    expect(state.current.hrefFor(state.current.locales[1]!)).toBe('/fr/shop?sort=new#top');
+    // Unknown code: stays on the current page.
+    expect(state.current.hrefFor('xx')).toBe('/fr/shop?sort=new#top');
+  });
+
+  it('switchTo pushes the live URL and ignores the active or an unknown language', () => {
+    const state = capture({ locales: LOCALES });
+    act(() => window.history.replaceState(null, '', '/shop?page=3'));
+    act(() => state.current.switchTo('fr'));
+    expect(nav.push).toHaveBeenCalledWith('/fr/shop?page=3');
+    nav.push.mockClear();
+    act(() => state.current.switchTo('en'));
+    act(() => state.current.switchTo('xx'));
+    expect(nav.push).not.toHaveBeenCalled();
+  });
+});
+
+describe('LanguageSwitcher', () => {
+  /** What the switcher put on the page: the provider's brand wrapper stays, its content must be empty. */
+  const rendered = () => (container.querySelector('[data-brand-root]') ?? container).innerHTML;
+  const selectOf = () => container.querySelector('select') as HTMLSelectElement;
+
+  it('renders nothing with one language, none, or outside a storefront', () => {
+    mount(<LanguageSwitcher />);
+    expect(rendered()).toBe('');
+    mount(<LanguageSwitcher />, { locales: [LOCALES[0]!] });
+    expect(rendered()).toBe('');
+    act(() => root.render(<LanguageSwitcher />));
+    expect(rendered()).toBe('');
+  });
+
+  it('renders nothing on the server for a single language, and the control for several', () => {
+    const html = (locales?: StoreLocaleInput[]) =>
+      renderToStaticMarkup(
+        <Provider options={{ locales }}>
+          <LanguageSwitcher />
+        </Provider>,
+      );
+    expect(html()).not.toContain('qn-lang');
+    expect(html([LOCALES[0]!])).not.toContain('qn-lang');
+    expect(html(LOCALES)).toContain('data-qn-language-switcher');
+  });
+
+  it('renders a labelled native select with every language and the active one selected', () => {
+    mount(<LanguageSwitcher />, { locales: LOCALES, locale: 'fr', basePath: '/fr' });
+    const group = container.querySelector('[data-qn-language-switcher]')!;
+    expect(group.getAttribute('role')).toBe('group');
+    expect(group.getAttribute('aria-label')).toBe('Language');
+    expect(selectOf().getAttribute('aria-label')).toBe('Language: French');
+    expect(selectOf().value).toBe('fr');
+    const options = [...container.querySelectorAll('option')];
+    expect(options.map((o) => o.textContent)).toEqual(['English', 'Français', 'العربية']);
+    expect(options.map((o) => o.getAttribute('lang'))).toEqual(['en', 'fr', 'ar']);
+    expect(options[2]!.getAttribute('dir')).toBe('rtl');
+    expect(options[0]!.getAttribute('dir')).toBe('ltr');
+  });
+
+  it('navigates when the selection changes (keyboard or pointer)', () => {
+    window.history.replaceState(null, '', '/shop?sort=new');
+    mount(<LanguageSwitcher />, { locales: LOCALES });
+    act(() => {
+      selectOf().value = 'fr';
+      selectOf().dispatchEvent(new Event('change', { bubbles: true }));
+    });
+    expect(nav.push).toHaveBeenCalledWith('/fr/shop?sort=new');
+  });
+
+  it('goes back to the root path when the default language is chosen', () => {
+    nav.pathname = '/ar/products/mug';
+    mount(<LanguageSwitcher />, { locales: LOCALES, locale: 'ar', basePath: '/ar' });
+    act(() => {
+      selectOf().value = 'en';
+      selectOf().dispatchEvent(new Event('change', { bubbles: true }));
+    });
+    expect(nav.push).toHaveBeenCalledWith('/products/mug');
+  });
+
+  it('honours showCode and showNativeName, and className', () => {
+    mount(<LanguageSwitcher className="in-header" showCode showNativeName={false} />, { locales: LOCALES });
+    expect([...container.querySelectorAll('option')].map((o) => o.textContent)).toEqual([
+      'English · EN',
+      'French · FR',
+      'Arabic · AR',
+    ]);
+    expect(container.querySelector('[data-qn-language-switcher]')!.className).toBe('qn-lang qn-lang--select in-header');
+  });
+
+  it('takes its labels from the theme strings', () => {
+    mount(<LanguageSwitcher />, {
+      locales: LOCALES,
+      strings: { language: { label: 'Langue', named: 'Langue : {name}' } },
+    });
+    expect(container.querySelector('[role="group"]')!.getAttribute('aria-label')).toBe('Langue');
+    expect(selectOf().getAttribute('aria-label')).toBe('Langue : English');
+  });
+
+  it('renders the inline list with links, the current language marked, and wraps in a nav', () => {
+    window.history.replaceState(null, '', '/shop?sort=new');
+    mount(<LanguageSwitcher variant="inline-list" />, { locales: LOCALES, locale: null });
+    const nav_ = container.querySelector('nav')!;
+    expect(nav_.getAttribute('aria-label')).toBe('Language');
+    const links = [...container.querySelectorAll('a')];
+    expect(links.map((a) => a.getAttribute('href'))).toEqual(['/shop?sort=new', '/fr/shop?sort=new', '/ar/shop?sort=new']);
+    expect(links.map((a) => a.getAttribute('aria-current'))).toEqual(['true', null, null]);
+    expect(links[0]!.getAttribute('aria-label')).toBe('Language: English');
+    expect(links[1]!.getAttribute('lang')).toBe('fr');
+    expect(links[1]!.getAttribute('hreflang')).toBe('fr');
+  });
+
+  it('inline-list: a plain click switches with the live URL, a modified click is left alone', () => {
+    mount(<LanguageSwitcher variant="inline-list" />, { locales: LOCALES });
+    const fr = [...container.querySelectorAll('a')][1]!;
+    act(() => {
+      fr.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true, button: 0 }));
+    });
+    expect(nav.push).toHaveBeenCalledWith('/fr/shop');
+    nav.push.mockClear();
+    // jsdom cannot navigate: swallow the default action it would otherwise try.
+    const swallow = (event: Event) => event.preventDefault();
+    document.addEventListener('click', swallow);
+    const modified = new MouseEvent('click', { bubbles: true, cancelable: true, button: 0, metaKey: true });
+    act(() => {
+      fr.dispatchEvent(modified);
+    });
+    document.removeEventListener('click', swallow);
+    expect(nav.push).not.toHaveBeenCalled();
+  });
+
+  it('hands the state to a render-prop and renders only what it returns', () => {
+    const seen: string[] = [];
+    mount(
+      <LanguageSwitcher>
+        {(state) => (
+          <ul data-testid="custom">
+            {state.locales.map((l) => {
+              seen.push(state.labelFor(l));
+              return (
+                <li key={l.locale}>
+                  <button type="button" onClick={() => state.switchTo(l)}>
+                    {state.displayName(l)}
+                  </button>
+                  <a href={state.hrefFor(l)}>{state.label}</a>
+                </li>
+              );
+            })}
+          </ul>
+        )}
+      </LanguageSwitcher>,
+      { locales: LOCALES },
+    );
+    expect(container.querySelector('[data-qn-language-switcher]')).toBeNull();
+    expect(container.querySelector('select')).toBeNull();
+    expect(seen).toEqual(['Language: English', 'Language: French', 'Language: Arabic']);
+    act(() => {
+      (container.querySelectorAll('button')[1] as HTMLButtonElement).click();
+    });
+    expect(nav.push).toHaveBeenCalledWith('/fr/shop');
+  });
+
+  it('the render-prop is not called for a single language', () => {
+    const children = vi.fn(() => <p>custom</p>);
+    mount(<LanguageSwitcher>{children}</LanguageSwitcher>, { locales: [LOCALES[0]!] });
+    expect(children).not.toHaveBeenCalled();
+    expect(rendered()).toBe('');
+  });
+
+  it('keeps the same markup on the server and on first client render (no hydration mismatch)', () => {
+    window.history.replaceState(null, '', '/shop?sort=new');
+    const tree = (
+      <Provider options={{ locales: LOCALES }}>
+        <LanguageSwitcher variant="inline-list" />
+      </Provider>
+    );
+    const server = renderToStaticMarkup(tree);
+    expect(server).toContain('href="/fr/shop"');
+    expect(server).not.toContain('sort=new');
+  });
+});
+
+describe('LanguageSwitcher styling', () => {
+  const css = readFileSync(join(__dirname, '..', 'components', 'language-switcher.css'), 'utf8');
+
+  it('uses logical properties only (right-to-left safe)', () => {
+    expect(css).not.toMatch(/(^|[\s{;])(left|right|margin-left|margin-right|padding-left|padding-right|border-left|border-right)\s*:/m);
+    expect(css).not.toMatch(/text-align:\s*(left|right)/);
+  });
+
+  it('styles only through --qn-* tokens, each with a fallback', () => {
+    const tokens = [...css.matchAll(/var\((--[a-z0-9-]+)/g)].map((m) => m[1]!);
+    expect(tokens.length).toBeGreaterThan(0);
+    expect(tokens.filter((t) => !t.startsWith('--qn-'))).toEqual([]);
+    expect(css).not.toMatch(/var\(--qn-[a-z0-9-]+\)/);
+  });
+});
+
+describe('provider', () => {
+  it('leaves the context untouched when no locales are passed (backward compatible)', () => {
+    let seen: unknown;
+    function Probe() {
+      seen = (globalThis as never as { __ctx?: unknown }).__ctx;
+      return null;
+    }
+    act(() =>
+      root.render(
+        <StorefrontProvider vendor={{ slug: 'acme' } as never} config={{} as never} menus={[]}>
+          <StorefrontContext.Consumer>
+            {(value) => {
+              (globalThis as never as { __ctx?: unknown }).__ctx = value;
+              return <Probe />;
+            }}
+          </StorefrontContext.Consumer>
+        </StorefrontProvider>,
+      ),
+    );
+    expect((seen as { locales: unknown[] }).locales).toEqual([]);
+    delete (globalThis as never as { __ctx?: unknown }).__ctx;
+  });
+});
+
+describe('theme manifest', () => {
+  it("declares the theme places the switcher with languageSwitcher: 'theme'", () => {
+    const field: Pick<ThemeManifest, 'languageSwitcher'> = { languageSwitcher: 'theme' };
+    const none: Pick<ThemeManifest, 'languageSwitcher'> = {};
+    expect(field.languageSwitcher).toBe('theme');
+    expect(none.languageSwitcher).toBeUndefined();
+  });
+});

package/tests/list-pagination.test.tsx

@@ -5,13 +5,13 @@ import { BlogPagination } from '../components/blog/pagination';
 import type { Pagination } from '../types/page';
 
 vi.mock('next/headers', () => ({
-  headers: async () => new Headers({ host: 'kili-foods.usequeek.com' }),
+  headers: async () => new Headers({ host: 'demo-store.usequeek.com' }),
 }));
 
 /**
  * Storefront lists answer `{data, has_more, next_cursor}` with no totals, page
- * counts or page URLs (founder 28/9/26: prev/next + "Page N", zero COUNT). The
- * kit's readers must walk on `has_more` alone and label the page they asked for.
+ * counts or page URLs (prev/next + "Page N", no COUNT query). The kit's
+ * readers must walk on `has_more` alone and label the page they asked for.
  */
 describe('storefront list walk state (has_more, no totals)', () => {
   afterEach(() => vi.unstubAllGlobals());
@@ -27,7 +27,7 @@ describe('storefront list walk state (has_more, no totals)', () => {
     vi.stubGlobal('fetch', fetchMock);
     const { fetchCollectionProducts } = await import('../api/collections');
 
-    const page3 = await fetchCollectionProducts('kili-foods', 'new-season', { page: 3, perPage: 20 });
+    const page3 = await fetchCollectionProducts('demo-store', 'new-season', { page: 3, perPage: 20 });
     expect(page3.pagination).toEqual({ current_page: 3, per_page: 20, has_more: true, next_cursor: 'eyJ2IjoxfQ' });
     const productsCall = fetchMock.mock.calls.map(([url]) => String(url)).find((url) => url.includes('/products'));
     expect(productsCall).toContain('page=3');
@@ -41,13 +41,13 @@ describe('storefront list walk state (has_more, no totals)', () => {
     })));
     const { fetchCollectionProducts } = await import('../api/collections');
 
-    const page = await fetchCollectionProducts('kili-foods', 'new-season');
+    const page = await fetchCollectionProducts('demo-store', 'new-season');
     expect(page.pagination).toEqual({ current_page: 1, per_page: undefined, has_more: false, next_cursor: null });
   });
 
   const renderPager = (pagination: Pagination, category?: string): string =>
     renderToStaticMarkup(
-      <StorefrontContext.Provider value={{ vendor: { id: 'v1', slug: 'kili-foods' }, basePath: '/kili-foods' } as never}>
+      <StorefrontContext.Provider value={{ vendor: { id: 'v1', slug: 'demo-store' }, basePath: '/demo-store' } as never}>
         <BlogPagination pagination={pagination} category={category} />
       </StorefrontContext.Provider>,
     );
@@ -56,8 +56,8 @@ describe('storefront list walk state (has_more, no totals)', () => {
     const html = renderPager({ current_page: 2, per_page: 12, has_more: true }, 'news');
     expect(html).toContain('Page 2');
     expect(html).not.toMatch(/Page 2 of/);
-    expect(html).toContain('rel="prev" href="/kili-foods/blog?category=news"');
-    expect(html).toContain('rel="next" href="/kili-foods/blog?category=news&amp;page=3"');
+    expect(html).toContain('rel="prev" href="/demo-store/blog?category=news"');
+    expect(html).toContain('rel="next" href="/demo-store/blog?category=news&amp;page=3"');
   });
 
   it('BlogPagination: last page disables Next; a lone first page renders nothing', () => {