@usequeek/theme-kit 0.1.20 → 0.1.22

package/hooks/use-locales.ts

@@ -0,0 +1,107 @@
+'use client';
+
+import { useCallback, useContext, useEffect, useMemo, useState } from 'react';
+import { StorefrontContext } from '../provider';
+import { usePathname, useRouter } from '../navigation';
+import {
+  defaultStoreLocale,
+  localeHref,
+  resolveActiveLocale,
+  type StoreLocale,
+} from '../utils/locale-switch';
+
+export interface LocalesState {
+  /** The store's languages, the default first. One entry on a single-language store. */
+  locales: StoreLocale[];
+  /** The language the page renders in. */
+  active: StoreLocale;
+  /** The language served at the store root. */
+  defaultLocale: StoreLocale;
+  /** More than one language: whether a language choice makes sense at all. */
+  hasMultiple: boolean;
+  /**
+   * The current page in another language, e.g. `/fr/shop?sort=new`. Takes a
+   * language row or its code; an unknown code returns the current URL. The
+   * query string and hash are included once the page has mounted (the first
+   * render matches the server's markup), so use it for `href`s and call
+   * `switchTo` to navigate.
+   */
+  hrefFor: (locale: StoreLocale | string) => string;
+  /** Go to the current page in another language, reading the live query string and hash. */
+  switchTo: (locale: StoreLocale | string) => void;
+}
+
+const EMPTY_SUFFIX = { search: '', hash: '' };
+
+function readSuffix(): { search: string; hash: string } {
+  if (typeof window === 'undefined') return EMPTY_SUFFIX;
+  return { search: window.location.search, hash: window.location.hash };
+}
+
+/**
+ * The store's languages and the active one, for a theme that builds its own
+ * language control. Reads what the host passed to `StorefrontProvider`
+ * (`locales`) — no request. Absent or one language → a single-language state
+ * (`hasMultiple` false) with a no-op-safe `hrefFor`; outside a provider it
+ * does not throw.
+ *
+ * Most themes want the `LanguageSwitcher` component instead.
+ */
+export function useLocales(): LocalesState {
+  const context = useContext(StorefrontContext);
+  const pathname = usePathname();
+  const router = useRouter();
+  const basePath = context?.basePath ?? '';
+  const requestLocale = context?.locale ?? null;
+  const contextLocales = context?.locales;
+
+  const locales = useMemo(() => contextLocales ?? [], [contextLocales]);
+  const defaultLocale = useMemo(() => defaultStoreLocale(locales), [locales]);
+  const active = useMemo(() => resolveActiveLocale(locales, requestLocale), [locales, requestLocale]);
+
+  // Query and hash only exist in the browser: start empty so the first client
+  // render matches the server, then adopt them (and follow later changes).
+  const [suffix, setSuffix] = useState(EMPTY_SUFFIX);
+  useEffect(() => {
+    const next = readSuffix();
+    setSuffix((prev) => (prev.search === next.search && prev.hash === next.hash ? prev : next));
+  });
+
+  const resolve = useCallback(
+    (locale: StoreLocale | string): StoreLocale | null => {
+      if (typeof locale !== 'string') return locale;
+      const code = locale.toLowerCase();
+      return locales.find((row) => row.locale.toLowerCase() === code) ?? null;
+    },
+    [locales],
+  );
+
+  const build = useCallback(
+    (target: StoreLocale, search: string, hash: string) =>
+      localeHref({ pathname, search, hash, basePath, active, target }),
+    [pathname, basePath, active],
+  );
+
+  const hrefFor = useCallback(
+    (locale: StoreLocale | string): string => {
+      const target = resolve(locale);
+      return build(target ?? active, suffix.search, suffix.hash);
+    },
+    [resolve, build, active, suffix],
+  );
+
+  const switchTo = useCallback(
+    (locale: StoreLocale | string): void => {
+      const target = resolve(locale);
+      if (!target || target === active) return;
+      const live = readSuffix();
+      router.push(build(target, live.search, live.hash));
+    },
+    [resolve, build, active, router],
+  );
+
+  return useMemo(
+    () => ({ locales, active, defaultLocale, hasMultiple: locales.length > 1, hrefFor, switchTo }),
+    [locales, active, defaultLocale, hrefFor, switchTo],
+  );
+}

