@cartbase/storefront 0.20.0 → 0.20.1

package/src/lib/payment-constants.ts

@@ -1,53 +1,53 @@
-/**
- * Payment tender helpers — identifier sniffing for store payment sessions.
- *
- * The Cartbase wire has exactly TWO tender shapes since the pp_* kill
- * (20260811250000, no-payment-method-by-default card):
- *
- *   - a PROCESSOR the merchant connected — `provider_id` (`pp_stripe`
- *     today; PayPal etc. as integrations land);
- *   - a merchant-operated PAYMENT METHOD — `payment_method_id` + `name` +
- *     `kind` (`manual` for Bank transfer / Pay in store, `cod` for the
- *     collection-on-delivery switch). Its session carries `provider_id`
- *     NULL; the merchant's NAME is the display everywhere.
- *
- * The dead ids (`pp_cod`, `pp_manual`, `pp_system_default`) are gone from
- * the wire and from this module. The Medusa-era Stripe prefixes
- * (`pp_stripe_*`, `pp_medusa-*`) are kept as fallbacks so components
- * ported later keep working against either wire.
- *
- * Intentionally ships NO icons — stores render their own icons via their
- * own icon set. The library stays free of icon-kit imports at this layer.
- */
-
-/**
- * True if the provider id is a Stripe-backed card payment provider.
- * Cartbase's canonical ids first (`pp_stripe` / `stripe`), then the
- * Medusa-era prefixes (`pp_stripe_*`, `pp_medusa-*`).
- */
-export const isStripeLike = (providerId?: string | null): boolean => {
-  return Boolean(
-    providerId &&
-      (providerId === "pp_stripe" ||
-        providerId === "stripe" ||
-        providerId.startsWith("pp_stripe_") ||
-        providerId.startsWith("pp_medusa-"))
-  )
-}
-
-/** True if the provider id is PayPal. */
-export const isPaypal = (providerId?: string | null): boolean => {
-  return Boolean(providerId?.startsWith("pp_paypal"))
-}
-
-export const paymentInfoMap: Record<
-  string,
-  { title: string; icon: React.JSX.Element | null }
-> = {
-  pp_stripe: { title: "Credit / debit card", icon: null },
-  pp_stripe_stripe: { title: "Credit / debit card", icon: null },
-  "pp_medusa-payments_default": { title: "Credit / debit card", icon: null },
-  "pp_stripe-ideal_stripe": { title: "iDeal", icon: null },
-  "pp_stripe-bancontact_stripe": { title: "Bancontact", icon: null },
-  pp_paypal_paypal: { title: "PayPal", icon: null },
-}
+/**
+ * Payment tender helpers — identifier sniffing for store payment sessions.
+ *
+ * The Cartbase wire has exactly TWO tender shapes since the pp_* kill
+ * (20260811250000, no-payment-method-by-default card):
+ *
+ *   - a PROCESSOR the merchant connected — `provider_id` (`pp_stripe`
+ *     today; PayPal etc. as integrations land);
+ *   - a merchant-operated PAYMENT METHOD — `payment_method_id` + `name` +
+ *     `kind` (`manual` for Bank transfer / Pay in store, `cod` for the
+ *     collection-on-delivery switch). Its session carries `provider_id`
+ *     NULL; the merchant's NAME is the display everywhere.
+ *
+ * The dead ids (`pp_cod`, `pp_manual`, `pp_system_default`) are gone from
+ * the wire and from this module. The Medusa-era Stripe prefixes
+ * (`pp_stripe_*`, `pp_medusa-*`) are kept as fallbacks so components
+ * ported later keep working against either wire.
+ *
+ * Intentionally ships NO icons — stores render their own icons via their
+ * own icon set. The library stays free of icon-kit imports at this layer.
+ */
+
+/**
+ * True if the provider id is a Stripe-backed card payment provider.
+ * Cartbase's canonical ids first (`pp_stripe` / `stripe`), then the
+ * Medusa-era prefixes (`pp_stripe_*`, `pp_medusa-*`).
+ */
+export const isStripeLike = (providerId?: string | null): boolean => {
+  return Boolean(
+    providerId &&
+      (providerId === "pp_stripe" ||
+        providerId === "stripe" ||
+        providerId.startsWith("pp_stripe_") ||
+        providerId.startsWith("pp_medusa-"))
+  )
+}
+
+/** True if the provider id is PayPal. */
+export const isPaypal = (providerId?: string | null): boolean => {
+  return Boolean(providerId?.startsWith("pp_paypal"))
+}
+
+export const paymentInfoMap: Record<
+  string,
+  { title: string; icon: React.JSX.Element | null }
+> = {
+  pp_stripe: { title: "Credit / debit card", icon: null },
+  pp_stripe_stripe: { title: "Credit / debit card", icon: null },
+  "pp_medusa-payments_default": { title: "Credit / debit card", icon: null },
+  "pp_stripe-ideal_stripe": { title: "iDeal", icon: null },
+  "pp_stripe-bancontact_stripe": { title: "Bancontact", icon: null },
+  pp_paypal_paypal: { title: "PayPal", icon: null },
+}

