@usequeek/theme-kit 0.1.21 → 0.1.22

package/README.md

@@ -1,30 +1,35 @@
 # @usequeek/theme-kit
 
 The framework a Queek storefront theme is built against: hooks, stores, headless
-flows (auth, cart, checkout), types and the block renderer.
-
-**Ships TypeScript source, not a build.** Most of its modules carry a
-`'use client'` directive, and that directive is the whole contract with the React
-Server Components boundary — bundlers routinely strip or hoist it when a library
-is pre-compiled, which turns a client module into a server one silently. The
-consumer transpiles instead (`transpilePackages: ['@usequeek/theme-kit']`), so the
-directives survive to the bundler that actually enforces them.
-
-Deep subpaths resolve off the filesystem — there is deliberately NO `exports`
-map. One was tried: with source-shipped `.ts`/`.tsx` an extensionless wildcard
-target does not resolve, and spelling out extensions cannot cover both. Legacy
-resolution under `moduleResolution: bundler` handles it. The cost is that the
-package has no subpath encapsulation, so what a theme may import is enforced by
-convention plus tests: `tests/public-surface.test.ts` here (barrels declare
-only modules that exist) and `core-public-surface.test.ts` in the storefront
-repo (barrels cover every module the themes actually import).
-
-Every module that annotates a return as `JSX.Element` does
-`import type { JSX } from 'react'` — React 19 removed the global `JSX`
-namespace, and 0.1.0 shipped broken for every external consumer by relying on
-the storefront app's `next-env.d.ts` to provide it. `scripts/verify-package.ts`
-packs the current source and typechecks a real theme against it from a sandbox,
-so that class of breakage fails here instead of after publishing.
+flows (auth, cart, checkout), types and the block renderer. See the
+[theme documentation](https://docs.usequeek.com/docs/themes) for how themes
+work end to end.
+
+## Install
+
+```bash
+npm install @usequeek/theme-kit
+```
+
+Peer dependencies: `next` (>=15), `react` and `react-dom` (>=19) and
+`@queekai/client-sdk`.
+
+The package ships TypeScript source, not a build. Most modules carry a
+`'use client'` directive, and that directive is the whole contract with the
+React Server Components boundary; bundlers routinely strip or hoist it when a
+library is pre-compiled, which silently turns a client module into a server
+one. The consumer transpiles the package instead, so the directives reach the
+bundler that enforces them:
+
+```ts
+// next.config.ts
+export default { transpilePackages: ['@usequeek/theme-kit'] };
+```
+
+Compiling a theme against it needs `moduleResolution: bundler` and
+`jsx: react-jsx`. A vitest setup that renders kit components needs the package
+inlined (`server.deps.inline: ['@usequeek/theme-kit']`) so the shipped `.tsx`
+source is transformed like first-party code.
 
 ## Use
 
@@ -33,10 +38,16 @@ import { useCart } from '@usequeek/theme-kit/hooks/use-cart';
 import type { ThemeModule } from '@usequeek/theme-kit/types/theme';
 ```
 
-Deep paths, mirroring the old `@/lib/core/*`. Barrels exist (`.` and `./client`)
-to DECLARE the public surface — what a theme is allowed to build against — but
-importing through them pulls every client module into one chunk and was measured
-to break the app's build. Import the module you want.
+Import the module you need by its deep path. The barrels (`.` and `./client`)
+declare the public surface, meaning what a theme is allowed to build against,
+but importing through them pulls every client module into one chunk and can
+break an app's build.
+
+There is no `exports` map: with source-shipped `.ts`/`.tsx`, an extensionless
+wildcard target does not resolve, so subpaths resolve off the filesystem under
+`moduleResolution: bundler`. The package therefore has no subpath
+encapsulation; what a theme may import is the surface the barrels declare,
+checked by `tests/public-surface.test.ts`.
 
 Theme CSS ships with the package: `@usequeek/theme-kit/shared-blocks/core-blocks.css`
 (framework-owned blocks), plus per-component CSS next to its component
@@ -44,9 +55,9 @@ Theme CSS ships with the package: `@usequeek/theme-kit/shared-blocks/core-blocks
 
 ## Theme strings
 
-The kit's Shopify-shaped UI-string mechanism (`strings/theme-strings.ts`,
-pure: no `next/*`, no React). Additive and backward-compatible — a theme or
-provider that passes nothing renders exactly as today, in English.
+The kit's UI-string mechanism (`strings/theme-strings.ts`; pure, with no
+`next/*` and no React). A theme or provider that passes nothing renders in
+English. See also [Translating your theme](https://docs.usequeek.com/docs/themes/translations).
 
 - **Authoring contract.** `t(dictionaries, key, vars?, locale?)`: dot-path
   lookup (`cart.title`), `{var}` interpolation (`{{`/`}}` escape to literal
@@ -56,9 +67,9 @@ provider that passes nothing renders exactly as today, in English.
   `vars.count`, defaulting to `other`. Locale-aware `formatThemeNumber`,
   `formatThemeDate` and `formatThemeMoney` replace hardcoded `en-GB`
   formatting; an unknown locale falls back to English. Keys are dotted
-  lowercase `scope.thing.state`, max **40 chars**; values max **1000 chars**:
-  the backend overlay stores `<theme-slug>.<key>` in a varchar(64), so the
-  key budget leaves 23 chars for the slug plus the dot.
+  lowercase `scope.thing.state`, max **40 chars**; values max **1000 chars**.
+  Merchant overrides are stored as `<theme-slug>.<key>` in a 64-character
+  field, so the key budget leaves 23 chars for the slug plus the dot.
 - **Two surfaces.** Server (provider-free): the host supplies per-locale
   loaders and calls
   `createThemeStrings({ locale, loaders })` — `{ override, theme, core }`,
@@ -90,10 +101,9 @@ provider that passes nothing renders exactly as today, in English.
   provider — other `{lang}.json` files never enter the client bundle.
   Only `locales/en.default.json` may be statically imported (by
   `strings/theme-strings.ts` itself); every other locale arrives via the
-  host's dynamic `import()` per locale. `tests/theme-strings.test.tsx`
-  gates this: any other static locale import fails the suite.
+  host's dynamic `import()` per locale.
 - **Typed keys (optional, compile-time).** A theme opts in per call site —
-  existing untyped `t(key)` callers keep compiling unchanged.
+  untyped `t(key)` callers keep compiling unchanged.
   `ThemeStringKey<typeof strings>` derives the key union from the theme's
   English dictionary object (nested objects flatten to dotted keys, a
   plural map counts as ONE key, flat literal dotted keys stay one key),
@@ -110,9 +120,6 @@ provider that passes nothing renders exactly as today, in English.
   // tt('cart.titl'); // type error — typo keys fail, valid keys pass
   ```
 
-  (`tests/theme-typed-keys.fixture.ts` proves this under
-  `npm run typecheck`: valid keys pass, typo/unknown/plural-form keys are
-  `@ts-expect-error` errors.)
 - **Pseudo-locale QA (dev/test only, never shipped).**
   `pseudoLocalize(dictionary, options?)`
   (`strings/pseudo-locale.ts`, pure: no `next/*`, no React) returns a
@@ -123,9 +130,7 @@ provider that passes nothing renders exactly as today, in English.
   pseudo dictionary as the `strings` prop: everything that went through
   `t()` renders pseudo, so any text that remains plain English next to
   pseudo text is a hard-coded (un-wrapped) string. In tests, render with
-  the pseudo dictionary and run the English-leak scan over the HTML —
-  the reusable primitive theme tests import (the storefront and
-  theme-tools import it from the same pure module):
+  the pseudo dictionary and run the English-leak scan over the HTML:
 
   ```tsx
   import { pseudoLocalize, assertNoEnglishLeak } from '@usequeek/theme-kit/strings/pseudo-locale';
@@ -147,53 +152,39 @@ provider that passes nothing renders exactly as today, in English.
 
 ## Locale-aware dates, numbers and relative time
 
-Dates, counts, money and relative time follow the SHOPPER's locale (founder
-2/10/26). English renders in the British/Nigerian style — `2 October 2026`,
-never US `October 2, 2026` — so English stores look exactly as before.
+Dates, counts, money and relative time follow the SHOPPER's locale. English
+renders in the British/Nigerian style — `2 October 2026`, never US
+`October 2, 2026`.
 
 - **One mapping.** `resolveIntlLocale(locale)` (`utils/locale.ts`, pure: no
   `next/*`, no React) is the single canonical storefront-code → Intl-locale
   mapping every formatter goes through. Missing/invalid codes and every
   English variant (`en`, `en-GB`, `en-NG`, `en-US`, …) become `en-NG`;
   everything else passes through (`fr`, `ar`, `pt-BR`, `zh-CN`, `yo`, `ha`,
-  `sw`, …). `en-NG` — not `en-GB` — because only it reproduces current
-  output byte for byte: both print `2 October 2026`, but `en-GB` renders NGN
-  as `NGN 12,500` where the stores show `₦12,500` (verified on Node 22, full
-  ICU). `resolveSupportedLocale` falls back to English when the runtime's
-  ICU lacks a locale — formatting never throws.
+  `sw`, …). `en-NG` — not `en-GB` — because it renders NGN as `₦12,500`
+  where `en-GB` renders `NGN 12,500` (both print dates as `2 October 2026`;
+  checked on Node 22 with full ICU). `resolveSupportedLocale` falls back to
+  English when the runtime's ICU lacks a locale — formatting never throws.
 - **What themes call.** `formatThemeDate(value, locale?, options?)`
   (`strings/theme-strings.ts`) instead of a hardcoded-`'en-GB'`
   `toLocaleDateString`: pass the storefront locale — client components via
   `useStorefrontLocale()`, server components via the request locale the host
   already holds. Siblings: `formatThemeNumber`, `formatThemeMoney`, and
   `formatThemeRelativeTime(-1, 'day', locale)` (`hier`, `أمس`, `ontem`, …,
-  `numeric: 'auto'`). `formatThemeMoney` keeps the K0 currency-default
+  `numeric: 'auto'`). `formatThemeMoney` uses the currency's default
   decimals (`₦5,000.00`); `formatMoney` shows decimals only when present
   (`₦5,000`, `₦0.28`). The fixed-zone display path is `formatShopperDate`
-  (`utils/format.ts`, Africa/Lagos, `''` for invalid dates as before);
-  `formatCount`/`formatMoney` take an optional locale, defaulting to the
-  pinned English output. `PostMeta` (`components/blog/post-meta.tsx`) already
-  renders its byline through the provider locale.
+  (`utils/format.ts`, Africa/Lagos, `''` for invalid dates);
+  `formatCount`/`formatMoney` take an optional locale, defaulting to English
+  output. `PostMeta` (`components/blog/post-meta.tsx`) renders its byline
+  through the provider locale.
 - **Fallbacks.** Unknown locale → English style; invalid date → `''`;
   minimal-ICU runtimes render English rather than throwing.
 - **Plural selection stays separate.** `canonicalThemeLocale`
   (`strings/theme-strings.ts`) is for `t()` plural selection ONLY: it returns
   a bare `'en'` tag, which is a US-order Intl tag. Never pass it to a date,
   number, money or relative-time formatter — formatters use
-  `resolveIntlLocale` (en* → `en-NG`) instead. A test fails the suite if any
-  formatter body ever calls it.
-- **Shopify comparison.** Shopify's Liquid
-  [`date` filter](https://shopify.dev/docs/api/liquid/filters/date) formats
-  with explicit strftime strings, or locale-aware via named `format:` options
-  (`abbreviated_date`, `basic`, `date`, `date_at_time`, `default`, `on_date`)
-  whose patterns live in the theme's locale files (`date_formats`); the
-  [`money` filter](https://shopify.dev/docs/api/liquid/filters/money) renders
-  per the store's currency-formatting setting. This slice differs
-  intentionally: one code-level mapping (`resolveIntlLocale`) instead of
-  per-locale format files, every English variant pinned to `en-NG`
-  (British/Nigerian order, never US), and an English fallback when the
-  runtime's ICU lacks the locale. Number/relative-time have no Liquid
-  equivalent consulted — UNVERIFIED remainder, no parity claim made.
+  `resolveIntlLocale` (en* → `en-NG`) instead.
 
 ```tsx
 import { useStorefrontLocale } from '@usequeek/theme-kit/provider';
@@ -204,23 +195,14 @@ formatThemeDate(post.published_at, locale, { year: 'numeric', month: 'long', day
 // en → "2 October 2026" · fr → "2 octobre 2026" · ar → "2 أكتوبر 2026"
 ```
 
-`tests/display-format.test.ts` pins this: every existing English string is
-byte-identical with or without a locale, `fr`/`ar`/`pt-BR`/`zh-CN`/`yo`/
-`ha`/`sw` outputs are asserted against real `Intl` output (with the
-English fallback when ICU lacks a locale), and a scan fails the suite if a
-hardcoded English locale ever reaches a formatter again.
-
 ## Consumers
 
-- **The Queek storefront** (`usequeek/queek-storefront`) installs this package
-  from the npm registry (`"@usequeek/theme-kit": "^x.y.z"`) and transpiles it
-  via `transpilePackages`. Its vitest config inlines the package
-  (`server.deps.inline: ['@usequeek/theme-kit']`) so the shipped `.tsx`
-  source is transformed like first-party code.
-- **External theme developers** start from `packages/theme-starter` in the
-  storefront repo, which builds standalone against a packed tarball of this
-  source. Anyone testing a theme with vitest needs the same `inline` line;
-  anyone compiling one needs `moduleResolution: bundler` + `jsx: react-jsx`.
+- **Queek storefronts** install this package from npm
+  (`"@usequeek/theme-kit": "^x.y.z"`) and transpile it via
+  `transpilePackages`.
+- **Theme developers** start from
+  [`usequeek/theme-starter`](https://github.com/usequeek/theme-starter), which
+  builds against this package.
 
 ## Custom data: metafields & metaobjects
 
@@ -275,7 +257,7 @@ export default function ProductPage({ product }: ProductPageProps) {
 ```
 
 - MUST: place `<AppBlocks target="product" productId={...} />` on the
-  product page. `target` is product-only in phase 1 — no other slot exists.
+  product page. `target` is product-only: no other slot exists.
   `productId` scopes availability reads and deep links to the shown product;
   omit `vendorSlug` (the host resolves the store itself).
 - The host registers its placement component once through `AppBlocksProvider`
@@ -292,8 +274,7 @@ export default function ProductPage({ product }: ProductPageProps) {
 
 ## Attribution: Powered by Queek
 
-Every storefront is a billboard — every footer variant of every theme renders
-the core-owned attribution link:
+Every theme footer renders the core-owned attribution link:
 
 ```tsx
 import { PoweredByQueek } from '@usequeek/theme-kit/components/powered-by-queek';
@@ -311,7 +292,8 @@ export default function Footer() {
 - MUST: place `<PoweredByQueek />` on every footer variant (`footers/*.tsx`,
   or `footer.tsx` where a theme has no `footers/` dir). The placement and
   spacing are the theme's — the component is the content, the footer owns
-  where it sits. `theme-check` rule `theme/footer-shows-powered-by` enforces
+  where it sits. The theme check rule `theme/footer-shows-powered-by`
+  ([checks reference](https://docs.usequeek.com/docs/themes/checks)) enforces
   this, so a theme cannot ship without it.
 - Style only: the link emits `core-powered-by` with a
   `core-powered-by__brand` hook on the `Queek` wordmark; an optional
@@ -324,9 +306,8 @@ export default function Footer() {
   (`utm_source=powered_by&utm_medium=storefront&utm_campaign=<store slug>`,
   campaign omitted when the store has no slug); the component reads the slug
   from the storefront context, so themes pass nothing.
-- `hidden` (default false) takes the component's visibility from a prop as
-  the seam for a possible future plan perk. There is no merchant-facing
-  toggle for it in v1 — always render it visible.
+- `hidden` (default false) takes the component's visibility from a prop.
+  There is no merchant-facing toggle for it — always render it visible.
 
 ## Locales
 
@@ -337,7 +318,7 @@ request locale on every catalogue/content transport, server and browser:
 - Server: `createServerStoreClient().get()` reads the incoming request's
   `x-queek-locale` header (set by the storefront proxy for published
   non-primary locales only — absent on the primary), appends `locale=<code>`
-  to the backend URL, and suffixes every cache tag with `:locale:<code>` so
+  to the API URL, and suffixes every cache tag with `:locale:<code>` so
   locales never share a cache entry. `fetchShopPrefetch`, `fetchCollections`,
   `fetchCollection` and `fetchCollectionProducts` take the same behaviour plus
   an optional explicit override. No header → byte-identical requests and tags.
@@ -348,11 +329,96 @@ request locale on every catalogue/content transport, server and browser:
   `useProductQuestions` and `useProductDetail` send `?locale=` when it is set
   and key their client caches by it. No prop → unchanged.
 
-What this means for themes: nothing to handle. Never read the header, never
-append `locale` yourself, and never build a language switcher — locale
-routing, `basePath` prefixing and the switcher are core-owned in the
-storefront. Links built from `basePath` keep their locale prefix with zero
-theme changes.
+What this means for themes: nothing to handle for the content itself. Never
+read the header and never append `locale` yourself — locale routing and
+`basePath` prefixing are core-owned in the storefront, and links built from
+`basePath` keep their locale prefix with zero theme changes. To let shoppers
+change language, place the kit's `LanguageSwitcher` (next section); do not
+build your own URL logic.
+
+## Language switcher
+
+A store can serve several languages. Its default language lives at the store
+root; every other language, English included when it is not the default, lives
+under its bare lower-case code (`/fr`, `/en`, `/zh-cn`). Changing language
+keeps the page, the query string and the hash.
+
+```tsx
+import { LanguageSwitcher } from '@usequeek/theme-kit/components/language-switcher';
+
+<LanguageSwitcher />                        // native <select> (default)
+<LanguageSwitcher variant="inline-list" />  // every language as a link
+```
+
+Place it unconditionally, in the header or the footer: it renders nothing on a
+single-language store, outside a storefront, and until the host passes the
+store's languages.
+
+| Prop | Default | |
+| --- | --- | --- |
+| `className` | | Extra class on the root, to position or restyle it. |
+| `variant` | `'select'` | `'select'`: one native dropdown (best keyboard, touch and screen-reader behaviour). `'inline-list'`: a link per language that wraps on narrow screens; suits a footer. |
+| `showNativeName` | `true` | Label languages in their own language (`Français`) instead of English (`French`). |
+| `showCode` | `false` | Append the code: `Français · FR`. |
+| `children` | | Render-prop `(state) => ReactNode`: replaces the default control entirely (never called on a single-language store). `state` is `useLocales()` plus `label`, `labelFor(locale)` and `displayName(locale)`. |
+
+**Tell the storefront the theme places it.** Set `languageSwitcher: 'theme'` in
+the theme manifest. Without it the storefront keeps rendering its own floating
+language control next to yours; with it the storefront renders none and the
+shopper sees exactly one.
+
+```ts
+// in the theme module
+manifest: { /* … */ languageSwitcher: 'theme' }   // ThemeManifest.languageSwitcher
+```
+
+**Fully custom markup.** `useLocales()` (from
+`@usequeek/theme-kit/hooks/use-locales`) returns:
+
+| Field | |
+| --- | --- |
+| `locales` | The store's languages, default first. One entry, or none, on a single-language store. |
+| `active` | The language the page renders in. |
+| `defaultLocale` | The language served at the store root. |
+| `hasMultiple` | `locales.length > 1`. |
+| `hrefFor(locale)` | The current page in another language (takes a row or a code), e.g. `/fr/shop?sort=new`. The first render carries no query string or hash, so server and client markup match; they are added right after mount. |
+| `switchTo(locale)` | Navigate to it, reading the live query string and hash. Use it for `onClick`/`onChange`. |
+
+Each language is `{ locale, name, native_name, is_primary, is_default,
+path_prefix, hreflang, html_lang, dir }`. Use `lang={l.html_lang}` and
+`dir={l.dir}` on a label written in that language. The pure URL rules are also
+exported (`localeHref`, `normalizeStoreLocales`, `defaultStoreLocale`,
+`resolveActiveLocale` from `@usequeek/theme-kit/utils/locale-switch`).
+
+**Strings.** `language.label` ("Language") names the control and
+`language.named` ("Language: {name}") names the select and the current
+language. Both are kit core strings with English defaults; a theme can
+override them in its manifest `strings`, and merchants and translators in
+their locale packs.
+
+**Styling.** The default control reads only these tokens, each with a neutral
+fallback, and uses logical properties, so it mirrors in right-to-left
+storefronts and sits in a header or footer unstyled:
+
+| Token | Used for | Fallback |
+| --- | --- | --- |
+| `--qn-text` | text and icon colour | inherited |
+| `--qn-border` | select border | 22% of the text colour |
+| `--qn-border-strong` | select border on hover | the text colour |
+| `--qn-surface` | select background | transparent |
+| `--qn-radius-sm` | corner radius | `6px` |
+| `--qn-focus` | focus ring | the text colour |
+
+Class names for deeper overrides: `qn-lang`, `qn-lang--select`,
+`qn-lang--inline-list`, `qn-lang__select`, `qn-lang__list`, `qn-lang__link`.
+Targets are at least 44px. The root carries `data-qn-language-switcher`.
+
+**Host side.** The host passes the store's languages to
+`StorefrontProvider` as the optional `locales` prop (the rows as it already
+holds them; extra fields are ignored, and a row without `is_default` falls
+back to `is_primary`). `basePath` must already carry the active language
+prefix, as in the Locales section. No prop, or one language: no switcher, and
+everything behaves as before.
 
 ## Links and navigation
 
@@ -361,42 +427,46 @@ import { Link, useRouter, usePathname } from '@usequeek/theme-kit/navigation';
 ```
 
 A theme links and navigates through these, never through `next/link` or