package/hooks/use-posts.ts

@@ -11,7 +11,7 @@ import { withLocaleQuery } from '../utils/locale';
  * Client-side blog-post listing, for blocks embedded on an arbitrary page
  * (e.g. the 'blog' home-page block) — mirrors useProducts' shape/pattern.
  * The blog LISTING page itself (pages/blog.tsx) gets its posts via SSR props
- * instead (fetchPosts in lib/core/api/pages.ts); this hook is for anywhere
+ * instead (`fetchPosts` in the host's page loader); this hook is for anywhere
  * else a theme needs a live post list without page-level SSR data.
  */
 export function usePosts(options?: { category?: string | null; limit?: number }): { posts: Post[]; isLoading: boolean } {

package/hooks/use-product-detail.ts

@@ -15,8 +15,7 @@ interface UseProductDetailResult {
 
 /**
  * The product LIST/collection endpoint never returns `addons`, `options`, or
- * `variants` — those only exist on the single-product "view" response
- * (`ProductResource::buildBasePayload` vs `buildViewPayload`, queek_backend).
+ * `variants` — those only exist on the single-product "view" response.
  * Any quick-view/quick-add modal opened from a product card only has the
  * list-shaped object, so it must re-fetch full detail before it can render
  * or select an addon/option — rendering `listProduct.addons` directly always

package/hooks/use-product-sections.ts

@@ -31,8 +31,7 @@ export interface MenuGroupItem {
  * smart collection whose rule DOES reference other collections — a browsing
  * umbrella, not a product filter) offers those referenced collections as
  * tiles first. Every id here is already present in this same response's
- * flat product pool, so resolving a tap is a pure client-side lookup — see
- * VendorProductController::resolveQrTabGroups (queek_backend). */
+ * flat product pool, so resolving a tap is a pure client-side lookup. */
 export type MenuGroup =
   | { id: string; name: string; type: 'products'; product_ids: string[] }
   | { id: string; name: string; type: 'collections'; items: MenuGroupItem[] };
@@ -118,10 +117,9 @@ export function useProductSections(): {
         .get<ApiResponse<unknown>>('/products', withLocaleQuery(undefined, locale))
         .then((response) => {
           const data = response.data;
-          // instore_qr only — backend attaches this under meta.groups, never
-          // inside `data` (see resolveQrTabGroups): sectioned/menu-mode `data`
-          // is shared with the mobile app's response shape, so groups had to
-          // land somewhere additive instead.
+          // instore_qr only — the API attaches this under meta.groups, never
+          // inside `data`: sectioned/menu-mode `data` is shared with the mobile
+          // app's response shape, so groups land somewhere additive instead.
           const rawGroups = (response.meta as { groups?: MenuGroup[] } | undefined)?.groups;
           const groups = Array.isArray(rawGroups) ? rawGroups : [];
 

package/hooks/use-products.ts

@@ -102,7 +102,7 @@ export function useProducts(options?: ProductQuery & {
           if (options?.sort) query.sort = options.sort;
           if (options?.limit) query.per_page = options.limit;
           if (options?.hasVideo) query.has_video = 1;
-          // Ask the backend for exactly these products (whereIn) instead of
+          // Ask the API for exactly these products (by id) instead of
           // fetching an arbitrary `per_page`-sized page of the default listing
           // and hoping the requested ids happen to land in it — with a small
           // limit (bundle/shop-the-look/featured's 1-3) they almost never did,
@@ -149,13 +149,10 @@ export function useProducts(options?: ProductQuery & {
 /**
  * Full product detail (the same `/products/{slug}` request the PDP itself
  * uses), including the full ordered detail `media.images` list — the
- * list/collection endpoints `useProducts` calls only ever return the capped
- * `media.images` list (`media.listing.images_limit`, config/media.php:15)
- * plus `media.{image,thumbnail}` (see
- * Customer\ProductResource::buildBaseMediaPayload vs buildDetailMediaPayload
- * in queek_backend). Single-product spotlight blocks (e.g. glow's `featured`
- * variant) need this instead of substituting image/thumbnail as a fake
- * 2-image list.
+ * list/collection endpoints `useProducts` calls only ever return a capped
+ * `media.images` list plus `media.{image,thumbnail}`. Single-product spotlight
+ * blocks (e.g. a `featured` variant) need this instead of substituting
+ * image/thumbnail as a fake 2-image list.
  */
 /**
  * Fetch one product by SLUG.

package/index.ts

@@ -1,15 +1,12 @@
 /**
  * The public surface a theme is allowed to build against.
  *
- * The package is `@usequeek/theme-kit`: what a theme is built AGAINST, named for
- * the job rather than for our internals — "storefront core" describes where the
- * code lives here, which is meaningless to someone who has never seen this repo.
+ * The package is `@usequeek/theme-kit`: what a theme is built AGAINST.
  *
- * Themes currently import core through deep paths (`@/lib/core/hooks/use-cart`).
- * These two barrels name which of those paths are API — the set that would ship
- * as `@usequeek/theme-kit` — so the boundary is written down before it is
- * published and frozen. Anything NOT re-exported here is core's own plumbing and
- * may change without notice.
+ * Themes import the kit through deep paths (`@usequeek/theme-kit/hooks/use-cart`).
+ * These two barrels name which of those paths are API, so the boundary is written
+ * down. Anything NOT re-exported here is the kit's own plumbing and may change
+ * without notice.
  *
  * Two entries because the split is real, not cosmetic: this one is types and
  * pure functions, importable from anywhere including node tooling; `client.ts`
@@ -18,16 +15,15 @@
  * deliberately unreachable from both.
  *
  * THESE ARE A DECLARATION, NOT AN IMPORT PATH. Do not migrate themes onto them.
- * Measured 9/9/26: pointing one theme's 28 files at `client.ts` fails the build
- * outright — `theme:generate-registry` imports theme components under tsx, and
- * through the barrel a gallery block transitively pulls the SDK, which does not
- * resolve outside a bundler. It is the same reason a barrel would bloat every
+ * Pointing a theme's files at `client.ts` fails the build outright: tooling that
+ * imports theme components under tsx (a theme registry generator, for example)
+ * would reach a gallery block through the barrel, which transitively pulls the
+ * SDK, and the SDK does not resolve outside a bundler. It is the same reason a barrel would bloat every
  * theme chunk: the stores call `create()` at import time and package.json
  * declares no `sideEffects`, so webpack must treat every re-export as live and
  * cannot drop the unused ones. Themes keep importing the exact module they use;
- * when core is published it should expose SUBPATH exports
- * (`@usequeek/theme-kit/hooks/use-cart`) and these barrels stay the
- * machine-checkable statement of what is in the contract.
+ * these barrels stay the machine-checkable statement of what is in the public
+ * surface.
  */
 
 export * from './types/theme';
@@ -48,9 +44,14 @@ export * from './utils/benefit-icon';
 export * from './utils/video-embed';
 export * from './utils/match-variant';
 export * from './utils/announcement';
+export * from './utils/locale';
+export * from './utils/locale-switch';
 
 // Theme strings — the pure/server-safe i18n core (no next/*, no React).
 export * from './strings/theme-strings';
+// Pseudo-locale QA — dev/test-only dictionary transform + English-leak scan
+// (pure/server-safe: no next/*, no React, so Node tooling can import it too).
+export * from './strings/pseudo-locale';
 
 // Rendering a theme's own demo.json — what makes local preview possible.
 export * from './demo';

package/locales/en.default.json

@@ -87,18 +87,29 @@
       "title": "Sign in",
       "subtitle": "Enter your email and password",
       "email": "Email address",
-      "password": "Password"
+      "password": "Password",
+      "signing": "Signing in…",
+      "create": "Don't have an account? Create one",
+      "code": "Use an email code instead"
     },
     "email": {
       "title": "Sign in",
       "subtitle": "Enter your email to continue",
+      "placeholder": "your@email.com",
       "or": "or",
-      "placeholder": "your@email.com"
+      "google": "Continue with Google",
+      "sending": "Sending code…",
+      "continue": "Continue",
+      "password": "Have a password? Sign in with it instead"
     },
     "code": {
       "title": "Enter code",
-      "sent": "{length}-digit code sent to {email}",
-      "digit": "Digit {index}"
+      "lead": "{length}-digit code sent to",
+      "digit": "Digit {index}",
+      "verifying": "Verifying…",
+      "verify": "Verify",
+      "resend": "Resend code",
+      "change": "← Change email"
     },
     "register": {
       "title": "Create account",
@@ -106,13 +117,30 @@
       "first": "First name",
       "last": "Last name (optional)",
       "email": "Email address",
-      "password": "Password (min 8 characters)"
+      "password": "Password (min 8 characters)",
+      "creating": "Creating account…",
+      "signin": "Already have an account? Sign in"
     },
     "signup": {
       "title": "Create your account",
       "subtitle": "Just a few details to get you started",
       "first": "First name",
-      "last": "Last name (optional)"
+      "last": "Last name (optional)",
+      "create": "Create account",
+      "creating": "Creating account…",
+      "different": "← Use a different email"
+    },
+    "error": {
+      "credentials": "Wrong email or password. Please try again.",
+      "method": "This account uses a different sign-in method (Google or phone).",
+      "exists": "Email already registered. Please sign in instead.",
+      "phone": "Phone number already in use.",
+      "resend": "Please wait before requesting another code.",
+      "code": "Incorrect code. Please try again.",
+      "generic": "Something went wrong. Please try again.",
+      "firstname": "Please enter your first name.",
+      "register": "Registration failed. Try again.",
+      "google": "Could not connect to Google sign-in. Please try again."
     }
   },
   "blog": {
@@ -132,7 +160,21 @@
       "x": "Share on X",
       "facebook": "Share on Facebook",
       "whatsapp": "Share on WhatsApp",
-      "copy": "Copy link"
+      "copy": "Copy link",
+      "copied": "Copied"
+    },
+    "related": {
+      "title": "Related posts"
+    },
+    "meta": {
+      "reading": {
+        "one": "{count} min read",
+        "other": "{count} min read"
+      }
     }
+  },
+  "language": {
+    "label": "Language",
+    "named": "Language: {name}"
   }
 }

package/next-reference.d.ts

@@ -4,9 +4,7 @@
  * `/// <reference types="next" />` every Next app gets via next-env.d.ts.
  *
  * The kit runs inside Next apps, so depending on Next's own type package is
- * correct. Depending on the storefront's next-env.d.ts (as the kit implicitly
- * did before extraction — the file the kit free-rode on when 0.1.0 shipped
- * broken) is what must never happen again. This file is that dependency,
- * written down.
+ * correct. Depending on a host app's own next-env.d.ts would break every
+ * consumer that does not have one. This file is that dependency, written down.
  */
 /// <reference types="next" />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@usequeek/theme-kit",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "private": false,
   "license": "MIT",
   "description": "The framework a Queek storefront theme is built against.",
@@ -44,6 +44,7 @@
     "@types/node": "^20",
     "@types/react": "^19",
     "@types/react-dom": "^19",
+    "jsdom": "^28.1.0",
     "next": "^16.0.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
@@ -52,7 +53,7 @@
     "vitest": "^3.2.4"
   },
   "scripts": {
-    "test": "vitest run",
+    "test": "node scripts/check-public-text.mjs && node --test scripts/check-public-text.test.mjs && vitest run",
     "typecheck": "tsc --noEmit",
     "verify-package": "tsx scripts/verify-package.ts"
   }

package/page-renderer.tsx

@@ -121,11 +121,10 @@ export function PageRenderer({ blocks }: { blocks: Block[] }): JSX.Element {
     // help regardless of where the section's own text ends up. Forcing
     // `color: #fff` alongside it is deliberate, not decorative — the same
     // "on_accent independently defaulting to something unrelated" trap that
-    // broke Taylor's checkout (2026-08-21, see brand.ts's
-    // ensureReadableOnAccent) applies here too: a theme's own default text
-    // color was never chosen with an arbitrary vendor photo behind it, so
-    // legibility can't be left to inherit from wherever the theme happens to
-    // default to. `!important`-equivalent isn't needed — this is the
+    // brand.ts's ensureReadableOnAccent guards against applies here too: a
+    // theme's own default text color was never chosen with an arbitrary vendor
+    // photo behind it, so legibility can't be left to inherit from wherever the
+    // theme happens to default to. `!important`-equivalent isn't needed — this is the
     // closest ancestor rule, and CSS3 UI text is dark by default in every
     // theme (see brand.ts's own comment on directly-matched rules winning
     // over inherited ones for exactly the fix this exists to preempt).
@@ -167,7 +166,7 @@ export function PageRenderer({ blocks }: { blocks: Block[] }): JSX.Element {
             // a sensible default for a plain content page's paragraphs/
             // images, but for a colored band it leaves a seam of the page's
             // own background between adjacent sections, breaking the "solid
-            // band" look (confirmed live: 16px, exactly the default gap).
+            // band" look (the seam measures 16px, exactly the default gap).
             // Pull this section half a gap into the space above/below it;
             // when the neighbor is ALSO a bg_color band doing the same, the
             // two halves meet and the seam closes to zero. Derives from the

package/provider.tsx

@@ -9,6 +9,7 @@ import type { Product } from './types/product';
 import type { StorefrontConfig, VendorProfile } from './types/vendor';
 import { getBrandCssVariables } from './utils/brand';
 import { parseLocaleCode } from './utils/locale';
+import { normalizeStoreLocales, type StoreLocale, type StoreLocaleInput } from './utils/locale-switch';
 import {
   defaultThemeStrings,
   t as translateThemeStrings,
@@ -43,7 +44,7 @@ interface StorefrontContextValue {
   previewData?: StorefrontPreviewData;
   basePath: string;
   /** slug => 'full' | 'bare', for ShellInner to decide the CURRENT page's
-   * header/footer without a per-navigation fetch. See VendorShell. */
+   * header/footer without a per-navigation fetch. */
   pagesChrome: Record<string, 'full' | 'bare'>;
   /** Validated request locale (null = primary). Browser hooks read it via
    * `useStorefrontLocale()` and send `?locale=` when it is set. */
@@ -53,6 +54,11 @@ interface StorefrontContextValue {
    * Optional so hand-built context values (storefront scripts, tests) keep
    * compiling without it. */
   strings?: ThemeStringsDictionary[];
+  /** The store's languages (default first), normalised. Empty or omitted =
+   * a single-language store: `useLocales()` reports one language and the
+   * `LanguageSwitcher` renders nothing. Optional so hand-built context values
+   * keep compiling without it. */
+  locales?: StoreLocale[];
 }
 
 export const StorefrontContext = createContext<StorefrontContextValue | null>(null);
@@ -66,6 +72,7 @@ export function StorefrontProvider({
   pagesChrome,
   locale,
   strings,
+  locales,
   children,
 }: {
   vendor: VendorProfile;
@@ -89,6 +96,17 @@ export function StorefrontProvider({
    * renders exactly as before. Existing props are untouched.
    */
   strings?: ThemeStringsDictionary | ThemeStringsDictionary[] | null;
+  /**
+   * The store's languages, resolved by the host (no request from the kit).
+   * Pass the host's list as it is — rows follow the locales endpoint shape
+   * (`locale`, `name`, `native_name`, `is_primary`, `is_default`,
+   * `path_prefix`, …); extra fields are ignored and a missing `is_default`
+   * falls back to `is_primary`. Optional — absent or a single language
+   * means no language choice: `LanguageSwitcher` renders nothing and
+   * `useLocales()` reports one language. Themes never set this; the host
+   * owns it, like `basePath`.
+   */
+  locales?: readonly StoreLocaleInput[] | null;
   children: ReactNode;
 }): JSX.Element {
   const resolvedBasePath = basePath ?? `/${vendor.slug ?? ''}`;
@@ -102,6 +120,7 @@ export function StorefrontProvider({
           ),
     [strings],
   );
+  const resolvedLocales = useMemo(() => normalizeStoreLocales(locales), [locales]);
   const value = useMemo(
     () => ({
       vendor,
@@ -112,8 +131,9 @@ export function StorefrontProvider({
       pagesChrome: pagesChrome ?? {},
       locale: resolvedLocale,
       strings: resolvedStrings,
+      locales: resolvedLocales,
     }),
-    [config, menus, previewData, vendor, resolvedBasePath, pagesChrome, resolvedLocale, resolvedStrings],
+    [config, menus, previewData, vendor, resolvedBasePath, pagesChrome, resolvedLocale, resolvedStrings, resolvedLocales],
   );
   const brandRootRef = useRef<HTMLDivElement>(null);
 

package/scripts/verify-package.ts

@@ -8,12 +8,12 @@
  *     error TS2503: Cannot find namespace 'JSX'.
  *
  * 42 modules annotated returns as `JSX.Element`, relying on a GLOBAL JSX
- * namespace that came from the storefront app's `next-env.d.ts` — not from
- * React. Inside the storefront repo the kit free-rode on that file, so tsc,
- * the tests, the build and the render smoke were ALL green. The workspace
- * supplies exactly the file whose absence is the bug, which is why no in-repo
- * check could ever have found it. (Every module now does
- * `import type { JSX } from 'react'`, and this script proves it.)
+ * namespace that came from a host app's `next-env.d.ts` — not from React.
+ * Inside a host app the kit free-rode on that file, so tsc, the tests, the
+ * build and the render smoke were ALL green. The workspace supplies exactly the
+ * file whose absence is the bug, which is why no in-repo check could ever have
+ * found it. (Every module now does `import type { JSX } from 'react'`, and this
+ * script proves it.)
  *
  * It packs the CURRENT SOURCE rather than installing the published version, so
  * it fails before a broken version ships instead of after. Installing from the
@@ -26,8 +26,6 @@ import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 // The kit package is `"type": "module"`, so `__dirname` does not exist here.
-// (The storefront copy of this script could use it only because that package
-// is CJS.)
 const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
 const KIT = ROOT;
 

package/sdk/client.ts

@@ -5,8 +5,9 @@ import { getActivePlatform } from './platform';
 export const API_BASE_URL = process.env.QUEEK_API_URL ?? process.env.NEXT_PUBLIC_QUEEK_API_URL ?? 'http://127.0.0.1:8000/api/v1';
 // BROWSER-side only (createBrowserClient below, "for client components/hooks").
 // Hardcoded relative on purpose, same reasoning as queek-client.ts's
-// API_BASE_URL: next.config.ts's rewrite already proxies /api/v1/client/:path*
-// to the backend server-side, so the browser never needs the real host. This
+// API_BASE_URL: the host app's `next.config` rewrite already proxies
+// /api/v1/client/:path* to the API server-side, so the browser never needs the
+// real host. This
 // used to read NEXT_PUBLIC_QUEEK_API_URL directly — when that's set to the
 // same absolute value as the server-side QUEEK_API_URL, every hook built on
 // createBrowserClient (products, shop, categories, reviews, related products,
@@ -35,7 +36,7 @@ export interface RequestCachePolicy {
  * eventually releases, not to enforce an SLA on a shopper's mobile connection.
  *
  * A write gets far more room than a read, and `request()` NEVER retries: an
- * aborted POST may already have reached the backend, so re-sending it could
+ * aborted POST may already have reached the API, so re-sending it could
  * duplicate an order or a payment.
  */
 const BROWSER_GET_TIMEOUT_MS = 15_000;
@@ -44,8 +45,8 @@ const BROWSER_POST_TIMEOUT_MS = 25_000;
 /**
  * Carries the HTTP status so callers can tell a genuine "this does not exist"
  * (404) apart from an infrastructure failure (5xx, timeout, network). That
- * distinction is load-bearing in `app/[vendor]/layout.tsx`: 404 must render
- * not-found, while a backend blip must NOT — a 404 on every URL of a live store
+ * distinction is load-bearing in a host's vendor layout: 404 must render
+ * not-found, while an API blip must NOT — a 404 on every URL of a live store
  * is how storefronts get deindexed.
  */
 export class ApiRequestError extends Error {
@@ -85,7 +86,7 @@ export class ApiTimeoutError extends Error {
  * For fetchers whose caller renders not-found on a null result.
  *
  * Returns null ONLY for a real 404 and rethrows everything else. A bare
- * `catch { return null }` there turns a backend timeout or 5xx into a 404 for a
+ * `catch { return null }` there turns an API timeout or 5xx into a 404 for a
  * product/page that exists — which is what deindexes a store's highest-value
  * URLs during a blip, and became far more likely once SSR fetches gained an
  * abort budget.
@@ -114,7 +115,7 @@ function withQuery(path: string, query?: RequestOptions['query']): string {
       continue;
     }
 
-    // Laravel's query parser only builds a real array from bracket notation
+    // The API's query parser only builds a real array from bracket notation
     // (`key[]=a&key[]=b`) — a plain comma-joined `key=a,b` (URLSearchParams'
     // default for an array via String()) arrives server-side as a single
     // string, failing an `array` validation rule outright.
@@ -134,11 +135,11 @@ function withQuery(path: string, query?: RequestOptions['query']): string {
 }
 
 export async function request<T>(baseUrl: string, path: string, options: RequestOptions & { credentials?: RequestCredentials } = {}, extraHeaders?: Record<string, string>): Promise<T> {
-  // HARD RULE: the storefront only ever calls the `/v1/client/*` scope. That scope's
-  // ResolveClientContext middleware resolves the vendor AND forces the platform
-  // (storefront/instore_qr), so prices are always the storefront's (no marketplace
-  // commission). Legacy v1 routes (/products, /vendors/*, /categories) bypass that
-  // middleware → wrong platform → wrong price. Never call them from here.
+  // HARD RULE: the storefront only ever calls the `/v1/client/*` scope. That scope
+  // resolves the vendor AND forces the platform (storefront/instore_qr), so prices
+  // are always the storefront's (no marketplace commission). Legacy v1 routes
+  // (/products, /vendors/*, /categories) skip that resolution → wrong platform →
+  // wrong price. Never call them from here.
   if (!path.startsWith('/client/')) {
     throw new Error(`Storefront may only call /v1/client/* routes — got "${path}". Use createServerStoreClient / createBrowserClient (which prefix /client/store).`);
   }

package/sdk/error-handler.ts

@@ -7,7 +7,7 @@ import { isReauthSuppressed } from './reauth-guard';
 
 /**
  * Returns true if the caught error is an unauthenticated (401) error
- * from the backend or SDK token layer.
+ * from the API or SDK token layer.
  */
 export function isUnauthenticatedError(err: unknown): boolean {
   if (err instanceof QueekSdkError) {

package/sdk/platform.ts

@@ -2,7 +2,7 @@
  * Active API platform holder.
  *
  * Every API request the storefront makes carries an `X-Platform` header so the
- * backend can resolve the right config + fees. Most of the site runs on the
+ * API can resolve the right config + fees. Most of the site runs on the
  * `storefront` channel; the in-core QR ordering page (`/qr`) runs on `instore_qr`.
  *
  * The two client factories (`createBrowserClient`, `getQueekClient`) and the
@@ -18,8 +18,8 @@
  * `server-store-client`'s `X-Platform` header non-deterministic.
  *
  * SSR therefore always reads `storefront`, which is correct: server-side fetches
- * only ever load storefront-channel content, and the backend's
- * ResolveClientContext re-derives and forces the platform regardless.
+ * only ever load storefront-channel content, and the API re-derives and forces
+ * the platform regardless.
  */
 export type Platform = 'storefront' | 'instore_qr';
 
@@ -46,11 +46,9 @@ export function setActivePlatform(platform: Platform): void {
  * simply invisible to `/qr` and vice versa — no in-memory state to keep in
  * sync, no risk of one flow reading the other's leftovers.
  *
- * This is what a stale, non-QR `deliveryMode` (e.g. "pickup", picked earlier
- * on the ordinary storefront) reaching a `/qr` dine-in checkout and getting
- * its packaging wrongly enforced would have been caught by (production
- * incident 30/8/26 — Kili Foods "Nkwobi"; see DeliveryModePicker's own fix
- * for that specific symptom). Apply this to every persisted store/key a `/qr`
+ * Without it, a stale non-QR `deliveryMode` (e.g. "pickup", picked earlier on
+ * the ordinary storefront) could reach a `/qr` dine-in checkout and have its
+ * packaging wrongly enforced. Apply this to every persisted store/key a `/qr`
  * flow touches EXCEPT auth (`queek-storefront-user`, the access/refresh
  * tokens in `queek-client.ts`) — a signed-in customer must stay signed in
  * across both.