@usequeek/theme-kit 0.1.21 → 0.1.22

package/tests/locale-switch.test.ts

@@ -0,0 +1,197 @@
+import { describe, expect, it } from 'vitest';
+import {
+  defaultStoreLocale,
+  localeHref,
+  normalizeStoreLocales,
+  resolveActiveLocale,
+  type StoreLocale,
+  type StoreLocaleInput,
+} from '../utils/locale-switch';
+
+function row(locale: string, extra: Partial<StoreLocaleInput> = {}): StoreLocaleInput {
+  return { locale, name: locale, native_name: locale, is_primary: false, ...extra };
+}
+
+/** English default, French and Simplified Chinese under prefixes. */
+const EN_DEFAULT = normalizeStoreLocales([
+  row('en', { name: 'English', native_name: 'English', is_primary: true, is_default: true, path_prefix: '' }),
+  row('fr', { name: 'French', native_name: 'Français', is_default: false, path_prefix: 'fr' }),
+  row('zh-CN', { name: 'Chinese', native_name: '简体中文', is_default: false, path_prefix: 'zh-cn' }),
+]);
+
+/** French default; English (the primary) is not the default, so it lives under /en. */
+const FR_DEFAULT = normalizeStoreLocales([
+  row('fr', { name: 'French', native_name: 'Français', is_default: true, path_prefix: '' }),
+  row('en', { name: 'English', native_name: 'English', is_primary: true, is_default: false, path_prefix: 'en' }),
+]);
+
+function pick(locales: StoreLocale[], code: string): StoreLocale {
+  const found = locales.find((l) => l.locale === code);
+  if (!found) throw new Error(`fixture has no ${code}`);
+  return found;
+}
+
+function href(
+  locales: StoreLocale[],
+  from: string,
+  to: string,
+  url: { pathname: string; search?: string; hash?: string; basePath?: string },
+): string {
+  return localeHref({ ...url, active: pick(locales, from), target: pick(locales, to) });
+}
+
+describe('localeHref', () => {
+  it('moves the default language to a prefix and back to the root', () => {
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/shop' })).toBe('/fr/shop');
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/fr/shop', basePath: '/fr' })).toBe('/shop');
+  });
+
+  it('keeps the root path at the root of each language', () => {
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/' })).toBe('/fr');
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/fr', basePath: '/fr' })).toBe('/');
+  });
+
+  it('puts English under /en when English is not the default', () => {
+    expect(href(FR_DEFAULT, 'fr', 'en', { pathname: '/shop' })).toBe('/en/shop');
+    expect(href(FR_DEFAULT, 'en', 'fr', { pathname: '/en/shop', basePath: '/en' })).toBe('/shop');
+  });
+
+  it('uses the lower-case code as the prefix (zh-CN -> /zh-cn)', () => {
+    expect(href(EN_DEFAULT, 'en', 'zh-CN', { pathname: '/products/mug' })).toBe('/zh-cn/products/mug');
+    expect(href(EN_DEFAULT, 'zh-CN', 'fr', { pathname: '/zh-cn/products/mug', basePath: '/zh-cn' })).toBe('/fr/products/mug');
+  });
+
+  it('switches directly between two prefixed languages', () => {
+    expect(href(EN_DEFAULT, 'fr', 'zh-CN', { pathname: '/fr/shop/all', basePath: '/fr' })).toBe('/zh-cn/shop/all');
+  });
+
+  it('keeps the query string and the hash', () => {
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/shop', search: '?sort=new&page=2', hash: '#reviews' })).toBe(
+      '/fr/shop?sort=new&page=2#reviews',
+    );
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/fr', basePath: '/fr', search: '?q=a', hash: '#top' })).toBe('/?q=a#top');
+  });
+
+  it('accepts a query string and hash without their leading marks, and ignores empty ones', () => {
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/shop', search: 'a=1', hash: 'x' })).toBe('/fr/shop?a=1#x');
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/shop', search: '?', hash: '#' })).toBe('/fr/shop');
+  });
+
+  it('keeps a trailing slash on a nested path', () => {
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/shop/' })).toBe('/fr/shop/');
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/fr/shop/mugs/', basePath: '/fr' })).toBe('/shop/mugs/');
+  });
+
+  it('only strips whole segments: a page that starts like a language is a page', () => {
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/fr/french-press', basePath: '/fr' })).toBe('/french-press');
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/french-press' })).toBe('/fr/french-press');
+    // Active is the default (no prefix to strip): `/fr` as a path is a page there.
+    expect(href(EN_DEFAULT, 'en', 'zh-CN', { pathname: '/fr-news' })).toBe('/zh-cn/fr-news');
+  });
+
+  it('strips the active prefix once: a page slug equal to the prefix survives', () => {
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/fr/fr', basePath: '/fr' })).toBe('/fr');
+  });
+
+  it('handles a path-based host (basePath carries the store slug)', () => {
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/acme/shop', basePath: '/acme' })).toBe('/acme/fr/shop');
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/acme/fr/shop', basePath: '/acme/fr' })).toBe('/acme/shop');
+    expect(href(EN_DEFAULT, 'fr', 'zh-CN', { pathname: '/acme/fr', basePath: '/acme/fr' })).toBe('/acme/zh-cn');
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/acme/fr', basePath: '/acme/fr' })).toBe('/acme');
+  });
+
+  it('also copes with a non-localized basePath', () => {
+    expect(href(EN_DEFAULT, 'fr', 'en', { pathname: '/acme/fr/shop', basePath: '/acme' })).toBe('/acme/shop');
+    expect(href(EN_DEFAULT, 'en', 'fr', { pathname: '/acme', basePath: '/acme' })).toBe('/acme/fr');
+  });
+
+  it('matches the active prefix case-insensitively', () => {
+    expect(href(EN_DEFAULT, 'zh-CN', 'en', { pathname: '/ZH-CN/shop' })).toBe('/shop');
+  });
+
+  it('works on an old backend without is_default (primary is the default)', () => {
+    const old = normalizeStoreLocales([
+      { locale: 'en', name: 'English', native_name: 'English', is_primary: true, path_prefix: '' },
+      { locale: 'fr', name: 'French', native_name: 'Français', is_primary: false, path_prefix: 'fr' },
+    ]);
+    expect(old.map((l) => [l.locale, l.is_default, l.path_prefix])).toEqual([
+      ['en', true, ''],
+      ['fr', false, 'fr'],
+    ]);
+    expect(href(old, 'en', 'fr', { pathname: '/shop' })).toBe('/fr/shop');
+    expect(href(old, 'fr', 'en', { pathname: '/fr/shop', basePath: '/fr' })).toBe('/shop');
+  });
+});
+
+describe('normalizeStoreLocales', () => {
+  it('returns [] for nothing usable', () => {
+    expect(normalizeStoreLocales(undefined)).toEqual([]);
+    expect(normalizeStoreLocales(null)).toEqual([]);
+    expect(normalizeStoreLocales([])).toEqual([]);
+    expect(normalizeStoreLocales([{} as never, { locale: '' }, null as never])).toEqual([]);
+    expect(normalizeStoreLocales('fr' as never)).toEqual([]);
+  });
+
+  it('puts the default first and keeps the rest in order', () => {
+    const out = normalizeStoreLocales([
+      row('fr', { path_prefix: 'fr' }),
+      row('en', { is_primary: true, is_default: true }),
+      row('de', { path_prefix: 'de' }),
+    ]);
+    expect(out.map((l) => l.locale)).toEqual(['en', 'fr', 'de']);
+  });
+
+  it('keeps exactly one default, forces its prefix empty and fills empty prefixes', () => {
+    const out = normalizeStoreLocales([
+      row('en', { is_default: true, path_prefix: 'en' }),
+      row('FR', { is_default: true, path_prefix: '' }),
+      row('pt-BR', { path_prefix: '' }),
+    ]);
+    expect(out.map((l) => [l.locale, l.is_default, l.path_prefix])).toEqual([
+      ['en', true, ''],
+      ['FR', false, 'fr'],
+      ['pt-BR', false, 'pt-br'],
+    ]);
+  });
+
+  it('drops repeated codes, tolerates extra fields and defaults missing ones', () => {
+    const out = normalizeStoreLocales([
+      { locale: 'en', is_primary: true, extra: 'ignored' } as StoreLocaleInput,
+      { locale: 'EN', is_primary: false },
+      { locale: 'ar', path_prefix: 'ar', dir: 'rtl' },
+    ]);
+    expect(out).toHaveLength(2);
+    expect(out[0]).toMatchObject({ locale: 'en', name: 'en', native_name: 'en', dir: 'ltr', hreflang: 'en', html_lang: 'en' });
+    expect(out[0]).not.toHaveProperty('extra');
+    expect(out[1]?.dir).toBe('rtl');
+  });
+
+  it('accepts the storefront row shape without mapping', () => {
+    const storefrontRows: Array<{
+      locale: string; name: string; native_name: string; is_primary: boolean; is_default: boolean;
+      path_prefix: string; hreflang: string; html_lang: string; dir: string;
+    }> = [
+      { locale: 'en', name: 'English', native_name: 'English', is_primary: true, is_default: true, path_prefix: '', hreflang: 'en', html_lang: 'en', dir: 'ltr' },
+    ];
+    const accepted: readonly StoreLocaleInput[] = storefrontRows;
+    const exact: StoreLocale = normalizeStoreLocales(accepted)[0]!;
+    // A storefront-typed value is assignable to StoreLocale as well.
+    const back: typeof storefrontRows[number] = exact;
+    expect(back.locale).toBe('en');
+  });
+});
+
+describe('active and default resolution', () => {
+  it('resolves the request locale case-insensitively, unknown/null to the default', () => {
+    expect(resolveActiveLocale(EN_DEFAULT, 'zh-cn').locale).toBe('zh-CN');
+    expect(resolveActiveLocale(EN_DEFAULT, 'fr').locale).toBe('fr');
+    expect(resolveActiveLocale(EN_DEFAULT, null).locale).toBe('en');
+    expect(resolveActiveLocale(EN_DEFAULT, 'xx').locale).toBe('en');
+    expect(resolveActiveLocale(FR_DEFAULT, undefined).locale).toBe('fr');
+  });
+
+  it('falls back to English for an empty list', () => {
+    expect(defaultStoreLocale([]).locale).toBe('en');
+    expect(resolveActiveLocale([], 'fr').path_prefix).toBe('');
+  });
+});