-`next/navigation`. Which framework runs the storefront is Queek's decision: the
-kit is the one place that knows it, so a change there is a kit release, not an
-update to every theme. `Link` is an `<a>` that moves inside the store without a
-full page load (`href`, `prefetch`, `replace`, plus any anchor attribute);
-`useRouter()` gives `push`, `replace`, `back` and `refresh`; `usePathname()`
-returns the current path. The theme check rejects a theme that imports `next`.
+`next/navigation`. Which framework runs the storefront is Queek's decision, so
+the kit is the one place that knows it, and a framework change is a kit
+release, not an update to every theme. `Link` is an `<a>` that moves inside the
+store without a full page load (`href`, `prefetch`, `replace`, plus any anchor
+attribute); `useRouter()` gives `push`, `replace`, `back` and `refresh`;
+`usePathname()` returns the current path. The theme check rejects a theme that
+imports `next`.
 
 ## Boundary
 
-The kit must never import the storefront app, its themes, or `lib/storefront`.
-That one-way rule is what makes this package extractable at all. The reverse
-also holds for the framework: the kit may import `next`, a theme may not.
+The kit never imports a host app or any theme. The reverse rule holds for the
+framework: the kit may import `next`, a theme may not.
 
 ## Develop
 
 ```bash
 npm install
-npm run typecheck   # tsc --noEmit, standalone — no storefront files
-npm test            # vitest run
+npm run typecheck       # tsc --noEmit
+npm test                # public-text check, then vitest run
 npm run verify-package  # pack current source, typecheck a real theme against it
 ```
 