package/src/lib/platform.ts

@@ -1,13 +1,13 @@
-/**
- * The platform's origin (one key, store-birth-and-doors item 6, 2026-09-07):
- * a constant, not an input. Every Cartbase store's API lives here; a
- * storefront overrides it only to point at a local or staging platform
- * (`NEXT_PUBLIC_CARTBASE_URL`), never to find its own store, which the
- * publishable key does.
- */
-export const CARTBASE_API_ORIGIN = "https://admin.cartbase.ai"
-
-/** The origin to call: the override when set, else the platform. */
-export function cartbaseApiOrigin(override?: string | null): string {
-  return (override && override.trim()) || CARTBASE_API_ORIGIN
-}
+/**
+ * The platform's origin (one key, store-birth-and-doors item 6, 2026-09-07):
+ * a constant, not an input. Every Cartbase store's API lives here; a
+ * storefront overrides it only to point at a local or staging platform
+ * (`NEXT_PUBLIC_CARTBASE_URL`), never to find its own store, which the
+ * publishable key does.
+ */
+export const CARTBASE_API_ORIGIN = "https://admin.cartbase.ai"
+
+/** The origin to call: the override when set, else the platform. */
+export function cartbaseApiOrigin(override?: string | null): string {
+  return (override && override.trim()) || CARTBASE_API_ORIGIN
+}

package/src/lib/price.tsx

