@usequeek/theme-kit 0.1.21 → 0.1.22

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';
@@ -49,11 +45,12 @@ 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 theme-check can import it too).
+// (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.

package/locales/en.default.json

@@ -172,5 +172,9 @@
         "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.21",
+  "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.

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

@@ -1,8 +1,8 @@
 /**
- * Pseudo-locale QA (slice: typed keys + pseudo-locale QA helper).
+ * Pseudo-locale QA helper.
  *
  * PURE AND SERVER-SAFE: this module imports nothing from `next/*` and nothing
- * from React, so server components, Node tooling (theme-check), tests and the
+ * 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.
  *
@@ -19,8 +19,7 @@
  *    (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 (and the
- *    storefront, and theme-tools) import.
+ *    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.