+`verify-package` packs the current source and typechecks a real theme against
+it from a sandbox, so a break that only external consumers would see (for
+example a module relying on the global `JSX` namespace, which React 19 removed)
+fails here instead of after publishing.
+
 ## Release
 
-The package is public on npm; the repo is private. Publishing runs on tags via
-`.github/workflows/publish.yml` (needs the `NPM_TOKEN` secret):
+Publishing runs on tags via `.github/workflows/publish.yml`, which needs the
+`NPM_TOKEN` repository secret:
 
 ```bash
 # 1. Bump version in package.json and commit
-# 2. Tag and push the tag — the workflow typechecks, tests, verify-packages,
+# 2. Tag and push the tag — the workflow typechecks, tests, runs verify-package,
 #    then `npm publish --access public`:
-git tag v0.1.6
+git tag vX.Y.Z
 git push origin main --tags
 ```
 
-The storefront then bumps its dependency to match the published version
-(`yarn add @usequeek/theme-kit@^0.1.6` + lockfile) and pushes separately —
-never the other way round: the app must only ever depend on a version that
-actually exists on the registry.
+## License
+
+MIT

package/api/collections.ts

@@ -4,8 +4,8 @@ import type { Collection, Pagination } from '../types/page';
 import type { ApiResponse } from '../types/product';
 import { extractProducts, normalizeProduct } from '../utils/product-normalizer';
 