@@ -1,39 +1,39 @@
-import * as React from "react"
-
-import { convertToLocale } from "./money"
-
-/**
- * Price — render an amount in its own currency, and nothing else.
- *
- * Replaces `DualPrice` (deleted 2026-09-13, Alexander: "clean and clear
- * the dual pricing"). That component appended a grey BGN leg to every EUR
- * price for Bulgaria's euro-changeover disclosure rule, with the statutory
- * 1.95583 rate baked in. Cartbase prices in EUR (see the EUR-only law) and
- * the second currency belongs to a store's own locale work if it ever
- * wants one, not to every price in the library.
- *
- * Stateless and side-effect-free, so it renders in server and client
- * components alike, and it is deliberately NOT a client component: the old
- * one carried "use client" for no reason, which pulled every price
- * rendering into the client bundle.
- *
- * @example
- *   <Price amount={19.99} currencyCode="eur" />   // "€19.99"
- */
-
-export type PriceProps = {
-  /** Amount in major units of the currency (19.99 for €19.99). */
-  amount: number
-  /** ISO currency code, case-insensitive. */
-  currencyCode: string
-  /** Class for the span. */
-  className?: string
-}
-
-export function Price({ amount, currencyCode, className }: PriceProps): React.ReactElement {
-  return (
-    <span className={className}>
-      {convertToLocale({ amount, currency_code: currencyCode })}
-    </span>
-  )
-}
+import * as React from "react"
+
+import { convertToLocale } from "./money"
+
+/**
+ * Price — render an amount in its own currency, and nothing else.
+ *
+ * Replaces `DualPrice` (deleted 2026-09-13, Alexander: "clean and clear
+ * the dual pricing"). That component appended a grey BGN leg to every EUR
+ * price for Bulgaria's euro-changeover disclosure rule, with the statutory
+ * 1.95583 rate baked in. Cartbase prices in EUR (see the EUR-only law) and
+ * the second currency belongs to a store's own locale work if it ever
+ * wants one, not to every price in the library.
+ *
+ * Stateless and side-effect-free, so it renders in server and client
+ * components alike, and it is deliberately NOT a client component: the old
+ * one carried "use client" for no reason, which pulled every price
+ * rendering into the client bundle.
+ *
+ * @example
+ *   <Price amount={19.99} currencyCode="eur" />   // "€19.99"
+ */
+
+export type PriceProps = {
+  /** Amount in major units of the currency (19.99 for €19.99). */
+  amount: number
+  /** ISO currency code, case-insensitive. */
+  currencyCode: string
+  /** Class for the span. */
+  className?: string
+}
+
+export function Price({ amount, currencyCode, className }: PriceProps): React.ReactElement {
+  return (
+    <span className={className}>
+      {convertToLocale({ amount, currency_code: currencyCode })}
+    </span>
+  )
+}

package/src/lib/store-api-error.ts

@@ -1,36 +1,36 @@
-import { StoreApiError } from "../api/types"
-
-/**
- * storeApiError — the successor of `@1click/ui`'s `medusaError`.
- *
- * Normalizes any error thrown by the `@cartbase/storefront` SDK layer into a
- * clean, user-presentable `Error` whose message starts with a capital and
- * ends with a period — the same normalization contract the Medusa-era
- * helper enforced, adapted to the Cartbase error contract (`StoreApiError`
- * with `status` + `code` + raw `body`, see `../api/types`).
- *
- * Always throws — never returns. Use in `.catch()` chains:
- *
- *   addLineItem(client, cartId, input).catch(storeApiError)
- *
- * Callers that need the PROGRAMMATIC surface (branching on `status` /
- * `code`, e.g. `checkout_method_hidden`, `invalid_gift_card`) should catch
- * `StoreApiError` directly instead — this adapter is the display-boundary
- * normalizer, deliberately lossy about everything but the message.
- */
-export default function storeApiError(error: unknown): never {
-  if (error instanceof StoreApiError) {
-    const message = error.message || `Store API error (${error.status})`
-    throw new Error(sentence(message))
-  }
-  if (error instanceof Error) {
-    throw new Error(sentence(error.message || "Unknown error"))
-  }
-  throw new Error("Error setting up the request: " + String(error))
-}
-
-/** Capitalize + terminal period — the medusaError display normalization. */
-function sentence(message: string): string {
-  const capitalized = message.charAt(0).toUpperCase() + message.slice(1)
-  return capitalized.endsWith(".") ? capitalized : capitalized + "."
-}
+import { StoreApiError } from "../api/types"
+
+/**
+ * storeApiError — the successor of `@1click/ui`'s `medusaError`.
+ *
+ * Normalizes any error thrown by the `@cartbase/storefront` SDK layer into a
+ * clean, user-presentable `Error` whose message starts with a capital and
+ * ends with a period — the same normalization contract the Medusa-era
+ * helper enforced, adapted to the Cartbase error contract (`StoreApiError`
+ * with `status` + `code` + raw `body`, see `../api/types`).
+ *
+ * Always throws — never returns. Use in `.catch()` chains:
+ *
+ *   addLineItem(client, cartId, input).catch(storeApiError)
+ *
+ * Callers that need the PROGRAMMATIC surface (branching on `status` /
+ * `code`, e.g. `checkout_method_hidden`, `invalid_gift_card`) should catch
+ * `StoreApiError` directly instead — this adapter is the display-boundary
+ * normalizer, deliberately lossy about everything but the message.
+ */
+export default function storeApiError(error: unknown): never {
+  if (error instanceof StoreApiError) {
+    const message = error.message || `Store API error (${error.status})`
+    throw new Error(sentence(message))
+  }
+  if (error instanceof Error) {
+    throw new Error(sentence(error.message || "Unknown error"))
+  }
+  throw new Error("Error setting up the request: " + String(error))
+}
+
+/** Capitalize + terminal period — the medusaError display normalization. */
+function sentence(message: string): string {
+  const capitalized = message.charAt(0).toUpperCase() + message.slice(1)
+  return capitalized.endsWith(".") ? capitalized : capitalized + "."
+}