package/tests/locale-transport.test.tsx

@@ -16,7 +16,7 @@ import { normalizeShopQuery, type ShopPrefetch } from '../utils/shop-query';
 import type { Product } from '../types/product';
 
 /**
- * Theme-kit locale transport (slice K1): the backend answers `?locale=<code>`
+ * Theme-kit locale transport: the API answers `?locale=<code>`
  * with translated text, the proxy sets `x-queek-locale` for published
  * non-primary locales only, and every kit transport forwards it additively —
  * no locale anywhere means byte-identical behaviour to before.
@@ -194,7 +194,7 @@ describe('server transport (sdk/server-store-client)', () => {
 });
 
 describe('fetchShopPrefetch (api/shop)', () => {
-  async function runPrefetch(vendorSlug = 'kili-foods', locale?: string) {
+  async function runPrefetch(vendorSlug = 'demo-store', locale?: string) {
     const fetchMock = vi.fn(async (_url: string, _init?: RequestInit) => ({ ok: true, json: async () => ({ data: [], has_more: false }) }));
     vi.stubGlobal('fetch', fetchMock);
     const { fetchShopPrefetch } = await import('../api/shop');
@@ -226,7 +226,7 @@ function product(id: string, title: string): Product {
 function render(children: ReactNode, locale?: string | null): string {
   return renderToStaticMarkup(
     <StorefrontProvider
-      vendor={{ id: 'v1', slug: 'kili-foods', name: 'Kili Foods' } as never}
+      vendor={{ id: 'v1', slug: 'demo-store', name: 'Demo Store' } as never}
       config={{} as never}
       menus={[]}
       {...(locale !== undefined ? { locale } : {})}

package/tests/markdown-render.test.ts

@@ -4,12 +4,11 @@ import { describe, expect, it } from 'vitest';
 import { renderMarkdown } from '../utils/markdown';
 
 /**
- * Backend CT16 (queek_backend/.agent/frontend-chat/sessions/storefront-contact-block/chat.json):
- * a heading immediately followed by other content, with no blank line between them, gets
- * swallowed whole into the heading — `utils/markdown.tsx` used to treat an entire
- * blank-line-delimited block as heading text the moment it matched a heading prefix. Real
- * merchant copy (Jhema Wears' short_description) writes "### Our Offerings\n- item\n- item"
- * with no blank line, which is common, valid markdown — the list must not disappear into the h3.
+ * A heading immediately followed by other content, with no blank line between them, must
+ * not be swallowed whole into the heading — `utils/markdown.tsx` once treated an entire
+ * blank-line-delimited block as heading text the moment it matched a heading prefix.
+ * Merchant copy often writes "### Our Offerings\n- item\n- item" with no blank line, which
+ * is common, valid markdown — the list must not disappear into the h3.
  */
 
 function html(markdown: string): string {

package/tests/orders-walk.test.ts

@@ -2,9 +2,9 @@ import { afterEach, describe, expect, it, vi } from 'vitest';
 import { fetchOrders } from '../api/orders';
 
 /**
- * `GET store/orders` answers the ONE storefront list envelope (pagination
- * Slice 4b, founder 28/9/26): `has_more` + `next_cursor` top-level, no
- * `links`, no paginator `meta`. The kit reads the page it asked for.
+ * `GET store/orders` answers the ONE storefront list envelope: `has_more` +
+ * `next_cursor` top-level, no `links`, no paginator `meta`. The kit reads the
+ * page it asked for.
  */
 describe('fetchOrders walk state', () => {
   afterEach(() => vi.unstubAllGlobals());
@@ -23,7 +23,7 @@ describe('fetchOrders walk state', () => {
     }));
     vi.stubGlobal('fetch', fetchMock);
 
-    const page = await fetchOrders('kili-foods', 2, 'ongoing');
+    const page = await fetchOrders('demo-store', 2, 'ongoing');
 
     const url = String((fetchMock.mock.calls[0] as unknown[])[0]);
     expect(url).toContain('/client/store/orders');
@@ -39,7 +39,7 @@ describe('fetchOrders walk state', () => {
     const fetchMock = vi.fn(async () => ({ ok: true, json: async () => ({ data: [], has_more: false, next_cursor: null }) }));
     vi.stubGlobal('fetch', fetchMock);
 
-    const page = await fetchOrders('kili-foods', 1, 'all');
+    const page = await fetchOrders('demo-store', 1, 'all');
 
     expect(String((fetchMock.mock.calls[0] as unknown[])[0])).not.toContain('status=');
     expect(page.has_more).toBe(false);

package/tests/page-renderer-signature.test.tsx

@@ -27,7 +27,7 @@ describe('PageRenderer', () => {
       { type: 'content', data: { markdown: 'Fresh meals, delivered' }, productsPromise: circularThenable(), metaobjectsPromise: circularThenable() },
     ] as unknown as Block[];
     const theme = { getBlock: () => () => null } as unknown as ThemeModule;
-    const store = { vendor: { id: 'v1', slug: 'kili-foods' }, config: {}, menus: [], basePath: '', pagesChrome: {} };
+    const store = { vendor: { id: 'v1', slug: 'demo-store' }, config: {}, menus: [], basePath: '', pagesChrome: {} };
 
     const html = renderToStaticMarkup(
       <StorefrontContext.Provider value={store as never}>

package/tests/powered-by-queek.test.tsx

@@ -27,9 +27,9 @@ describe('PoweredByQueek', () => {
   });
 
   it('tags the link with the store slug as utm_campaign', () => {
-    const html = render(undefined, { id: 'uuid-1', slug: 'kili-foods' });
+    const html = render(undefined, { id: 'uuid-1', slug: 'demo-store' });
 
-    expect(html).toContain(`href="${BASE}&utm_campaign=kili-foods"`);
+    expect(html).toContain(`href="${BASE}&utm_campaign=demo-store"`);
     expect(html).toContain('rel="noopener noreferrer"');
   });
 
@@ -60,6 +60,6 @@ describe('PoweredByQueek', () => {
 
   it('renders nothing when hidden', () => {
     expect(render({ hidden: true })).toBe('');
-    expect(render({ hidden: true }, { id: 'uuid-1', slug: 'kili-foods' })).toBe('');
+    expect(render({ hidden: true }, { id: 'uuid-1', slug: 'demo-store' })).toBe('');
   });
 });

package/tests/powered-by-url.test.ts

@@ -7,13 +7,13 @@ function params(url: string): Record<string, string> {
 
 describe('poweredByQueekUrl', () => {
   it('keeps the business-page destination and adds source, medium and campaign', () => {
-    const url = poweredByQueekUrl('kili-foods');
+    const url = poweredByQueekUrl('demo-store');
 
     expect(url.startsWith(`${POWERED_BY_QUEEK_URL}?`)).toBe(true);
     expect(params(url)).toEqual({
       utm_source: 'powered_by',
       utm_medium: 'storefront',
-      utm_campaign: 'kili-foods',
+      utm_campaign: 'demo-store',
     });
   });
 

package/tests/public-surface.test.ts

@@ -20,10 +20,7 @@ function barrelModules(file: string): Set<string> {
  * `index.ts` + `client.ts` declare the surface a theme may build against — the
  * set that ships as `@usequeek/theme-kit`.
  *
- * This is the kit-internal half of the contract: every module the barrels
- * declare must exist. (The storefront repo holds the other half —
- * `core-public-surface.test.ts` there asserts the barrels cover every module
- * the themes actually import.)
+ * Every module the barrels declare must exist.
  */
 describe('core public surface (kit-internal)', () => {
   const declared = new Set([...barrelModules('index.ts'), ...barrelModules('client.ts')]);

package/tests/shopper-chrome-strings.test.tsx

@@ -1,10 +1,9 @@
 /**
  * Shopper-chrome theme strings (checkout / auth / blog) — English-safety guard.
  *
- * Stage A: every state below was rendered against the PRE-migration code and
- * stored in `tests/fixtures/shopper-chrome-baseline.json`. Each case asserts
- * `.toBe` equality against that stored OLD markup, so ANY English change
- * (value, markup, attribute, plural) fails here. S4 drift guard + S7 proof.
+ * Each state below is rendered and compared with the markup stored in
+ * `tests/fixtures/shopper-chrome-baseline.json` (`.toBe` equality), so ANY
+ * English change (value, markup, attribute, plural) fails here.
  */
 import { readFileSync } from 'node:fs';
 import { join, dirname } from 'node:path';
@@ -112,7 +111,7 @@ const AVATAR_USER = {
 function render(children: ReactNode): string {
   return renderToStaticMarkup(
     <StorefrontProvider
-      vendor={{ id: 'v1', slug: 'kili-foods', name: 'Kili Foods' } as never}
+      vendor={{ id: 'v1', slug: 'demo-store', name: 'Demo Store' } as never}
       config={{} as never}
       menus={[]}
     >
@@ -262,7 +261,7 @@ describe('shopper chrome English safety (checkout/auth/blog)', () => {
     });
   }
 
-  // S4 value guard: ShareButtons renders its copied branch only after a
+  // Value guard: ShareButtons renders its copied branch only after a
   // client-side clipboard write (internal useState, no prop), so no static
   // baseline can capture it. Pin the English through the real `t` instead —
   // any change to blog.share.copied fails here.

package/tests/storefront-client-scope.test.ts

@@ -4,11 +4,11 @@ import { join } from 'node:path';
 import { request } from '../sdk/client';
 
 /**
- * The storefront must ONLY ever call the `/v1/client/*` backend scope. That scope's
- * ResolveClientContext middleware resolves the vendor AND forces the platform
- * (storefront/instore_qr) — so prices are always the storefront's, never the
- * marketplace commission-inclusive price. Legacy v1 routes (/products, /vendors/*,
- * /categories, ...) bypass that middleware → wrong platform → wrong price.
+ * The storefront must ONLY ever call the `/v1/client/*` API scope. That scope
+ * resolves the vendor AND forces the platform (storefront/instore_qr) — so prices
+ * are always the storefront's, never the marketplace commission-inclusive price.
+ * Legacy v1 routes (/products, /vendors/*, /categories, ...) skip that
+ * resolution → wrong platform → wrong price.
  *
  * This guard prevents that whole class of bug from ever returning.
  */

package/tests/theme-hook-placement.test.tsx

@@ -1,5 +1,5 @@
 /**
- * Hook-placement rule (checkout / auth / blog slice) — S2 enforcement.
+ * Hook-placement rule for the checkout / auth / blog components.
  *
  * Rule: every `useThemeStrings()` call must sit at the top level of a
  * PascalCase component or a `use*` hook: no enclosing if / ternary / loop /
@@ -15,7 +15,7 @@ import ts from 'typescript';
 
 const kitRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
 
-// Files this slice migrated: each must call useThemeStrings() exactly once.
+// Files that use theme strings: each must call useThemeStrings() exactly once.
 const EXPECTED_FILES = [
   'components/checkout/checkout-contact.tsx',
   'components/checkout/default-checkout-shell.tsx',

package/tests/theme-strings-client.test.tsx

@@ -23,7 +23,7 @@ function render(
 ): string {
   return renderToStaticMarkup(
     <StorefrontProvider
-      vendor={{ id: 'v1', slug: 'kili-foods', name: 'Kili Foods' } as never}
+      vendor={{ id: 'v1', slug: 'demo-store', name: 'Demo Store' } as never}
       config={{} as never}
       menus={[]}
       {...(options?.locale !== undefined ? { locale: options.locale } : {})}
@@ -39,7 +39,7 @@ function Title(): JSX.Element {
   return <h1>{t('cart.title')}</h1>;
 }
 
-describe('client surface: StorefrontProvider strings + useThemeStrings (decision 4b)', () => {
+describe('client surface: StorefrontProvider strings + useThemeStrings', () => {
   it('renders the active locale through the hook', () => {
     expect(render(<Title />, { locale: 'fr', strings: FR_STRINGS })).toContain('<h1>Votre panier</h1>');
   });
@@ -105,7 +105,7 @@ describe('client surface through ThemeMount', () => {
   });
 });
 
-describe('manifest.strings travels with the theme (decision 15)', () => {
+describe('manifest.strings travels with the theme', () => {
   const MANIFEST_EN: ThemeStringsDictionary = {
     theme: {
       hero: { title: 'Fresh from the farm' },
@@ -216,10 +216,10 @@ describe('manifest.strings travels with the theme (decision 15)', () => {
     // No `strings` key at all: this literal must satisfy StorefrontContextValue
     // (it failed to compile while the field was required in 0.1.18).
     const value = {
-      vendor: { id: 'v1', slug: 'kili-foods', name: 'Kili Foods', logo: null } as VendorProfile,
+      vendor: { id: 'v1', slug: 'demo-store', name: 'Demo Store', logo: null } as VendorProfile,
       config: { theme: 'stub', brand: {} } as StorefrontConfig,
       menus: [],
-      basePath: '/kili-foods',
+      basePath: '/demo-store',
       pagesChrome: {},
       locale: null,
     };

package/tests/theme-strings-pseudo.test.tsx

@@ -17,7 +17,7 @@ const EN = enDefault as unknown as ThemeStringsDictionary;
 function render(children: ReactNode, strings: ThemeStringsDictionary | null): string {
   return renderToStaticMarkup(
     <StorefrontProvider
-      vendor={{ id: 'v1', slug: 'kili-foods', name: 'Kili Foods' } as never}
+      vendor={{ id: 'v1', slug: 'demo-store', name: 'Demo Store' } as never}
       config={{} as never}
       menus={[]}
       {...(strings ? { strings } : {})}

package/tests/theme-strings-typed.test.tsx

@@ -79,7 +79,7 @@ describe('typed keys: createThemeT (additive, opt-in)', () => {
   });
 
   it('drifts with the dictionary: the union is exactly the flattened keys', () => {
-    // Compile-time proof (positive direction; the negative direction — typos
+    // Compile-time check (positive direction; the negative direction — typos
     // fail — lives in tests/theme-typed-keys.fixture.ts via @ts-expect-error
     // so `npm run typecheck` stays green).
     const keys: Array<ThemeStringKey<typeof THEME_EN>> = [

package/tests/theme-strings.test.tsx

@@ -43,7 +43,7 @@ const FR_THEME = {
   'cart.empty.browse': 'Voir les produits',
 } as unknown as ThemeStringsDictionary;
 
-describe('t() fallback order (decision 3)', () => {
+describe('t() fallback order', () => {
   it('returns the first hit across override, theme, core, default', async () => {
     const bound = await createThemeStrings({
       locale: 'fr',
@@ -223,7 +223,7 @@ describe('RTL dir (locale catalogue)', () => {
   });
 });
 
-describe('default English dictionary budget (backend varchar(64))', () => {
+describe('default English dictionary budget (64-character stored key)', () => {
   function flatten(node: unknown, prefix: string, out: Array<[string, string]>): void {
     if (typeof node === 'string') {
       out.push([prefix, node]);
@@ -240,12 +240,9 @@ describe('default English dictionary budget (backend varchar(64))', () => {
   flatten(enDefault, '', pairs);
 
   it('ships the ~106-string core dictionary (intentional growth, still budgeted)', () => {
-    // Dictionary budget: the checkout/auth/blog shopper-chrome slice added 31
-    // keys and removed 1 orphaned pre-existing key (auth.code.sent, 0 usages,
-    // superseded by auth.code.lead): 76 -> 106, commit 5cb67dd + orphan removal.
-    // The ceiling stays tight (+9 headroom): any further growth must bump it
-    // here deliberately with its own justification, which keeps guarding
-    // against uncontrolled growth (backend varchar(64) per-key budget below).
+    // Dictionary budget: the ceiling stays tight (+9 headroom): any further
+    // growth must bump it here deliberately with its own justification, which
+    // guards against uncontrolled growth (64-character stored-key budget below).
     expect(pairs.length).toBeGreaterThanOrEqual(70);
     expect(pairs.length).toBeLessThanOrEqual(115);
   });
@@ -257,7 +254,7 @@ describe('default English dictionary budget (backend varchar(64))', () => {
       expect(key, `grammar: ${key}`).toMatch(/^[a-z0-9]+(\.[a-z0-9]+)*$/);
       expect(key.length, `budget: ${key}`).toBeLessThanOrEqual(THEME_STRING_KEY_MAX_LENGTH);
     }
-    // `<theme-slug>.<key>` must fit varchar(64): 40 + 1 + 23.
+    // `<theme-slug>.<key>` must fit the 64-character stored key: 40 + 1 + 23.
     expect(Math.max(...pairs.map(([k]) => k.length))).toBeLessThanOrEqual(40);
   });
 
@@ -272,7 +269,7 @@ describe('default English dictionary budget (backend varchar(64))', () => {
   });
 });
 
-describe('per-locale loading gate (decision 5)', () => {
+describe('per-locale loading gate', () => {
   function sourceFiles(dir: string, out: string[] = []): string[] {
     for (const entry of readdirSync(dir, { withFileTypes: true })) {
       if (entry.name === 'node_modules') continue;
@@ -335,7 +332,7 @@ describe('per-locale loading gate (decision 5)', () => {
   });
 });
 
-describe('server surface: bound t with NO provider (decision 4a)', () => {
+describe('server surface: bound t with NO provider', () => {
   function Greeting({ bound, name }: { bound: BoundThemeStrings; name: string }): JSX.Element {
     return (
       <main>

package/tests/use-shop-prefetch.test.tsx

@@ -34,7 +34,7 @@ function Grid(props: Parameters<typeof useShop>[0]): JSX.Element {
 
 function render(children: ReactNode, opts: { prefetch?: ShopPrefetch | null; preview?: Product[] } = {}): string {
   const store = {
-    vendor: { id: 'v1', slug: 'kili-foods', name: 'Kili Foods' },
+    vendor: { id: 'v1', slug: 'demo-store', name: 'Demo Store' },
     config: {},
     menus: [],
     previewData: opts.preview ? { products: opts.preview } : undefined,

package/theme-mount.tsx

@@ -7,18 +7,13 @@ import { ThemeProvider } from './theme-context';
 /**
  * Renders a theme. THE MINIMUM A THEME NEEDS TO BE SEEN.
  *
- * Without this, installing `@usequeek/theme-kit` gave a developer every hook,
- * store, type and shared block — and no way to actually mount what they built.
- * The component that does it, `VendorShell`, lives in the storefront app, so it
- * was never part of what shipped. A theme could be written and typechecked from
- * outside this repo but never rendered.
+ * It mounts a theme's header, page and footer inside the kit's provider, so a
+ * theme written and typechecked outside a Queek storefront can still be rendered.
  *
- * DELIBERATELY SMALLER THAN VendorShell. That composes the same three pieces and
- * then layers on the Queek storefront's own chrome — checkout header, cart and
- * auth modals, toasts, WhatsApp chat, analytics, the merchant edit-mode bridge.
- * None of that is a theme's concern, and pulling it in would drag the whole app
- * into the package. What is left is the actual contract: a Layout wrapping a
- * header, the page, and a footer.
+ * DELIBERATELY SMALL. It leaves out the Queek storefront's own chrome — checkout
+ * header, cart and auth modals, toasts, WhatsApp chat, analytics, the merchant
+ * edit-mode bridge. None of that is a theme's concern. What is left is the
+ * actual contract: a Layout wrapping a header, the page, and a footer.
  *
  * Themes render inside a boundary because a theme's header and footer are
  * SIBLINGS of the page, so a crash in either escapes any boundary the page sets

package/types/block.ts

@@ -42,7 +42,7 @@ export interface GalleryBlockData {
   heading?: string | null;
   description?: string | null;
   /** Block-level (not per-slide) hero display controls — currently only
-   *  glow's 'slider'/'thumb-rail' variants read these; harmless no-op
+   *  some themes' 'slider'/'thumb-rail' variants read these; harmless no-op
    *  elsewhere. */
   zoom_effect?: boolean | null;
   overlay?: 'none' | 'light' | 'medium' | 'strong' | null;
@@ -62,7 +62,7 @@ export interface GalleryBlockData {
     /** YouTube/Vimeo/direct file URL — takes over from `url` as the slide's
      * media when set, with `url` still used as the poster/fallback. Only
      * takes effect on themes/variants that render a single full-bleed slide
-     * (e.g. glow's `slider`/`thumb-rail` with exactly 1 image) — a
+     * (e.g. a `slider`/`thumb-rail` variant with exactly 1 image) — a
      * multi-slide carousel would autoplay every slide's video concurrently
      * since inactive slides stay mounted, not unmounted. */
     video?: string | null;
@@ -258,7 +258,7 @@ export interface MetaobjectsBlockData {
  * Server-seeded resolution for a `metaobjects` block — the entries of
  * `data.type` plus the definition meta needed to decide whether each card
  * links out (`definition.has_pages`). Mirrors `MetaobjectsResolved` shape
- * used by `hydrateProductBlocks` in the storefront.
+ * used by `hydrateProductBlocks` in the host app.
  */
 export interface MetaobjectsResolved {
   entries: MetaobjectEntry[];
@@ -293,17 +293,17 @@ export type Block<T extends BlockType = BlockType> = {
   /**
    * Section-scoped design-token overrides — only the keys set here are
    * applied; everything else inherits the global tokens via the CSS
-   * cascade. See `expandDesignTokensPartial` in `lib/core/utils/brand.ts`.
+   * cascade. See `expandDesignTokensPartial` in `utils/brand.ts`.
    */
   tokens?: Partial<DesignTokens>;
   /**
    * Stable in-page-scroll target — a menu item's `meta.anchor` links here.
-   * Lowercase-kebab, enforced by the backend (ValidStorefrontBlocks).
+   * Lowercase-kebab, enforced by the API.
    */
   anchor_id?: string;
   /**
    * Server-seeded product data for `products` blocks — set by
-   * `hydrateProductBlocks` (lib/core/api/products.ts) before blocks reach
+   * the host's `hydrateProductBlocks` before blocks reach
    * `PageRenderer`, which awaits it via `use()` inside a per-block
    * `<Suspense>` boundary. Lives on the block, not inside `data`, so it never
    * gets spread into theme components as a prop. Absent for every other
@@ -312,7 +312,7 @@ export type Block<T extends BlockType = BlockType> = {
   productsPromise?: Promise<Product[]>;
   /**
    * Server-seeded entries + definition meta for `metaobjects` blocks — set
-   * by `hydrateProductBlocks` alongside `productsPromise`. Same contract:
+   * by the host's `hydrateProductBlocks` alongside `productsPromise`. Same rule:
    * absent for every other block type and for any route that hasn't been
    * wired to hydrate; the renderer falls back to rendering nothing (themes
    * never fetch metaobjects client-side).