@usequeek/theme-kit 0.1.18 → 0.1.20

package/README.md

@@ -70,11 +70,21 @@ provider that passes nothing renders exactly as today, in English.
   plus `useThemeStrings()` returning the same bound `t`; works inside
   `ThemeMount`. The kit ships `locales/en.default.json` (cart, checkout,
   auth, blog) as the last-resort English default.
-- **Fallback.** Ordered dictionaries (override → theme → core → English
-  default); first hit wins. The last fallback is the English default
-  *value* — never the raw key, never "translation missing". Absent
-  everywhere renders `""` (and warns once per key in development only —
-  an empty string would otherwise leak internal key names into the UI).
+- **Fallback.** Ordered dictionaries (merchant override → host-loaded
+  locale dictionaries → `manifest.strings` → kit core English default);
+  first hit wins. The last fallback is the English default *value* —
+  never the raw key, never "translation missing". Absent everywhere
+  renders `""` (and warns once per key in development only — an empty
+  string would otherwise leak internal key names into the UI).
+- **Theme English travels with the theme.** A theme ships its own English
+  defaults in its manifest: `import strings from './locales/en.default.json'`
+  inside the theme, then `manifest: { …, strings }` (`ThemeManifest.strings`,
+  ENGLISH ONLY — never other locales). `useThemeStrings()` layers it
+  between the host's `strings` prop and the kit core English, so hosts that
+  mount a theme with no `strings` (e.g. theme previews) still render the
+  theme's English with zero host cooperation. Host dictionaries always win
+  where present; keys missing there fall back to manifest English, never
+  to `""`.
 - **Per-locale loading.** `createThemeStrings` reads ONLY the active
   locale's dictionaries, and the host passes ONLY that locale to the
   provider — other `{lang}.json` files never enter the client bundle.