package/src/lib/variant-caption.ts

@@ -1,32 +1,32 @@
-/**
- * The variant caption a shopper sees under a product title.
- *
- * A product with one variant has no real variant, only a placeholder name
- * for the row that holds its price: the platform names it "Default", a
- * Shopify import carries "Default Title", Medusa "Default variant". None of
- * them is a fact about the product, so none is shown. Every surface that
- * prints a variant (cart drawer, checkout summary, order page) goes through
- * this one function; a real variant title ("Size M / Red") passes through.
- *
- * Found 2026-09-14 on evoo's checkout summary, where every Shopify-imported
- * product read "Default Title" under its name while three surfaces each
- * tested a different spelling of the placeholder.
- */
-
-const PLACEHOLDER_TITLES = new Set(["default", "default title", "default variant"])
-
-/** True for an empty title or any spelling of the single-variant placeholder. */
-export function isPlaceholderVariantTitle(
-  title: string | null | undefined
-): boolean {
-  if (!title) return true
-  return PLACEHOLDER_TITLES.has(title.trim().toLowerCase())
-}
-
-/** The caption to render, or null when there is nothing worth showing. */
-export function variantCaption(title: string | null | undefined): string | null {
-  if (!title) return null
-  const trimmed = title.trim()
-  if (!trimmed || isPlaceholderVariantTitle(trimmed)) return null
-  return trimmed
-}
+/**
+ * The variant caption a shopper sees under a product title.
+ *
+ * A product with one variant has no real variant, only a placeholder name
+ * for the row that holds its price: the platform names it "Default", a
+ * Shopify import carries "Default Title", Medusa "Default variant". None of
+ * them is a fact about the product, so none is shown. Every surface that
+ * prints a variant (cart drawer, checkout summary, order page) goes through
+ * this one function; a real variant title ("Size M / Red") passes through.
+ *
+ * Found 2026-09-14 on evoo's checkout summary, where every Shopify-imported
+ * product read "Default Title" under its name while three surfaces each
+ * tested a different spelling of the placeholder.
+ */
+
+const PLACEHOLDER_TITLES = new Set(["default", "default title", "default variant"])
+
+/** True for an empty title or any spelling of the single-variant placeholder. */
+export function isPlaceholderVariantTitle(
+  title: string | null | undefined
+): boolean {
+  if (!title) return true
+  return PLACEHOLDER_TITLES.has(title.trim().toLowerCase())
+}
+
+/** The caption to render, or null when there is nothing worth showing. */
+export function variantCaption(title: string | null | undefined): string | null {
+  if (!title) return null
+  const trimmed = title.trim()
+  if (!trimmed || isPlaceholderVariantTitle(trimmed)) return null
+  return trimmed
+}

package/src/locales/context.ts

