create-cartbase 0.1.14 → 0.1.15

package/template/app/docs/components.md

@@ -1,1246 +1,1290 @@
-# Components
-
-The component layer of `@cartbase/storefront`: what each family ships, the SDK
-calls it requires, the admin settings that change its behavior, and its mount
-rules. Every family is production-proven — ported from live commerce
-storefronts and rewired to Cartbase data seams.
-
-This page has no executable curls — the endpoints these components consume
-are executably documented in their own domain files
-([integrations.md](integrations.md), [consent.md](consent.md), etc.); this
-page is the component-side contract that binds to them.
-
-Import discipline: always import from the subpath
-(`@cartbase/storefront/tracking/meta-pixel`, `@cartbase/storefront/lib/money`) —
-tree-shaking and Next.js RSC boundary detection both work better than via
-barrels. Styling resolves against STOREFRONT theme tokens (`bg-card`,
-`text-foreground`, …, shadcn-standard names) — `@import
-"@cartbase/storefront/theme"` in the app's CSS supplies both the token names
-and a filled default set of values, so components render designed out of the
-box. No component hardcodes a colour; retheming means overriding values, never
-renaming tokens.
-
----
-
-## Language: the library is English, a language is a pack
-
-No component holds copy. Every string comes from a label pack, and the
-library's own defaults are **international English** (`products/labels`,
-`checkout/labels`, and so on, beside each family's type).
-
-A language is one object covering all six families, imported by its own
-subpath so a store bundles only what it ships:
-
-```tsx
-import { es } from "@cartbase/storefront/locales/es"
-import { StorefrontLocaleProvider } from "@cartbase/storefront/locales"
-
-<StorefrontLocaleProvider locale={es}>{children}</StorefrontLocaleProvider>
-```
-
-Shipping: `locales/en`, `locales/es`, `locales/bg`. Each is typed
-`StorefrontLocale`, so a label added to the library breaks an incomplete
-pack at compile time instead of falling back to English mid-checkout.
-
-The provider mounts the three pure label contexts (products, checkout,
-order), and the cart drawer and the reviews family read the language from
-it directly, so every CLIENT component inside it speaks the pack with no
-further wiring. What it cannot reach is a SERVER component: the store,
-product and order templates render on the server, so each page hands them
-their area of the pack, and that prop is REQUIRED. A page that forgets it
-does not compile; `PropLabelAreas` in `locales` names the areas.
-
-```tsx
-<StoreTemplate          labels={STORE_LOCALE.store} />
-<SearchTemplate         labels={STORE_LOCALE.store} />
-<CollectionTemplate     labels={STORE_LOCALE.store} />
-<CategoryTemplate       labels={STORE_LOCALE.store} />
-<ProductTemplate        labels={STORE_LOCALE.products} />
-<OrderCompletedTemplate labels={STORE_LOCALE.order} />
-```
-
-`STORE_LOCALE` is the pack the store declared once in its config (`en`, or
-`bg`, or `es`); the scaffold ships it that way. English is not a special
-case: an English store passes `en.store`.
-
-**Failure copy is copy.** What a shopper reads when an address, a payment, a
-gift card or a discount code fails lives in the checkout pack too
-(`addressErrors`, `paymentErrors`, `giftCardErrors`, `promotionErrors`).
-The modules that recognize each failure keep their English patterns,
-because those match the API's wire format and are never shown to anyone.
-
-Overriding one word is a partial: every provider merges over the defaults.
-
----
-
-## Family: tracking (`@cartbase/storefront/tracking/*`)
-Meta Pixel + GA4 + Rybbit + Consent Mode v2. The Cartbase split of duties:
-**this package fires client events and writes attribution; server-side CAPI /
-GA4 Measurement Protocol sending is Cartbase-backend-owned** (the
-`order.placed` forwarder). The whole family is safe to render
-unconditionally — every component renders nothing when its id prop is absent,
-every helper no-ops outside the browser.
-
-### `<ConsentInit required />` — `tracking/consent-init`
-
-- **Purpose** — the synchronous Consent Mode v2 "default" snippet: sets
-  gtag's consent default before any Google tag loads. `required` is the
-  store's consent switch (`consent.enabled` from `GET /api/store/consent`).
-  With it true a new visitor starts DENIED until they choose on the banner;
-  with it false the store collects no consent and a new visitor starts
-  GRANTED. A choice stored in `_1c_consent` wins either way.
-- **SDK calls** — none in the browser. The layout resolves the consent
-  config on the server (it fetches it for the banner anyway) and passes the
-  switch; the script must NEVER wait on a fetch (async default = first-hit
-  consent race).
-- **Mount rules** — FIRST child of `<body>` in the root layout, before any
-  tag component. Plain inline `<script>` by design (not next/script). The
-  prop is REQUIRED: neither default is safe, so a layout must say what the
-  store does, and one that does not fails to compile (2026-09-14).
-- **Settings** — the consent card's `enabled` (admin → Settings → Consent).
-
-### `<ConsentBanner copy layout privacyHref rejectOnFirstLayer />` — `tracking/consent-banner`
-
-- **Purpose** — the built-in two-layer CMP UI; writes the `_1c_consent`
-  cookie and applies the live `gtag('consent','update')` + `fbq('consent')`.
-- **SDK calls** — `GET /api/store/consent` (via `@cartbase/storefront/api/consent`)
-  for the store's config; pass `copy = pickConsentCopy(consent.copy, locale)`,
-  plus `layout` / `privacy_href` / `reject_on_first_layer` from the payload.
-- **Mount rules** — mount ONLY when `shouldRenderBanner(consent)` (i.e.
-  `enabled && mode === "builtin"`). In `mode: "external"` render nothing —
-  the merchant's CMP must write the same `_1c_consent` cookie or call
-  `setConsent()`; all gating keeps working off that one seam. z-index is
-  `z-[70]` (above the cart drawer's `z-[60]`).
-- **Settings** — the consent card config (admin → Settings → Consent):
-  `enabled`, `mode`, `layout` (`modal` blocks + scroll-locks;
-  `banner-bottom` is non-blocking and must not trap focus), `privacy_href`,
-  `reject_on_first_layer`, per-locale `copy`.
-- Also ships `<ConsentSettingsLink>` (footer link that re-opens the settings
-  layer — "withdraw as easily as given") and the pure `<ConsentBannerCard>`.
-
-### `<MetaPixel pixelId consentRequired />` — `tracking/meta-pixel`
-
-- **Purpose** — injects fbevents.js, pushes the consent state BEFORE
-  `fbq('init')` (pre-init revoke = Pixel queues events until grant), fires
-  the initial PageView. The state is the store's default overridden by the
-  visitor's stored `_1c_consent` choice: revoked on a store that collects
-  consent, granted on a store with the banner off.
-- **SDK calls** — `getTrackingConfig(client)` (`tracking/get-tracking-config`,
-  wraps `GET /api/store/integrations` → `tracking.facebookPixel.pixelId` and
-  `tracking.consent_required`).
-- **Mount rules** — root layout, after `<ConsentInit>`; `<StorefrontTags>`
-  mounts it with both props from the block. Renders nothing when `pixelId`
-  is falsy. `consentRequired` is REQUIRED for the reason `<ConsentInit>`
-  gives, and so it is on `<TikTokPixel>` and `<ChatGptPixel>`, the two
-  other tags that gate their own SDK (2026-09-14). Google needs no prop: it
-  reads the `<ConsentInit>` default.
-- **Settings** — admin Integrations hub `facebook_capi` row (`enabled` +
-  `credentials.pixel_id`); consent card `enabled` → `consent_required`.
-- Companion: `updatePixelAdvancedMatching(visitor)` — call from checkout /
-  signup as PII becomes known; hashes em/ph/fn/ln/ct/st/zp/country
-  (SHA-256, Meta normalization) and re-inits the Pixel so every subsequent
-  event carries Advanced Matching. Also persists raw values for
-  `getKnownVisitor()`.
-
-### `<GA4 measurementId />` — `tracking/ga4`
-
-- **Purpose** — loads gtag.js + `gtag('config')`. gtag then owns the `_ga` /
-  `_ga_<MEASUREMENT_ID>` cookies that `getTrackingAttribution()` later reads.
-- **SDK calls** — `getTrackingConfig(client)` → `tracking.ga4.measurementId`.
-- **Mount rules** — root layout, after `<ConsentInit>` (the consent default
-  governs whether gtag writes cookies or sends cookieless pings). Renders
-  nothing when falsy. SPA route changes are NOT auto-tracked — fire
-  `page_view` from a route-change effect if per-route views are wanted.
-- **Settings** — Integrations hub `ga4` row (`credentials.measurement_id`);
-  consent card.
-
-### `<Rybbit siteId baseUrl? />` — `tracking/rybbit`
-
-- **Purpose** — the platform's self-hosted, cookieless analytics tracker;
-  auto-tracks pageviews incl. SPA route changes.
-- **SDK calls** — NONE. Rybbit is deliberately absent from the store
-  `tracking` block: platform-provisioned, the host app passes props from
-  platform env. Outside the consent system by design (cookieless).
-- **Mount rules** — root layout; renders nothing when `siteId` falsy.
-- **Settings** — none merchant-facing.
-
-### Client events — `tracking/events` (use this one)
-
-ONE call per commerce moment, every vendor at once. Reach for these rather
-than the per-vendor helpers below, because the failure they prevent is the
-common one and it is invisible: a store adds a vendor, updates three of the
-four call sites, and an ad account optimises on partial data for a month
-before anyone notices.
-
-| Step | Call |
-|---|---|
-| Product view | `trackProductView({ line, currency, value })` |
-| Add to cart | `trackCartAdd({ line, currency, value })` |
-| Checkout start | `trackCheckoutStart({ lines, currency, value, coupon? })` |
-| Order confirmed | `trackOrderPurchase(order, trackingConfig)` |
-
-A `line` is `{ productId, variantId?, title, quantity, price }`. Pass the
-PRODUCT id: Meta's content_ids, TikTok's content_id and the catalogue
-feed's `<g:id>` must be the same value or the event matches no catalogue
-entry, which costs dynamic ads on both platforms. GA4 is keyed by variant
-instead, on purpose, and these helpers do that split for you.
-
-`trackOrderPurchase` takes the tracking config as its second argument
-because Google Ads only fires when the store configured BOTH the account id
-and the purchase label. Pass `order.metadata.customer_type` through as
-`customerType` when present: it is computed once server-side, so the
-browser and the server tell Google and TikTok the same thing.
-
-### Per-vendor helpers — `tracking/fbq`, `tracking/gtag`, `tracking/ttq`, `tracking/rybbit-events`, `tracking/google-ads`
-
-Call on the matching funnel step; all are no-op-safe (SSR, blocked, absent
-tag). The Rybbit helpers additionally queue-buffer through the script-load
-race (10s cap, v2.2.6 production fix).
-
-| Step | Meta (`fbq.ts`) | TikTok (`ttq.ts`) | GA4 (`gtag.ts`) | Rybbit (`rybbit-events.ts`) |
-|---|---|---|---|---|
-| Product view | `trackViewContent` | `trackTikTokViewContent` | `trackGAViewItem` | `trackRybbitViewItem` |
-| Add to cart | `trackAddToCart` | `trackTikTokAddToCart` | `trackGAAddToCart` | `trackRybbitAddToCart` |
-| Checkout start | `trackInitiateCheckout` | `trackTikTokInitiateCheckout` | `trackGABeginCheckout` | `trackRybbitBeginCheckout` |
-| Order confirmed | `trackPurchase(data, order.display_id)` | `trackTikTokPurchase({…, displayId})` | `trackGAPurchase({transaction_id: String(order.display_id), …})` | `trackRybbitPurchase` |
-| Newsletter/popup signup | `trackLead` | — | — | — |
-
-Google Ads has one event, the purchase conversion:
-`trackGoogleAdsPurchase({ sendTo, value, currency, transactionId, newCustomer? })`,
-with `sendTo` from `googleAdsPurchaseSendTo(config)` (null when the label
-is not configured — skip the conversion rather than fire a malformed
-`send_to`, which Google accepts and silently drops).
-
-**THE Purchase dedupe contract** (must never drift; mirrored server-side in
-`src/lib/tracking/constants.ts`):
-
-- Meta: browser Pixel `eventID` = **`"purchase_" + order.display_id`** — the
-  exact id the backend `order.placed` CAPI Purchase uses. `trackPurchase()`
-  builds it from the caller's `display_id` so the format cannot drift. Meta
-  dedupes by event_name + event_id (~3 days).
-- TikTok: browser pixel `event_id` = **`"tt_purchase_" + order.display_id`**,
-  the same id the backend Events API Purchase sends. The `tt_` prefix keeps
-  it from colliding with Meta's on a page carrying both pixels. TikTok
-  dedupes on event_source_id + event + event_id and discards duplicates for
-  48 hours; the backend ALSO carries an idempotency flag, because 48 hours
-  does not cover an order email opened on day four.
-- GA4: `transaction_id = String(order.display_id)` on both browser event and
-  backend Measurement Protocol — GA4 dedupes by transaction_id natively.
-- Google Ads: `transaction_id` again, the same value. Never send it empty:
-  an empty transaction_id dedupes nothing, so every re-open of the
-  confirmation page counts another conversion.
-- All other events get `<eventname>_<unixSeconds>_<6hex>` ids
-  (`generateEventId`).
-
-`setEnhancedConversions(input)` (gtag.ts) — Google Ads Enhanced Conversions
-for Web: hashes email/phone/names client-side and `gtag('set','user_data',…)`.
-Call alongside `updatePixelAdvancedMatching` at checkout. The phone is
-normalised to E.164 WITH the plus, which is NOT the digits-only string Meta
-wants: two vendors, two normalisers, and merging them re-creates a defect
-that fails silently and costs match rate with nothing in any log.
-
-### Attribution — `tracking/attribution`, `tracking/get-tracking-attribution`, `tracking/use-engagement-time`
-
-- Browser side (call from a top-level client component, e.g. `TrackInit`):
-  `captureUtmsFromUrl()` (first-touch `_1c_utm_first` 365d, last-touch
-  `_1c_utm_last` 90d), `getOrCreateFbp()` / `getOrCreateFbc()` (defensive
-  `_fbp`/`_fbc` writes so the Pixel-load race never ships empty match keys —
-  production fix), `getOrCreateAnonId()` (`_1c_anon`, the guest
-  `external_id`), `initEngagementTime()`.
-- Server side, at checkout completion:
-  `getTrackingAttribution(clientHints?, opts?)` reads the cookies + headers
-  and returns the `TrackingAttribution` keys to write into `cart.metadata`
-  (CONSENT-GATED — only when the visitor's choice allows). Cart completion
-  copies them to `order.metadata`; the backend forwarder inherits
-  fbp/fbc/anon-id/ga signals from there. Pass
-  `{ engagementTimeMsec: getEngagementTimeMsec() }` as clientHints, and
-  either `opts.ga4MeasurementId` or `opts.client` so the `_ga_<id>` session
-  cookie can be located.
-- **Settings** — Integrations hub rows (which signals exist), consent card
-  (whether capture happens).
-
----
-
-## Family: primitives (`@cartbase/storefront/primitives/*`)
-Generic shadcn-style building blocks. No SDK calls, no admin settings —
-pure UI over the theme tokens.
-
-- `primitives/field` — `<Field label … />`: floating-label input (checkout
-  house style) with the `pulse` attention cue (soft blue 2-cycle pulse,
-  distinct from focus/error — production UX fix).
-- `primitives/select-field` — `<SelectField label>…options…</SelectField>`:
-  floating-label native select (native mobile keyboards).
-- `primitives/ui/*` — shadcn-standard `button` (cva variants incl.
-  `default/destructive/outline/secondary/ghost/link`), `input`, `label`,
-  `select`, `dialog`, `sheet`, `tabs`, `accordion`, `collapsible`,
-  `popover`. Radix-backed, ported verbatim; import per file.
-- Mount rules: all are `"use client"`. Requires the Tailwind preset tokens.
-
----
-
-## Family: lib (`@cartbase/storefront/lib/*`)
-Pure helpers — no React except `price`, no fetches. The SDK never
-invents server truths: prices/totals arrive computed from the API
-(`variant.calculated_price`, `cart.total`); these helpers only select and
-format.
-
-- `lib/utils` — `cn()` (clsx + tailwind-merge).
-- `lib/money` — `convertToLocale({amount, currency_code, …})` Intl currency
-  formatting (amounts are decimal EUR major units per the store contract);
-  `noDivisionCurrencies`.
-- `lib/price` — `<Price amount currencyCode className />`: the amount in its
-  own currency, formatted through `convertToLocale`. Every price in the
-  library renders through it. It shows ONE currency; a store that wants a
-  second one displayed adds it in its own locale layer rather than in
-  every price.
-- `lib/cart-helpers` — `isProductLine` / `isFeeLine` / `productTotal` /
-  `productItemCount` / `findFeeLine` + `COD_FEE_METADATA_KEY`. THE single
-  source of truth for hiding the backend-injected COD-fee line in cart
-  surfaces while checkout/order totals show it as its own row. Affected by:
-  COD settings (whether a fee line ever appears).
-- `lib/get-product-price` — `getProductPrice({product, variantId})` /
-  `getPricesForVariant` → formatted `VariantPrice` (cheapest + selected)
-  from server-computed `calculated_price`. Reads Cartbase's flat
-  `price_list_type` with a legacy nested shape as fallback. Affected by:
-  price lists / B2B pricing context (what `calculated_price` contains),
-  currency + region query context.
-- `lib/get-percentage-diff` — sale badge math.
-- `lib/product` — `isSimpleProduct` (skip the option selector for
-  one-option-one-value products).
-- `lib/sort-products` — client-side re-sort of a fetched page
-  (`price_asc|price_desc|created_at`); the API's `order` param stays the
-  authority for paginated listings.
-- `lib/payment-constants` — `isStripeLike` / `isPaypal` +
-  `paymentInfoMap`. Two tender shapes since the pp_* kill: a processor
-  `provider_id` (`pp_stripe` exact, code truth
-  `src/lib/stripe/providers.ts`, plus legacy Medusa-era prefixes as
-  fallbacks) or a merchant METHOD rendered by its snapshot NAME — a
-  method never has a provider id to bucket. Affected by: connected
-  processors + enabled methods + checkout rules (which entries ever
-  reach the client).
-- `lib/store-api-error` — `storeApiError(err)`: display-boundary normalizer
-  (capitalized message + terminal period).
-  Catch `StoreApiError` directly instead when branching on `status`/`code`.
-- `lib/hooks/use-intersection`, `lib/hooks/use-toggle-state` — viewport +
-  toggle micro-hooks (client).
-
----
-
-## Family: checkout (`@cartbase/storefront/checkout/*`)
-The full checkout page family, production-proven (deferred-
-intent architecture — no payment session exists until Buy click) onto the
-Cartbase orchestration endpoints. The flow every component serves
-(executable ground truth: [checkout.md](checkout.md)):
-
-```
-listShippingOptions(cart_id) + listPaymentProviders(cart_id)  (render pickers)
-   → Buy click → prepareCheckout (ONE atomic, compensated call)
-   → pp_stripe: stripe.confirmPayment(client_secret) | merchant method: skip
-   → completeCart → navigate to the confirmed page
-```
-
-Amounts are EUR major units and SERVER truth — components render totals,
-never compute money; the only client-side arithmetic is the *optimistic
-display* overlay (shipping/COD-fee prediction) that the server value
-replaces at prepare. All user-facing copy flows from `CheckoutProvider`
-labels (English by default; a language is a pack from `locales/*`); errors surface
-code-first through the error-copy maps, never raw API strings.
-
-### `<CheckoutProvider labels orderConfirmedPath />` — `checkout/context`
-
-- **Purpose** — supplies labels + the order-confirmed path template
-  (`{id}`/`{country}` substitution) to every checkout primitive.
-- **SDK calls** — none.
-- **Mount rules** — wrap the checkout page (or any custom composition).
-  Default path template `"/{country}/order/{id}/confirmed"`; single-country
-  stores pass `"/order/{id}/confirmed"`.
-- **A NESTED PROVIDER INHERITS (0.12.0)** — mounting a second one, which is
-  what you do when you set `orderConfirmedPath` on a page inside a
-  `StorefrontLocaleProvider`, keeps every label from the provider above and
-  changes only the keys you name. Before 0.12.0 it merged over the ENGLISH
-  defaults, so a provider mounted for the path alone silently reset the
-  whole checkout to English on an otherwise translated store. The same now
-  holds for `ProductLabelsProvider` and `OrderLabelsProvider`.
-- **Settings** — none (labels come from the store's locale pack).
-
-### `useCheckoutOrchestration(options)` — `checkout/use-checkout-orchestration`
-
-- **Purpose** — THE hardened checkout state machine: address form +
-  debounced autosave, shipping/payment selection (client-state-only
-  pre-Buy), carrier metadata, optimistic totals, the atomic Buy click,
-  3DS-return handling, completed-cart detection. Every production race
-  guard from production is preserved.
-- **SDK calls** — `carts.updateCart` (address autosave + tracking metadata),
-  `customers.updateMe` (best-effort profile sync incl. Cartbase's first-class
-  `company_name`/`company_eik`), `checkout.calculateShippingOption`
-  (calculated-rate forward-compat), `checkout.prepareCheckout`,
-  `checkout.syncPaymentAmount` (exposed + fired on payment-tab switch with
-  the new `provider_id`), `checkout.refreshPaymentIfTerminal` (exposed —
-  call REACTIVELY from Elements `loaderror` only), `carts.completeCart`.
-- **Props contract** — `{client, cart, customer, availableShippingMethods,
-  availablePaymentMethods, countryCode?, countries?, paymentMethodFilter?,
-  orderConfirmedPath?, onOrderPlaced?,
-  resolveTrackingMetadata?, logError?}`. `countries` is OPTIONAL and is an
-  override: omit it and the hook calls `GET /api/store/countries` itself, so
-  the address form offers the countries the store's Markets declare, or the
-  whole catalogue when it declares none (0.11.0 — before that, omitting it
-  produced a ONE-country read-only field). A failure to load the list never
-  blocks a checkout: it falls back to `countryCode` and reports through
-  `logError` as `country_list_failed`. Fee prediction is never
-  hardcoded: each method LISTING entry carries its own
-  `fee_amount`/`fee_label`. `logError` replaces the legacy log writers
-  (all production log points preserved). Returns the full orchestration
-  surface (`performBuyClick`, `optimisticTotal(Cents)`, `deliveryReady`, …).
-- **Cartbase specifics** — zero-remainder gift path: `prepareCheckout`
-  returning `client_secret:null` + `provider_id:null` +
-  `payment_method_id:null` SKIPS Stripe and completes on the gift session
-  ([gift-cards.md](gift-cards.md)). Processors are `pp_stripe` exactly;
-  merchant methods list as `{payment_method_id, name, kind, instructions,
-  fee_amount, fee_label}` entries — the COD-kind method wins the offline
-  tab, else the first manual method. The charged fee reads the cart-level
-  `payment_method_fee_total` decoration.
-- **Settings** — checkout rules (filter the listings + complete guard),
-  the methods' own fee configuration (Payments settings), Stripe
-  credentials, gift cards, `accounts_mode`.
-
-### `<CheckoutClient />` — `checkout/checkout-client`
-
-- **Purpose** — the assembled single-page checkout layout over the hook +
-  every component below. Stores wanting a custom layout compose the same
-  hook + primitives instead.
-- **SDK calls** — everything the hook + summary widgets call; the host
-  fetches `listShippingOptions`/`listPaymentProviders` (+ customer, +
-  `getIntegrationsConfig().cod`) and passes them down.
-- **Props contract** — hook options + `showGiftCards?`,
-  `logoByFulfillmentOptionId?`, Stripe `appearance`/`fonts`, `onCartChange?`
-  (receives every decorated cart from summary mutations; the layout also
-  re-runs `syncPaymentAmount` on those).
-- **Mount rules** — `"use client"`; inside `CheckoutProvider`; redirect
-  server-side when `cart.completed_at` is set (the hook also flags
-  `cartIsCompleted`).
-
-### `<PaymentWrapper cart amount />` + Stripe scope — `checkout/payment-wrapper`, `checkout/stripe-wrapper`
-
-- **Purpose** — deferred-intent Stripe context: `PaymentWrapper` publishes
-  `{stripePromise, amount, currency, appearance, fonts}`;
-  `StripeElementsScope` mounts `<Elements mode:"payment">` where needed
-  (`passthrough` renders children scope-less on COD-only stores);
-  `StripeContext` boolean = "Stripe.js ready".
-- **SDK calls** — none (env: `NEXT_PUBLIC_STRIPE_KEY`; legacy env names
-  kept as fallbacks).
-- **Mount rules** — `PaymentWrapper` wraps the page ONCE with
-  `amount={optimisticTotalCents}` (cents at this Stripe boundary only);
-  `StripeElementsScope` lives INSIDE the payment section so a session
-  rotation never tears down the form/tracking tree.
-- **Settings** — Stripe integration (whether `pp_stripe` is ever listed).
-
-### `<CheckoutAddressForm />` (+ `<AddressSelect />`, `<CompanyDetails />`) — `checkout/address-form`, `checkout/address-select`, `checkout/company-details`
-
-- **Purpose** — email + delivery address (floating-label `Field`s, 3s-idle
-  pulse cue), saved-address picker, collapsible BG company-invoice fields
-  (name/VAT/MOL/address → `cart.metadata` + customer profile).
-- **SDK calls** — none directly; the hook autosaves via `updateCart` /
-  `updateMe`. Saved addresses come from `customers.getMe()` →
-  `addressesInRegion`.
-- **Props contract** — everything from the hook (`formData`,
-  `handleFormChange`, `handleFieldBlur`, `regionCountries`, `addressInput`,
-  `addressError`, `pulseFields`); `hideCountry?` for single-country stores.
-  The country field is a NATIVE select carrying the chosen country's flag,
-  and it keeps `autocomplete="country"` on purpose: a custom listbox would
-  draw a flag per row but lose browser autofill and the phone's own picker,
-  and a checkout does not trade autofill for decoration. A list of exactly
-  one country still renders as a read-only name, which is right for a store
-  that truly sells to one country and is no longer the default for everyone
-  else (0.11.0).
-- **Settings** — Admin → Settings → Markets → Regions, read through
-  `GET /api/store/countries`.
-
-### `<CheckoutShippingMethodList />` — `checkout/shipping-method-list`
-
-- **Purpose** — radio list of shipping options with inline carrier-picker
-  expansion, free-shipping label, optional per-carrier logos, optional
-  read-only price preview pre-address (`previewWhenAddressNotReady`).
-- **SDK calls** — renders `checkout.listShippingOptions(client, {cart_id})`
-  rows AS SERVED (rule-filtering + `checkout_method_order` are server-side).
-- **Props contract** — hook state + `econt?`/`boxnow?` picker configs
-  (detection by the STABLE `shipping_option.data.id` — `"econt-office"` /
-  `"boxnow-locker"` — never display names; `boxnow.client` carries the SDK
-  transport) + `logoByFulfillmentOptionId?`.
-- **Settings** — checkout rules (`target_type=shipping_option`), method
-  ordering, carrier integrations (which options exist at all).
-
-### `<EcontOfficeSelector />` / `<BoxNowLockerSelector />` — `checkout/econt-office-selector`, `checkout/boxnow-locker-selector`
-
-- **Purpose** — Bulgarian office/locker pickers: nearest-3 by haversine
-  distance (Nominatim geocode of the typed address), city-locked search
-  with Cyrillic↔Latin normalization, selected pill + change.
-- **SDK calls** — Econt: none (public Econt Nomenclatures endpoint,
-  page-level cache). BoxNow: `integrations.listBoxNowLockers(client)`
-  ([integrations.md](integrations.md)); 503/502/network all render one
-  "temporarily unavailable" state — discover availability via
-  `carriers.boxnow.lockers_url`, don't probe.
-- **Props contract** — `{userCity, userAddress, selectedOffice|Locker,
-  onSelect}` (+ `client` for BoxNow). The CHOSEN office/locker is client
-  state; the hook writes it into `carrier_metadata` exactly once at
-  prepare (previous carrier keys are server-side swept —
-  `_prepared_carrier_keys`).
-- **Settings** — the carrier integrations (enabled/lockers).
-
-### `<CheckoutPaymentMethodList />` + `<PaymentButton />` — `checkout/payment-method-list`, `checkout/payment-button`
-
-- **Purpose** — pay-online vs cash-on-delivery radio rail. The online tab
-  hosts Stripe `<PaymentElement layout:"accordion">` (every
-  Dashboard-enabled method, no per-method code; deliberately NO
-  `fields.billingDetails.address` override — the strict-completeness
-  IntegrationError fix). `PaymentButton` = the Buy button: re-entry-guarded
-  click → `performBuyClick`, cycling processing narration, translated
-  inline errors, Price total.
-- **SDK calls** — renders `checkout.listPaymentProviders` results via the
-  hook's `hasCard`/`hasCod`; the click path runs the hook's calls.
-- **Props contract** — hook state + `buyButtonNotReady(Reason?)`,
-  `gatePaymentUntilDelivery?` (false = always-visible payment section),
-  `beforePaymentButton?` slot, `total` (pass `optimisticTotal`),
-  `logError?`.
-- **Settings** — COD integration (`labels.codNote` + fee timing), Stripe
-  credentials, checkout rules (`target_type=payment_method`) — hidden
-  methods are also re-enforced at complete (`checkout_method_hidden`).
-
-### `<OrderSummary />` (+ `CheckoutLineItem`, `<LineItemCard />`) — `checkout/order-summary`, `checkout/line-item-card`
-
-- **Purpose** — items (flat rows with qty pill), promo + gift-card
-  widgets, totals breakdown (subtotal / shipping / COD fee / discount /
-  VAT / total + gift-card tender rows UNDER the unchanged total), secure
-  badge. `LineItemCard` is the standalone card variant.
-- **SDK calls** — `carts.updateLineItem` (quantity); child widgets below.
-  Totals are rendered STRAIGHT from the cart decoration: `item_total`,
-  `shipping_total`, `payment_method_fee_total`/`payment_method_fee_label`, `discount_total`,
-  `tax_total`, `total`, `gift_card_total`, `gift_card_remainder`.
-- **Props contract** — `{client, cart, optimisticShippingCost,
-  onOptimisticShippingClear?, optimisticCodFee?, onOptimisticCodFeeClear?,
-  methodFeeLabel?, showGiftCards?, onCartChange?}`. Optimistic values clear
-  automatically once the server cart catches up.
-- **Settings** — COD integration (fee row), gift cards, promotions.
-
-### `<DiscountSection />` — `checkout/discount-section`
-
-- **Purpose** — collapsible promo-code input + applied-promotion list
-  (percentage or fixed amount display).
-- **SDK calls** — `POST /api/store/carts/:id/promotions {promo_codes}`
-  via the client transport (additive apply; the carts SDK module ships no
-  wrapper for this route yet — see [carts.md](carts.md) for the cart
-  shape; `cart.promotions` arrives as the `{promotion:{…}}` pivot embed,
-  unwrapped here).
-- **Props contract** — `{client, cart, onCartChange?}`. Errors code-first
-  via `promotion-error-copy` (`promotion_not_found`/`promotion_inactive`/…
-  + the no-email campaign-budget heuristic).
-- **Settings** — promotions admin (codes, status, application method).
-
-### `<GiftCardSection />` — `checkout/gift-card-section`
-
-- **Purpose** — gift-card code input + applied-cards chips (masked
-  `••••last4`, per-card live coverage, remove). Cartbase-new — no legacy
-  equivalent.
-- **SDK calls** — `giftCards.applyGiftCard` / `giftCards.removeGiftCard`
-  ([gift-cards.md](gift-cards.md)). Renders `cart.gift_cards[]` /
-  `gift_card_total` / `gift_card_remainder` — server truth, no client
-  math; totals never move (tender, not discount).
-- **Props contract** — `{client, cart, onCartChange?}`. Error copy honors
-  the anti-oracle contract: ONE generic message for `invalid_gift_card`
-  (never branch on reasons the API hides), `rate_limited` for burned
-  windows. After apply/remove the host must `syncPaymentAmount` (the
-  CheckoutClient wiring does).
-- **Settings** — gift-cards admin (issue/disable, expiry, balances).
-
-### Error-copy maps — `checkout/payment-error-copy`, `checkout/address-error-copy`, `checkout/promotion-error-copy`
-
-- **Purpose** — every raw failure → actionable Bulgarian copy, CODE-FIRST
-  against the Cartbase error envelope (`StoreApiError.code`), then the
-  production substring layers (Stripe.js browser errors carry no Cartbase
-  code), then a clean per-context generic. `PAYMENT_ERROR_CODE_COPY`
-  covers EVERY documented code of complete/prepare/sync/refresh —
-  `checkout_method_hidden`, `account_required`,
-  `gift_card_insufficient_balance`, the 402 payment family, …
-  (unit-gated by `tests/unit/storefront-checkout.test.ts`).
-- **SDK calls** — none (pure).
-- **Mount rules** — call `translatePaymentError(err, "card"|"cod")` /
-  `translateAddressError(err)` / `translatePromotionError(err,
-  {hasEmail})` / `translateGiftCardError(err)` at the display boundary;
-  never show `err.message` raw.
-
-Also in the family barrel: `compareAddresses` (saved-address match
-detection) and the `geocode` helpers (`normalizeForMatch`,
-`distanceMeters`, `formatDistance`, `cleanAddress`, `geocodeAddress`) —
-extra modules beyond the per-file exports, imported from
-`@cartbase/storefront/checkout`.
-
----
-
-## Family: cart-drawer (`@cartbase/storefront/cart-drawer/*`)
-Sliding cart UI, production-proven layout. All
-components are `"use client"`. Money is EUR decimal major units everywhere
-(cart totals are SERVER truth from the decorated cart — components render,
-never compute; the only client arithmetic is the optimistic
-`unit_price × quantity` preview that the next server snapshot replaces).
-Domain doc for every call: [carts.md](carts.md); gift-card tender:
-[gift-cards.md](gift-cards.md); cross-sell sources: [products.md](products.md)
-+ [search.md](search.md).
-
-### `<CartDrawerProvider client cart onCartChange … />` — `cart-drawer/context`
-
-- **Purpose** — the family's root: open/close state, the optimistic cart
-  snapshot (React 19 `useOptimistic`), labels + hrefs, and the SDK-wired
-  mutations every child uses. Auto-opens when the product-line item count
-  rises **from a nonzero base** (the guard that keeps the late-arriving
-  initial cart snapshot from opening the drawer on page load — so the very
-  FIRST add does not auto-open; open explicitly via `useCartDrawer().open`
-  / the header `CartButtonClient`, or wire `ProductActions`' `openCart`
-  seam in a client composition). Locks body scroll while open, closes on
-  Escape.
-- **SDK calls** — `@cartbase/storefront/api/carts`: `createCart` (first
-  `addItem` with no cart — `region_id` falls back to the store default),
-  `retrieveCart` (mount in `client`+`cartId` mode, and `refresh()`),
-  `addLineItem`, `updateLineItem` (body `{quantity}` ONLY — Cartbase accepts
-  no metadata on update; quantity 0 deletes), `deleteLineItem`. Every
-  mutation returns the FULL decorated cart, which becomes the confirmed
-  snapshot — no page refetch needed.
-- **Props contract** — `cart?: Cart|null` (server-fetched snapshot; prop
-  updates win), `client?: StorefrontClient` (enables `addItem`/
-  `updateQuantity`/`removeItem`/`refresh`), `cartId?` (retrieve-on-mount
-  when no snapshot), `onCartChange?(cart)` (fires on every confirmed
-  change INCLUDING first-add cart creation — persist `cart.id` here),
-  `onOptimisticError?(failure)` (the ops funnel for every failed
-  optimistic mutation — wire to store logging; replaces the source's
-  `logEvent` backend call), `labels?: Partial<CartDrawerLabels>` (overrides:
-  the language mounted by `StorefrontLocaleProvider` is the default),
-  `hrefs?: {checkout, browse, productPrefix}`.
-- **Hook** — `useCartDrawer()` → `{isOpen, open, close, toggle, cart,
-  addItem(variantId, qty?, display?), updateQuantity(lineId, qty),
-  removeItem(lineId), refresh, applyOptimistic, dispatchOptimistic,
-  labels, hrefs}`. `applyOptimistic(action, serverAction)` stays for
-  store-owned server actions (PDP add via RSC).
-- **Settings** — store default region + enabled currencies (cart create),
-  B2B price lists via attached customer, gift-card product flags
-  (`is_giftcard` lines are non-discountable), automatic promotions,
-  COD-fee integration (injects the fee line the drawer hides).
-- **Mount rules** — wrap the root layout; ONE provider per app. i18n: mount
-  `StorefrontLocaleProvider` above it and the drawer speaks the pack with
-  nothing handed over (since 2026-09-14); `labels` overrides single keys
-  (`cart-drawer/labels` holds the English defaults).
-
-### `<CartDrawer sidebar children />` — `cart-drawer/cart-drawer`
-
-- **Purpose** — the slide-out shell: overlay + right panel (`z-[60]`/
-  `z-[61]` — the consent banner sits above at `z-[70]`), optional desktop
-  left sidebar slot for cross-sell. No SDK calls.
-- **Mount rules** — render once, inside the provider; put drawer body
-  components in `children`. `panelClassName` composes onto the panel.
-
-### `<CartDrawerHeader />` — `cart-drawer/header`
-
-- **Purpose** — title + item-count badge + close button. Counts PRODUCT
-  lines via `productItemCount` (`lib/cart-helpers`) so a backend-injected
-  COD-fee line never inflates the count. No SDK calls (context cart).
-
-### `<CartPromoBanner message variant />` — `cart-drawer/promo-banner`
-
-- **Purpose** — top strip message (`info|success|warning`). Pure props.
-
-### `<CartTieredProgress tiers currencyCode />` — `cart-drawer/tiered-progress`
-
-- **Purpose** — progress bar to the next shipping/discount tier with
-  checkpoint markers. Reads `cart.total` (tax-inclusive server truth).
-- **Props contract** — `tiers: CartTier[]` sorted ascending;
-  `threshold` in EUR major units (50 = €50). Pure math exported as
-  `computeTierProgress(amount, tiers)` (unit-tested).
-
-### `<CartItem item currencyCode>{upsell?}</CartItem>` — `cart-drawer/item`
-
-- **Purpose** — one line row: thumbnail, title link, variant, quantity
-  stepper, per-line price with strikethrough (server `total` <
-  `original_total`), remove button (optimistic, via the provider's
-  `removeItem` → `DELETE line-items/:id`).
-- **Props contract** — `item: CartLineItem` (the SDK's decorated line —
-  per-line totals are server-computed), `currencyCode`, `children` =
-  per-item upsell slot.
-- Subcomponents: `item/quantity` (`<CartItemQuantity lineId quantity
-  maxQuantity? />` — stepper floor 1, calls `updateQuantity` with
-  `{quantity}`), `item/variant` (`<CartItemVariant variantTitle
-  options? />` — Cartbase lines carry the flat `variant_title` string, not
-  an embedded variant object), `item/upsell` (`<CartItemUpsell products
-  onAdd />` — feed from `listRelatedProducts`, `variantId` included so
-  `onAdd` can call `addItem`).
-
-### `<CartFreeGift … />`, `<CartGiftWrap … />`, `<CartNotes … />`, `<CartRewardsPoints … />`
-
-- Merchandising slots (`cart-drawer/free-gift`, `gift-wrap`, `notes`,
-  `rewards-points`) — pure props + labels; prices EUR major units. The
-  store owns the effects: `CartGiftWrap.onToggle` → add/remove the store's
-  gift-wrap variant via `addItem`/`removeItem`; `CartNotes.onSave` →
-  `updateCart(client, cartId, {metadata: {...cart.metadata, gift_note}})`
-  — the update route REPLACES metadata wholesale (no merge), so always
-  spread the current `cart.metadata`; cart metadata is copied onto the
-  order at complete. No admin settings — configured per store in code.
-
-### `<CartCrossSellSidebar / CartCrossSellCarousel products onAdd label? />` — `cart-drawer/cross-sell-*`
-
-- **Purpose** — desktop sidebar card list / horizontal strip of
-  recommendations.
-- **SDK calls** — feed `products` from `api/products.listProducts`
-  (curated collection/tag) or `api/search.listRelatedProducts` (anchor
-  complements — manual admin picks first, deterministic fallback fills;
-  see [search.md](search.md)). Map responses with `toCrossSellProduct`
-  (exported from `cart-drawer/cross-sell-sidebar`; picks the first variant
-  with a server-computed `calculated_price`, returns null unpriced — pass
-  `currency_code` on the listing call). Wire `onAdd(productId, variantId)`
-  → `addItem(variantId)`.
-- **Settings** — Admin → Product → Related (manual picks); price lists
-  (what `calculated_price` contains); publishable-key channel scope.
-
-### `<CartSummaryBreakdown />` — `cart-drawer/summary-breakdown`
-
-- **Purpose** — full totals breakdown rendered EXACTLY from the decorated
-  cart: `subtotal`, `discount_total` (>0, negated for display),
-  `shipping_total` (once a shipping method is set; 0 renders FREE; before
-  that "calculated at checkout"), `tax_total` (>0), `payment_method_fee_total` (>0,
-  labeled by the server's `payment_method_fee_label`), `total`, then one row per
-  applied gift card (masked `last4`, negated; a depleted card stays listed
-  at 0) and `gift_card_remainder` — what the remainder provider charges.
-  Row selection is the pure `selectSummaryRows(cart)` (unit-tested).
-- **SDK calls** — none directly (context cart; every cart read re-derives
-  gift-card tender from the live ledger).
-- **Settings** — COD integration (fee + label), promotions, gift cards.
-
-### `<CartStickyFooter />` — `cart-drawer/sticky-footer`
-
-- **Purpose** — pre-checkout subtotal + checkout CTA. Deliberately shows
-  `productTotal(cart.items)` (product lines only) — NOT `cart.total`,
-  which carries shipping/tax/COD checkout-context state that must not
-  leak into the shopping drawer. Navigates to `hrefs.checkout`.
-
-### `<CartPaymentBadges methods? badges? />`, `<CartContinueShopping />`, `<CartEmpty />`
-
-- `payment-badges` — inline SVG payment logos (visa/mastercard/googlepay/
-  applepay/amex), overridable per store. `continue-shopping` — close link.
-  `empty` — empty state with `hrefs.browse` CTA. Pure props + labels.
-
-### `<CartDrawerTemplate config />` — `cart-drawer/template`
-
-- **Purpose** — the optional default assembly; every
-  feature opt-in via `CartDrawerConfig`. Stores wanting a different layout
-  compose the primitives themselves inside `<CartDrawer>`.
-- **Props contract** — `config`: `promoBanner`, `shippingTiers`
-  (EUR thresholds), `freeGift` (`minCartTotal` EUR), `giftWrap`,
-  `notes`, `rewards` (`pointsPerCurrency` = points per 1 EUR —
-  major-unit port change from the source's per-cent rate), `crossSell`
-  (`products` or async `loader` — fires once when the drawer first has
-  items; build it from the SDK + `toCrossSellProduct`). Cross-sell adds
-  are wired to the provider's `addItem` automatically.
-- **Mount rules** — renders product lines only (`isProductLine`) — a
-  fee-only cart renders as empty rather than a fake product row.
-
----
-
-## Family: products (`@cartbase/storefront/products/*`)
-The PDP + product-card family, production-proven. All prices
-render the SERVER-computed `variant.calculated_price` via
-`lib/get-product-price` (Cartbase's flat `price_list_type` wire shape) — no
-component computes money. Product data is the canonical `StoreProduct`
-(`@cartbase/storefront/api/products`) every discovery endpoint serves.
-
-**Labels / i18n** — `products/labels` (`ProductLabels` + English defaults),
-and a pack from `locales/*` for any other language,
-`products/context` (`<ProductLabelsProvider labels>` + `useProductLabels()`;
-components read copy only through the context or explicit `labels` props).
-
-### `<ProductLabelsProvider labels />` — `products/context`
-
-- **SDK calls** — none. **Settings** — none.
-- **Mount rules** — client component; wrap the product page (or app) once;
-  partial `labels` merge over English defaults.
-
-### `<Thumbnail thumbnail images size isFeatured />` — `products/thumbnail`
-
-- **Purpose** — the product image tile used by cards; `ImageOff` fallback
-  when no image exists.
-- **SDK calls** — none (props: `product.thumbnail` / `product.images`).
-- **Props** — `size: "small"|"medium"|"large"|"full"|"square"` (aspect +
-  width), `isFeatured` (11/14 aspect), `className`.
-- **Mount rules** — server-safe; uses `next/image` (host must allow the
-  media domain in `next.config` images).
-
-### `<PreviewPrice price />` — `products/preview-price`
-
-- **Purpose** — card price line; strikethrough original + accent price when
-  `price_type === "sale"`.
-- **SDK calls** — none; takes a `VariantPrice` from
-  `lib/get-product-price` `getProductPrice(...).cheapestPrice`.
-- **Settings** — price lists (whether a `sale` type ever appears).
-
-### `<ProductPrice product variant? />` — `products/product-price`
-
-- **Purpose** — PDP price panel: "From <cheapest>" until a variant is
-  selected, then the variant price; sale shows original + percentage off.
-- **SDK calls** — none directly; the product must have been fetched WITH a
-  pricing context (`currency_code`/`region_id`) or it renders the loading
-  shimmer (no `calculated_price` → no price, by design).
-- **Settings** — price lists / B2B groups (via the Bearer JWT on the fetch),
-  region/currency context.
-- **Mount rules** — client; reads labels from context.
-
-### `<OptionSelect option current updateOption title disabled />` — `products/option-select`
-
-- **Purpose** — one option row of value buttons (`product.options[]`, which
-  carries `values[]`).
-- **SDK calls** — none. **Mount rules** — client; controlled by the parent.
-
-### Pure: `products/variant-matching` (extra module, Cartbase addition)
-
-`optionsAsKeymap` / `optionsMatch` / `findMatchingVariant` — the
-option-choice → variant resolution extracted from product-actions, reading
-Cartbase's option-value LINK shape (`variant.options[].value.{option_id,value}`)
-with a legacy flat-row fallback. Unit-tested
-(tests/unit/storefront-catalog.test.ts).
-
-### `<ImageGallery images />` — `products/image-gallery`
-
-- **Purpose** — stacked PDP gallery (rank order as served); first three
-  images `priority`.
-- **SDK calls** — none (props: `product.images`). Server-safe.
-
-### `<ProductActions product addToCart disabled? onAddToCart? openCart? />` — `products/product-actions`
-
-- **Purpose** — THE add-to-cart panel: option selection → variant
-  resolution, URL `v_id` sync, price, stock gate, add button, mobile bar.
-- **SDK calls** — none itself; the injected `addToCart({variantId,
-  quantity})` seam is the host's cart orchestration (typically `api/carts`
-  `addLineItem` + the host's cart-id cookie). `openCart` replaces the
-  legacy cart-drawer context import (no hard cross-family dependency).
-- **Stock contract** — Cartbase's store surface exposes NO
-  `inventory_quantity`; managed-inventory variants are optimistically in
-  stock and the SERVER enforces at add (400 `insufficient_inventory`, which
-  flips the button to the out-of-stock state). `!manage_inventory` and
-  `allow_backorder` are always addable.
-- **Settings** — inventory (manage/backorder flags, kit components at add),
-  price lists, promotions (server re-applies on add).
-- **Mount rules** — client; needs `ProductLabelsProvider` for non-English.
-  Fire the tracking trio (`trackAddToCart`/GA4/Rybbit) from `onAddToCart`.
-
-### `<MobileActions … />` — `products/mobile-actions`
-
-- **Purpose** — the `lg:hidden` sticky bottom bar + options bottom sheet
-  (z-[75], above the cart drawer's z-[60]) shown when the desktop actions
-  scroll out of view.
-- **SDK calls** — none; pure props from `ProductActions` (which mounts it —
-  rarely used directly).
-
-### `<ProductTabs product />` — `products/product-tabs`
-
-- **Purpose** — accordion: product information (material, origin, type,
-  weight, dimensions) + static shipping/returns copy from labels.
-- **SDK calls** — none. **Settings** — none (copy via labels).
-
-### `<ProductInfo product />` — `products/product-info`
-
-- **Purpose** — collection link (`/collections/<handle>`), title,
-  description. **SDK calls** — none. Server-safe.
-
-### `<ProductPreview product isFeatured? />` — `products/product-preview`
-
-- **Purpose** — THE product card (links `/products/<handle>`): thumbnail +
-  title + cheapest price. Reused by store grids, search results, related
-  strip; every template accepts `renderProduct` to swap it for a custom
-  card.
-- **SDK calls** — none; expects a `StoreProduct` fetched with pricing
-  context for the price line. Server-safe.
-
-### `<RelatedProducts client product labels pricingContext? limit? renderProduct? />` — `products/related-products`
-
-- **Purpose** — the "You might also like" strip.
-- **SDK calls** — `api/search` `listRelatedProducts(product.id)` — manual
-  admin picks first, deterministic fallback fills to `limit`
-  (`auto_filled`); anchor never appears. Renders nothing on empty/404.
-- **Labels** — `labels: ProductLabels`, REQUIRED: a server component cannot
-  read the provider, so pass `STORE_LOCALE.products`; `ProductTemplate`
-  passes its own through.
-- **Settings** — Admin → Product → Related (manual picks), price lists.
-- **Mount rules** — async server component; render inside `<Suspense>`.
-
-### `<ProductActionsWrapper client id pricingContext? addToCart … />` — `products/product-actions-wrapper`
-
-- **Purpose** — re-fetches the product with the LIVE pricing context (and
-  the client's Bearer JWT → group-aware B2B prices) and mounts
-  `ProductActions`; the PDP shell stays cacheable.
-- **SDK calls** — `api/products` `retrieveProduct(idOrHandle,
-  pricingContext)`; 404 → renders nothing.
-- **Mount rules** — async server component inside `<Suspense>` (fallback:
-  disabled `<ProductActions>`).
-
-### `<ProductTemplate client product labels addToCart pricingContext? onAddToCart? openCart? promises? hideSpecs? sections? />` — `products/product-template`
-
-- **Purpose** — the full PDP: sticky info column (`ProductInfo` +
-  `ProductTabs`), gallery, sticky actions column (suspended
-  `ProductActionsWrapper`), related strip.
-- **SDK calls** — via children (retrieveProduct, listRelatedProducts). The
-  page fetches the product by handle (`retrieveProduct`) and passes it in.
-- **Settings** — union of children's.
-- **Mount rules** — server component; `labels` is REQUIRED (the pack's
-  `products` area) because the related strip renders on the server; the
-  client parts inside read `ProductLabelsProvider`, which
-  `StorefrontLocaleProvider` mounts; `addToCart`/`openCart` seams as on
-  `ProductActions`.
-
-## Family: store (`@cartbase/storefront/store/*`)
-The listing family: paginated grids, sort, collection/category/search
-templates. Sorting discipline: the API's `order` param is the authority for
-paginated listings; client-side re-sort (`lib/sort-products`) exists ONLY
-for the price sorts on the plain products listing (price is not a products
-column) over the legacy 100-item window.
-
-**Labels / i18n** — `store/labels` (`StoreLabels` + defaults + the pure
-`sortOptionLabelKeys` map — completeness unit-tested) and `locale.store`
-from a pack. Templates take `labels: StoreLabels`, REQUIRED: they are
-server components and cannot read the provider, so a page hands them
-`STORE_LOCALE.store` (`en.store` for an English store).
-
-### `<Pagination page totalPages />` — `store/pagination`
-
-- **Purpose** — windowed page-number pagination; writes the `page` query
-  param and pushes the route (server re-renders with the new offset).
-- **SDK calls** — none. **Mount rules** — client.
-
-### `<SortSelect sortBy? labels? />` — `store/sort-select`
-
-- **Purpose** — sort sidebar; writes the `sortBy` query param
-  (`created_at` | `price_asc` | `price_desc`, rendered from
-  `sortOptionLabelKeys`).
-- **Props** — `sortBy` OPTIONAL (port adaptation): on collection pages no
-  selection = the collection's admin `default_sort`, nothing highlighted.
-- **SDK calls** — none. **Mount rules** — client.
-
-### `<PaginatedProducts client page sortBy? collectionId? categoryId? productsIds? pricingContext? renderProduct? />` — `store/paginated-products`
-
-- **Purpose** — the 12-per-page product grid + pagination over the plain
-  products listing.
-- **SDK calls** — `api/products` `listProducts`: `created_at` →
-  server `order:"-created_at"` + real offset pagination; `price_asc`/
-  `price_desc` → 100-item window fetch, `lib/sort-products` re-sort, slice
-  (the proven production approach — see module JSDoc for the >100 caveat).
-- **Props note** — `collectionId` filters by PRIMARY collection
-  (`products.collection_id`); the membership join lives in
-  `CollectionTemplate`.
-- **Settings** — price lists (pricing context), sales-channel/publishable-
-  key scope on the client.
-- **Mount rules** — async server component; render inside `<Suspense>`
-  with `<SkeletonProductGrid />`.
-
-### `<SkeletonProductGrid numberOfProducts? />` — `store/skeleton-product-grid`
-
-- **Purpose** — pulse skeleton for any product grid. Server-safe, no calls.
-
-### `<StoreTemplate client labels sortBy? page? pricingContext? renderProduct? />` — `store/store-template`
-
-- **Purpose** — the `/store` all-products page: sort sidebar + heading +
-  suspended `PaginatedProducts`.
-- **SDK calls** — via `PaginatedProducts`. Pass the page's `sortBy`/`page`
-  query params straight in.
-
-### `<CollectionTemplate client collection labels sortBy? page? pricingContext? renderProduct? />` — `store/collection-template`
-
-- **Purpose** — collection page over the MEMBERSHIP listing (multi-
-  collection products appear in every collection).
-- **SDK calls** — `api/collections` `listCollectionProducts(collection.id)`
-  — the admin `default_sort` is honored SERVER-side when `sortBy` is unset
-  (no client re-sort, port adaptation); a shopper override maps
-  `created_at→newest`, `price_asc`, `price_desc` to the `order` param
-  (price sorting server-side here, unlike the plain listing). Fetch the
-  collection itself via `listCollections({handle})` in the page.
-- **Settings** — collection `default_sort` + manual order, smart-collection
-  conditions, channel links (scoped-away collection 404s), price lists.
-- **Mount rules** — server component; grid suspends internally.
-
-### `<CategoryTemplate client category labels sortBy? page? pricingContext? renderProduct? />` — `store/category-template`
-
-- **Purpose** — category page: breadcrumbs (ancestor chain), description,
-  child-category links, `PaginatedProducts` filtered by `category_id`.
-- **SDK calls** — via `PaginatedProducts`. Fetch the category in the page
-  with `retrieveCategory(id, {include_ancestors_tree: true,
-  include_descendants_tree: true})` — without the flags the breadcrumb and
-  children sections don't render.
-- **Settings** — category tree (active/internal flags are server-filtered).
-
-### `<SearchTemplate client searchParams labels basePath? pricingContext? limit? renderProduct? />` — `store/search-template`
-
-- **Purpose** — the search results page in the
-  store-template idiom — GET query box, facet sidebar from the response
-  `facets[]`, result grid (reuses the product card), pagination. Fully
-  URL-state driven: works server-rendered with zero own client JS.
-- **SDK calls** — `api/search` `searchProducts` (only when `q` present).
-  Facet buckets toggle by rewriting the wire-named query params
-  (`collection_id`/`type_id`/`tag_id` CSV, `price_min`/`price_max`,
-  `availability`, `option.<Title>` CSV) via the pure `store/search-params`
-  helpers (round-trip unit-tested); every toggle resets `page`.
-- **Settings** — Search & discovery: synonyms, pins/boosts, facet config
-  (order/enabled, price bucket strategy `auto`/`fixed`); price facet
-  currency follows the pricing context.
-- **Mount rules** — async server component; pass the route's raw
-  `searchParams`; `basePath` defaults to `/search`.
-
-### Pure: `store/search-params` (extra module, Cartbase addition)
-
-`parseSearchParams` / `buildSearchQueryString` / `fromQueryString` /
-`toggleFacetSelection` / `isFacetSelected` / `clearFilters` /
-`toSearchQuery` — the search page's URL-state machine, exported for custom
-search UIs (chips, drawers) that want the same URL contract.
-
----
-
-## Family: order (`@cartbase/storefront/order/*`)
-Order confirmation + account order views, production-proven. Some
-platforms ship ONE `StoreOrder` object carrying computed line
-totals, order totals, shipping methods and payments; Cartbase splits those
-across surfaces, so the family takes them as separate props — the Cartbase
-`StoreOrderDetail` (`api/orders`) carries items as version-pivot rows
-(`{quantity, line_item}`), fulfillments with tracking labels, and both
-addresses, while MONEY comes from the decorated cart (`api/carts` `Cart`)
-or the order summary snapshot. Components render server truths; the only
-arithmetic is the two documented production subtractions in the totals
-selector.
-
-Labels: `OrderLabelsProvider`/`useOrderLabels` (`order/context`) +
-`defaultOrderLabels` (`order/labels`, English) + `locale.order` from a
-pack in `locales/*` for any other language. Every
-component also takes a `labels` prop pick, and the template's is REQUIRED
-(`labels: OrderLabels`): it renders on the server, where no provider
-reaches, so the page passes `STORE_LOCALE.order`.
-
-### `<OrderCompletedTemplate order totals labels items? shippingMethod? paymentProviderId? cardLast4? … />` — `order/order-completed-template`
-
-- **Purpose** — the full confirmation page: hero header, fulfillment
-  timeline, items+totals card, contact/delivery/payment/help cards,
-  continue-shopping CTA.
-- **SDK calls** — none itself; feed it: `order` (`retrieveOrder` /
-  `retrieveOrderByDisplayId` detail, or the `completeCart()` response),
-  `totals` (the decorated cart from checkout, or
-  `orderTotalsFromSummary(completeCart().order.summary)`), optional
-  normalized `items` (prefer `displayItemFromCartLine` right after
-  checkout — keeps server-computed per-line discounts), `shippingMethod` /
-  `paymentProviderId` / `cardLast4` from checkout state.
-- **Mount rules** — order-confirmation route (server component OK; only
-  the timeline child is client). The Purchase tracking trio (fbq/gtag/
-  rybbit, deduped by `order.display_id`) is APP-OWNED: fire it from the
-  confirmation route exactly once per order per the tracking family's
-  dedupe contract — the template deliberately does NOT fire it.
-- **Settings** — COD settings (fee row presence + `payment_method_fee_label`),
-  checkout rules (which provider ids appear), store locales (labels pack).
-
-### `<OrderConfirmationHeader order />` — `order/order-confirmation-header`
-
-- **Purpose** — check hero + "Order #display_id" + localized date chips.
-- **Props** — structural `OrderHeaderData` (`display_id`, `email`,
-  `created_at`) — order detail and `completeCart().order` both satisfy it.
-  `locale` drives `toLocaleDateString`.
-
-### `<OrderItemsList items currencyCode />` + `<OrderItem item currencyCode />` — `order/order-items-list`, `order/order-item`
-
-- **Purpose** — the purchased lines (thumb, title, variant caption, qty,
-  line total with discount strike-through when the source had it).
-- **Data seam** — normalized `OrderDisplayItem[]` via the pure converters
-  `displayItemFromOrderItem(pivot)` (order path: `unit_price × quantity`)
-  / `displayItemFromCartLine(line)` (cart path: server `total` /
-  `original_total`). Legacy COD-fee line items
-  (`metadata.is_cod_fee=true`) are hidden here and surfaced in
-  `OrderTotals` instead (`lib/cart-helpers.isProductLine`); Cartbase-native
-  COD fees are never line items, so on pure Cartbase data the filter is a
-  no-op safety net. Newest-first sort by `createdAt` when present.
-
-### `<OrderTotals totals currencyCode items? methodFeeLabel? />` — `order/order-totals`
-
-- **Purpose** — the money breakdown: Subtotal / Shipping (FREE badge at
-  0) / COD fee / Discount (negated) / Tax / Total, all via `Price`.
-- **Data seam** — `OrderTotalsSource` (the decorated cart satisfies it:
-  `item_subtotal`, `shipping_subtotal`, `discount_total`, `tax_total`,
-  `total`, `payment_method_fee_total`, `payment_method_fee_label`); the summary snapshot adapts
-  via `orderTotalsFromSummary`. Row policy is the pure, unit-tested
-  `selectOrderTotalsRows`: native `payment_method_fee_total` wins over a legacy fee
-  LINE; a legacy fee line's net is subtracted from the visible subtotal
-  (v2.3.1 production fix); COD label preference `methodFeeLabel` prop →
-  server `payment_method_fee_label` → fee-line title → `labels.paymentMethodFee`.
-- **Settings** — COD settings (`payment_method_fee_total`/`payment_method_fee_label`),
-  promotions (discount row).
-
-### `<OrderAddressCard order />` — `order/order-address-card`
-
-- Contact info card: shipping-address name + phone + order email.
-  Structural `OrderContactData` — the order detail satisfies it.
-
-### `<OrderDeliveryCard order shippingMethod? currencyCode />` — `order/order-delivery-card`
-
-- **Purpose** — pickup point (Econt office metadata / stable
-  fulfillment-option ids `econt-office`, `boxnow-locker` — id beats name
-  parsing, production fix) or shipping address, the method row with
-  price/FREE, and — Cartbase addition — the fulfillment tracking labels.
-- **Data seam** — `order.metadata` + `order.shipping_address` +
-  `order.fulfillments` from the detail; `shippingMethod` (structural,
-  `CartShippingMethod` fits) from checkout state since the Cartbase order
-  read has no shipping-method embed. Tracking rows come from the pure,
-  unit-tested `pickTrackingLabels(order.fulfillments)` — skips canceled
-  fulfillments, drops number-less labels, dedupes re-prints.
-- **Settings** — carrier integrations (whether labels/urls exist),
-  shipping options (ids/names).
-
-### `<OrderPaymentCard providerId cardLast4? />` — `order/order-payment-card`
-
-- Payment method card; `resolvePaymentTitle(providerId, titles,
-  methodName?)` — the method's merchant NAME wins verbatim when present
-  (the snapshot from session data); otherwise the processor id buckets
-  via `lib/payment-constants` (`pp_stripe` = card) through the locale
-  pack, falling back to `paymentInfoMap` then the raw id. Payment
-  internals never cross the Cartbase store surface — both arrive via
-  props from checkout state.
-
-### `<OrderTimeline fulfillmentStatus? />` — `order/order-timeline`
-
-- Placed → Processing → Shipped → Delivered progress (client, animated).
-  Cartbase has no `fulfillment_status` column on the store surface —
-  derive it with the pure, unit-tested
-  `deriveFulfillmentStatus(order.fulfillments)` (packed_at/shipped_at/
-  delivered_at ladder, `partially_*` when only some active fulfillments
-  reached a stage, canceled ignored).
-
-### `<OrderHelpSection contactHref? returnsHref? />` — `order/order-help-section`
-
-- "Need help?" links card (contact + returns). No SDK calls, no settings.
-
----
-
-## Family: common (`@cartbase/storefront/common/*`)
-Shared storefront chrome, production-proven.
-
-### `<LocalizedLink href … />` — `common/localized-link`
-
-- `next/link` that persists the URL locale/country segment when the route
-  has one (`[countryCode]` param by default, `paramName` overridable);
-  plain link on cookie-locale apps (the Cartbase default). Client.
-
-### `<CartButton client cartId? />` + `<CartButtonClient cart />` — `common/cart-button`, `common/cart-button-client`
-
-- **Purpose** — header cart button: badge count + opens the cart drawer.
-- **SDK calls** — server wrapper: `api/carts.retrieveCart(client, cartId)`
-  (the app owns the cart-id cookie); fetch failure degrades to an empty
-  button. Client half takes the decorated `Cart`; badge count =
-  `productItemCount(cart.items)` (fee-line-aware, consistent with the
-  drawer).
-- **Mount rules** — `CartButtonClient` must sit inside the cart-drawer
-  family's `<CartDrawerProvider>` (it calls `useCartDrawer().open`).
-
-### `<DeleteButton client cartId id onDeleted? />` — `common/delete-button`
-
-- Cart-line remove with spinner. Calls
-  `api/carts.deleteLineItem(client, cartId, id)` (idempotent) and hands
-  the refreshed `{cart}` to `onDeleted`; spinner resets on failure.
-
-### `<MarketSelect regions value? onChange />` — `common/market-select`
-
-- **Purpose** — the market picker for a header or footer: the store's
-  REGIONS (`api/regions.listRegions`) by name, valued by region id;
-  persistence is app-owned via `onChange` (usually
-  `carts.updateCart(client, cartId, {region_id})` + a cookie). A country is
-  a different thing: the checkout picks one from `listCountries`, with
-  `CountryFlag` beside it.
-- **Was `CountrySelect`** (`common/country-select`) until 2026-09-14, a name
-  the port carried for a component that never listed countries here. The
-  old path and names still import for one release and then go.
-- **Settings** — Admin → Settings → Markets → Regions: which rows exist.
-
-### `<CountryFlag code title? className? />` — `common/country-flag`
-
-- **Purpose** — a country's flag from its ISO-3166 alpha-2 code, at the size
-  of the text beside it. An unknown or empty code renders a neutral box that
-  holds the same space, so a field does not jump when a shopper picks their
-  country.
-- **Why a sprite and not an emoji** — Windows ships no flag glyphs, so an
-  emoji flag reads as the two letters "BG" there. This draws `flag-icons`
-  SVG under a CSS class, which renders the same on every platform, and it is
-  the same sprite the Cartbase admin uses, so one country treatment runs
-  across the admin and the storefront.
-- **Accessibility** — decorative and `aria-hidden`: a flag never carries
-  meaning the name beside it does not. Pass `title` when it stands alone.
-
-### `<LanguageSelect locales currentLocale onChange labels? />` — `common/language-select`
-
-- **Purpose** — locale switcher. Feed `locales` from
-  `api/regions.listLocales(client)` (bare codes, store default first —
-  SDK wins over the source's `{code,name}` objects); display names via
-  `localeDisplayName()` (`Intl.DisplayNames` autonym) with per-store
-  `labels` overrides. `onChange` persists (cookie read by
-  `StorefrontClient.getLocale`) inside the preserved `useTransition`
-  pending-disable UX.
-- **Settings** — Settings → Store → locales (per-store `store_locales`).
-
-### `<Skeleton className? />` + `<SkeletonProductPreview />` — `common/skeleton`
-
-- Loading placeholders (pure UI over theme tokens).
-
----
-
-## Family: reviews-ui (`@cartbase/storefront/reviews-ui`)
-Verified-purchase review components, ported from a production storefront,
-over `api/reviews`. ONE barrel export seam: everything imports from
-`@cartbase/storefront/reviews-ui`. Endpoint truth:
-[reviews.md](reviews.md). Labels: the family reads the language mounted by
-`StorefrontLocaleProvider` on its own (English with none, since
-2026-09-14), `labels?` on any component overrides keys, and `StarBadge`,
-the one server-safe piece, takes its labels as a prop. Strings are
-parameterized with `{n}`/`{pct}`/`{name}`/`{mb}`/`{s}`/`{email}` slots
-(resolve via `formatLabel`).
-
-### `<ReviewWidget client productId initialData? />` — the PDP section
-
-- **Purpose** — aggregate header (score badge + 5→1 distribution bars +
-  sort select) + masonry card list + load-more + lightbox. Renders null
-  at zero reviews (production rule); derives avg/distribution from the
-  loaded page if the aggregate is missing (never a misleading "0.0").
-- **SDK calls** — bootstrap: `getWidget(client, productId)` (ONE call:
-  aggregate + first page per the store's display options; edge-cached
-  60s) — server-fetch it and pass `initialData` (recommended), else the
-  widget fetches on mount. Sort changes / load-more: `listReviews`
-  (`sortParamsFor` maps the UI keys to the API `(sort, order)` tuple).
-- **Mount rules** — client component, PDP below the fold; `id="reviews"`
-  anchor built in. Verified badge is unconditional (every review is
-  token-minted — a system tautology, not a flag).
-- **Settings** — Settings → Reviews display options: `widget_layout`
-  (masonry|list), `widget_page_size`, `widget_photo_first` (all arrive
-  via `getWidget().options`); moderation decides visibility.
-- Pieces exported for custom layouts: `<StarRow>`, `<StarBadge>`,
-  `<RatingDistribution>` (`star-badge`), `<ReviewList>` +
-  `<ReviewLightbox>` (presentational cards + overlay),
-  `reviewDisplayName` (first name + surname initial — shared with any
-  app JSON-LD so UI and structured data can't drift, production fix),
-  `formatReviewDate`.
-
-### `<ReviewWizard client token validation rewardPct? supportEmail? … />` — the token page
-
-- **Purpose** — everything behind `<review_link_base>/<token>`: invalid/
-  expired panels, the terminal already-submitted panel, and the two-step
-  form (rate → photo → done) with the reward-code reveal.
-- **SDK calls** — `validateToken(client, token)` SERVER-SIDE in the page
-  (pass the result as `validation` — never flash a form on a dead
-  token; mark the route noindex), then client-side: `submitReview`
-  (step 1 — consumes the token, rating locked in even if the customer
-  bails), `createUploadUrl` → signed R2 PUT → `attachReviewPhoto`
-  (step 2 — mints the single-use reward code; `code: null` on 200 =
-  media saved, mint failed → "write to us" note, never an error).
-- **Step resolution** — the pure, unit-tested
-  `resolveWizardEntry(validation)`; THE RESUME RULE: consumed token +
-  review row + `reward_code` null → resume at photo; `reward_code` set →
-  done showing the code; consumed with no review row → terminal panel.
-  Submit errors map by status via `submitErrorKeyFor` (429/409/410).
-- **Mount rules** — `ReviewWizard` is the full page body (client);
-  `ReviewWizardForm` and `<ReviewPhotoUpload>` (drag-drop, per-file slot
-  caps ≤6 images/≤1 video, 8/50 MB, 60s video, blob-preview swap +
-  revoke) are exported for custom pages.
-- **Settings** — Settings → Reviews: `reward_enabled` /
-  `reward_percentage` (the store surface does not expose the percentage —
-  pass `rewardPct`, default 10), `moderation_mode` (`hold` lands the
-  review pending; the thanks copy stays true either way), request-scanner
-  settings decide when tokens are minted at all.
+# Components
+
+The component layer of `@cartbase/storefront`: what each family ships, the SDK
+calls it requires, the admin settings that change its behavior, and its mount
+rules. Every family is production-proven — ported from live commerce
+storefronts and rewired to Cartbase data seams.
+
+This page has no executable curls — the endpoints these components consume
+are executably documented in their own domain files
+([integrations.md](integrations.md), [consent.md](consent.md), etc.); this
+page is the component-side contract that binds to them.
+
+Import discipline: always import from the subpath
+(`@cartbase/storefront/tracking/meta-pixel`, `@cartbase/storefront/lib/money`) —
+tree-shaking and Next.js RSC boundary detection both work better than via
+barrels. Styling resolves against STOREFRONT theme tokens (`bg-card`,
+`text-foreground`, …, shadcn-standard names) — `@import
+"@cartbase/storefront/theme"` in the app's CSS supplies both the token names
+and a filled default set of values, so components render designed out of the
+box. No component hardcodes a colour; retheming means overriding values, never
+renaming tokens.
+
+---
+
+## Language: the library is English, a language is a pack
+
+No component holds copy. Every string comes from a label pack, and the
+library's own defaults are **international English** (`products/labels`,
+`checkout/labels`, and so on, beside each family's type).
+
+A language is one object covering all six families, imported by its own
+subpath so a store bundles only what it ships:
+
+```tsx
+import { es } from "@cartbase/storefront/locales/es"
+import { StorefrontLocaleProvider } from "@cartbase/storefront/locales"
+
+<StorefrontLocaleProvider locale={es}>{children}</StorefrontLocaleProvider>
+```
+
+Shipping: `locales/en`, `locales/es`, `locales/bg`. Each is typed
+`StorefrontLocale`, so a label added to the library breaks an incomplete
+pack at compile time instead of falling back to English mid-checkout.
+
+The provider mounts the three pure label contexts (products, checkout,
+order), and the cart drawer and the reviews family read the language from
+it directly, so every CLIENT component inside it speaks the pack with no
+further wiring. What it cannot reach is a SERVER component: the store,
+product and order templates render on the server, so each page hands them
+their area of the pack, and that prop is REQUIRED. A page that forgets it
+does not compile; `PropLabelAreas` in `locales` names the areas.
+
+```tsx
+<StoreTemplate          labels={STORE_LOCALE.store} />
+<SearchTemplate         labels={STORE_LOCALE.store} />
+<CollectionTemplate     labels={STORE_LOCALE.store} />
+<CategoryTemplate       labels={STORE_LOCALE.store} />
+<ProductTemplate        labels={STORE_LOCALE.products} />
+<OrderCompletedTemplate labels={STORE_LOCALE.order} />
+```
+
+`STORE_LOCALE` is the pack the store declared once in its config (`en`, or
+`bg`, or `es`); the scaffold ships it that way. English is not a special
+case: an English store passes `en.store`.
+
+**Failure copy is copy.** What a shopper reads when an address, a payment, a
+gift card or a discount code fails lives in the checkout pack too
+(`addressErrors`, `paymentErrors`, `giftCardErrors`, `promotionErrors`).
+The modules that recognize each failure keep their English patterns,
+because those match the API's wire format and are never shown to anyone.
+
+Overriding one word is a partial: every provider merges over the defaults.
+
+---
+
+## Family: tracking (`@cartbase/storefront/tracking/*`)
+Meta Pixel + GA4 + Rybbit + Consent Mode v2. The Cartbase split of duties:
+**this package fires client events and writes attribution; server-side CAPI /
+GA4 Measurement Protocol sending is Cartbase-backend-owned** (the
+`order.placed` forwarder). The whole family is safe to render
+unconditionally — every component renders nothing when its id prop is absent,
+every helper no-ops outside the browser.
+
+### `<ConsentInit required />` — `tracking/consent-init`
+
+- **Purpose** — the synchronous Consent Mode v2 "default" snippet: sets
+  gtag's consent default before any Google tag loads. `required` is the
+  store's consent switch (`consent.enabled` from `GET /api/store/consent`).
+  With it true a new visitor starts DENIED until they choose on the banner;
+  with it false the store collects no consent and a new visitor starts
+  GRANTED. A choice stored in `_1c_consent` wins either way.
+- **SDK calls** — none in the browser. The layout resolves the consent
+  config on the server (it fetches it for the banner anyway) and passes the
+  switch; the script must NEVER wait on a fetch (async default = first-hit
+  consent race).
+- **Mount rules** — FIRST child of `<body>` in the root layout, before any
+  tag component. Plain inline `<script>` by design (not next/script). The
+  prop is REQUIRED: neither default is safe, so a layout must say what the
+  store does, and one that does not fails to compile (2026-09-14).
+- **Settings** — the consent card's `enabled` (admin → Settings → Consent).
+
+### `<ConsentBanner copy layout privacyHref rejectOnFirstLayer />` — `tracking/consent-banner`
+
+- **Purpose** — the built-in two-layer CMP UI; writes the `_1c_consent`
+  cookie and applies the live `gtag('consent','update')` + `fbq('consent')`.
+- **SDK calls** — `GET /api/store/consent` (via `@cartbase/storefront/api/consent`)
+  for the store's config; pass `copy = pickConsentCopy(consent.copy, locale)`,
+  plus `layout` / `privacy_href` / `reject_on_first_layer` from the payload.
+- **Mount rules** — mount ONLY when `shouldRenderBanner(consent)` (i.e.
+  `enabled && mode === "builtin"`). In `mode: "external"` render nothing —
+  the merchant's CMP must write the same `_1c_consent` cookie or call
+  `setConsent()`; all gating keeps working off that one seam. z-index is
+  `z-[70]` (above the cart drawer's `z-[60]`).
+- **Settings** — the consent card config (admin → Settings → Consent):
+  `enabled`, `mode`, `layout` (`modal` blocks + scroll-locks;
+  `banner-bottom` is non-blocking and must not trap focus), `privacy_href`,
+  `reject_on_first_layer`, per-locale `copy`.
+- Also ships `<ConsentSettingsLink>` (footer link that re-opens the settings
+  layer — "withdraw as easily as given") and the pure `<ConsentBannerCard>`.
+
+### `<MetaPixel pixelId consentRequired />` — `tracking/meta-pixel`
+
+- **Purpose** — injects fbevents.js, pushes the consent state BEFORE
+  `fbq('init')` (pre-init revoke = Pixel queues events until grant), fires
+  the initial PageView. The state is the store's default overridden by the
+  visitor's stored `_1c_consent` choice: revoked on a store that collects
+  consent, granted on a store with the banner off.
+- **SDK calls** — `getTrackingConfig(client)` (`tracking/get-tracking-config`,
+  wraps `GET /api/store/integrations` → `tracking.facebookPixel.pixelId` and
+  `tracking.consent_required`).
+- **Mount rules** — root layout, after `<ConsentInit>`; `<StorefrontTags>`
+  mounts it with both props from the block. Renders nothing when `pixelId`
+  is falsy. `consentRequired` is REQUIRED for the reason `<ConsentInit>`
+  gives, and so it is on `<TikTokPixel>` and `<ChatGptPixel>`, the two
+  other tags that gate their own SDK (2026-09-14). Google needs no prop: it
+  reads the `<ConsentInit>` default.
+- **Settings** — admin Integrations hub `facebook_capi` row (`enabled` +
+  `credentials.pixel_id`); consent card `enabled` → `consent_required`.
+- Companion: `updatePixelAdvancedMatching(visitor)` — call from checkout /
+  signup as PII becomes known; hashes em/ph/fn/ln/ct/st/zp/country
+  (SHA-256, Meta normalization) and re-inits the Pixel so every subsequent
+  event carries Advanced Matching. Also persists raw values for
+  `getKnownVisitor()`.
+
+### `<GA4 measurementId />` — `tracking/ga4`
+
+- **Purpose** — loads gtag.js + `gtag('config')`. gtag then owns the `_ga` /
+  `_ga_<MEASUREMENT_ID>` cookies that `getTrackingAttribution()` later reads.
+- **SDK calls** — `getTrackingConfig(client)` → `tracking.ga4.measurementId`.
+- **Mount rules** — root layout, after `<ConsentInit>` (the consent default
+  governs whether gtag writes cookies or sends cookieless pings). Renders
+  nothing when falsy. SPA route changes are NOT auto-tracked — fire
+  `page_view` from a route-change effect if per-route views are wanted.
+- **Settings** — Integrations hub `ga4` row (`credentials.measurement_id`);
+  consent card.
+
+### `<Rybbit siteId baseUrl? />` — `tracking/rybbit`
+
+- **Purpose** — the platform's self-hosted, cookieless analytics tracker;
+  auto-tracks pageviews incl. SPA route changes.
+- **SDK calls** — NONE. Rybbit is deliberately absent from the store
+  `tracking` block: platform-provisioned, the host app passes props from
+  platform env. Outside the consent system by design (cookieless).
+- **Mount rules** — root layout; renders nothing when `siteId` falsy.
+- **Settings** — none merchant-facing.
+
+### Client events — `tracking/events` (use this one)
+
+ONE call per commerce moment, every vendor at once. Reach for these rather
+than the per-vendor helpers below, because the failure they prevent is the
+common one and it is invisible: a store adds a vendor, updates three of the
+four call sites, and an ad account optimises on partial data for a month
+before anyone notices.
+
+| Step | Call |
+|---|---|
+| Product view | `trackProductView({ line, currency, value })` |
+| Add to cart | `trackCartAdd({ line, currency, value })` |
+| Checkout start | `trackCheckoutStart({ lines, currency, value, coupon? })` |
+| Order confirmed | `trackOrderPurchase(order, trackingConfig)` |
+
+A `line` is `{ productId, variantId?, title, quantity, price }`. Pass the
+PRODUCT id: Meta's content_ids, TikTok's content_id and the catalogue
+feed's `<g:id>` must be the same value or the event matches no catalogue
+entry, which costs dynamic ads on both platforms. GA4 is keyed by variant
+instead, on purpose, and these helpers do that split for you.
+
+`trackOrderPurchase` takes the tracking config as its second argument
+because Google Ads only fires when the store configured BOTH the account id
+and the purchase label. Pass `order.metadata.customer_type` through as
+`customerType` when present: it is computed once server-side, so the
+browser and the server tell Google and TikTok the same thing.
+
+### Per-vendor helpers — `tracking/fbq`, `tracking/gtag`, `tracking/ttq`, `tracking/rybbit-events`, `tracking/google-ads`
+
+Call on the matching funnel step; all are no-op-safe (SSR, blocked, absent
+tag). The Rybbit helpers additionally queue-buffer through the script-load
+race (10s cap, v2.2.6 production fix).
+
+| Step | Meta (`fbq.ts`) | TikTok (`ttq.ts`) | GA4 (`gtag.ts`) | Rybbit (`rybbit-events.ts`) |
+|---|---|---|---|---|
+| Product view | `trackViewContent` | `trackTikTokViewContent` | `trackGAViewItem` | `trackRybbitViewItem` |
+| Add to cart | `trackAddToCart` | `trackTikTokAddToCart` | `trackGAAddToCart` | `trackRybbitAddToCart` |
+| Checkout start | `trackInitiateCheckout` | `trackTikTokInitiateCheckout` | `trackGABeginCheckout` | `trackRybbitBeginCheckout` |
+| Order confirmed | `trackPurchase(data, order.display_id)` | `trackTikTokPurchase({…, displayId})` | `trackGAPurchase({transaction_id: String(order.display_id), …})` | `trackRybbitPurchase` |
+| Newsletter/popup signup | `trackLead` | — | — | — |
+
+Google Ads has one event, the purchase conversion:
+`trackGoogleAdsPurchase({ sendTo, value, currency, transactionId, newCustomer? })`,
+with `sendTo` from `googleAdsPurchaseSendTo(config)` (null when the label
+is not configured — skip the conversion rather than fire a malformed
+`send_to`, which Google accepts and silently drops).
+
+**THE Purchase dedupe contract** (must never drift; mirrored server-side in
+`src/lib/tracking/constants.ts`):
+
+- Meta: browser Pixel `eventID` = **`"purchase_" + order.display_id`** — the
+  exact id the backend `order.placed` CAPI Purchase uses. `trackPurchase()`
+  builds it from the caller's `display_id` so the format cannot drift. Meta
+  dedupes by event_name + event_id (~3 days).
+- TikTok: browser pixel `event_id` = **`"tt_purchase_" + order.display_id`**,
+  the same id the backend Events API Purchase sends. The `tt_` prefix keeps
+  it from colliding with Meta's on a page carrying both pixels. TikTok
+  dedupes on event_source_id + event + event_id and discards duplicates for
+  48 hours; the backend ALSO carries an idempotency flag, because 48 hours
+  does not cover an order email opened on day four.
+- GA4: `transaction_id = String(order.display_id)` on both browser event and
+  backend Measurement Protocol — GA4 dedupes by transaction_id natively.
+- Google Ads: `transaction_id` again, the same value. Never send it empty:
+  an empty transaction_id dedupes nothing, so every re-open of the
+  confirmation page counts another conversion.
+- All other events get `<eventname>_<unixSeconds>_<6hex>` ids
+  (`generateEventId`).
+
+`setEnhancedConversions(input)` (gtag.ts) — Google Ads Enhanced Conversions
+for Web: hashes email/phone/names client-side and `gtag('set','user_data',…)`.
+Call alongside `updatePixelAdvancedMatching` at checkout. The phone is
+normalised to E.164 WITH the plus, which is NOT the digits-only string Meta
+wants: two vendors, two normalisers, and merging them re-creates a defect
+that fails silently and costs match rate with nothing in any log.
+
+### Attribution — `tracking/attribution`, `tracking/get-tracking-attribution`, `tracking/use-engagement-time`
+
+- Browser side (call from a top-level client component, e.g. `TrackInit`):
+  `captureUtmsFromUrl()` (first-touch `_1c_utm_first` 365d, last-touch
+  `_1c_utm_last` 90d), `getOrCreateFbp()` / `getOrCreateFbc()` (defensive
+  `_fbp`/`_fbc` writes so the Pixel-load race never ships empty match keys —
+  production fix), `getOrCreateAnonId()` (`_1c_anon`, the guest
+  `external_id`), `initEngagementTime()`.
+- Server side, at checkout completion:
+  `getTrackingAttribution(clientHints?, opts?)` reads the cookies + headers
+  and returns the `TrackingAttribution` keys to write into `cart.metadata`
+  (CONSENT-GATED — only when the visitor's choice allows). Cart completion
+  copies them to `order.metadata`; the backend forwarder inherits
+  fbp/fbc/anon-id/ga signals from there. Pass
+  `{ engagementTimeMsec: getEngagementTimeMsec() }` as clientHints, and
+  either `opts.ga4MeasurementId` or `opts.client` so the `_ga_<id>` session
+  cookie can be located.
+- **Settings** — Integrations hub rows (which signals exist), consent card
+  (whether capture happens).
+
+---
+
+## Family: primitives (`@cartbase/storefront/primitives/*`)
+Generic shadcn-style building blocks. No SDK calls, no admin settings —
+pure UI over the theme tokens.
+
+- `primitives/field` — `<Field label … />`: floating-label input (checkout
+  house style) with the `pulse` attention cue (soft blue 2-cycle pulse,
+  distinct from focus/error — production UX fix).
+- `primitives/select-field` — `<SelectField label>…options…</SelectField>`:
+  floating-label native select (native mobile keyboards).
+- `primitives/ui/*` — shadcn-standard `button` (cva variants incl.
+  `default/destructive/outline/secondary/ghost/link`), `input`, `label`,
+  `select`, `dialog`, `sheet`, `tabs`, `accordion`, `collapsible`,
+  `popover`. Radix-backed, ported verbatim; import per file.
+- Mount rules: all are `"use client"`. Requires the Tailwind preset tokens.
+
+---
+
+## Family: lib (`@cartbase/storefront/lib/*`)
+Pure helpers — no React except `price`, no fetches. The SDK never
+invents server truths: prices/totals arrive computed from the API
+(`variant.calculated_price`, `cart.total`); these helpers only select and
+format.
+
+- `lib/utils` — `cn()` (clsx + tailwind-merge).
+- `lib/money` — `convertToLocale({amount, currency_code, …})` Intl currency
+  formatting (amounts are decimal EUR major units per the store contract);
+  `noDivisionCurrencies`.
+- `lib/price` — `<Price amount currencyCode className />`: the amount in its
+  own currency, formatted through `convertToLocale`. Every price in the
+  library renders through it. It shows ONE currency; a store that wants a
+  second one displayed adds it in its own locale layer rather than in
+  every price.
+- `lib/cart-helpers` — `isProductLine` / `isFeeLine` / `productTotal` /
+  `productItemCount` / `findFeeLine` + `COD_FEE_METADATA_KEY`. THE single
+  source of truth for hiding the backend-injected COD-fee line in cart
+  surfaces while checkout/order totals show it as its own row. Affected by:
+  COD settings (whether a fee line ever appears).
+- `lib/get-product-price` — `getProductPrice({product, variantId})` /
+  `getPricesForVariant` → formatted `VariantPrice` (cheapest + selected)
+  from server-computed `calculated_price`. Reads Cartbase's flat
+  `price_list_type` with a legacy nested shape as fallback. Affected by:
+  price lists / B2B pricing context (what `calculated_price` contains),
+  currency + region query context.
+- `lib/get-percentage-diff` — sale badge math.
+- `lib/product` — `isSimpleProduct` (skip the option selector for
+  one-option-one-value products).
+- `lib/sort-products` — client-side re-sort of a fetched page
+  (`price_asc|price_desc|created_at`); the API's `order` param stays the
+  authority for paginated listings.
+- `lib/payment-constants` — `isStripeLike` / `isPaypal` +
+  `paymentInfoMap`. Two tender shapes since the pp_* kill: a processor
+  `provider_id` (`pp_stripe` exact, code truth
+  `src/lib/stripe/providers.ts`, plus legacy Medusa-era prefixes as
+  fallbacks) or a merchant METHOD rendered by its snapshot NAME — a
+  method never has a provider id to bucket. Affected by: connected
+  processors + enabled methods + checkout rules (which entries ever
+  reach the client).
+- `lib/store-api-error` — `storeApiError(err)`: display-boundary normalizer
+  (capitalized message + terminal period).
+  Catch `StoreApiError` directly instead when branching on `status`/`code`.
+- `lib/hooks/use-intersection`, `lib/hooks/use-toggle-state` — viewport +
+  toggle micro-hooks (client).
+
+---
+
+## Family: checkout (`@cartbase/storefront/checkout/*`)
+The full checkout page family, production-proven (deferred-
+intent architecture — no payment session exists until Buy click) onto the
+Cartbase orchestration endpoints. The flow every component serves
+(executable ground truth: [checkout.md](checkout.md)):
+
+```
+listShippingOptions(cart_id) + listPaymentProviders(cart_id)  (render pickers)
+   → Buy click → prepareCheckout (ONE atomic, compensated call)
+   → pp_stripe: stripe.confirmPayment(client_secret) | merchant method: skip
+   → completeCart → navigate to the confirmed page
+```
+
+Amounts are EUR major units and SERVER truth — components render totals,
+never compute money; the only client-side arithmetic is the *optimistic
+display* overlay (shipping/COD-fee prediction) that the server value
+replaces at prepare. All user-facing copy flows from `CheckoutProvider`
+labels (English by default; a language is a pack from `locales/*`); errors surface
+code-first through the error-copy maps, never raw API strings.
+
+### `<CheckoutProvider labels orderConfirmedPath />` — `checkout/context`
+
+- **Purpose** — supplies labels + the order-confirmed path template
+  (`{id}`/`{country}` substitution) to every checkout primitive.
+- **SDK calls** — none.
+- **Mount rules** — wrap the checkout page (or any custom composition).
+  Default path template `"/{country}/order/{id}/confirmed"`; single-country
+  stores pass `"/order/{id}/confirmed"`.
+- **A NESTED PROVIDER INHERITS (0.12.0)** — mounting a second one, which is
+  what you do when you set `orderConfirmedPath` on a page inside a
+  `StorefrontLocaleProvider`, keeps every label from the provider above and
+  changes only the keys you name. Before 0.12.0 it merged over the ENGLISH
+  defaults, so a provider mounted for the path alone silently reset the
+  whole checkout to English on an otherwise translated store. The same now
+  holds for `ProductLabelsProvider` and `OrderLabelsProvider`.
+- **Settings** — none (labels come from the store's locale pack).
+
+### `useCheckoutOrchestration(options)` — `checkout/use-checkout-orchestration`
+
+- **Purpose** — THE hardened checkout state machine: address form +
+  debounced autosave, shipping/payment selection (client-state-only
+  pre-Buy), carrier metadata, optimistic totals, the atomic Buy click,
+  3DS-return handling, completed-cart detection. Every production race
+  guard from production is preserved.
+- **SDK calls** — `carts.updateCart` (address autosave + tracking metadata),
+  `customers.updateMe` (best-effort profile sync incl. Cartbase's first-class
+  `company_name`/`company_eik`), `checkout.calculateShippingOption`
+  (calculated-rate forward-compat), `checkout.prepareCheckout`,
+  `checkout.syncPaymentAmount` (exposed + fired on payment-tab switch with
+  the new `provider_id`), `checkout.refreshPaymentIfTerminal` (exposed —
+  call REACTIVELY from Elements `loaderror` only), `carts.completeCart`.
+- **Props contract** — `{client, cart, customer, availableShippingMethods,
+  availablePaymentMethods, countryCode?, countries?, paymentMethodFilter?,
+  orderConfirmedPath?, onOrderPlaced?,
+  resolveTrackingMetadata?, logError?}`. `countries` is OPTIONAL and is an
+  override: omit it and the hook calls `GET /api/store/countries` itself, so
+  the address form offers the countries the store's Markets declare, or the
+  whole catalogue when it declares none (0.11.0 — before that, omitting it
+  produced a ONE-country read-only field). A failure to load the list never
+  blocks a checkout: it falls back to `countryCode` and reports through
+  `logError` as `country_list_failed`. Fee prediction is never
+  hardcoded: each method LISTING entry carries its own
+  `fee_amount`/`fee_label`. `logError` replaces the legacy log writers
+  (all production log points preserved). Returns the full orchestration
+  surface (`performBuyClick`, `optimisticTotal(Cents)`, `deliveryReady`, …).
+- **Cartbase specifics** — zero-remainder gift path: `prepareCheckout`
+  returning `client_secret:null` + `provider_id:null` +
+  `payment_method_id:null` SKIPS Stripe and completes on the gift session
+  ([gift-cards.md](gift-cards.md)). Processors are `pp_stripe` exactly;
+  merchant methods list as `{payment_method_id, name, kind, instructions,
+  fee_amount, fee_label}` entries — the COD-kind method wins the offline
+  tab, else the first manual method. The charged fee reads the cart-level
+  `payment_method_fee_total` decoration.
+- **Settings** — checkout rules (filter the listings + complete guard),
+  the methods' own fee configuration (Payments settings), Stripe
+  credentials, gift cards, `accounts_mode`.
+
+### `<CheckoutClient />` — `checkout/checkout-client`
+
+- **Purpose** — the assembled single-page checkout layout over the hook +
+  every component below. Stores wanting a custom layout compose the same
+  hook + primitives instead.
+- **SDK calls** — everything the hook + summary widgets call; the host
+  fetches `listShippingOptions`/`listPaymentProviders` (+ customer, +
+  `getIntegrationsConfig().cod`) and passes them down.
+- **Props contract** — hook options + `showGiftCards?`,
+  `logoByFulfillmentOptionId?`, Stripe `appearance`/`fonts`, `onCartChange?`
+  (receives every decorated cart from summary mutations; the layout also
+  re-runs `syncPaymentAmount` on those).
+- **Mount rules** — `"use client"`; inside `CheckoutProvider`; redirect
+  server-side when `cart.completed_at` is set (the hook also flags
+  `cartIsCompleted`).
+
+### `<PaymentWrapper cart amount />` + Stripe scope — `checkout/payment-wrapper`, `checkout/stripe-wrapper`
+
+- **Purpose** — deferred-intent Stripe context: `PaymentWrapper` publishes
+  `{stripePromise, amount, currency, appearance, fonts}`;
+  `StripeElementsScope` mounts `<Elements mode:"payment">` where needed
+  (`passthrough` renders children scope-less on COD-only stores);
+  `StripeContext` boolean = "Stripe.js ready".
+- **SDK calls** — none (env: `NEXT_PUBLIC_STRIPE_KEY`; legacy env names
+  kept as fallbacks).
+- **Mount rules** — `PaymentWrapper` wraps the page ONCE with
+  `amount={optimisticTotalCents}` (cents at this Stripe boundary only);
+  `StripeElementsScope` lives INSIDE the payment section so a session
+  rotation never tears down the form/tracking tree.
+- **Settings** — Stripe integration (whether `pp_stripe` is ever listed).
+
+### `<CheckoutAddressForm />` (+ `<AddressSelect />`, `<CompanyDetails />`) — `checkout/address-form`, `checkout/address-select`, `checkout/company-details`
+
+- **Purpose** — email + delivery address (floating-label `Field`s, 3s-idle
+  pulse cue), saved-address picker, collapsible BG company-invoice fields
+  (name/VAT/MOL/address → `cart.metadata` + customer profile).
+- **SDK calls** — none directly; the hook autosaves via `updateCart` /
+  `updateMe`. Saved addresses come from `customers.getMe()` →
+  `addressesInRegion`.
+- **Props contract** — everything from the hook (`formData`,
+  `handleFormChange`, `handleFieldBlur`, `regionCountries`, `addressInput`,
+  `addressError`, `pulseFields`); `hideCountry?` for single-country stores.
+  The country field is a NATIVE select carrying the chosen country's flag,
+  and it keeps `autocomplete="country"` on purpose: a custom listbox would
+  draw a flag per row but lose browser autofill and the phone's own picker,
+  and a checkout does not trade autofill for decoration. A list of exactly
+  one country still renders as a read-only name, which is right for a store
+  that truly sells to one country and is no longer the default for everyone
+  else (0.11.0).
+- **Settings** — Admin → Settings → Markets → Regions, read through
+  `GET /api/store/countries`.
+
+### `<CheckoutShippingMethodList />` — `checkout/shipping-method-list`
+
+- **Purpose** — radio list of shipping options with inline carrier-picker
+  expansion, free-shipping label, optional per-carrier logos, optional
+  read-only price preview pre-address (`previewWhenAddressNotReady`).
+- **SDK calls** — renders `checkout.listShippingOptions(client, {cart_id})`
+  rows AS SERVED (rule-filtering + `checkout_method_order` are server-side).
+- **Props contract** — hook state + `econt?`/`boxnow?` picker configs
+  (detection by the STABLE `shipping_option.data.id` — `"econt-office"` /
+  `"boxnow-locker"` — never display names; `boxnow.client` carries the SDK
+  transport) + `logoByFulfillmentOptionId?`.
+- **Settings** — checkout rules (`target_type=shipping_option`), method
+  ordering, carrier integrations (which options exist at all).
+
+### `<EcontOfficeSelector />` / `<BoxNowLockerSelector />` — `checkout/econt-office-selector`, `checkout/boxnow-locker-selector`
+
+- **Purpose** — Bulgarian office/locker pickers: nearest-3 by haversine
+  distance (Nominatim geocode of the typed address), city-locked search
+  with Cyrillic↔Latin normalization, selected pill + change.
+- **SDK calls** — Econt: none (public Econt Nomenclatures endpoint,
+  page-level cache). BoxNow: `integrations.listBoxNowLockers(client)`
+  ([integrations.md](integrations.md)); 503/502/network all render one
+  "temporarily unavailable" state — discover availability via
+  `carriers.boxnow.lockers_url`, don't probe.
+- **Props contract** — `{userCity, userAddress, selectedOffice|Locker,
+  onSelect}` (+ `client` for BoxNow). The CHOSEN office/locker is client
+  state; the hook writes it into `carrier_metadata` exactly once at
+  prepare (previous carrier keys are server-side swept —
+  `_prepared_carrier_keys`).
+- **Settings** — the carrier integrations (enabled/lockers).
+
+### `<CheckoutPaymentMethodList />` + `<PaymentButton />` — `checkout/payment-method-list`, `checkout/payment-button`
+
+- **Purpose** — pay-online vs cash-on-delivery radio rail. The online tab
+  hosts Stripe `<PaymentElement layout:"accordion">` (every
+  Dashboard-enabled method, no per-method code; deliberately NO
+  `fields.billingDetails.address` override — the strict-completeness
+  IntegrationError fix). `PaymentButton` = the Buy button: re-entry-guarded
+  click → `performBuyClick`, cycling processing narration, translated
+  inline errors, Price total.
+- **SDK calls** — renders `checkout.listPaymentProviders` results via the
+  hook's `hasCard`/`hasCod`; the click path runs the hook's calls.
+- **Props contract** — hook state + `buyButtonNotReady(Reason?)`,
+  `gatePaymentUntilDelivery?` (false = always-visible payment section),
+  `beforePaymentButton?` slot, `total` (pass `optimisticTotal`),
+  `logError?`.
+- **Settings** — COD integration (`labels.codNote` + fee timing), Stripe
+  credentials, checkout rules (`target_type=payment_method`) — hidden
+  methods are also re-enforced at complete (`checkout_method_hidden`).
+
+### `<OrderSummary />` (+ `CheckoutLineItem`, `<LineItemCard />`) — `checkout/order-summary`, `checkout/line-item-card`
+
+- **Purpose** — items (flat rows with qty pill), promo + gift-card
+  widgets, totals breakdown (subtotal / shipping / COD fee / discount /
+  VAT / total + gift-card tender rows UNDER the unchanged total), secure
+  badge. `LineItemCard` is the standalone card variant.
+- **SDK calls** — `carts.updateLineItem` (quantity); child widgets below.
+  Totals are rendered STRAIGHT from the cart decoration: `item_total`,
+  `shipping_total`, `payment_method_fee_total`/`payment_method_fee_label`, `discount_total`,
+  `tax_total`, `total`, `gift_card_total`, `gift_card_remainder`.
+- **Props contract** — `{client, cart, optimisticShippingCost,
+  onOptimisticShippingClear?, optimisticCodFee?, onOptimisticCodFeeClear?,
+  methodFeeLabel?, showGiftCards?, onCartChange?}`. Optimistic values clear
+  automatically once the server cart catches up.
+- **Settings** — COD integration (fee row), gift cards, promotions.
+
+### `<DiscountSection />` — `checkout/discount-section`
+
+- **Purpose** — collapsible promo-code input + applied-promotion list
+  (percentage or fixed amount display).
+- **SDK calls** — `POST /api/store/carts/:id/promotions {promo_codes}`
+  via the client transport (additive apply; the carts SDK module ships no
+  wrapper for this route yet — see [carts.md](carts.md) for the cart
+  shape; `cart.promotions` arrives as the `{promotion:{…}}` pivot embed,
+  unwrapped here).
+- **Props contract** — `{client, cart, onCartChange?}`. Errors code-first
+  via `promotion-error-copy` (`promotion_not_found`/`promotion_inactive`/…
+  + the no-email campaign-budget heuristic).
+- **Settings** — promotions admin (codes, status, application method).
+
+### `<GiftCardSection />` — `checkout/gift-card-section`
+
+- **Purpose** — gift-card code input + applied-cards chips (masked
+  `••••last4`, per-card live coverage, remove). Cartbase-new — no legacy
+  equivalent.
+- **SDK calls** — `giftCards.applyGiftCard` / `giftCards.removeGiftCard`
+  ([gift-cards.md](gift-cards.md)). Renders `cart.gift_cards[]` /
+  `gift_card_total` / `gift_card_remainder` — server truth, no client
+  math; totals never move (tender, not discount).
+- **Props contract** — `{client, cart, onCartChange?}`. Error copy honors
+  the anti-oracle contract: ONE generic message for `invalid_gift_card`
+  (never branch on reasons the API hides), `rate_limited` for burned
+  windows. After apply/remove the host must `syncPaymentAmount` (the
+  CheckoutClient wiring does).
+- **Settings** — gift-cards admin (issue/disable, expiry, balances).
+
+### Error-copy maps — `checkout/payment-error-copy`, `checkout/address-error-copy`, `checkout/promotion-error-copy`
+
+- **Purpose** — every raw failure → actionable Bulgarian copy, CODE-FIRST
+  against the Cartbase error envelope (`StoreApiError.code`), then the
+  production substring layers (Stripe.js browser errors carry no Cartbase
+  code), then a clean per-context generic. `PAYMENT_ERROR_CODE_COPY`
+  covers EVERY documented code of complete/prepare/sync/refresh —
+  `checkout_method_hidden`, `account_required`,
+  `gift_card_insufficient_balance`, the 402 payment family, …
+  (unit-gated by `tests/unit/storefront-checkout.test.ts`).
+- **SDK calls** — none (pure).
+- **Mount rules** — call `translatePaymentError(err, "card"|"cod")` /
+  `translateAddressError(err)` / `translatePromotionError(err,
+  {hasEmail})` / `translateGiftCardError(err)` at the display boundary;
+  never show `err.message` raw.
+
+Also in the family barrel: `compareAddresses` (saved-address match
+detection) and the `geocode` helpers (`normalizeForMatch`,
+`distanceMeters`, `formatDistance`, `cleanAddress`, `geocodeAddress`) —
+extra modules beyond the per-file exports, imported from
+`@cartbase/storefront/checkout`.
+
+---
+
+## Family: cart-drawer (`@cartbase/storefront/cart-drawer/*`)
+Sliding cart UI, production-proven layout. All
+components are `"use client"`. Money is EUR decimal major units everywhere
+(cart totals are SERVER truth from the decorated cart — components render,
+never compute; the only client arithmetic is the optimistic
+`unit_price × quantity` preview that the next server snapshot replaces).
+Domain doc for every call: [carts.md](carts.md); gift-card tender:
+[gift-cards.md](gift-cards.md); cross-sell sources: [products.md](products.md)
++ [search.md](search.md).
+
+### `<CartDrawerProvider client cart onCartChange … />` — `cart-drawer/context`
+
+- **Purpose** — the family's root: open/close state, the optimistic cart
+  snapshot (React 19 `useOptimistic`), labels + hrefs, and the SDK-wired
+  mutations every child uses. Auto-opens when the product-line item count
+  rises **from a nonzero base** (the guard that keeps the late-arriving
+  initial cart snapshot from opening the drawer on page load — so the very
+  FIRST add does not auto-open; open explicitly via `useCartDrawer().open`
+  / the header `CartButtonClient`, or wire `ProductActions`' `openCart`
+  seam in a client composition). Locks body scroll while open, closes on
+  Escape.
+- **SDK calls** — `@cartbase/storefront/api/carts`: `createCart` (first
+  `addItem` with no cart — `region_id` falls back to the store default),
+  `retrieveCart` (mount in `client`+`cartId` mode, and `refresh()`),
+  `addLineItem`, `updateLineItem` (body `{quantity}` ONLY — Cartbase accepts
+  no metadata on update; quantity 0 deletes), `deleteLineItem`. Every
+  mutation returns the FULL decorated cart, which becomes the confirmed
+  snapshot — no page refetch needed.
+- **Props contract** — `cart?: Cart|null` (server-fetched snapshot; prop
+  updates win), `client?: StorefrontClient` (enables `addItem`/
+  `updateQuantity`/`removeItem`/`refresh`), `cartId?` (retrieve-on-mount
+  when no snapshot), `onCartChange?(cart)` (fires on every confirmed
+  change INCLUDING first-add cart creation — persist `cart.id` here),
+  `onOptimisticError?(failure)` (the ops funnel for every failed
+  optimistic mutation — wire to store logging; replaces the source's
+  `logEvent` backend call), `labels?: Partial<CartDrawerLabels>` (overrides:
+  the language mounted by `StorefrontLocaleProvider` is the default),
+  `hrefs?: {checkout, browse, productPrefix}`.
+- **Hook** — `useCartDrawer()` → `{isOpen, open, close, toggle, cart,
+  addItem(variantId, qty?, display?), updateQuantity(lineId, qty),
+  removeItem(lineId), refresh, applyOptimistic, dispatchOptimistic,
+  labels, hrefs}`. `applyOptimistic(action, serverAction)` stays for
+  store-owned server actions (PDP add via RSC).
+- **Settings** — store default region + enabled currencies (cart create),
+  B2B price lists via attached customer, gift-card product flags
+  (`is_giftcard` lines are non-discountable), automatic promotions,
+  COD-fee integration (injects the fee line the drawer hides).
+- **Mount rules** — wrap the root layout; ONE provider per app. i18n: mount
+  `StorefrontLocaleProvider` above it and the drawer speaks the pack with
+  nothing handed over (since 2026-09-14); `labels` overrides single keys
+  (`cart-drawer/labels` holds the English defaults).
+
+### `<CartDrawer sidebar children />` — `cart-drawer/cart-drawer`
+
+- **Purpose** — the slide-out shell: overlay + right panel (`z-[60]`/
+  `z-[61]` — the consent banner sits above at `z-[70]`), optional desktop
+  left sidebar slot for cross-sell. No SDK calls.
+- **Mount rules** — render once, inside the provider; put drawer body
+  components in `children`. `panelClassName` composes onto the panel.
+
+### `<CartDrawerHeader />` — `cart-drawer/header`
+
+- **Purpose** — title + item-count badge + close button. Counts PRODUCT
+  lines via `productItemCount` (`lib/cart-helpers`) so a backend-injected
+  COD-fee line never inflates the count. No SDK calls (context cart).
+
+### `<CartPromoBanner message variant />` — `cart-drawer/promo-banner`
+
+- **Purpose** — top strip message (`info|success|warning`). Pure props.
+
+### `<CartTieredProgress tiers currencyCode />` — `cart-drawer/tiered-progress`
+
+- **Purpose** — progress bar to the next shipping/discount tier with
+  checkpoint markers. Reads `cart.total` (tax-inclusive server truth).
+- **Props contract** — `tiers: CartTier[]` sorted ascending;
+  `threshold` in EUR major units (50 = €50). Pure math exported as
+  `computeTierProgress(amount, tiers)` (unit-tested).
+
+### `<CartItem item currencyCode>{upsell?}</CartItem>` — `cart-drawer/item`
+
+- **Purpose** — one line row: thumbnail, title link, variant, quantity
+  stepper, per-line price with strikethrough (server `total` <
+  `original_total`), remove button (optimistic, via the provider's
+  `removeItem` → `DELETE line-items/:id`).
+- **Props contract** — `item: CartLineItem` (the SDK's decorated line —
+  per-line totals are server-computed), `currencyCode`, `children` =
+  per-item upsell slot.
+- Subcomponents: `item/quantity` (`<CartItemQuantity lineId quantity
+  maxQuantity? />` — stepper floor 1, calls `updateQuantity` with
+  `{quantity}`), `item/variant` (`<CartItemVariant variantTitle
+  options? />` — Cartbase lines carry the flat `variant_title` string, not
+  an embedded variant object), `item/upsell` (`<CartItemUpsell products
+  onAdd />` — feed from `listRelatedProducts`, `variantId` included so
+  `onAdd` can call `addItem`).
+
+### `<CartFreeGift … />`, `<CartGiftWrap … />`, `<CartNotes … />`, `<CartRewardsPoints … />`
+
+- Merchandising slots (`cart-drawer/free-gift`, `gift-wrap`, `notes`,
+  `rewards-points`) — pure props + labels; prices EUR major units. The
+  store owns the effects: `CartGiftWrap.onToggle` → add/remove the store's
+  gift-wrap variant via `addItem`/`removeItem`; `CartNotes.onSave` →
+  `updateCart(client, cartId, {metadata: {...cart.metadata, gift_note}})`
+  — the update route REPLACES metadata wholesale (no merge), so always
+  spread the current `cart.metadata`; cart metadata is copied onto the
+  order at complete. No admin settings — configured per store in code.
+
+### `<CartCrossSellSidebar / CartCrossSellCarousel products onAdd label? />` — `cart-drawer/cross-sell-*`
+
+- **Purpose** — desktop sidebar card list / horizontal strip of
+  recommendations.
+- **SDK calls** — feed `products` from `api/products.listProducts`
+  (curated collection/tag) or `api/search.listRelatedProducts` (anchor
+  complements — manual admin picks first, deterministic fallback fills;
+  see [search.md](search.md)). Map responses with `toCrossSellProduct`
+  (exported from `cart-drawer/cross-sell-sidebar`; picks the first variant
+  with a server-computed `calculated_price`, returns null unpriced — pass
+  `currency_code` on the listing call). Wire `onAdd(productId, variantId)`
+  → `addItem(variantId)`.
+- **Settings** — Admin → Product → Related (manual picks); price lists
+  (what `calculated_price` contains); publishable-key channel scope.
+
+### `<CartSummaryBreakdown />` — `cart-drawer/summary-breakdown`
+
+- **Purpose** — full totals breakdown rendered EXACTLY from the decorated
+  cart: `subtotal`, `discount_total` (>0, negated for display),
+  `shipping_total` (once a shipping method is set; 0 renders FREE; before
+  that "calculated at checkout"), `tax_total` (>0), `payment_method_fee_total` (>0,
+  labeled by the server's `payment_method_fee_label`), `total`, then one row per
+  applied gift card (masked `last4`, negated; a depleted card stays listed
+  at 0) and `gift_card_remainder` — what the remainder provider charges.
+  Row selection is the pure `selectSummaryRows(cart)` (unit-tested).
+- **SDK calls** — none directly (context cart; every cart read re-derives
+  gift-card tender from the live ledger).
+- **Settings** — COD integration (fee + label), promotions, gift cards.
+
+### `<CartStickyFooter />` — `cart-drawer/sticky-footer`
+
+- **Purpose** — pre-checkout subtotal + checkout CTA. Deliberately shows
+  `productTotal(cart.items)` (product lines only) — NOT `cart.total`,
+  which carries shipping/tax/COD checkout-context state that must not
+  leak into the shopping drawer. Navigates to `hrefs.checkout`.
+
+### `<CartPaymentBadges methods? badges? />`, `<CartContinueShopping />`, `<CartEmpty />`
+
+- `payment-badges` — inline SVG payment logos (visa/mastercard/googlepay/
+  applepay/amex), overridable per store. `continue-shopping` — close link.
+  `empty` — empty state with `hrefs.browse` CTA. Pure props + labels.
+
+### `<CartDrawerTemplate config />` — `cart-drawer/template`
+
+- **Purpose** — the optional default assembly; every
+  feature opt-in via `CartDrawerConfig`. Stores wanting a different layout
+  compose the primitives themselves inside `<CartDrawer>`.
+- **Props contract** — `config`: `promoBanner`, `shippingTiers`
+  (EUR thresholds), `freeGift` (`minCartTotal` EUR), `giftWrap`,
+  `notes`, `rewards` (`pointsPerCurrency` = points per 1 EUR —
+  major-unit port change from the source's per-cent rate), `crossSell`
+  (`products` or async `loader` — fires once when the drawer first has
+  items; build it from the SDK + `toCrossSellProduct`). Cross-sell adds
+  are wired to the provider's `addItem` automatically.
+- **Mount rules** — renders product lines only (`isProductLine`) — a
+  fee-only cart renders as empty rather than a fake product row.
+
+---
+
+## Family: products (`@cartbase/storefront/products/*`)
+The PDP + product-card family, production-proven. All prices
+render the SERVER-computed `variant.calculated_price` via
+`lib/get-product-price` (Cartbase's flat `price_list_type` wire shape) — no
+component computes money. Product data is the canonical `StoreProduct`
+(`@cartbase/storefront/api/products`) every discovery endpoint serves.
+
+**Labels / i18n** — `products/labels` (`ProductLabels` + English defaults),
+and a pack from `locales/*` for any other language,
+`products/context` (`<ProductLabelsProvider labels>` + `useProductLabels()`;
+components read copy only through the context or explicit `labels` props).
+
+### `<ProductLabelsProvider labels />` — `products/context`
+
+- **SDK calls** — none. **Settings** — none.
+- **Mount rules** — client component; wrap the product page (or app) once;
+  partial `labels` merge over English defaults.
+
+### `<Thumbnail thumbnail images size isFeatured />` — `products/thumbnail`
+
+- **Purpose** — the product image tile used by cards; `ImageOff` fallback
+  when no image exists.
+- **SDK calls** — none (props: `product.thumbnail` / `product.images`).
+- **Props** — `size: "small"|"medium"|"large"|"full"|"square"` (aspect +
+  width), `isFeatured` (11/14 aspect), `className`.
+- **Mount rules** — server-safe; uses `next/image` (host must allow the
+  media domain in `next.config` images).
+
+### `<PreviewPrice price />` — `products/preview-price`
+
+- **Purpose** — card price line; strikethrough original + accent price when
+  `price_type === "sale"`.
+- **SDK calls** — none; takes a `VariantPrice` from
+  `lib/get-product-price` `getProductPrice(...).cheapestPrice`.
+- **Settings** — price lists (whether a `sale` type ever appears).
+
+### `<ProductPrice product variant? />` — `products/product-price`
+
+- **Purpose** — PDP price panel: "From <cheapest>" until a variant is
+  selected, then the variant price; sale shows original + percentage off.
+- **SDK calls** — none directly; the product must have been fetched WITH a
+  pricing context (`currency_code`/`region_id`) or it renders the loading
+  shimmer (no `calculated_price` → no price, by design).
+- **Settings** — price lists / B2B groups (via the Bearer JWT on the fetch),
+  region/currency context.
+- **Mount rules** — client; reads labels from context.
+
+### `<OptionSelect option current updateOption title disabled />` — `products/option-select`
+
+- **Purpose** — one option row of value buttons (`product.options[]`, which
+  carries `values[]`).
+- **SDK calls** — none. **Mount rules** — client; controlled by the parent.
+
+### The product page contract — `products/variant-url`, `products/use-product-actions`
+
+Five rules every buy panel is held to, the package's own and a store's:
+
+1. **The address is the state.** The chosen variant is named in the URL as
+   `?variant=<id>`, Shopify's parameter, so a link copied from an email, an
+   ad or a chat opens on the variant it was copied from and a refresh never
+   forgets a choice. The value is the id's DIGITS (`pvar_1000683784068`
+   travels as `1000683784068`), the platform's law for every id in a URL;
+   reading accepts the whole key too.
+2. **The first paint is right.** The page reads `searchParams.variant` on the
+   server and passes it down (`initialVariantId` on `ProductTemplate`,
+   `ProductActions` or the hook), so the server renders that variant's
+   price, code and stock and nothing flashes.
+3. **A switch is a browser event.** The address is rewritten with the
+   browser's own history call, which Next's router picks up; no server render
+   runs. (Going through the router made every click a navigation: the address
+   lagged a whole render behind the click and a fast second click left it on
+   the first variant.)
+4. **The default is the merchant's.** With no variant in the address, the
+   variant made of each option's FIRST value is chosen, in the option order
+   the admin shows; never the wire's first variant, which is the database's
+   scan order.
+5. **The server is asked only for what needs it:** adding to the cart.
+
+`products/variant-url` is the pure half (`VARIANT_PARAM`,
+`variantParamValue`, `findVariantByParam`, `defaultVariant`, `variantHref`;
+unit-tested in tests/unit/storefront-product-page-contract.test.ts).
+`useProductActions({product, addToCart, initialVariantId?, onAddToCart?,
+openCart?, syncAddress?})` is the behaviour as a headless hook: the chosen
+values, `choose`, the resolved `variant`, `quantity`/`setQuantity`,
+`inStock` (the server's `in_stock` predicate, never re-derived;
+`insufficient_inventory` on add flips it until the choice changes),
+`price`, `add`. A store that wants its own look draws its own panel on the
+hook and inherits every rule; `ProductActions` below is the package's own
+panel on the same hook. Client hook; it reads `useSearchParams`, so mount it
+under a `<Suspense>` boundary on a static page (a dynamic page needs none).
+
+### Pure: `products/variant-matching` (extra module, Cartbase addition)
+
+`optionsAsKeymap` / `optionsMatch` / `findMatchingVariant` — the
+option-choice → variant resolution extracted from product-actions, reading
+Cartbase's option-value LINK shape (`variant.options[].value.{option_id,value}`)
+with a legacy flat-row fallback. Unit-tested
+(tests/unit/storefront-catalog.test.ts).
+
+### `<ImageGallery images />` — `products/image-gallery`
+
+- **Purpose** — stacked PDP gallery in the merchant's order (the store API
+  serves every product's images by rank since 2026-09-15); first three
+  images `priority`.
+- **SDK calls** — none (props: `product.images`). Server-safe.
+
+### `<ProductActions product addToCart initialVariantId? disabled? onAddToCart? openCart? showQuantity? />` — `products/product-actions`
+
+- **Purpose** — the package's own buy panel on `useProductActions`: option
+  rows, price, the quantity stepper (`showQuantity`, on by default), the
+  add button, the mobile bar. Every rule of the product page contract above
+  is the hook's; this is only the markup.
+- **SDK calls** — none itself; the injected `addToCart({variantId,
+  quantity})` seam is the host's cart orchestration (typically `api/carts`
+  `addLineItem` + the host's cart-id cookie). `openCart` replaces the
+  legacy cart-drawer context import (no hard cross-family dependency).
+- **Stock contract** — the variant's `in_stock` is THE availability
+  predicate, computed by the server on every product read and only read
+  here; the SERVER still enforces at add (400 `insufficient_inventory`,
+  which flips the button to the out-of-stock state until the choice
+  changes).
+- **Settings** — inventory (manage/backorder flags, kit components at add),
+  price lists, promotions (server re-applies on add).
+- **Mount rules** — client; needs `ProductLabelsProvider` for non-English.
+  Fire the tracking trio (`trackAddToCart`/GA4/Rybbit) from `onAddToCart`.
+
+### `<MobileActions … />` — `products/mobile-actions`
+
+- **Purpose** — the `lg:hidden` sticky bottom bar + options bottom sheet
+  (z-[75], above the cart drawer's z-[60]) shown when the desktop actions
+  scroll out of view.
+- **SDK calls** — none; pure props from `ProductActions` (which mounts it —
+  rarely used directly).
+
+### `<ProductTabs product />` — `products/product-tabs`
+
+- **Purpose** — accordion: product information (material, origin, type,
+  weight, dimensions) + static shipping/returns copy from labels.
+- **SDK calls** — none. **Settings** — none (copy via labels).
+
+### `<ProductInfo product />` — `products/product-info`
+
+- **Purpose** — collection link (`/collections/<handle>`), title,
+  description. **SDK calls** — none. Server-safe.
+
+### `<ProductPreview product isFeatured? />` — `products/product-preview`
+
+- **Purpose** — THE product card (links `/products/<handle>`): thumbnail +
+  title + cheapest price. Reused by store grids, search results, related
+  strip; every template accepts `renderProduct` to swap it for a custom
+  card.
+- **SDK calls** — none; expects a `StoreProduct` fetched with pricing
+  context for the price line. Server-safe.
+
+### `<RelatedProducts client product labels pricingContext? limit? renderProduct? />` — `products/related-products`
+
+- **Purpose** — the "You might also like" strip.
+- **SDK calls** — `api/search` `listRelatedProducts(product.id)` — manual
+  admin picks first, deterministic fallback fills to `limit`
+  (`auto_filled`); anchor never appears. Renders nothing on empty/404.
+- **Labels** — `labels: ProductLabels`, REQUIRED: a server component cannot
+  read the provider, so pass `STORE_LOCALE.products`; `ProductTemplate`
+  passes its own through.
+- **Settings** — Admin → Product → Related (manual picks), price lists.
+- **Mount rules** — async server component; render inside `<Suspense>`.
+
+### `<ProductActionsWrapper client id pricingContext? initialVariantId? addToCart … />` — `products/product-actions-wrapper`
+
+- **Purpose** — re-fetches the product with the LIVE pricing context (and
+  the client's Bearer JWT → group-aware B2B prices) and mounts
+  `ProductActions`; the PDP shell stays cacheable.
+- **SDK calls** — `api/products` `retrieveProduct(idOrHandle,
+  pricingContext)`; 404 → renders nothing.
+- **Mount rules** — async server component inside `<Suspense>` (fallback:
+  disabled `<ProductActions>`).
+
+### `<ProductTemplate client product labels addToCart initialVariantId? renderProduct? pricingContext? onAddToCart? openCart? promises? hideSpecs? sections? />` — `products/product-template`
+
+- **Purpose** — the full PDP: sticky info column (`ProductInfo` +
+  `ProductTabs`), gallery, sticky actions column (suspended
+  `ProductActionsWrapper`), related strip. `initialVariantId` is the
+  address's variant (`searchParams.variant`, rule 2 of the contract);
+  `renderProduct` is the store's card for the related strip, so a store
+  with its own card no longer draws the library's preview on one page.
+- **SDK calls** — via children (retrieveProduct, listRelatedProducts). The
+  page fetches the product by handle (`retrieveProduct`) and passes it in.
+- **Settings** — union of children's.
+- **Mount rules** — server component; `labels` is REQUIRED (the pack's
+  `products` area) because the related strip renders on the server; the
+  client parts inside read `ProductLabelsProvider`, which
+  `StorefrontLocaleProvider` mounts; `addToCart`/`openCart` seams as on
+  `ProductActions`.
+
+## Family: store (`@cartbase/storefront/store/*`)
+The listing family: paginated grids, sort, collection/category/search
+templates. Sorting discipline: the API's `order` param is the authority for
+paginated listings; client-side re-sort (`lib/sort-products`) exists ONLY
+for the price sorts on the plain products listing (price is not a products
+column) over the legacy 100-item window.
+
+**Labels / i18n** — `store/labels` (`StoreLabels` + defaults + the pure
+`sortOptionLabelKeys` map — completeness unit-tested) and `locale.store`
+from a pack. Templates take `labels: StoreLabels`, REQUIRED: they are
+server components and cannot read the provider, so a page hands them
+`STORE_LOCALE.store` (`en.store` for an English store).
+
+### `<Pagination page totalPages />` — `store/pagination`
+
+- **Purpose** — windowed page-number pagination; writes the `page` query
+  param and pushes the route (server re-renders with the new offset).
+- **SDK calls** — none. **Mount rules** — client.
+
+### `<SortSelect sortBy? labels? />` — `store/sort-select`
+
+- **Purpose** — sort sidebar; writes the `sortBy` query param
+  (`created_at` | `price_asc` | `price_desc`, rendered from
+  `sortOptionLabelKeys`).
+- **Props** — `sortBy` OPTIONAL (port adaptation): on collection pages no
+  selection = the collection's admin `default_sort`, nothing highlighted.
+- **SDK calls** — none. **Mount rules** — client.
+
+### `<PaginatedProducts client page sortBy? collectionId? categoryId? productsIds? pricingContext? renderProduct? />` — `store/paginated-products`
+
+- **Purpose** — the 12-per-page product grid + pagination over the plain
+  products listing.
+- **SDK calls** — `api/products` `listProducts`: `created_at` →
+  server `order:"-created_at"` + real offset pagination; `price_asc`/
+  `price_desc` → 100-item window fetch, `lib/sort-products` re-sort, slice
+  (the proven production approach — see module JSDoc for the >100 caveat).
+- **Props note** — `collectionId` filters by collection MEMBERSHIP since
+  2026-09-15 (a product in three collections is listed under all three); the
+  collection's own ordered page lives in `CollectionTemplate`.
+- **Settings** — price lists (pricing context), sales-channel/publishable-
+  key scope on the client.
+- **Mount rules** — async server component; render inside `<Suspense>`
+  with `<SkeletonProductGrid />`.
+
+### `<SkeletonProductGrid numberOfProducts? />` — `store/skeleton-product-grid`
+
+- **Purpose** — pulse skeleton for any product grid. Server-safe, no calls.
+
+### `<StoreTemplate client labels sortBy? page? pricingContext? renderProduct? />` — `store/store-template`
+
+- **Purpose** — the `/store` all-products page: sort sidebar + heading +
+  suspended `PaginatedProducts`.
+- **SDK calls** — via `PaginatedProducts`. Pass the page's `sortBy`/`page`
+  query params straight in.
+
+### `<CollectionTemplate client collection labels sortBy? page? pricingContext? renderProduct? />` — `store/collection-template`
+
+- **Purpose** — collection page over the MEMBERSHIP listing (multi-
+  collection products appear in every collection).
+- **SDK calls** — `api/collections` `listCollectionProducts(collection.id)`
+  — the admin `default_sort` is honored SERVER-side when `sortBy` is unset
+  (no client re-sort, port adaptation); a shopper override maps
+  `created_at→newest`, `price_asc`, `price_desc` to the `order` param
+  (price sorting server-side here, unlike the plain listing). Fetch the
+  collection itself via `listCollections({handle})` in the page.
+- **Settings** — collection `default_sort` + manual order, smart-collection
+  conditions, channel links (scoped-away collection 404s), price lists.
+- **Mount rules** — server component; grid suspends internally.
+
+### `<CategoryTemplate client category labels sortBy? page? pricingContext? renderProduct? />` — `store/category-template`
+
+- **Purpose** — category page: breadcrumbs (ancestor chain), description,
+  child-category links, `PaginatedProducts` filtered by `category_id`.
+- **SDK calls** — via `PaginatedProducts`. Fetch the category in the page
+  with `retrieveCategory(id, {include_ancestors_tree: true,
+  include_descendants_tree: true})` — without the flags the breadcrumb and
+  children sections don't render.
+- **Settings** — category tree (active/internal flags are server-filtered).
+
+### `<SearchTemplate client searchParams labels basePath? pricingContext? limit? renderProduct? />` — `store/search-template`
+
+- **Purpose** — the search results page in the
+  store-template idiom — GET query box, facet sidebar from the response
+  `facets[]`, result grid (reuses the product card), pagination. Fully
+  URL-state driven: works server-rendered with zero own client JS.
+- **SDK calls** — `api/search` `searchProducts` (only when `q` present).
+  Facet buckets toggle by rewriting the wire-named query params
+  (`collection_id`/`type_id`/`tag_id` CSV, `price_min`/`price_max`,
+  `availability`, `option.<Title>` CSV) via the pure `store/search-params`
+  helpers (round-trip unit-tested); every toggle resets `page`.
+- **Settings** — Search & discovery: synonyms, pins/boosts, facet config
+  (order/enabled, price bucket strategy `auto`/`fixed`); price facet
+  currency follows the pricing context.
+- **Mount rules** — async server component; pass the route's raw
+  `searchParams`; `basePath` defaults to `/search`.
+
+### Pure: `store/search-params` (extra module, Cartbase addition)
+
+`parseSearchParams` / `buildSearchQueryString` / `fromQueryString` /
+`toggleFacetSelection` / `isFacetSelected` / `clearFilters` /
+`toSearchQuery` — the search page's URL-state machine, exported for custom
+search UIs (chips, drawers) that want the same URL contract.
+
+---
+
+## Family: order (`@cartbase/storefront/order/*`)
+Order confirmation + account order views, production-proven. Some
+platforms ship ONE `StoreOrder` object carrying computed line
+totals, order totals, shipping methods and payments; Cartbase splits those
+across surfaces, so the family takes them as separate props — the Cartbase
+`StoreOrderDetail` (`api/orders`) carries items as version-pivot rows
+(`{quantity, line_item}`), fulfillments with tracking labels, and both
+addresses, while MONEY comes from the decorated cart (`api/carts` `Cart`)
+or the order summary snapshot. Components render server truths; the only
+arithmetic is the two documented production subtractions in the totals
+selector.
+
+Labels: `OrderLabelsProvider`/`useOrderLabels` (`order/context`) +
+`defaultOrderLabels` (`order/labels`, English) + `locale.order` from a
+pack in `locales/*` for any other language. Every
+component also takes a `labels` prop pick, and the template's is REQUIRED
+(`labels: OrderLabels`): it renders on the server, where no provider
+reaches, so the page passes `STORE_LOCALE.order`.
+
+### `<OrderCompletedTemplate order totals labels items? shippingMethod? paymentProviderId? cardLast4? … />` — `order/order-completed-template`
+
+- **Purpose** — the full confirmation page: hero header, fulfillment
+  timeline, items+totals card, contact/delivery/payment/help cards,
+  continue-shopping CTA.
+- **SDK calls** — none itself; feed it: `order` (`retrieveOrder` /
+  `retrieveOrderByDisplayId` detail, or the `completeCart()` response),
+  `totals` (the decorated cart from checkout, or
+  `orderTotalsFromSummary(completeCart().order.summary)`), optional
+  normalized `items` (prefer `displayItemFromCartLine` right after
+  checkout — keeps server-computed per-line discounts), `shippingMethod` /
+  `paymentProviderId` / `cardLast4` from checkout state.
+- **Mount rules** — order-confirmation route (server component OK; only
+  the timeline child is client). The Purchase tracking trio (fbq/gtag/
+  rybbit, deduped by `order.display_id`) is APP-OWNED: fire it from the
+  confirmation route exactly once per order per the tracking family's
+  dedupe contract — the template deliberately does NOT fire it.
+- **Settings** — COD settings (fee row presence + `payment_method_fee_label`),
+  checkout rules (which provider ids appear), store locales (labels pack).
+
+### `<OrderConfirmationHeader order />` — `order/order-confirmation-header`
+
+- **Purpose** — check hero + "Order #display_id" + localized date chips.
+- **Props** — structural `OrderHeaderData` (`display_id`, `email`,
+  `created_at`) — order detail and `completeCart().order` both satisfy it.
+  `locale` drives `toLocaleDateString`.
+
+### `<OrderItemsList items currencyCode />` + `<OrderItem item currencyCode />` — `order/order-items-list`, `order/order-item`
+
+- **Purpose** — the purchased lines (thumb, title, variant caption, qty,
+  line total with discount strike-through when the source had it).
+- **Data seam** — normalized `OrderDisplayItem[]` via the pure converters
+  `displayItemFromOrderItem(pivot)` (order path: `unit_price × quantity`)
+  / `displayItemFromCartLine(line)` (cart path: server `total` /
+  `original_total`). Legacy COD-fee line items
+  (`metadata.is_cod_fee=true`) are hidden here and surfaced in
+  `OrderTotals` instead (`lib/cart-helpers.isProductLine`); Cartbase-native
+  COD fees are never line items, so on pure Cartbase data the filter is a
+  no-op safety net. Newest-first sort by `createdAt` when present.
+
+### `<OrderTotals totals currencyCode items? methodFeeLabel? />` — `order/order-totals`
+
+- **Purpose** — the money breakdown: Subtotal / Shipping (FREE badge at
+  0) / COD fee / Discount (negated) / Tax / Total, all via `Price`.
+- **Data seam** — `OrderTotalsSource` (the decorated cart satisfies it:
+  `item_subtotal`, `shipping_subtotal`, `discount_total`, `tax_total`,
+  `total`, `payment_method_fee_total`, `payment_method_fee_label`); the summary snapshot adapts
+  via `orderTotalsFromSummary`. Row policy is the pure, unit-tested
+  `selectOrderTotalsRows`: native `payment_method_fee_total` wins over a legacy fee
+  LINE; a legacy fee line's net is subtracted from the visible subtotal
+  (v2.3.1 production fix); COD label preference `methodFeeLabel` prop →
+  server `payment_method_fee_label` → fee-line title → `labels.paymentMethodFee`.
+- **Settings** — COD settings (`payment_method_fee_total`/`payment_method_fee_label`),
+  promotions (discount row).
+
+### `<OrderAddressCard order />` — `order/order-address-card`
+
+- Contact info card: shipping-address name + phone + order email.
+  Structural `OrderContactData` — the order detail satisfies it.
+
+### `<OrderDeliveryCard order shippingMethod? currencyCode />` — `order/order-delivery-card`
+
+- **Purpose** — pickup point (Econt office metadata / stable
+  fulfillment-option ids `econt-office`, `boxnow-locker` — id beats name
+  parsing, production fix) or shipping address, the method row with
+  price/FREE, and — Cartbase addition — the fulfillment tracking labels.
+- **Data seam** — `order.metadata` + `order.shipping_address` +
+  `order.fulfillments` from the detail; `shippingMethod` (structural,
+  `CartShippingMethod` fits) from checkout state since the Cartbase order
+  read has no shipping-method embed. Tracking rows come from the pure,
+  unit-tested `pickTrackingLabels(order.fulfillments)` — skips canceled
+  fulfillments, drops number-less labels, dedupes re-prints.
+- **Settings** — carrier integrations (whether labels/urls exist),
+  shipping options (ids/names).
+
+### `<OrderPaymentCard providerId cardLast4? />` — `order/order-payment-card`
+
+- Payment method card; `resolvePaymentTitle(providerId, titles,
+  methodName?)` — the method's merchant NAME wins verbatim when present
+  (the snapshot from session data); otherwise the processor id buckets
+  via `lib/payment-constants` (`pp_stripe` = card) through the locale
+  pack, falling back to `paymentInfoMap` then the raw id. Payment
+  internals never cross the Cartbase store surface — both arrive via
+  props from checkout state.
+
+### `<OrderTimeline fulfillmentStatus? />` — `order/order-timeline`
+
+- Placed → Processing → Shipped → Delivered progress (client, animated).
+  Cartbase has no `fulfillment_status` column on the store surface —
+  derive it with the pure, unit-tested
+  `deriveFulfillmentStatus(order.fulfillments)` (packed_at/shipped_at/
+  delivered_at ladder, `partially_*` when only some active fulfillments
+  reached a stage, canceled ignored).
+
+### `<OrderHelpSection contactHref? returnsHref? />` — `order/order-help-section`
+
+- "Need help?" links card (contact + returns). No SDK calls, no settings.
+
+---
+
+## Family: common (`@cartbase/storefront/common/*`)
+Shared storefront chrome, production-proven.
+
+### `<LocalizedLink href … />` — `common/localized-link`
+
+- `next/link` that persists the URL locale/country segment when the route
+  has one (`[countryCode]` param by default, `paramName` overridable);
+  plain link on cookie-locale apps (the Cartbase default). Client.
+
+### `<CartButton client cartId? />` + `<CartButtonClient cart />` — `common/cart-button`, `common/cart-button-client`
+
+- **Purpose** — header cart button: badge count + opens the cart drawer.
+- **SDK calls** — server wrapper: `api/carts.retrieveCart(client, cartId)`
+  (the app owns the cart-id cookie); fetch failure degrades to an empty
+  button. Client half takes the decorated `Cart`; badge count =
+  `productItemCount(cart.items)` (fee-line-aware, consistent with the
+  drawer).
+- **Mount rules** — `CartButtonClient` must sit inside the cart-drawer
+  family's `<CartDrawerProvider>` (it calls `useCartDrawer().open`).
+
+### `<DeleteButton client cartId id onDeleted? />` — `common/delete-button`
+
+- Cart-line remove with spinner. Calls
+  `api/carts.deleteLineItem(client, cartId, id)` (idempotent) and hands
+  the refreshed `{cart}` to `onDeleted`; spinner resets on failure.
+
+### `<MarketSelect regions value? onChange />` — `common/market-select`
+
+- **Purpose** — the market picker for a header or footer: the store's
+  REGIONS (`api/regions.listRegions`) by name, valued by region id;
+  persistence is app-owned via `onChange` (usually
+  `carts.updateCart(client, cartId, {region_id})` + a cookie). A country is
+  a different thing: the checkout picks one from `listCountries`, with
+  `CountryFlag` beside it.
+- **Was `CountrySelect`** (`common/country-select`) until 2026-09-14, a name
+  the port carried for a component that never listed countries here. The
+  old path and names still import for one release and then go.
+- **Settings** — Admin → Settings → Markets → Regions: which rows exist.
+
+### `<CountryFlag code title? className? />` — `common/country-flag`
+
+- **Purpose** — a country's flag from its ISO-3166 alpha-2 code, at the size
+  of the text beside it. An unknown or empty code renders a neutral box that
+  holds the same space, so a field does not jump when a shopper picks their
+  country.
+- **Why a sprite and not an emoji** — Windows ships no flag glyphs, so an
+  emoji flag reads as the two letters "BG" there. This draws `flag-icons`
+  SVG under a CSS class, which renders the same on every platform, and it is
+  the same sprite the Cartbase admin uses, so one country treatment runs
+  across the admin and the storefront.
+- **Accessibility** — decorative and `aria-hidden`: a flag never carries
+  meaning the name beside it does not. Pass `title` when it stands alone.
+
+### `<LanguageSelect locales currentLocale onChange labels? />` — `common/language-select`
+
+- **Purpose** — locale switcher. Feed `locales` from
+  `api/regions.listLocales(client)` (bare codes, store default first —
+  SDK wins over the source's `{code,name}` objects); display names via
+  `localeDisplayName()` (`Intl.DisplayNames` autonym) with per-store
+  `labels` overrides. `onChange` persists (cookie read by
+  `StorefrontClient.getLocale`) inside the preserved `useTransition`
+  pending-disable UX.
+- **Settings** — Settings → Store → locales (per-store `store_locales`).
+
+### `<Skeleton className? />` + `<SkeletonProductPreview />` — `common/skeleton`
+
+- Loading placeholders (pure UI over theme tokens).
+
+---
+
+## Family: reviews-ui (`@cartbase/storefront/reviews-ui`)
+Verified-purchase review components, ported from a production storefront,
+over `api/reviews`. ONE barrel export seam: everything imports from
+`@cartbase/storefront/reviews-ui`. Endpoint truth:
+[reviews.md](reviews.md). Labels: the family reads the language mounted by
+`StorefrontLocaleProvider` on its own (English with none, since
+2026-09-14), `labels?` on any component overrides keys, and `StarBadge`,
+the one server-safe piece, takes its labels as a prop. Strings are
+parameterized with `{n}`/`{pct}`/`{name}`/`{mb}`/`{s}`/`{email}` slots
+(resolve via `formatLabel`).
+
+### `<ReviewWidget client productId initialData? />` — the PDP section
+
+- **Purpose** — aggregate header (score badge + 5→1 distribution bars +
+  sort select) + masonry card list + load-more + lightbox. Renders null
+  at zero reviews (production rule); derives avg/distribution from the
+  loaded page if the aggregate is missing (never a misleading "0.0").
+- **SDK calls** — bootstrap: `getWidget(client, productId)` (ONE call:
+  aggregate + first page per the store's display options; edge-cached
+  60s) — server-fetch it and pass `initialData` (recommended), else the
+  widget fetches on mount. Sort changes / load-more: `listReviews`
+  (`sortParamsFor` maps the UI keys to the API `(sort, order)` tuple).
+- **Mount rules** — client component, PDP below the fold; `id="reviews"`
+  anchor built in. Verified badge is unconditional (every review is
+  token-minted — a system tautology, not a flag).
+- **Settings** — Settings → Reviews display options: `widget_layout`
+  (masonry|list), `widget_page_size`, `widget_photo_first` (all arrive
+  via `getWidget().options`); moderation decides visibility.
+- Pieces exported for custom layouts: `<StarRow>`, `<StarBadge>`,
+  `<RatingDistribution>` (`star-badge`), `<ReviewList>` +
+  `<ReviewLightbox>` (presentational cards + overlay),
+  `reviewDisplayName` (first name + surname initial — shared with any
+  app JSON-LD so UI and structured data can't drift, production fix),
+  `formatReviewDate`.
+
+### `<ReviewWizard client token validation rewardPct? supportEmail? … />` — the token page
+
+- **Purpose** — everything behind `<review_link_base>/<token>`: invalid/
+  expired panels, the terminal already-submitted panel, and the two-step
+  form (rate → photo → done) with the reward-code reveal.
+- **SDK calls** — `validateToken(client, token)` SERVER-SIDE in the page
+  (pass the result as `validation` — never flash a form on a dead
+  token; mark the route noindex), then client-side: `submitReview`
+  (step 1 — consumes the token, rating locked in even if the customer
+  bails), `createUploadUrl` → signed R2 PUT → `attachReviewPhoto`
+  (step 2 — mints the single-use reward code; `code: null` on 200 =
+  media saved, mint failed → "write to us" note, never an error).
+- **Step resolution** — the pure, unit-tested
+  `resolveWizardEntry(validation)`; THE RESUME RULE: consumed token +
+  review row + `reward_code` null → resume at photo; `reward_code` set →
+  done showing the code; consumed with no review row → terminal panel.
+  Submit errors map by status via `submitErrorKeyFor` (429/409/410).
+- **Mount rules** — `ReviewWizard` is the full page body (client);
+  `ReviewWizardForm` and `<ReviewPhotoUpload>` (drag-drop, per-file slot
+  caps ≤6 images/≤1 video, 8/50 MB, 60s video, blob-preview swap +
+  revoke) are exported for custom pages.
+- **Settings** — Settings → Reviews: `reward_enabled` /
+  `reward_percentage` (the store surface does not expose the percentage —
+  pass `rewardPct`, default 10), `moderation_mode` (`hold` lands the
+  review pending; the thanks copy stays true either way), request-scanner
+  settings decide when tokens are minted at all.