@usequeek/theme-kit 0.1.20 → 0.1.22

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

@@ -0,0 +1,271 @@
+/**
+ * Shopper-chrome theme strings (checkout / auth / blog) — English-safety guard.
+ *
+ * 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';
+import { fileURLToPath } from 'node:url';
+import { renderToStaticMarkup } from 'react-dom/server';
+import { describe, expect, it, vi } from 'vitest';
+import type { JSX, ReactNode } from 'react';
+import { StorefrontProvider } from '../provider';
+import { CheckoutContactSection } from '../components/checkout/checkout-contact';
+import { DefaultCheckoutShell } from '../components/checkout/default-checkout-shell';
+import { PolicyLinks } from '../components/checkout/policy-links';
+import { AuthEmailLoginStep } from '../components/auth/auth-email-login-step';
+import { AuthEmailOtpStep } from '../components/auth/auth-email-otp-step';
+import { AuthEmailOtpVerifyStep } from '../components/auth/auth-email-otp-verify-step';
+import { AuthEmailRegisterStep } from '../components/auth/auth-email-register-step';
+import { AuthSignupStep } from '../components/auth/auth-signup-step';
+import { CategoryFilter } from '../components/blog/category-filter';
+import { BlogPagination } from '../components/blog/pagination';
+import { RelatedPosts } from '../components/blog/related-posts';
+import { ShareButtons } from '../components/blog/share-buttons';
+import { PostMeta } from '../components/blog/post-meta';
+import type { Page } from '../types/page';
+import { t, defaultThemeStrings } from '../strings/theme-strings';
+
+vi.mock('../hooks/use-auth-flow', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../hooks/use-auth-flow')>();
+  return {
+    ...actual,
+    useAuthFlow: () => (globalThis as unknown as { __flow: unknown }).__flow,
+  };
+});
+
+vi.mock('../hooks/use-auth', () => ({
+  useAuth: () => (globalThis as unknown as { __auth: unknown }).__auth,
+}));
+
+const G = globalThis as unknown as { __flow: unknown; __auth: unknown };
+
+function baseFlow(over: Record<string, unknown> = {}): void {
+  G.__flow = {
+    step: 'email-otp',
+    otp: '',
+    firstName: '',
+    lastName: '',
+    email: '',
+    password: '',
+    loading: false,
+    error: null,
+    setOtp: vi.fn(),
+    setFirstName: vi.fn(),
+    setLastName: vi.fn(),
+    setEmail: vi.fn(),
+    setPassword: vi.fn(),
+    submitEmailRequestOtp: vi.fn(),
+    submitEmailVerifyOtp: vi.fn(),
+    submitRegister: vi.fn(),
+    submitEmailLogin: vi.fn(),
+    submitEmailRegister: vi.fn(),
+    initiateGoogleAuth: vi.fn(),
+    reset: vi.fn(),
+    goToEmailOtp: vi.fn(),
+    goToEmailLogin: vi.fn(),
+    goToEmailRegister: vi.fn(),
+    ...over,
+  };
+}
+
+function signedOut(): void {
+  G.__auth = {
+    user: null,
+    isAuthenticated: false,
+    openAuthModal: vi.fn(),
+    logout: vi.fn(),
+  };
+}
+
+function signedIn(over: Record<string, unknown> = {}): void {
+  G.__auth = {
+    user: {
+      id: 'u1',
+      name: 'Adaeze Okafor',
+      first_name: 'Adaeze',
+      last_name: 'Okafor',
+      email: 'ada@example.com',
+      phone: '',
+      avatar: null,
+    },
+    isAuthenticated: true,
+    openAuthModal: vi.fn(),
+    logout: vi.fn(),
+    ...over,
+  };
+}
+
+const AVATAR_USER = {
+  id: 'u1',
+  name: 'Adaeze Okafor',
+  first_name: 'Adaeze',
+  last_name: 'Okafor',
+  email: 'ada@example.com',
+  phone: '',
+  avatar: 'https://cdn.example.com/a.png',
+};
+
+function render(children: ReactNode): string {
+  return renderToStaticMarkup(
+    <StorefrontProvider
+      vendor={{ id: 'v1', slug: 'demo-store', name: 'Demo Store' } as never}
+      config={{} as never}
+      menus={[]}
+    >
+      {children}
+    </StorefrontProvider>,
+  );
+}
+
+function PICK({ label }: { label: string }): JSX.Element {
+  return <span data-pick={label}>{label}</span>;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function shellProps(over: Record<string, unknown> = {}): any {
+  return {
+    cartItems: <PICK label="items" />,
+    deliveryModes: <PICK label="modes" />,
+    addressPicker: <PICK label="address" />,
+    deliverySourcePicker: null,
+    shippingZonePicker: <PICK label="zone" />,
+    schedulePicker: <PICK label="schedule" />,
+    paymentPicker: <PICK label="pay" />,
+    promoInput: <PICK label="promo" />,
+    noteInputs: <PICK label="notes" />,
+    feesBreakdown: <PICK label="fees" />,
+    deliveryMessage: null,
+    submitButton: <PICK label="submit" />,
+    activeTab: 'summary',
+    onTabChange: () => {},
+    totalCount: 0,
+    subtotal: 0,
+    currency: 'NGN',
+    mode: 'page',
+    policies: [],
+    ...over,
+  };
+}
+
+const POLICIES = [
+  { id: 'p1', slug: 'refund', type: 'page', title: 'Refund policy', content: [], excerpt: null, cover_image_url: null },
+  { id: 'p2', slug: 'shipping', type: 'page', title: 'Shipping policy', content: [], excerpt: null, cover_image_url: null },
+] as unknown as Page[];
+
+const CATS = [
+  { slug: 'news', name: 'News', posts_count: 4 },
+  { slug: 'recipes', name: 'Recipes' },
+];
+
+function post(over: Record<string, unknown> = {}): Record<string, unknown> {
+  return {
+    id: 'post1',
+    slug: 'hello-world',
+    type: 'post',
+    title: 'Hello world',
+    content: [],
+    excerpt: null,
+    cover_image_url: null,
+    author: { name: 'Adaeze Okafor', avatar_url: null },
+    published_at: '2026-09-15T12:00:00.000Z',
+    reading_time: 5,
+    ...over,
+  };
+}
+
+const REL = [
+  post({ id: 'r1', slug: 'p-one' }),
+  post({ id: 'r2', slug: 'p-two' }),
+];
+
+/** Every covered state: mock setup + element. Keys match the JSON fixture. */
+const STATES: Record<string, () => string> = {
+  'contact.out': () => { signedOut(); return render(<CheckoutContactSection />); },
+  'contact.in.initial': () => { signedIn(); return render(<CheckoutContactSection />); },
+  'contact.in.avatar': () => { signedIn({ user: AVATAR_USER }); return render(<CheckoutContactSection />); },
+
+  'shell.page.empty': () => { signedOut(); return render(<DefaultCheckoutShell {...shellProps({ totalCount: 0 })} />); },
+  'shell.page.full': () => { signedOut(); return render(<DefaultCheckoutShell {...shellProps({ totalCount: 3, subtotal: 4500, policies: POLICIES })} />); },
+  'shell.page.minimal': () => { signedOut(); return render(<DefaultCheckoutShell {...shellProps({ totalCount: 2, subtotal: 1000, addressPicker: null, shippingZonePicker: null, schedulePicker: null, deliveryMessage: { type: 'warning', message: 'Slow courier' } })} />); },
+  'shell.panel.summary.empty': () => { signedOut(); return render(<DefaultCheckoutShell {...shellProps({ mode: 'panel', activeTab: 'summary', totalCount: 0 })} />); },
+  'shell.panel.summary.items3': () => { signedOut(); return render(<DefaultCheckoutShell {...shellProps({ mode: 'panel', activeTab: 'summary', totalCount: 3, subtotal: 4500 })} />); },
+  'shell.panel.summary.items1': () => { signedOut(); return render(<DefaultCheckoutShell {...shellProps({ mode: 'panel', activeTab: 'summary', totalCount: 1, subtotal: 1500 })} />); },
+  'shell.panel.checkout': () => { signedOut(); return render(<DefaultCheckoutShell {...shellProps({ mode: 'panel', activeTab: 'checkout', totalCount: 2, subtotal: 2000 })} />); },
+
+  'policies.empty': () => { signedOut(); return render(<PolicyLinks policies={[]} />); },
+  'policies.list': () => { signedOut(); return render(<PolicyLinks policies={POLICIES} />); },
+
+  'login.default': () => { baseFlow(); return render(<AuthEmailLoginStep />); },
+  'login.loading': () => { baseFlow({ loading: true, email: 'ada@example.com', password: 'secret123' }); return render(<AuthEmailLoginStep />); },
+  'login.error': () => { baseFlow({ email: 'ada@example.com', password: 'secret123', error: 'Wrong email or password. Please try again.' }); return render(<AuthEmailLoginStep />); },
+
+  'otp.default': () => { baseFlow(); return render(<AuthEmailOtpStep />); },
+  'otp.loading': () => { baseFlow({ loading: true, email: 'ada@example.com' }); return render(<AuthEmailOtpStep />); },
+  'otp.error': () => { baseFlow({ email: 'ada@example.com', error: 'Something went wrong. Please try again.' }); return render(<AuthEmailOtpStep />); },
+
+  'verify.empty': () => { baseFlow({ email: 'ada@example.com', otp: '' }); return render(<AuthEmailOtpVerifyStep />); },
+  'verify.partial': () => { baseFlow({ email: 'ada@example.com', otp: '123' }); return render(<AuthEmailOtpVerifyStep />); },
+  'verify.loading': () => { baseFlow({ email: 'ada@example.com', otp: '123456', loading: true }); return render(<AuthEmailOtpVerifyStep />); },
+  'verify.error': () => { baseFlow({ email: 'ada@example.com', otp: '12', error: 'Incorrect code. Please try again.' }); return render(<AuthEmailOtpVerifyStep />); },
+
+  'register.default': () => { baseFlow(); return render(<AuthEmailRegisterStep />); },
+  'register.loading': () => { baseFlow({ loading: true, firstName: 'Adaeze', email: 'ada@example.com', password: 'secret123' }); return render(<AuthEmailRegisterStep />); },
+  'register.error': () => { baseFlow({ firstName: 'Adaeze', email: 'ada@example.com', password: 'secret123', error: 'Email already registered. Please sign in instead.' }); return render(<AuthEmailRegisterStep />); },
+
+  'signup.default': () => { baseFlow(); return render(<AuthSignupStep />); },
+  'signup.loading': () => { baseFlow({ loading: true, firstName: 'Adaeze', lastName: 'Okafor' }); return render(<AuthSignupStep />); },
+  'signup.error': () => { baseFlow({ firstName: 'Adaeze', error: 'Please enter your first name.' }); return render(<AuthSignupStep />); },
+
+  'filter.pills': () => render(<CategoryFilter categories={CATS} />),
+  'filter.pills.active': () => render(<CategoryFilter categories={CATS} active="news" />),
+  'filter.tabs': () => render(<CategoryFilter categories={CATS} variant="tabs" />),
+  'filter.tabs.active': () => render(<CategoryFilter categories={CATS} variant="tabs" active="recipes" />),
+  'filter.empty': () => render(<CategoryFilter categories={[]} />),
+  'filter.null': () => render(<CategoryFilter categories={null} />),
+
+  'page.mid': () => render(<BlogPagination pagination={{ current_page: 2, per_page: 12, has_more: true }} category="news" />),
+  'page.last': () => render(<BlogPagination pagination={{ current_page: 4, has_more: false }} />),
+  'page.first.next': () => render(<BlogPagination pagination={{ current_page: 1, has_more: true }} />),
+  'page.lone': () => render(<BlogPagination pagination={{ current_page: 1, has_more: false }} />),
+  'page.unset': () => render(<BlogPagination pagination={undefined} />),
+
+  'related.default': () => render(<RelatedPosts posts={REL as never} />),
+  'related.custom': () => render(<RelatedPosts posts={REL as never} heading="Keep reading" />),
+  'related.empty': () => render(<RelatedPosts posts={[]} />),
+  'related.null': () => render(<RelatedPosts posts={null} />),
+
+  'share.default': () => render(<ShareButtons title="Hello world" />),
+
+  'meta.full': () => render(<PostMeta post={post() as never} />),
+  'meta.reading1': () => render(<PostMeta post={post({ reading_time: 1 }) as never} />),
+  'meta.noauthor': () => render(<PostMeta post={post({ author: null }) as never} />),
+  'meta.minimal': () => render(<PostMeta post={post({ author: null, published_at: null, reading_time: 0 }) as never} />),
+};
+
+const root = dirname(fileURLToPath(import.meta.url));
+const BASELINES = JSON.parse(
+  readFileSync(join(root, 'fixtures', 'shopper-chrome-baseline.json'), 'utf-8'),
+) as Record<string, string>;
+
+describe('shopper chrome English safety (checkout/auth/blog)', () => {
+  it('covers every baseline state (fixture and STATES map stay in sync)', () => {
+    expect(Object.keys(STATES).sort()).toEqual(Object.keys(BASELINES).sort());
+  });
+
+  for (const [name, renderState] of Object.entries(STATES)) {
+    it(`${name}: byte-identical to the stored OLD markup`, () => {
+      expect(renderState()).toBe(BASELINES[name]);
+    });
+  }
+
+  // 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.
+  it("share.copied: English value pinned ('Copied')", () => {
+    expect(t(defaultThemeStrings, 'blog.share.copied')).toBe('Copied');
+  });
+});

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