@@ -1,37 +1,37 @@
-"use client"
-
-import { createContext, useContext } from "react"
-import type { StorefrontLocale } from "./types"
-
-/**
- * THE MOUNTED LANGUAGE, as a context. Null outside `StorefrontLocaleProvider`.
- *
- * Its default is null and not `en` on purpose: `en` gathers every area's
- * English, and a client component that needs one area (the cart drawer, a
- * review card) must not bundle the other five to read it. Each reader hands
- * over its own area's English instead, through `useLocaleArea`, so a
- * component rendered with no language mounted behaves exactly as before.
- */
-export const StorefrontLocaleContext = createContext<StorefrontLocale | null>(null)
-
-/**
- * One area of the mounted language, for a CLIENT component that renders it.
- *
- *   const l = { ...useLocaleArea("reviews", defaultReviewsUiLabels), ...labels }
- *
- * The pack the store mounted wins over the area's English; a `labels` prop
- * still wins over both, so a store can override one word without a pack.
- * Since 2026-09-14 this is how the cart drawer and the reviews family are
- * localized: mount the provider once and there is nothing left to forget.
- *
- * A SERVER component cannot call this, because a server component has no
- * context. That is why the store, product and order templates take their
- * pack as a REQUIRED prop instead (`PropLabelAreas` in ./types).
- */
-export function useLocaleArea<K extends keyof StorefrontLocale>(
-  area: K,
-  english: StorefrontLocale[K]
-): StorefrontLocale[K] {
-  const locale = useContext(StorefrontLocaleContext)
-  return locale ? locale[area] : english
-}
+"use client"
+
+import { createContext, useContext } from "react"
+import type { StorefrontLocale } from "./types"
+
+/**
+ * THE MOUNTED LANGUAGE, as a context. Null outside `StorefrontLocaleProvider`.
+ *
+ * Its default is null and not `en` on purpose: `en` gathers every area's
+ * English, and a client component that needs one area (the cart drawer, a
+ * review card) must not bundle the other five to read it. Each reader hands
+ * over its own area's English instead, through `useLocaleArea`, so a
+ * component rendered with no language mounted behaves exactly as before.
+ */
+export const StorefrontLocaleContext = createContext<StorefrontLocale | null>(null)
+
+/**
+ * One area of the mounted language, for a CLIENT component that renders it.
+ *
+ *   const l = { ...useLocaleArea("reviews", defaultReviewsUiLabels), ...labels }
+ *
+ * The pack the store mounted wins over the area's English; a `labels` prop
+ * still wins over both, so a store can override one word without a pack.
+ * Since 2026-09-14 this is how the cart drawer and the reviews family are
+ * localized: mount the provider once and there is nothing left to forget.
+ *
+ * A SERVER component cannot call this, because a server component has no
+ * context. That is why the store, product and order templates take their
+ * pack as a REQUIRED prop instead (`PropLabelAreas` in ./types).
+ */
+export function useLocaleArea<K extends keyof StorefrontLocale>(
+  area: K,
+  english: StorefrontLocale[K]
+): StorefrontLocale[K] {
+  const locale = useContext(StorefrontLocaleContext)
+  return locale ? locale[area] : english
+}

package/src/locales/en.ts

@@ -1,26 +1,26 @@
-import { defaultCartDrawerLabels } from "../cart-drawer/labels"
-import { defaultCheckoutLabels } from "../checkout/labels"
-import { defaultOrderLabels } from "../order/labels"
-import { defaultProductLabels } from "../products/labels"
-import { defaultReviewsUiLabels } from "../reviews-ui/labels"
-import { defaultStoreLabels } from "../store/labels"
-import type { StorefrontLocale } from "./types"
-
-/**
- * ENGLISH — the library's own default, gathered into one locale object.
- *
- * It holds NO copy of its own: every field points at the defaults that
- * live beside each area's type, which are what a component renders when no
- * provider is mounted. So English cannot drift from the library, and a new
- * label added to any area appears here with no edit.
- */
-export const en: StorefrontLocale = {
-  code: "en",
-  name: "English",
-  products: defaultProductLabels,
-  store: defaultStoreLabels,
-  cartDrawer: defaultCartDrawerLabels,
-  checkout: defaultCheckoutLabels,
-  order: defaultOrderLabels,
-  reviews: defaultReviewsUiLabels,
-}
+import { defaultCartDrawerLabels } from "../cart-drawer/labels"
+import { defaultCheckoutLabels } from "../checkout/labels"
+import { defaultOrderLabels } from "../order/labels"
+import { defaultProductLabels } from "../products/labels"
+import { defaultReviewsUiLabels } from "../reviews-ui/labels"
+import { defaultStoreLabels } from "../store/labels"
+import type { StorefrontLocale } from "./types"
+
+/**
+ * ENGLISH — the library's own default, gathered into one locale object.
+ *
+ * It holds NO copy of its own: every field points at the defaults that
+ * live beside each area's type, which are what a component renders when no
+ * provider is mounted. So English cannot drift from the library, and a new
+ * label added to any area appears here with no edit.
+ */
+export const en: StorefrontLocale = {
+  code: "en",
+  name: "English",
+  products: defaultProductLabels,
+  store: defaultStoreLabels,
+  cartDrawer: defaultCartDrawerLabels,
+  checkout: defaultCheckoutLabels,
+  order: defaultOrderLabels,
+  reviews: defaultReviewsUiLabels,
+}

