@usequeek/theme-kit 0.1.21 → 0.1.23

package/components/powered-by-queek.tsx

@@ -8,8 +8,8 @@ export interface PoweredByQueekProps {
   /** Extra class so a footer can position the link — styling stays theme-owned. */
   className?: string;
   /**
-   * Reserved for a future plan perk (paid removal). Defaults to false and is
-   * always rendered in v1 — there is no merchant-facing toggle for it.
+   * Lets a caller hide the link from a prop. Defaults to false; themes always
+   * render it visible — there is no merchant-facing toggle for it.
    */
   hidden?: boolean;
 }
@@ -18,8 +18,8 @@ export interface PoweredByQueekProps {
  * Core-owned storefront attribution — the `ProductMetafields` pattern: themes
  * import-and-place it, never re-implement it.
  *
- * Required on every footer variant of every theme (enforced by `theme-check`
- * rule `theme/footer-shows-powered-by` in the storefront repo). The link
+ * Required on every footer variant of every theme (enforced by the
+ * `theme/footer-shows-powered-by` rule of the theme check). The link
  * target (`https://usequeek.com/business`) and `rel` are the contract —
  * do not change them. The href is tagged `utm_source=powered_by`,
  * `utm_medium=storefront`, `utm_campaign=<store slug>` via `poweredByQueekUrl`

package/components/product-media-frame.tsx

@@ -41,7 +41,7 @@ export function ProductMediaFrame({
   }
 
   // Thumbnail strips render at ~64-90px across every theme — the `thumb` tier
-  // (a fixed-src, never-in-a-srcset tier by contract) is exactly right there.
+  // (a fixed-src tier that is never part of a srcset) is exactly right there.
   const resolvedIntent: ImageIntent = intent ?? (variant === 'thumbnail' ? 'avatar' : 'hero');
 
   return (

package/components/product-metafields.tsx

@@ -23,8 +23,7 @@ export interface ProductMetafieldsProps {
  * Renders the product's presented metafields (all types), with linked
  * metaobject entries as cards. Renders nothing when there are no visible
  * values. Markup carries `core-metafields*` classes so each theme styles it
- * in its own `theme.css` (framework-owned styling contract) — no theme CSS
- * lives in core.
+ * in its own `theme.css` — no theme CSS ships in the kit.
  */
 
 function isEntry(value: unknown): value is MetaobjectEntry {
@@ -95,7 +94,7 @@ function renderScalar(value: MetafieldScalar, key: string, label: string, type:
 
   if (type === 'media_id') {
     return /^https?:\/\//i.test(text) ? (
-      // Media values arrive as resolved URLs (media contract) — plain <img>:
+      // Media values arrive as resolved URLs — plain <img>:
       // this is core, not a theme, so the themes' <Image> rule doesn't apply.
       <img className="core-metafields__image" src={text} alt={label} loading="lazy" />
     ) : (

package/components/variant-picker.tsx

@@ -14,17 +14,14 @@ interface VariantPickerProps {
 /**
  * Renders a product's option groups as color swatch / image swatch / text
  * buttons — standard e-commerce priority: color_code first, else a
- * representative image, else plain text. Extracted from quick-add-page.tsx
- * (the channel/chat add-to-cart flow, the one place that already got this
- * right) so the other two surfaces missing a picker entirely — the QR
- * ordering sheet and the default theme's quick-view modal — can reuse it
- * instead of a third reimplementation. Pair with `matchVariant()`
- * (lib/core/utils/match-variant.ts) to resolve `selectedOptions` into a real
+ * representative image, else plain text. Shared by every surface that needs
+ * an option picker (quick-add, the QR ordering sheet, a theme's quick-view
+ * modal) instead of each re-implementing it. Pair with `matchVariant()`
+ * (utils/match-variant.ts) to resolve `selectedOptions` into a real
  * `ProductVariant`, and gate the add action on that being non-null before
  * calling `addProduct`/`addItemWithAddons` — a variant-enabled product added
- * without one fails the cart save server-side (DiscountService's
- * VariantSelectionException) rather than merely being "no variant"; there
- * is no valid no-selection state to fall back to.
+ * without one fails the cart save server-side rather than merely being "no
+ * variant"; there is no valid no-selection state to fall back to.
  */
 export function VariantPicker({ product, selectedOptions, onSelect, className }: VariantPickerProps): JSX.Element | null {
   if (product.options.length === 0) return null;

package/demo.ts

@@ -1,16 +1,13 @@
 /**
  * Turns a theme's `demo.json` into the props its components expect.
  *
- * SHIPPED WITH THE KIT because without it a theme developer has demo data and
- * no way to render it. THEME.md already requires every theme to carry a
- * demo.json; these are the functions that resolve its block references into
- * real products, categories, posts and collections. They lived in the
- * storefront's own preview routes, so they existed only here — a theme could be
- * written outside this repo and never shown running against its own data.
+ * Shipped with the kit so a theme developer can render the demo data every
+ * theme carries in its `demo.json`: these are the functions that resolve its
+ * block references into real products, categories, posts and collections, so a
+ * theme can be previewed running against its own data.
  *
- * Pure and type-only by construction: no `fs`, no `next`, no app imports. That
- * is what made moving it a rename rather than a rewrite, and it is why these
- * work identically in a developer's preview and in this repo's preview routes.
+ * Pure and type-only by construction: no `fs`, no `next`, no app imports, so
+ * these work identically in any preview.
  */
 import type { Block, ReviewItem } from './types/block';
 import type { Menu } from './types/menu';
@@ -81,11 +78,10 @@ export function getEnrichedPage<T extends Page>(page: T, demo: PreviewDemoData):
 }
 
 /**
- * `demo.json`'s `posts` array is the documented, spec-correct source (see
- * `themes/THEME.md` — "must mirror the vendor bootstrap shape") — a few
- * themes authored it before the `content: Block[]` / `cover_image_url`
- * convention settled, so this tolerates the older shapes instead of
- * assuming every theme's data is current.
+ * `demo.json`'s `posts` array must mirror the shape of a store's blog posts
+ * (`content: Block[]`, `cover_image_url`). Some themes authored it before that
+ * convention settled, so this tolerates the older shapes instead of assuming
+ * every theme's data is current.
  */
 function normalizePost(raw: Record<string, unknown>): Post {
   const legacyMedia = raw.media as { image?: string; thumbnail?: string } | undefined;

package/design-token-preview.tsx

@@ -58,8 +58,6 @@ export function attachDesignTokenPreviewListener(target: StylableTarget): () =>
  * onto the brand-root element's inline style, overlaying (not replacing)
  * the SSR vars from `getBrandCssVariables`. Never persisted — a normal
  * navigation/refresh reloads the real config.
- *
- * Frozen protocol: queek_backend `.agent/.tmp/live-preview-protocol.md`.
  */
 export function DesignTokenPreviewListener({
   targetRef,

package/edit-mode-active.tsx

@@ -11,9 +11,8 @@ const MESSAGE_SOURCE = 'queek-storefront';
 const MESSAGE_SOURCE_PARENT = 'queek-merchant';
 
 // Longest edge of the captured JPEG, in CSS px. Keeps the resulting
-// data-URI small (~50-150KB) so it can ride the qee chat POST body inline.
-// TODO: upload the capture to media (media.usequeek.com) and send a URL
-// instead of a data-URI once resume-persistence of attachments is needed.
+// data-URI small (~50-150KB) so it can ride a Qee chat request body inline
+// instead of being uploaded and referenced by URL.
 const CAPTURE_MAX_EDGE = 1000;
 
 async function captureBlock(el: HTMLElement): Promise<string> {
@@ -146,7 +145,7 @@ export function ActiveBlock({
 
   // Screenshot THIS section locally (edit mode only — the whole component tree
   // only renders inside the editor iframe) and hand the JPEG data-URI to the
-  // merchant, which turns it into a pending qee-chat attachment.
+  // merchant, which attaches it to a Qee chat message.
   const captureToQee = async (): Promise<void> => {
     const el = elRef.current;
     if (!el || capturing) return;

package/hooks/use-announcement.ts

@@ -8,7 +8,7 @@ const ROTATE_EVERY_MS = 6000;
  * Turns the stored announcement into the rotating one every header receives:
  * `text` is the message currently showing (so a header that only ever read
  * `text` rotates with no change), `messages`/`index`/`next`/`prev` let a
- * header draw its own pager (roast). Auto-advances while there is more than
+ * header draw its own pager. Auto-advances while there is more than
  * one message; a manual step restarts the clock so the message just chosen
  * gets its full turn.
  */

package/hooks/use-auth-flow.tsx

@@ -255,7 +255,7 @@ export function AuthFlowProvider({ children }: { children: ReactNode }): JSX.Ele
         console.warn('[google-auth] redirect endpoint returned non-2xx', res.status, text);
         throw new Error(`Failed to initiate Google auth (HTTP ${res.status}).`);
       }
-      // Laravel envelope: { status, message, data: { url } }
+      // Response envelope: { status, message, data: { url } }
       const body = (await res.json()) as {
         data?: { url?: string; redirect_url?: string };
         url?: string;

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';
@@ -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.23",
   "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;