@usequeek/theme-kit 0.1.19 → 0.1.21

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

@@ -0,0 +1,272 @@
+/**
+ * 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.
+ */
+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: 'kili-foods', name: 'Kili Foods' } 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]);
+    });
+  }
+
+  // S4 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/theme-hook-placement.test.tsx

@@ -0,0 +1,179 @@
+/**
+ * Hook-placement rule (checkout / auth / blog slice) — S2 enforcement.
+ *
+ * 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 this slice migrated: 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-pseudo.test.tsx

@@ -0,0 +1,171 @@
+import { renderToStaticMarkup } from 'react-dom/server';
+import type { JSX, ReactNode } from 'react';
+import { describe, expect, it } from 'vitest';
+import enDefault from '../locales/en.default.json';
+import { StorefrontProvider, useThemeStrings } from '../provider';
+import { defaultThemeStrings, t, type ThemeStringsDictionary } from '../strings/theme-strings';
+import {
+  assertNoEnglishLeak,
+  findEnglishLeaks,
+  isPseudoLocalized,
+  pseudoLocalize,
+  pseudoLocalizeText,
+} from '../strings/pseudo-locale';
+
+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}
+      config={{} as never}
+      menus={[]}
+      {...(strings ? { strings } : {})}
+    >
+      {children}
+    </StorefrontProvider>,
+  );
+}
+
+function Title(): JSX.Element {
+  const t = useThemeStrings();
+  return <h1>{t('cart.title')}</h1>;
+}
+
+describe('pseudoLocalize (pure dictionary transform)', () => {
+  it('accent-maps, expands ~30% and wraps in markers', () => {
+    expect(pseudoLocalizeText('Your cart')).toBe('[!! Ÿòùŕ çàŕţ~~~ !!]');
+  });
+
+  it('preserves {placeholders} byte-for-byte and still interpolates', () => {
+    const pseudo = pseudoLocalizeText('{count} items');
+    expect(pseudo).toBe('[!! {count} ìţèṁš~~~~ !!]');
+    expect(pseudo).toContain('{count}');
+    expect(t([{ v: pseudo }], 'v', { count: 3 }, 'en')).toBe('[!! 3 ìţèṁš~~~~ !!]');
+  });
+
+  it('preserves `{{` / `}}` escapes (structure survives, literal is pseudo)', () => {
+    const pseudo = pseudoLocalizeText('a {{b}} c');
+    expect(pseudo).toContain('{{');
+    expect(pseudo).toContain('}}');
+    // Same interpolation behaviour as the source: escapes still escape.
+    expect(t([{ v: pseudo }], 'v', {}, 'en')).toBe('[!! à {ƀ} ç~~~ !!]');
+  });
+
+  it('keeps plural-map shape (one key, every form pseudo)', () => {
+    const dict: ThemeStringsDictionary = {
+      items: { count: { one: '{count} item', other: '{count} items' } },
+    };
+    const pseudo = pseudoLocalize(dict);
+    expect(Object.keys((pseudo['items'] as Record<string, unknown>)['count'] as object)).toEqual([
+      'one',
+      'other',
+    ]);
+    const forms = (pseudo['items'] as { count: { one: string; other: string } }).count;
+    expect(forms.one).toContain('{count}');
+    expect(isPseudoLocalized(forms.one)).toBe(true);
+    expect(isPseudoLocalized(forms.other)).toBe(true);
+    // t() still selects forms from the pseudo dictionary.
+    expect(t([pseudo], 'items.count', { count: 1 }, 'en')).toContain('1');
+    expect(t([pseudo], 'items.count', { count: 5 }, 'en')).toContain('5');
+  });
+
+  it('recurses nested objects and never touches keys (incl. flat dotted keys)', () => {
+    const dict = {
+      cart: { title: 'Your cart', empty: { message: 'Your cart is empty.' } },
+      'flat.key': 'Flat value',
+    } as unknown as ThemeStringsDictionary;
+    const pseudo = pseudoLocalize(dict);
+    expect(Object.keys(pseudo).sort()).toEqual(['cart', 'flat.key']);
+    expect(Object.keys(pseudo['cart'] as object).sort()).toEqual(['empty', 'title']);
+    expect(t([pseudo], 'flat.key')).toBe(pseudoLocalizeText('Flat value'));
+  });
+
+  it('leaves empty values empty (an intentional empty renders no node)', () => {
+    expect(pseudoLocalizeText('')).toBe('');
+    const pseudo = pseudoLocalize({ hidden: { label: '' } });
+    expect((pseudo['hidden'] as { label: string }).label).toBe('');
+  });
+
+  it('expands very long values by ~30% (1000-char budget value)', () => {
+    const long = 'a'.repeat(1000);
+    const pseudo = pseudoLocalizeText(long);
+    const core = pseudo.slice('[!! '.length, -' !!]'.length);
+    expect(core.length).toBe(1000 + Math.round(1000 * 0.3));
+  });
+
+  it('leaves unicode (non-Latin, emoji) intact, wrapped', () => {
+    const pseudo = pseudoLocalizeText('こんにちは世界 🛒');
+    expect(pseudo).toContain('こんにちは世界');
+    expect(pseudo).toContain('🛒');
+    expect(isPseudoLocalized(pseudo)).toBe(true);
+  });
+
+  it('rtl option wraps the core in U+202B … U+202C', () => {
+    const pseudo = pseudoLocalizeText('Your cart', { rtl: true });
+    expect(pseudo.includes('\u202B')).toBe(true);
+    expect(pseudo.includes('\u202C')).toBe(true);
+    expect(isPseudoLocalized(pseudo)).toBe(true);
+  });
+
+  it('custom markers are honoured by the scan', () => {
+    const pseudo = pseudoLocalizeText('Your cart', { prefix: '‹', suffix: '›' });
+    expect(pseudo.startsWith('‹')).toBe(true);
+    expect(isPseudoLocalized(pseudo)).toBe(false);
+    expect(isPseudoLocalized(pseudo, { prefix: '‹', suffix: '›' })).toBe(true);
+    expect(findEnglishLeaks(`<h1>${pseudo}</h1>`, { pseudo: { prefix: '‹', suffix: '›' } })).toEqual(
+      [],
+    );
+  });
+});
+
+describe('English leak scan (reusable theme-test primitive)', () => {
+  it('a fully pseudo render is clean', () => {
+    const html = render(<Title />, pseudoLocalize(EN));
+    expect(html).not.toContain('Your cart');
+    expect(findEnglishLeaks(html)).toEqual([]);
+    expect(() => assertNoEnglishLeak(html)).not.toThrow();
+  });
+
+  it('a hard-coded English string is reported (the control that proves the scan fails)', () => {
+    function Leaky(): JSX.Element {
+      const t = useThemeStrings();
+      return (
+        <main>
+          <h1>{t('cart.title')}</h1>
+          <p>Hard-coded checkout copy</p>
+        </main>
+      );
+    }
+    const html = render(<Leaky />, pseudoLocalize(EN));
+    expect(findEnglishLeaks(html)).toEqual(['Hard-coded checkout copy']);
+    expect(() => assertNoEnglishLeak(html)).toThrow(/Hard-coded checkout copy/);
+  });
+
+  it('flags hard-coded user-visible attributes (aria-label, placeholder)', () => {
+    const html = `<button aria-label="Close dialog">×</button><input placeholder="Search products" />`;
+    expect(findEnglishLeaks(html)).toEqual(['Close dialog', 'Search products']);
+    expect(findEnglishLeaks(html, { includeAttributes: false })).toEqual([]);
+  });
+
+  it('ignores numbers, symbols and pseudo-wrapped attributes', () => {
+    const html = render(<Title />, pseudoLocalize(EN));
+    expect(findEnglishLeaks(`<span>₦5,000</span><span>2 / 5</span>${html}`)).toEqual([]);
+  });
+
+  it('allowlists brand names and codes', () => {
+    const html = `<footer><span>${pseudoLocalizeText('Powered by')}</span><span>Queek</span></footer>`;
+    expect(findEnglishLeaks(html)).toEqual(['Queek']);
+    expect(findEnglishLeaks(html, { allowlist: ['Queek'] })).toEqual([]);
+    expect(findEnglishLeaks(html, { allowlist: [/^Q/] })).toEqual([]);
+  });
+
+  it('pseudo of the real English default keeps every key (renamed-key drift fails here)', () => {
+    const pseudo = pseudoLocalize(EN);
+    expect(Object.keys(pseudo).sort()).toEqual(Object.keys(EN).sort());
+    // Spot values still resolve through t() — a changed English default that
+    // was not rebuilt into pseudo expectations fails loudly, never silently.
+    expect(t([pseudo], 'cart.title')).toBe(pseudoLocalizeText('Your cart'));
+    expect(t([defaultThemeStrings], 'cart.title')).toBe('Your cart');
+  });
+});