package/src/locales/index.ts

@@ -1,19 +1,19 @@
-/**
- * THE LOCALE LAYER.
- *
- * The library speaks international ENGLISH by default and knows nothing
- * about any other language. A language is a PACK the store imports:
- *
- *   import { es } from "@cartbase/storefront/locales/es"
- *   <StorefrontLocaleProvider locale={es}>{children}</StorefrontLocaleProvider>
- *
- * Import a pack by its own subpath (`/locales/es`, `/locales/bg`) rather
- * than from here, so a store that ships one language does not bundle the
- * others. This barrel carries the type, the provider and English only.
- *
- * Shipping: English, Spanish, Bulgarian (2026-09-13). Adding a language is
- * one file in this folder plus its export path, and nothing else.
- */
-export { en } from "./en"
-export { StorefrontLocaleProvider, useStorefrontLocale } from "./provider"
-export type { PropLabelAreas, StorefrontLocale } from "./types"
+/**
+ * THE LOCALE LAYER.
+ *
+ * The library speaks international ENGLISH by default and knows nothing
+ * about any other language. A language is a PACK the store imports:
+ *
+ *   import { es } from "@cartbase/storefront/locales/es"
+ *   <StorefrontLocaleProvider locale={es}>{children}</StorefrontLocaleProvider>
+ *
+ * Import a pack by its own subpath (`/locales/es`, `/locales/bg`) rather
+ * than from here, so a store that ships one language does not bundle the
+ * others. This barrel carries the type, the provider and English only.
+ *
+ * Shipping: English, Spanish, Bulgarian (2026-09-13). Adding a language is
+ * one file in this folder plus its export path, and nothing else.
+ */
+export { en } from "./en"
+export { StorefrontLocaleProvider, useStorefrontLocale } from "./provider"
+export type { PropLabelAreas, StorefrontLocale } from "./types"

package/src/locales/provider.tsx