@@ -193,7 +203,10 @@ export default function Footer() {
   it — style the classes in your theme.
 - The href (`https://usequeek.com/business`), `target="_blank"` and
   `rel="noopener noreferrer"` are the contract — never re-implement the
-  markup by hand.
+  markup by hand. The href is tagged for attribution by `poweredByQueekUrl`
+  (`utm_source=powered_by&utm_medium=storefront&utm_campaign=<store slug>`,
+  campaign omitted when the store has no slug); the component reads the slug
+  from the storefront context, so themes pass nothing.
 - `hidden` (default false) takes the component's visibility from a prop as
   the seam for a possible future plan perk. There is no merchant-facing
   toggle for it in v1 — always render it visible.

package/components/powered-by-queek.tsx

@@ -1,4 +1,8 @@
-import type { JSX } from 'react';
+'use client';
+
+import { useContext, type JSX } from 'react';
+import { StorefrontContext } from '../provider';
+import { poweredByQueekUrl } from '../utils/powered-by';
 
 export interface PoweredByQueekProps {
   /** Extra class so a footer can position the link — styling stays theme-owned. */
@@ -17,15 +21,20 @@ export interface PoweredByQueekProps {
  * Required on every footer variant of every theme (enforced by `theme-check`
  * rule `theme/footer-shows-powered-by` in the storefront repo). The link
  * target (`https://usequeek.com/business`) and `rel` are the contract —
- * do not change them. Markup carries `core-powered-by` classes so each theme
+ * do not change them. The href is tagged `utm_source=powered_by`,
+ * `utm_medium=storefront`, `utm_campaign=<store slug>` via `poweredByQueekUrl`
+ * (read from the storefront context, so themes pass nothing; no provider means
+ * no campaign, never an error). Markup carries `core-powered-by` classes so each theme
  * styles it in its own `theme.css`; no kit CSS ships for it.
  */
 export function PoweredByQueek({ className, hidden = false }: PoweredByQueekProps): JSX.Element | null {
+  const vendor = useContext(StorefrontContext)?.vendor;
+
   if (hidden) return null;
 
   return (
     <a
-      href="https://usequeek.com/business"
+      href={poweredByQueekUrl(vendor?.slug)}
       target="_blank"
       rel="noopener noreferrer"
       className={className ? `core-powered-by ${className}` : 'core-powered-by'}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "private": false,
   "license": "MIT",
   "description": "The framework a Queek storefront theme is built against.",

package/provider.tsx

@@ -17,6 +17,7 @@ import {
   type ThemeStringsVars,
 } from './strings/theme-strings';
 import { DesignTokenPreviewListener } from './design-token-preview';
+import { useOptionalTheme } from './theme-context';
 
 export interface StorefrontPreviewData {
   products?: Product[];
@@ -48,8 +49,10 @@ interface StorefrontContextValue {
    * `useStorefrontLocale()` and send `?locale=` when it is set. */
   locale: string | null;
   /** Active locale's dictionaries (override, theme, core — the host merges and
-   * passes ONLY the active locale). Empty = English defaults only. */
-  strings: ThemeStringsDictionary[];
+   * passes ONLY the active locale). Empty or omitted = English defaults only.
+   * Optional so hand-built context values (storefront scripts, tests) keep
+   * compiling without it. */
+  strings?: ThemeStringsDictionary[];
 }
 
 export const StorefrontContext = createContext<StorefrontContextValue | null>(null);
@@ -151,11 +154,15 @@ export function useStorefrontLocale(): string | null {
 }
 
 /**
- * The client theme-string surface: the bound `t` for the active locale
- * (`strings` prop, then the English default — never the raw key). Works in
- * themes mounted by `ThemeMount` (which renders inside the host's provider).
- * No `strings` prop → the English defaults, so kit components render exactly
- * as before and third-party themes keep working untranslated.
+ * The client theme-string surface: the bound `t` for the active locale.
+ * Chain order: merchant/host override dictionaries (`strings` prop), then
+ * the mounted theme's `manifest.strings` (theme English — travels WITH the
+ * theme, so preview hosts that pass no `strings` still render English),
+ * then the kit core English default — never the raw key. Works in themes
+ * mounted by `ThemeMount` and in hosts that provide the theme directly
+ * (both expose it through the theme context). No `strings` prop and no
+ * manifest → the English defaults, so kit components render exactly as
+ * before and third-party themes keep working untranslated.
  */
 export function useThemeStrings(): ThemeStringsFn {
   const context = useContext(StorefrontContext);
@@ -164,16 +171,18 @@ export function useThemeStrings(): ThemeStringsFn {
     throw new Error('useThemeStrings must be used within StorefrontProvider');
   }
 
+  const theme = useOptionalTheme();
+  const manifestStrings = theme?.manifest?.strings ?? null;
   const { strings, locale } = context;
   return useMemo(
     () =>
       (key: string, vars?: ThemeStringsVars, overrideLocale?: string | null) =>
         translateThemeStrings(
-          [...strings, defaultThemeStrings],
+          [...(strings ?? []), ...(manifestStrings ? [manifestStrings] : []), defaultThemeStrings],
           key,
           vars,
           overrideLocale ?? locale ?? undefined,
         ),
-    [strings, locale],
+    [strings, manifestStrings, locale],
   );
 }

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

@@ -2,9 +2,18 @@ import React from 'react';
 import { renderToStaticMarkup } from 'react-dom/server';
 import { describe, expect, it } from 'vitest';
 import { PoweredByQueek } from '../components/powered-by-queek';
+import { StorefrontContext } from '../provider';
 
-function render(props?: { className?: string; hidden?: boolean }): string {
-  return renderToStaticMarkup(React.createElement(PoweredByQueek, props));
+const BASE = 'https://usequeek.com/business?utm_source=powered_by&utm_medium=storefront';
+
+function render(props?: { className?: string; hidden?: boolean }, vendor?: { id: string; slug: string | null }): string {
+  const element = React.createElement(PoweredByQueek, props);
+
+  if (!vendor) return renderToStaticMarkup(element);
+
+  return renderToStaticMarkup(
+    React.createElement(StorefrontContext.Provider, { value: { vendor } as never }, element),
+  );
 }
 
 describe('PoweredByQueek', () => {
@@ -12,11 +21,29 @@ describe('PoweredByQueek', () => {
     const html = render();
 
     expect(html).toContain('<a');
-    expect(html).toContain('href="https://usequeek.com/business"');
+    expect(html).toContain(`href="${BASE}"`);
     expect(html).toContain('target="_blank"');
     expect(html).toContain('rel="noopener noreferrer"');
   });
 
+  it('tags the link with the store slug as utm_campaign', () => {
+    const html = render(undefined, { id: 'uuid-1', slug: 'kili-foods' });
+
+    expect(html).toContain(`href="${BASE}&amp;utm_campaign=kili-foods"`);
+    expect(html).toContain('rel="noopener noreferrer"');
+  });
+
+  it('omits utm_campaign (never the internal UUID) when the store has no slug', () => {
+    const html = render(undefined, { id: 'uuid-1', slug: null });
+
+    expect(html).not.toContain('utm_campaign');
+    expect(html).not.toContain('uuid-1');
+  });
+
+  it('omits utm_campaign (never errors) when no storefront provider is mounted', () => {
+    expect(render()).not.toContain('utm_campaign');
+  });
+
   it('renders "Powered by Queek" with the brand hook for theme styling', () => {
     const html = render();
 
@@ -33,5 +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('');
   });
 });

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

@@ -0,0 +1,49 @@
+import { describe, expect, it } from 'vitest';
+import { POWERED_BY_QUEEK_URL, poweredByQueekUrl } from '../utils/powered-by';
+
+function params(url: string): Record<string, string> {
+  return Object.fromEntries(new URL(url).searchParams.entries());
+}
+
+describe('poweredByQueekUrl', () => {
+  it('keeps the business-page destination and adds source, medium and campaign', () => {
+    const url = poweredByQueekUrl('kili-foods');
+
+    expect(url.startsWith(`${POWERED_BY_QUEEK_URL}?`)).toBe(true);
+    expect(params(url)).toEqual({
+      utm_source: 'powered_by',
+      utm_medium: 'storefront',
+      utm_campaign: 'kili-foods',
+    });
+  });
+
+  it.each([undefined, null, '', '   '])('omits utm_campaign for a blank campaign (%j)', (campaign) => {
+    expect(params(poweredByQueekUrl(campaign))).toEqual({
+      utm_source: 'powered_by',
+      utm_medium: 'storefront',
+    });
+  });
+
+  it('preserves an existing query and overrides only its own utm keys', () => {
+    const url = poweredByQueekUrl('shop-1', 'https://usequeek.com/business?plan=pro&utm_source=old&utm_campaign=stale');
+
+    expect(params(url)).toEqual({
+      plan: 'pro',
+      utm_source: 'powered_by',
+      utm_medium: 'storefront',
+      utm_campaign: 'shop-1',
+    });
+  });
+
+  it('drops a stale utm_campaign when the new campaign is blank', () => {
+    expect(params(poweredByQueekUrl(null, 'https://usequeek.com/business?utm_campaign=stale'))).not.toHaveProperty('utm_campaign');
+  });
+
+  it('url-encodes the campaign and is deterministic (SSR-safe, no window/Date)', () => {
+    const url = poweredByQueekUrl('a b&c');
+
+    expect(url).toContain('utm_campaign=a+b%26c');
+    expect(params(url).utm_campaign).toBe('a b&c');
+    expect(poweredByQueekUrl('a b&c')).toBe(url);
+  });
+});

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

@@ -1,12 +1,13 @@
 import { renderToStaticMarkup } from 'react-dom/server';
-import { describe, expect, it } from 'vitest';
+import { describe, expect, it, vi } from 'vitest';
 import type { JSX, ReactNode } from 'react';
-import { StorefrontProvider, useThemeStrings } from '../provider';
+import { StorefrontContext, StorefrontProvider, useThemeStrings } from '../provider';
 import { ThemeMount } from '../theme-mount';
 import { DefaultCartShell } from '../components/cart/default-cart-shell';
 import { defaultThemeStrings, t as translate, type ThemeStringsDictionary } from '../strings/theme-strings';
 import type { CartItem } from '../types/cart';
 import type { ThemeModule } from '../types/theme';
+import type { StorefrontConfig, VendorProfile } from '../types/vendor';
 
 const FR_STRINGS: ThemeStringsDictionary = {
   cart: {
@@ -104,6 +105,133 @@ describe('client surface through ThemeMount', () => {
   });
 });
 
+describe('manifest.strings travels with the theme (decision 15)', () => {
+  const MANIFEST_EN: ThemeStringsDictionary = {
+    theme: {
+      hero: { title: 'Fresh from the farm' },
+      lines: { count: { one: '{count} line', other: '{count} lines' } },
+    },
+  };
+
+  function ManifestHero(): JSX.Element {
+    const t = useThemeStrings();
+    return (
+      <header>
+        <h1>{t('theme.hero.title')}</h1>
+        <p>{t('theme.lines.count', { count: 1 })}</p>
+        <p>{t('theme.lines.count', { count: 5 })}</p>
+        <span>{t('cart.title')}</span>
+      </header>
+    );
+  }
+
+  function themeWithManifest(strings?: ThemeStringsDictionary): ThemeModule {
+    return {
+      Layout: ({ children }: { children: ReactNode }) => <div>{children}</div>,
+      Header: ManifestHero,
+      Footer: () => <footer />,
+      blocks: {},
+      getHeader: () => ManifestHero,
+      getFooter: () => (() => <footer />),
+      getBlock: () => (() => null),
+      pages: {},
+      manifest: strings
+        ? { name: 'manifest-theme', slug: 'manifest-theme', description: '', version: '0', strings }
+        : { name: 'manifest-theme', slug: 'manifest-theme', description: '', version: '0' },
+    } as unknown as ThemeModule;
+  }
+
+  function mount(
+    theme: ThemeModule,
+    options?: { locale?: string | null; strings?: ThemeStringsDictionary | ThemeStringsDictionary[] | null },
+  ): string {
+    return render(
+      <ThemeMount theme={theme} headerProps={{ menu: [], announcement: null }} footerProps={{}}>
+        <p>page</p>
+      </ThemeMount>,
+      options,
+    );
+  }
+
+  it('(a) renders theme + kit core English with NO provider strings prop', () => {
+    const html = mount(themeWithManifest(MANIFEST_EN));
+    expect(html).toContain('<h1>Fresh from the farm</h1>');
+    expect(html).toContain('<p>1 line</p>');
+    expect(html).toContain('<p>5 lines</p>');
+    // The manifest says nothing about kit keys: kit core English still renders.
+    expect(html).toContain('<span>Your cart</span>');
+  });
+
+  it('(b) manifest beats kit core English', () => {
+    const html = mount(
+      themeWithManifest({ ...MANIFEST_EN, cart: { title: 'Theme cart title' } }),
+    );
+    expect(html).toContain('<span>Theme cart title</span>');
+    expect(html).not.toContain('<span>Your cart</span>');
+  });
+
+  it('(b) host override beats manifest', () => {
+    const html = mount(themeWithManifest({ ...MANIFEST_EN, cart: { title: 'Theme cart title' } }), {
+      strings: { cart: { title: 'Host cart title' } },
+    });
+    expect(html).toContain('<span>Host cart title</span>');
+  });
+
+  it('(b) first host dictionary wins (merchant override position)', () => {
+    const html = mount(themeWithManifest({ ...MANIFEST_EN, cart: { title: 'Theme cart title' } }), {
+      strings: [{ cart: { title: 'First' } }, { cart: { title: 'Second' } }],
+    });
+    expect(html).toContain('<span>First</span>');
+  });
+
+  it('(c) non-English host dict falls back per key to manifest English, never empty', () => {
+    const html = mount(themeWithManifest(MANIFEST_EN), {
+      locale: 'fr',
+      strings: { cart: { title: 'Votre panier' } },
+    });
+    expect(html).toContain('<span>Votre panier</span>');
+    expect(html).toContain('<h1>Fresh from the farm</h1>');
+    expect(html).not.toContain('<h1></h1>');
+  });
+
+  it('(d) manifest without strings behaves exactly as 0.1.18', () => {
+    const warn = vi.spyOn(console, 'warn').mockImplementation(() => {});
+    try {
+      const html = mount(themeWithManifest());
+      // Theme key absent everywhere: empty + one dev warning, as in 0.1.18.
+      expect(html).toContain('<h1></h1>');
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining('theme.hero.title'));
+      // Kit key: English default, unchanged.
+      expect(html).toContain('<span>Your cart</span>');
+    } finally {
+      warn.mockRestore();
+    }
+  });
+
+  it('(e) a hand-built context value without strings type-checks and renders kit English', () => {
+    function Probe(): JSX.Element {
+      const t = useThemeStrings();
+      return <h1>{t('cart.title')}</h1>;
+    }
+    // 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,
+      config: { theme: 'stub', brand: {} } as StorefrontConfig,
+      menus: [],
+      basePath: '/kili-foods',
+      pagesChrome: {},
+      locale: null,
+    };
+    const html = renderToStaticMarkup(
+      <StorefrontContext.Provider value={value}>
+        <Probe />
+      </StorefrontContext.Provider>,
+    );
+    expect(html).toContain('<h1>Your cart</h1>');
+  });
+});
+
 describe('migrated DefaultCartShell (identical English output)', () => {
   const item: CartItem = {
     id: 'li-1',

package/tests/theme-strings.test.tsx

@@ -246,7 +246,9 @@ describe('default English dictionary budget (backend varchar(64))', () => {
 
   it('every key fits the dotted-lowercase grammar and the 40-char budget', () => {
     for (const [key] of pairs) {
-      expect(key, `grammar: ${key}`).toMatch(/^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)*$/);
+      // Same grammar as the backend overlay (ThemeStringTranslatable::KEY_PATTERN suffix) and theme-check
+      // `theme/locale-key-naming`: segments may start with a digit (e.g. `auth.2fa.code`).
+      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.

package/theme-context.tsx

@@ -27,3 +27,13 @@ export function useTheme(): ThemeModule {
 
   return theme;
 }
+
+/**
+ * Null outside a theme provider (kit chrome such as the cart shell renders
+ * under `StorefrontProvider` with no theme mounted). `useThemeStrings`
+ * reads the mounted theme's `manifest.strings` through this, so a missing
+ * theme simply contributes no dictionary instead of throwing.
+ */
+export function useOptionalTheme(): ThemeModule | null {
+  return useContext(ThemeContext);
+}

package/types/theme.ts

@@ -6,6 +6,7 @@ import type { MenuItem } from './menu';
 import type { BlogCategory, Collection, Page, Pagination, Post } from './page';
 import type { MetaobjectEntry, Product } from './product';
 import type { DesignTokenAxisPath, DesignTokens, StorefrontConfig, VendorProfile } from './vendor';
+import type { ThemeStringsDictionary } from '../strings/theme-strings';
 
 export interface HomePageProps {
   blocks: Block[];
@@ -350,6 +351,26 @@ export interface ThemeManifest {
    * injector's own hardcoded defaults (`lib/core/utils/brand.ts`).
    */
   tokens?: DesignTokens;
+  /**
+   * The theme's English default dictionary — the theme's own English
+   * locale file (authored as `en.default.json` in the theme's `locales/`
+   * dir and imported as an object) referenced here.
+   * Same shape as the kit core English default
+   * (nested objects by dot-path, or flat dotted keys; CLDR plural maps
+   * allowed); keys follow the shared grammar (dotted lowercase, <= 40
+   * chars) because the backend overlay stores `<theme-slug>.<key>` in a
+   * varchar(64).
+   *
+   * The kit layers it between the host-loaded locale dictionaries and the
+   * kit core English, so ANY host that mounts the theme (vendor layout,
+   * theme preview, CLI dev preview) renders the theme's English with zero
+   * host cooperation — a host that passes nothing still shows English,
+   * never empty labels. ENGLISH ONLY: non-English packs stay host-loaded
+   * per locale and are never bundled into the theme. Optional during the
+   * migration — a manifest without it behaves exactly as before (kit core
+   * English, then `''` for unknown keys).
+   */
+  strings?: ThemeStringsDictionary;
 }
 
 /**

package/utils/powered-by.ts

@@ -0,0 +1,31 @@
+/**
+ * The one place the "Powered by Queek" destination is built, so every theme's
+ * footer link carries the same attribution and the affiliate/referral program
+ * can trace a signup back to the store it came from.
+ */
+export const POWERED_BY_QUEEK_URL = 'https://usequeek.com/business';
+
+export const POWERED_BY_UTM_SOURCE = 'powered_by';
+export const POWERED_BY_UTM_MEDIUM = 'storefront';
+
+/**
+ * `campaign` is the store's public slug (never an internal UUID) so signups
+ * are attributable per store. Existing query parameters on the base
+ * URL are kept; the `utm_*` keys are always ours. A blank campaign omits
+ * `utm_campaign` rather than sending an empty value.
+ */
+export function poweredByQueekUrl(campaign?: string | null, base: string = POWERED_BY_QUEEK_URL): string {
+  const url = new URL(base);
+
+  url.searchParams.set('utm_source', POWERED_BY_UTM_SOURCE);
+  url.searchParams.set('utm_medium', POWERED_BY_UTM_MEDIUM);
+
+  const trimmed = campaign?.trim();
+  if (trimmed) {
+    url.searchParams.set('utm_campaign', trimmed);
+  } else {
+    url.searchParams.delete('utm_campaign');
+  }
+
+  return url.toString();
+}