-/** Matches `VendorCollectionProductsRequest`'s validated `sort` values exactly
- *  (queek_backend) — a value outside this list gets a 422 from the backend. */
+/** The `sort` values the collection-products endpoint accepts; any other value
+ *  gets a 422 from the API. */
 export type CollectionSort = 'newest' | 'popular' | 'price_low' | 'price_high';
 
 export interface FetchCollectionProductsOptions {
@@ -17,9 +17,9 @@ export interface FetchCollectionProductsOptions {
   locale?: string;
 }
 
-// SSR collection reads go through `/client/store/*` so ResolveClientContext forces
-// X-Platform=storefront (base prices, no marketplace commission) — never the
-// legacy v1 routes shared with the commission-bearing marketplace.
+// SSR collection reads go through `/client/store/*`, which resolves the store and
+// forces X-Platform=storefront (base prices, no marketplace commission) — never
+// the legacy v1 routes shared with the marketplace.
 export async function fetchCollections(vendorSlug: string, storefrontOnly = true, locale?: string): Promise<Collection[]> {
   const client = createServerStoreClient(vendorSlug, await getRequestOrigin());
 

package/api/shop.ts

@@ -6,7 +6,7 @@ import { parseShopResponse, shopRequestParams, type ShopPrefetch, type ShopQuery
  * The shop page's first page of products, fetched while the server renders
  * `/shop`, for `ShopPrefetchProvider` to hand to `useShop` — so the product grid
  * is in the HTML instead of appearing after the browser has run the JS and
- * fetched it (kili-foods' `/shop` main content landed at 2.8 s that way).
+ * fetched it.
  *
  * Same request and the same parsing as the browser's `useShop` (both come from
  * utils/shop-query). Reads go through `/client/store/*` like every SSR read, so

package/client.ts

@@ -16,6 +16,7 @@ export * from './components/blog';
 export * from './components/image';
 export * from './components/product-metafields';
 export * from './components/powered-by-queek';
+export * from './components/language-switcher';
 export * from './components/default-metaobject-page';
 export * from './components/product-media-frame';
 export * from './components/variant-picker';
@@ -30,6 +31,7 @@ export * from './apps/subscribe-form';
 export * from './api/collections';
 export * from './api/orders';
 export * from './hooks/use-href';
+export * from './hooks/use-locales';
 export * from './hooks/use-auth';
 export * from './hooks/use-cart';
 export * from './hooks/use-shop-cart';

package/components/checkout/checkout-contact.tsx

@@ -8,9 +8,9 @@ import { Image } from '../image';
 
 /**
  * First section of the checkout form — shows who's checking out. Ordering
- * requires auth (`canCheckout` in checkout-controller.tsx), so unlike
- * Shopify's guest-friendly email field this is purely an identity
- * confirmation: avatar + email when signed in, a sign-in prompt otherwise.
+ * requires auth (`canCheckout` in checkout-controller.tsx), so this is purely
+ * an identity confirmation, not an email field: avatar + email when signed in,
+ * a sign-in prompt otherwise.
  */
 export function CheckoutContactSection(): JSX.Element {
   const { user, isAuthenticated, openAuthModal, logout } = useAuth();

package/components/image.tsx

@@ -35,11 +35,11 @@ type ImageProps = ImgHTMLAttributes<HTMLImageElement> & {
   fallback?: string;
   placeholder?: PlaceholderProp;
   /**
-   * The backend's srcset-ready tier map (product.media.image_variants,
+   * The API's srcset-ready tier map (product.media.image_variants,
    * vendor.logo_variants, collection.image_variants, mediaIndex[url], …).
-   * Purely additive: when absent — as it is at every call site that hasn't been
-   * migrated, and whenever the backend legitimately sends null (off-host image,
-   * SVG, legacy upload) — this component behaves exactly as it did before.
+   * Purely additive: when absent — and whenever the API legitimately sends null
+   * (off-host image, SVG, legacy upload) — this component renders the plain
+   * image URL.
    */
   variants?: ImageVariants | null;
   /**
@@ -133,7 +133,7 @@ export function Image({ fallback, placeholder, variants, intent = 'raw', onError
   // image is invisible until hover. Eager, a server-rendered grid of 24 cards
   // made React preload the first ~10 (also into the 103 Early Hints header) and
   // fetch every image at once, racing the page's render-blocking CSS: /shop's
-  // first paint went 1.8 s → 2.9 s on Slow 4G (24/9/26). Lazy is next/image's
+  // first paint went from 1.8 s to 2.9 s on Slow 4G. Lazy is next/image's
   // default as well. A theme whose card IS the page's main image passes
   // loading="eager" or fetchPriority="high".
   const lazyByDefault = (intent === 'card' || intent === 'card2x') && props.fetchPriority !== 'high';