@@ -1,59 +1,59 @@
-"use client"
-
-import { useContext, type ReactNode } from "react"
-import { CheckoutProvider } from "../checkout/context"
-import { OrderLabelsProvider } from "../order/context"
-import { ProductLabelsProvider } from "../products/context"
-import { StorefrontLocaleContext } from "./context"
-import type { StorefrontLocale } from "./types"
-import { en } from "./en"
-
-/**
- * ONE PROVIDER FOR THE STORE'S LANGUAGE.
- *
- *   import { es } from "@cartbase/storefront/locales/es"
- *   <StorefrontLocaleProvider locale={es}>{children}</StorefrontLocaleProvider>
- *
- * Every CLIENT component inside it speaks the pack, and nothing else has to
- * be wired: it mounts the three label contexts (products, checkout, order),
- * and the cart drawer and the reviews family read the language from it
- * directly (`useLocaleArea`, since 2026-09-14). It does not MOUNT the cart
- * drawer, because that provider carries the cart's state, its client and its
- * persistence callbacks, which belong where the app owns that state; the
- * drawer only reads the language from here.
- *
- * What it cannot reach is a SERVER component, because a server component has
- * no context. The store, product and order templates render on the server,
- * so each page hands them their area of the pack as a REQUIRED prop:
- * `PropLabelAreas` in ./types names them, with the mounts written out.
- *
- * DEFAULT IS ENGLISH. A component rendered outside this provider reads the
- * library's own English defaults, so nothing renders blank or crashes for
- * want of a provider.
- */
-export function StorefrontLocaleProvider({
-  locale,
-  children,
-}: {
-  locale: StorefrontLocale
-  children: ReactNode
-}) {
-  return (
-    <StorefrontLocaleContext.Provider value={locale}>
-      <ProductLabelsProvider labels={locale.products}>
-        <CheckoutProvider labels={locale.checkout}>
-          <OrderLabelsProvider labels={locale.order}>{children}</OrderLabelsProvider>
-        </CheckoutProvider>
-      </ProductLabelsProvider>
-    </StorefrontLocaleContext.Provider>
-  )
-}
-
-/**
- * The whole mounted locale, English when none is mounted: for the code that
- * needs the language itself, e.g. `<html lang={locale.code}>`, and for a
- * client shell that hands a server template its pack.
- */
-export function useStorefrontLocale(): StorefrontLocale {
-  return useContext(StorefrontLocaleContext) ?? en
-}
+"use client"
+
+import { useContext, type ReactNode } from "react"
+import { CheckoutProvider } from "../checkout/context"
+import { OrderLabelsProvider } from "../order/context"
+import { ProductLabelsProvider } from "../products/context"
+import { StorefrontLocaleContext } from "./context"
+import type { StorefrontLocale } from "./types"
+import { en } from "./en"
+
+/**
+ * ONE PROVIDER FOR THE STORE'S LANGUAGE.
+ *
+ *   import { es } from "@cartbase/storefront/locales/es"
+ *   <StorefrontLocaleProvider locale={es}>{children}</StorefrontLocaleProvider>
+ *
+ * Every CLIENT component inside it speaks the pack, and nothing else has to
+ * be wired: it mounts the three label contexts (products, checkout, order),
+ * and the cart drawer and the reviews family read the language from it
+ * directly (`useLocaleArea`, since 2026-09-14). It does not MOUNT the cart
+ * drawer, because that provider carries the cart's state, its client and its
+ * persistence callbacks, which belong where the app owns that state; the
+ * drawer only reads the language from here.
+ *
+ * What it cannot reach is a SERVER component, because a server component has
+ * no context. The store, product and order templates render on the server,
+ * so each page hands them their area of the pack as a REQUIRED prop:
+ * `PropLabelAreas` in ./types names them, with the mounts written out.
+ *
+ * DEFAULT IS ENGLISH. A component rendered outside this provider reads the
+ * library's own English defaults, so nothing renders blank or crashes for
+ * want of a provider.
+ */
+export function StorefrontLocaleProvider({
+  locale,
+  children,
+}: {
+  locale: StorefrontLocale
+  children: ReactNode
+}) {
+  return (
+    <StorefrontLocaleContext.Provider value={locale}>
+      <ProductLabelsProvider labels={locale.products}>
+        <CheckoutProvider labels={locale.checkout}>
+          <OrderLabelsProvider labels={locale.order}>{children}</OrderLabelsProvider>
+        </CheckoutProvider>
+      </ProductLabelsProvider>
+    </StorefrontLocaleContext.Provider>
+  )
+}
+
+/**
+ * The whole mounted locale, English when none is mounted: for the code that
+ * needs the language itself, e.g. `<html lang={locale.code}>`, and for a
+ * client shell that hands a server template its pack.
+ */
+export function useStorefrontLocale(): StorefrontLocale {
+  return useContext(StorefrontLocaleContext) ?? en
+}