@usequeek/theme-kit 0.1.20 → 0.1.22

package/sdk/queek-client.ts

@@ -5,13 +5,13 @@ import { triggerReauth } from './error-handler';
 import { getActivePlatform } from './platform';
 
 // This file is 'use client' — every export here only ever runs in the browser.
-// ALWAYS same-origin-relative, on purpose: next.config.ts's rewrite already
-// proxies /api/v1/client/:path* to the real backend server-side, so the
-// browser never needs (or should have) the backend's actual host. Reading
+// ALWAYS same-origin-relative, on purpose: the host app's `next.config` rewrite
+// already proxies /api/v1/client/:path* to the real API server-side, so the
+// browser never needs (or should have) the API's actual host. Reading
 // NEXT_PUBLIC_QUEEK_API_URL here would let a misconfigured env var (e.g. the
 // same absolute value used for the SERVER-side QUEEK_API_URL) leak
-// api.usequeek.com straight into every client-side request — confirmed live,
-// visible in the browser Network tab for autocomplete/resolve/fees/couriers/
+// api.usequeek.com straight into every client-side request, visible in the
+// browser Network tab for autocomplete/resolve/fees/couriers/
 // addresses. No such var read = structurally impossible to leak it from here.
 export const API_BASE_URL = '/api/v1';
 export const QUEEK_AUTH_URL = process.env.NEXT_PUBLIC_QUEEK_AUTH_URL ?? 'https://auth.usequeek.com';
@@ -45,12 +45,11 @@ const platformFetch: typeof fetch = (input, init) => {
 };
 
 /**
- * Every API response carries a backend request id. The SDK's `request()` returns
- * only the parsed body, so this wrapper — the one place every SDK call's raw
- * Response passes through — is where it can be read at all. Kept as the last-seen
- * value: the storefront has no error-reporting integration (no Sentry), so the
- * only consumer today is the checkout failure log, which is exactly the report a
- * customer support ticket needs to be traceable to a backend request.
+ * Every API response carries a request id. The SDK's `request()` returns only
+ * the parsed body, so this wrapper — the one place every SDK call's raw Response
+ * passes through — is where it can be read at all. Kept as the last-seen value:
+ * the only consumer is the checkout failure log, which is exactly the report a
+ * customer support ticket needs to be traceable to an API request.
  */
 const REQUEST_ID_HEADERS = ['x-request-id', 'x-correlation-id', 'request-id'];
 
@@ -68,7 +67,7 @@ function captureRequestId(response: Response): Response {
   return response;
 }
 
-/** The backend request id of the most recent SDK call, when it sent one. */
+/** The API request id of the most recent SDK call, when it sent one. */
 export function getLastRequestId(): string | null {
   return lastRequestId;
 }

package/sdk/server-store-client.ts

@@ -5,7 +5,7 @@ import { API_BASE_URL, request, type RequestCachePolicy, type RequestOptions } f
 import { getActivePlatform } from './platform';
 
 /**
- * Origin of the incoming storefront request, forwarded to the backend so it
+ * Origin of the incoming storefront request, forwarded to the API so it
  * resolves the vendor exactly as it does for a real browser request (subdomain,
  * apex/path and custom-domain storefronts all work with zero configuration).
  *
@@ -26,9 +26,7 @@ export async function getRequestOrigin(): Promise<string | undefined> {
  * for the subdomain-vs-path `basePath` resolution (subdomain/custom-domain
  * storefronts serve at the bare origin; path-based access serves under
  * `/vendor-slug`). Every canonical URL, sitemap entry, and JSON-LD `url` field
- * must derive from this instead of re-deriving `basePath` inline — see
- * `app/[vendor]/layout.tsx` and `app/[vendor]/products/[slug]/page.tsx`, which
- * used to duplicate this logic before it was extracted here.
+ * must derive from this instead of re-deriving `basePath` inline.
  */
 export async function resolveStoreBaseUrl(vendor: string): Promise<string | null> {
   const origin = await getRequestOrigin();
@@ -56,7 +54,7 @@ export async function resolveStoreBaseUrl(vendor: string): Promise<string | null
  * Abort budget for SSR reads. Sized above the observed p99 of the slowest
  * bootstrap call (`/theme`, ~4.4s) with headroom, so it never fails a legitimate
  * slow response — its job is to stop in-flight renders accumulating without
- * bound when the backend hangs, not to enforce an SLA.
+ * bound when the API hangs, not to enforce an SLA.
  */
 const SSR_TIMEOUT_MS = 8_000;
 
@@ -70,7 +68,7 @@ const SSR_TIMEOUT_MS = 8_000;
  *
  * Tags are per vendor so one store's edit never flushes another's. The TTL is a
  * safety net, not the primary mechanism — `POST /api/revalidate?tag=…` from the
- * backend is what makes an edit show up immediately.
+ * API is what makes an edit show up immediately.
  */
 function resolveCachePolicy(vendorSlug: string, path: string): RequestCachePolicy | null {
   const vendor = `v:${vendorSlug}`;
@@ -80,15 +78,13 @@ function resolveCachePolicy(vendorSlug: string, path: string): RequestCachePolic
   });
 
   // `/config` is deliberately NOT here: nothing fetches it server-side today, and