@@ -0,0 +1,179 @@
+/**
+ * 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 /
+ * try / switch / && / ||, no early return before it, and never nested inside
+ * another function (e.g. a `.map` callback). Violations break the Rules of
+ * Hooks and silently untranslate strings, so this test FAILS when broken.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import ts from 'typescript';
+
+const kitRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+
+// 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',
+  'components/checkout/policy-links.tsx',
+  'components/auth/auth-email-login-step.tsx',
+  'components/auth/auth-email-otp-step.tsx',
+  'components/auth/auth-email-otp-verify-step.tsx',
+  'components/auth/auth-email-register-step.tsx',
+  'components/auth/auth-signup-step.tsx',
+  'components/blog/category-filter.tsx',
+  'components/blog/pagination.tsx',
+  'components/blog/post-meta.tsx',
+  'components/blog/related-posts.tsx',
+  'components/blog/share-buttons.tsx',
+  'hooks/use-auth-flow.tsx',
+];
+
+function listTsx(dir: string): string[] {
+  const out: string[] = [];
+  for (const entry of readdirSync(dir)) {
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) out.push(...listTsx(full));
+    else if (entry.endsWith('.tsx')) out.push(full);
+  }
+  return out;
+}
+
+const NAME_RE = /^[A-Z][A-Za-z0-9]*$|^use[A-Z]/;
+
+interface CallSite {
+  file: string;
+  line: number;
+  problems: string[];
+}
+
+function enclosingName(fn: ts.Node): string | null {
+  if (ts.isFunctionDeclaration(fn)) return fn.name?.text ?? null;
+  if (ts.isMethodDeclaration(fn)) return ts.isIdentifier(fn.name) ? fn.name.text : null;
+  if ((ts.isArrowFunction(fn) || ts.isFunctionExpression(fn)) && ts.isVariableDeclaration(fn.parent)) {
+    return fn.parent.name.getText();
+  }
+  return null;
+}
+
+function isTopLevelFunction(fn: ts.Node): boolean {
+  if (ts.isFunctionDeclaration(fn)) return ts.isSourceFile(fn.parent);
+  if (ts.isArrowFunction(fn) || ts.isFunctionExpression(fn)) {
+    return (
+      ts.isVariableDeclaration(fn.parent) &&
+      ts.isVariableDeclarationList(fn.parent.parent) &&
+      ts.isVariableStatement(fn.parent.parent.parent) &&
+      ts.isSourceFile(fn.parent.parent.parent.parent)
+    );
+  }
+  return false;
+}
+
+function checkFile(rel: string): CallSite[] {
+  const src = readFileSync(join(kitRoot, rel), 'utf8');
+  const sf = ts.createSourceFile(rel, src, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
+  const sites: CallSite[] = [];
+  const stack: ts.Node[] = [];
+
+  function pushFn(node: ts.Node): void {
+    stack.push(node);
+    ts.forEachChild(node, visit);
+    stack.pop();
+  }
+
+  function visit(node: ts.Node): void {
+    if (
+      ts.isFunctionDeclaration(node) ||
+      ts.isFunctionExpression(node) ||
+      ts.isArrowFunction(node) ||
+      ts.isMethodDeclaration(node)
+    ) {
+      pushFn(node);
+      return;
+    }
+    if (
+      ts.isCallExpression(node) &&
+      ts.isIdentifier(node.expression) &&
+      node.expression.text === 'useThemeStrings'
+    ) {
+      const problems: string[] = [];
+      const enclosing = stack.length > 0 ? stack[stack.length - 1] : null;
+      if (!enclosing || stack.length !== 1) {
+        problems.push('not directly inside one top-level function (nested callback?)');
+      } else {
+        const name = enclosingName(enclosing);
+        if (!name || !NAME_RE.test(name)) problems.push(`enclosing function '${name ?? '<anonymous>'}' is not a PascalCase component or use* hook`);
+        if (!isTopLevelFunction(enclosing)) problems.push('enclosing function is not a module top-level declaration');
+        let p: ts.Node = node.parent;
+        while (p && p !== enclosing) {
+          if (
+            ts.isIfStatement(p) ||
+            ts.isConditionalExpression(p) ||
+            ts.isForStatement(p) ||
+            ts.isForInStatement(p) ||
+            ts.isForOfStatement(p) ||
+            ts.isWhileStatement(p) ||
+            ts.isDoStatement(p) ||
+            ts.isTryStatement(p) ||
+            ts.isCatchClause(p) ||
+            ts.isSwitchStatement(p) ||
+            ts.isCaseClause(p) ||
+            ts.isDefaultClause(p) ||
+            (ts.isBinaryExpression(p) &&
+              (p.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken ||
+                p.operatorToken.kind === ts.SyntaxKind.BarBarToken))
+          ) {
+            problems.push(`conditionally enclosed by ${ts.SyntaxKind[p.kind]}`);
+            break;
+          }
+          p = p.parent;
+        }
+        const body = (enclosing as ts.FunctionLikeDeclaration).body;
+        if (body && ts.isBlock(body)) {
+          let host: ts.Node = node;
+          while (host.parent && host.parent !== body) host = host.parent;
+          for (const stmt of body.statements) {
+            if (stmt === host) break;
+            if (ts.isReturnStatement(stmt)) {
+              problems.push('an early return precedes the hook call');
+              break;
+            }
+          }
+        }
+      }
+      const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf));
+      sites.push({ file: rel, line: line + 1, problems });
+      return;
+    }
+    ts.forEachChild(node, visit);
+  }
+
+  visit(sf);
+  return sites;
+}
+
+const scopeFiles = listTsx(join(kitRoot, 'components'))
+  .concat(listTsx(join(kitRoot, 'hooks')))
+  .map((f) => f.slice(kitRoot.length + 1));
+
+describe('useThemeStrings() placement (Rules of Hooks)', () => {
+  it('every migrated file calls useThemeStrings() exactly once', () => {
+    for (const rel of EXPECTED_FILES) {
+      expect(checkFile(rel).length, `${rel}: expected exactly one call`).toBe(1);
+    }
+  });
+
+  it('every call in components/ + hooks/ is top-level in a component or hook', () => {
+    const bad: string[] = [];
+    for (const rel of scopeFiles) {
+      for (const site of checkFile(rel)) {
+        for (const problem of site.problems) bad.push(`${site.file}:${site.line}: ${problem}`);
+      }
+    }
+    expect(bad, bad.join('\n')).toEqual([]);
+  });
+});

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,
     };