-  // its response varies by platform (VendorConfigRequest), so allowlisting it
+  // its response varies by platform, so allowlisting it
   // would let a future SSR caller that omits `platform` collapse two platforms
   // onto one cached entry.
   if (path === '/info') return policy(300, 'profile');
-  // Combines /theme + /menus + /pages-chrome into one backend round trip (see
-  // StoreContentController::bootstrapForClient). Tagged with all three resource
-  // suffixes so a merchant edit to any one of them busts this entry — the
-  // existing observers (MenuObserver, PostObserver, VendorConfigObserver)
-  // already emit exactly these suffixes, no backend change needed.
+  // Combines /theme + /menus + /pages-chrome into one API round trip. Tagged
+  // with all three resource suffixes so a merchant edit to any one of them busts
+  // this entry.
   if (path === '/bootstrap') return { revalidate: 300, tags: [vendor, `${vendor}:theme`, `${vendor}:menus`, `${vendor}:pages`] };
   if (path === '/blog-categories') return policy(300, 'posts');
   if (/^\/pages(\/[^/]+)?$/.test(path)) return policy(300, 'pages');
@@ -99,7 +95,7 @@ function resolveCachePolicy(vendorSlug: string, path: string): RequestCachePolic
   if (/^\/collections(\/[^/]+\/products)?$/.test(path)) return policy(300, 'collections');
 
   // Shorter, because price and stock live here: a stale card that a shopper then
-  // cannot buy at the shown price is a trust problem, even though the backend
+  // cannot buy at the shown price is a trust problem, even though the API
   // recomputes both at order time.
   if (path === '/products') return policy(60, 'products');
 
@@ -127,14 +123,14 @@ function resolveCachePolicy(vendorSlug: string, path: string): RequestCachePolic
  * storefront with `?preview=true&id=<vendorId>`. Set by `proxy.ts`, which is the only
  * place that can see query params before the fetch layer runs.
  *
- * A preview render MUST bypass the cache outright rather than rely on the backend's
+ * A preview render MUST bypass the cache outright rather than rely on the API's
  * invalidation call. Invalidation is a distributed handshake — it needs two env vars
- * to match across two repos and a live HTTP round trip — and when any part of that
+ * to match across two services and a live HTTP round trip — and when any part of that
  * is wrong it fails SILENTLY, leaving a merchant staring at an unchanged store for
  * the full TTL. The editor is the one surface where "eventually" is not acceptable,
  * and it already knows it is the editor, so it should not have to ask anyone.
  *
- * The backend still flushes tags on save; that is what keeps the PUBLIC store fresh.
+ * The API still flushes tags on save; that is what keeps the PUBLIC store fresh.
  * This just removes the editor's dependence on it.
  */
 async function isPreviewRender(): Promise<boolean> {
@@ -147,7 +143,7 @@ async function isPreviewRender(): Promise<boolean> {
  * Validated locale of the incoming storefront request, or null for the
  * primary rendering. The proxy sets `x-queek-locale` for published
  * non-primary locales ONLY (absent on the primary); anything else is
- * ignored, mirroring the backend's unknown-locale → source-text rule.
+ * ignored, mirroring the API's unknown-locale → source-text rule.
  *
  * THE single header-parsing site — every server fetcher resolves its locale
  * through here (directly or via `resolveRequestLocale`), never by reading

package/shared-blocks/metaobjects.tsx

@@ -15,7 +15,7 @@ export interface CoreMetaobjectsBlockProps extends MetaobjectsResolved {
  * `EntryCard` a product's linked-entry metafields render. Renders nothing
  * when the type is unknown, hidden, or has no active entries (the server
  * seeds `entries: []` for all three cases — see `hydrateProductBlocks` in
- * the storefront). Each card links to `/{type}/{handle}` only when the
+ * the host app). Each card links to `/{type}/{handle}` only when the
  * definition opted into entry pages (`has_pages`); otherwise it's inert.
  */
 export function CoreMetaobjectsBlock({

package/stores/cart-store.ts

@@ -59,8 +59,8 @@ export const useCartStore = create<CartState>()(
       },
       addItemWithAddons: (product, quantity = 1, addons = [], variant = null) => {
         // A variant-enabled product has no valid "no selection" line: the cart
-        // save fails server-side (DiscountService's VariantSelectionException),
-        // so persisting one only moves the failure to checkout. Themes gate
+        // save fails server-side, so persisting one only moves the failure to
+        // checkout. Themes gate
         // their add button too, but a theme is presentation — correctness
         // cannot depend on all seven, or on the next one, getting it right.
         if (!variant && productRequiresVariant(product)) {

package/stores/checkout-store.ts

@@ -66,7 +66,7 @@ interface CheckoutState {
   isEditingAddress: boolean;
   /** The customer's saved address (CustomerAddress uuid) currently selected for
    *  delivery, when they picked one from their address book instead of
-   *  searching a fresh address. Lets the backend reuse the cached courier
+   *  searching a fresh address. Lets the API reuse the cached courier
    *  geocode. Null whenever the address came from a fresh Google search. */
   savedAddressId: string | null;
 

package/stores/edit-preview-store.ts

@@ -21,15 +21,14 @@ interface EditPreviewState {
  * Draft page content streamed live from the merchant editor, so a section edit
  * renders immediately instead of waiting for a network round trip.
  *
- * Before this, every field change took the long way: 900ms debounce → PUT the
- * draft → postMessage 'refresh' → router.refresh() → RSC fetch → backend
- * render, and the preview showed the OLD content the whole time. The merchant
+ * Without it, every field change would take the long way: 900ms debounce → PUT
+ * the draft → postMessage 'refresh' → router.refresh() → RSC fetch → API render,
+ * and the preview would show the OLD content the whole time. The merchant
  * already holds the edited section in its own state; sending it costs nothing
  * and removes both network hops from the interactive path.
  *
- * Design tokens have worked this way all along (design-token-preview.tsx) — this
- * is the same idea applied to section content, which is the thing merchants
- * actually spend their time editing.
+ * Design tokens work the same way (design-token-preview.tsx) — this applies the
+ * idea to section content, which is what merchants spend their time editing.
  *
  * The server stays authoritative: PageRenderer drops this override the moment a
  * fresh server payload arrives, so the debounced save still reconciles and a

package/stores/user-store.ts

@@ -11,7 +11,7 @@ export interface StorefrontUser {
   email: string | null;
   phone: string;
   avatar: string | null;
-  /** Backend flag: false for social/email signups that still lack a real phone. */
+  /** API flag: false for social/email signups that still lack a real phone. */
   profile_complete?: boolean;
   delivery_info?: {
     map_lat: number;
@@ -22,10 +22,9 @@ export interface StorefrontUser {
 
 /**
  * A signed-in customer whose account is missing the details we require to
- * fulfil an order. The backend's `profile_complete` is itself derived purely
- * from phone+name presence (`ClientAuthUserResource`: `phone !== null && name
- * !== ''`), so both it and the raw `!user.phone` check are gated by
- * `requiresPhone` together — there's no case where one applies without the
+ * fulfil an order. The API's `profile_complete` is itself derived purely from
+ * phone+name presence (`phone !== null && name !== ''`), so both it and the raw
+ * `!user.phone` check are gated by `requiresPhone` together — there's no case where one applies without the
  * other.
  *
  * `requiresPhone` — defaults true (delivery/pickup orders need a real number

package/strings/pseudo-locale.ts

@@ -0,0 +1,263 @@
+/**
+ * Pseudo-locale QA helper.
+ *
+ * PURE AND SERVER-SAFE: this module imports nothing from `next/*` and nothing
+ * from React, so server components, Node tooling (such as the theme check), tests and the
+ * browser all share it (precedent: `utils/locale.ts`, `strings/theme-strings.ts`).
+ * Keep it that way.
+ *
+ * What it is: `pseudoLocalize(dictionary, options?)` returns a pseudo
+ * dictionary with the SAME keys and the SAME plural-map shape, where every
+ * string value is accent-mapped, ~30% longer, and wrapped in markers like
+ * `[!! … !!]`. `{placeholders}` and `{{`/`}}` escapes pass through
+ * untouched, keys are never touched.
+ *
+ * Two uses (both documented in the README):
+ *  - Dev-only locale: mount the app with the pseudo dictionary as the
+ *    `strings` prop. Every string that went through `t()` renders pseudo;
+ *    any text that remains plain English next to pseudo text is a hard-coded
+ *    (un-wrapped) string. Never ship pseudo to shoppers.
+ *  - Tests: render a component with the pseudo dictionary, then run the
+ *    English-leak scan (`findEnglishLeaks` / `assertNoEnglishLeak`) over the
+ *    HTML. That scan is the reusable primitive theme tests import.
+ *
+ * English safety: this module never changes an English value — pseudo
+ * dictionaries are built on demand in dev/test and never enter a bundle.
+ */
+
+import type { ThemeStringsDictionary, ThemeStringsValue } from './theme-strings';
+
+export interface PseudoLocalizeOptions {
+  /** Marker prepended to every value. Default `'[!! '`. */
+  prefix?: string;
+  /** Marker appended to every value. Default `' !!]'`. */
+  suffix?: string;
+  /** Fraction of extra padding appended inside the markers. Default `0.3`. */
+  expansionRatio?: number;
+  /** Padding character. Default `'~'`. */
+  expansionChar?: string;
+  /**
+   * Wrap the core in U+202B … U+202C (RTL embedding) for a visual RTL check.
+   * Default `false`. This is a spot-check aid, not bidi-correct output.
+   */
+  rtl?: boolean;
+}
+
+export const PSEUDO_PREFIX = '[!! ';
+export const PSEUDO_SUFFIX = ' !!]';
+export const PSEUDO_EXPANSION_RATIO = 0.3;
+export const PSEUDO_EXPANSION_CHAR = '~';
+
+const ACCENT_MAP: Record<string, string> = {
+  a: 'à', A: 'À', b: 'ƀ', B: 'Ɓ', c: 'ç', C: 'Ç', d: 'ď', D: 'Ď',
+  e: 'è', E: 'È', f: 'ƒ', F: 'Ƒ', g: 'ĝ', G: 'Ĝ', h: 'ĥ', H: 'Ĥ',
+  i: 'ì', I: 'Ì', j: 'ĵ', J: 'Ĵ', k: 'ķ', K: 'Ķ', l: 'ŀ', L: 'Ŀ',
+  m: 'ṁ', M: 'Ṁ', n: 'ñ', N: 'Ñ', o: 'ò', O: 'Ò', p: 'ṗ', P: 'Ṗ',
+  q: 'ǫ', Q: 'Ǫ', r: 'ŕ', R: 'Ŕ', s: 'š', S: 'Š', t: 'ţ', T: 'Ţ',
+  u: 'ù', U: 'Ù', v: 'ṽ', V: 'Ṽ', w: 'ŵ', W: 'Ŵ', x: 'ẋ', X: 'Ẋ',
+  y: 'ÿ', Y: 'Ÿ', z: 'ž', Z: 'Ž',
+};
+
+const PLURAL_FORMS = ['one', 'two', 'few', 'many', 'other'];
+
+/** Same leaf rule as `t()`'s runtime: all keys are plural forms, all values strings. */
+function isPluralMapValue(value: unknown): value is Record<string, string> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return false;
+  const keys = Object.keys(value);
+  return (
+    keys.length > 0 &&
+    keys.every((k) => PLURAL_FORMS.includes(k)) &&
+    keys.every((k) => typeof (value as Record<string, unknown>)[k] === 'string')
+  );
+}
+
+function isPlaceholderName(name: string): boolean {
+  return /^[A-Za-z0-9_]+$/.test(name);
+}
+
+/**
+ * Pseudo-localize one string value. `{placeholder}` interpolations and
+ * `{{`/`}}` escapes are preserved byte-for-byte; only plain-text letters are
+ * accent-mapped. `''` stays `''` (an intentional empty renders nothing, so
+ * there is no node to mark).
+ */
+export function pseudoLocalizeText(value: string, options?: PseudoLocalizeOptions): string {
+  if (value === '') return '';
+  const prefix = options?.prefix ?? PSEUDO_PREFIX;
+  const suffix = options?.suffix ?? PSEUDO_SUFFIX;
+  const ratio = options?.expansionRatio ?? PSEUDO_EXPANSION_RATIO;
+  const expansionChar = options?.expansionChar ?? PSEUDO_EXPANSION_CHAR;
+  const rtl = options?.rtl ?? false;
+
+  let core = '';
+  let i = 0;
+  while (i < value.length) {
+    const ch = value[i];
+    if (ch === '{' && value[i + 1] === '{') {
+      core += '{{';
+      i += 2;
+      continue;
+    }
+    if (ch === '}' && value[i + 1] === '}') {
+      core += '}}';
+      i += 2;
+      continue;
+    }
+    if (ch === '{') {
+      const close = value.indexOf('}', i + 1);
+      const name = close === -1 ? '' : value.slice(i + 1, close);
+      if (close !== -1 && isPlaceholderName(name)) {
+        core += value.slice(i, close + 1);
+        i = close + 1;
+        continue;
+      }
+      core += ACCENT_MAP[ch] ?? ch;
+      i += 1;
+      continue;
+    }
+    core += /[A-Za-z]/.test(ch) ? (ACCENT_MAP[ch] ?? ch) : ch;
+    i += 1;
+  }
+
+  const padLength = Math.max(0, Math.round(core.length * ratio));
+  const expanded = core + expansionChar.repeat(padLength);
+  const inner = rtl ? '\u202B' + expanded + '\u202C' : expanded;
+  return `${prefix}${inner}${suffix}`;
+}
+
+function pseudoLocalizeValue(value: ThemeStringsValue, options?: PseudoLocalizeOptions): ThemeStringsValue {
+  if (typeof value === 'string') return pseudoLocalizeText(value, options);
+  if (isPluralMapValue(value)) {
+    const out: Record<string, string> = {};
+    for (const [form, template] of Object.entries(value)) {
+      out[form] = pseudoLocalizeText(template, options);
+    }
+    return out as ThemeStringsValue;
+  }
+  if (typeof value === 'object' && value !== null) {
+    const out: ThemeStringsDictionary = {};
+    for (const [k, v] of Object.entries(value as ThemeStringsDictionary)) {
+      out[k] = pseudoLocalizeValue(v, options);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Pseudo-localize a whole dictionary. Keys (including flat literal dotted
+ * keys) are copied verbatim; nested objects recurse; plural maps keep their
+ * exact form keys with each template pseudo-localized.
+ */
+export function pseudoLocalize(
+  dictionary: ThemeStringsDictionary,
+  options?: PseudoLocalizeOptions,
+): ThemeStringsDictionary {
+  const out: ThemeStringsDictionary = {};
+  for (const [key, value] of Object.entries(dictionary)) {
+    out[key] = pseudoLocalizeValue(value, options);
+  }
+  return out;
+}
+
+/** True when the rendered text carries this run's pseudo markers. */
+export function isPseudoLocalized(text: string, options?: PseudoLocalizeOptions): boolean {
+  const prefix = options?.prefix ?? PSEUDO_PREFIX;
+  const suffix = options?.suffix ?? PSEUDO_SUFFIX;
+  const trimmed = text.trim();
+  return (
+    trimmed.length >= prefix.length + suffix.length &&
+    trimmed.startsWith(prefix) &&
+    trimmed.endsWith(suffix)
+  );
+}
+
+export interface EnglishLeakScanOptions {
+  /**
+   * Visible strings that are English by design (brand names, codes) and must
+   * not be reported. Exact strings or patterns, matched against the trimmed
+   * node text.
+   */
+  allowlist?: Array<string | RegExp>;
+  /**
+   * Also scan user-visible attributes (`aria-label`, `aria-valuetext`,
+   * `placeholder`, `title`, `alt`). Default `true` — hard-coded aria copy is
+   * the same bug class as hard-coded text nodes.
+   */
+  includeAttributes?: boolean;
+  /** Marker options used for the pseudo run being scanned. */
+  pseudo?: PseudoLocalizeOptions;
+}
+
+function decodeEntities(value: string): string {
+  return value
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;|&#x27;/g, "'")
+    .replace(/&nbsp;/g, ' ');
+}
+
+function visibleTexts(html: string, includeAttributes: boolean): string[] {
+  const found: string[] = [];
+  let text = html
+    .replace(/<script[\s\S]*?<\/script>/gi, ' ')
+    .replace(/<style[\s\S]*?<\/style>/gi, ' ')
+    .replace(/<!--[\s\S]*?-->/g, ' ');
+  if (includeAttributes) {
+    for (const match of text.matchAll(
+      /(?:aria-label|aria-valuetext|placeholder|title|alt)\s*=\s*"([^"]*)"/gi,
+    )) {
+      const attr = decodeEntities(match[1] ?? '').trim().replace(/\s+/g, ' ');
+      if (attr) found.push(attr);
+    }
+    for (const match of text.matchAll(
+      /(?:aria-label|aria-valuetext|placeholder|title|alt)\s*=\s*'([^']*)'/gi,
+    )) {
+      const attr = decodeEntities(match[1] ?? '').trim().replace(/\s+/g, ' ');
+      if (attr) found.push(attr);
+    }
+  }
+  const stripped = text.replace(/<[^>]*>/g, '\u0000');
+  for (const part of stripped.split('\u0000')) {
+    const node = decodeEntities(part).trim().replace(/\s+/g, ' ');
+    if (node) found.push(node);
+  }
+  return found;
+}
+
+/**
+ * The English-leak scan primitive: every visible text node of the rendered
+ * HTML that is NOT pseudo-localized (and not allowlisted, and containing at
+ * least one ASCII letter so numbers/symbols never report) is a hard-coded
+ * English string. Returns the offending node texts (trimmed, in document
+ * order). Pure — theme tests render with the pseudo dictionary, then call
+ * this (or `assertNoEnglishLeak`).
+ */
+export function findEnglishLeaks(html: string, options?: EnglishLeakScanOptions): string[] {
+  const allowlist = options?.allowlist ?? [];
+  const includeAttributes = options?.includeAttributes ?? true;
+  return visibleTexts(html, includeAttributes).filter((node) => {
+    if (isPseudoLocalized(node, options?.pseudo)) return false;
+    if (!/[A-Za-z]/.test(node)) return false;
+    if (allowlist.some((rule) => (typeof rule === 'string' ? rule === node : rule.test(node)))) {
+      return false;
+    }
+    return true;
+  });
+}
+
+/** Throw listing every leaked node, or return silently when the render is clean. */
+export function assertNoEnglishLeak(html: string, options?: EnglishLeakScanOptions): void {
+  const leaks = findEnglishLeaks(html, options);
+  if (leaks.length > 0) {
+    throw new Error(
+      `[theme-kit] English leak: ${leaks.length} visible string(s) are not pseudo-localized:\n` +
+        leaks
+          .slice(0, 20)
+          .map((leak) => ` - ${JSON.stringify(leak)}`)
+          .join('\n'),
+    );
+  }
+}