create-cartbase 0.1.20 → 0.1.22

package/template/app/docs/components.md

@@ -177,8 +177,22 @@ before anyone notices.
 | Product view | `trackProductView({ line, currency, value })` |
 | Add to cart | `trackCartAdd({ line, currency, value })` |
 | Checkout start | `trackCheckoutStart({ lines, currency, value, coupon? })` |
+| Address complete | `trackCheckoutShippingInfo({ lines, currency, value, cartId, shippingTier?, coupon? })` |
+| Tender chosen | `trackCheckoutPaymentInfo({ lines, currency, value, cartId, paymentType?, coupon? })` |
 | Order confirmed | `trackOrderPurchase(order, trackingConfig)` |
 
+**The three checkout moments fire on their own.** `useCheckoutOrchestration`
+mounts `useCheckoutFunnel`, so a checkout built on the kit reports the whole
+funnel with no wiring, and a store with its own layout gets it from the
+hook. Call the two above by hand only in a checkout that uses neither, and
+pass `trackFunnel: false` to the hook if you do, so nothing counts twice.
+
+`cartId` is not decoration: the mid-funnel steps are driven by form state
+rather than by a click, so their Meta event id is DERIVED from the cart
+(`checkoutStepEventId`, `tracking/once`). Two tabs on one cart, a restored
+session or a retried request then collapse into one event instead of three.
+Pair it with `markFiredOnce(event, cartId)` if you fire them yourself.
+
 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
@@ -202,9 +216,16 @@ race (10s cap, v2.2.6 production fix).
 | Product view | `trackViewContent` | `trackTikTokViewContent` | `trackGAViewItem` | `trackRybbitViewItem` |
 | Add to cart | `trackAddToCart` | `trackTikTokAddToCart` | `trackGAAddToCart` | `trackRybbitAddToCart` |
 | Checkout start | `trackInitiateCheckout` | `trackTikTokInitiateCheckout` | `trackGABeginCheckout` | `trackRybbitBeginCheckout` |
+| Address complete | `trackAddShippingInfo` | — | `trackGAAddShippingInfo` | `trackRybbitAddShippingInfo` |
+| Tender chosen | `trackAddPaymentInfo` | `trackTikTokAddPaymentInfo` | `trackGAAddPaymentInfo` | `trackRybbitAddPaymentInfo` |
 | Order confirmed | `trackPurchase(data, order.display_id)` | `trackTikTokPurchase({…, displayId})` | `trackGAPurchase({transaction_id: String(order.display_id), …})` | `trackRybbitPurchase` |
 | Newsletter/popup signup | `trackLead` | — | — | — |
 
+Two gaps in that table are deliberate. AddShippingInfo is not in Meta's
+standard vocabulary, so `fbq` takes it through `trackCustom`; TikTok has no
+shipping-step event at all, and a custom one there would optimise nothing
+and report nowhere.
+
 Google Ads has one event, the purchase conversion:
 `trackGoogleAdsPurchase({ sendTo, value, currency, transactionId, newCustomer? })`,
 with `sendTo` from `googleAdsPurchaseSendTo(config)` (null when the label
@@ -256,6 +277,22 @@ that fails silently and costs match rate with nothing in any log.
   `{ engagementTimeMsec: getEngagementTimeMsec() }` as clientHints, and
   either `opts.ga4MeasurementId` or `opts.client` so the `_ga_<id>` session
   cookie can be located.
+- Browser side, at the checkout: `readBrowserAttribution()` returns the same
+  flat keys from the cookies a client component can read (the Facebook
+  pair, the visitor id, both UTM tuples, every ad-click id). The checkout
+  funnel writes them onto the cart for you at checkout start, so a store
+  needs none of this by hand; it exists because a checkout is a client
+  component and the server reader cannot run there, which is why no order
+  carried an ad-click id before 2026-09-18. The server reader stays the
+  authority for the request facts it alone sees (user agent, IP, referer,
+  GA session), and the two payloads merge by key.
+- **Whether any of it is written** is `consentDecision()` (`tracking/consent`):
+  the visitor's stored choice, and before they make one, the store's own
+  default (a banner means nothing until they agree; no banner means the
+  store collects none). `CONSENT_CHANGED_EVENT` fires on `window` whenever a
+  decision is applied, by the built-in banner or an external CMP through
+  `setConsent`, so a surface that must ACT on consent can hear a later
+  Accept instead of reading once and missing it.
 - **Settings** — Integrations hub rows (which signals exist), consent card
   (whether capture happens).
 
@@ -370,6 +407,28 @@ code-first through the error-copy maps, never raw API strings.
   pre-Buy), carrier metadata, optimistic totals, the atomic Buy click,
   3DS-return handling, completed-cart detection. Every production race
   guard from production is preserved.
+- **The typed form survives a refresh** (2026-09-18) — the form is kept in
+  the tab's own sessionStorage (`cartbase:checkout-form`), restored after
+  mount into EMPTY fields only, so what the server knows (the cart's
+  address, a signed-in customer's) always wins, and cleared when the order
+  is placed. Storage that throws never breaks a checkout.
+- **A completed cart is forgotten everywhere** (2026-09-18) — the tab that
+  placed the order already cleared the cart; a second tab or the back
+  button now clears it too the moment the hook sees `completed_at`, so the
+  next Add starts a new cart instead of being refused by a placed one.
+- **The funnel fires itself** (2026-09-18) — the hook mounts
+  `useCheckoutFunnel`: begin_checkout on arrival, add_shipping_info when
+  contact and address are complete, add_payment_info when the tender is
+  settled, each once per cart to every configured tag; the ad platforms'
+  identity signals (`updatePixelAdvancedMatching` +
+  `setEnhancedConversions`) as the fields are typed, with the shopper's own
+  country rather than a constant; and the ad-click ids written onto the
+  cart so they reach the order. `trackFunnel: false` for a store that fires
+  its own.
+- **Nothing left to pay** (2026-09-18) — `nothingToPay` / `amountDue` on the
+  returned surface: a promotion that covered the order, or gift cards that
+  cover the whole total. The Buy click then skips Stripe from the start,
+  and `<CheckoutPaymentMethodList nothingToPay>` offers no tender at all.
 - **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`
@@ -426,13 +485,25 @@ code-first through the error-copy maps, never raw API strings.
   `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).
+- **SDK calls** — none. The KEY comes from the store: the `pp_stripe`
+  entry of `GET /api/store/payment-providers` carries `publishable_key`
+  and, for a Connect store, `account_id`, and `CheckoutClient` passes them
+  as `publishableKey`/`stripeAccountId`. Under Connect the key is
+  Cartbase's and the account is the merchant's, so this pair only exists
+  on the platform: connecting Stripe in the admin is the whole setup and a
+  storefront configures nothing (2026-09-18). `NEXT_PUBLIC_STRIPE_KEY` and
+  `NEXT_PUBLIC_STRIPE_ACCOUNT_ID` remain the fallback, as a PAIR, for a
+  storefront running its own Stripe outside the platform.
 - **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).
+- **A card with no key is not offered.** `resolveCardOffer`
+  (`checkout/card-offer`) reads the entry and the fallback together;
+  without a publishable key Stripe.js never loads, so the tab would sit on
+  a skeleton for ever. The orchestration hook hides it and reports
+  `card_unmountable` to the merchant's checkout error log instead.
 
 ### `<CheckoutAddressForm />` (+ `<AddressSelect />`, `<CompanyDetails />`) — `checkout/address-form`, `checkout/address-select`, `checkout/company-details`
 
@@ -469,18 +540,74 @@ code-first through the error-copy maps, never raw API strings.
 - **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`
-
+### Which destination an option books, and the carrier's mark — `checkout/fulfillment-option`, `checkout/carrier-marks`
+
+- **`fulfillmentOptionId(option)`** — the merchant's choice on the shipping
+  option: `econt-office`, `speedy-address`, `boxnow-locker`,
+  `pigeon-office` and the rest of the carrier registry. Cartbase writes it
+  as `data.fulfillment_option` (the Shipping option drawer); `data.id` is
+  read as a fallback for a cart carried over from the ported platform.
+  Every picker, every mark and the hook's own readiness go through this one
+  function: the kit read `data.id` alone until 2026-09-18, and since nothing
+  on this side writes that key, no office or locker picker had ever opened
+  on a Cartbase store.
+- **`carrierMarks(origin)`** — the default `logoByFulfillmentOptionId` for
+  the shipping list: the platform's own carrier marks
+  (`{origin}/integrations/{carrier}.png`, the files the admin wears), both
+  modes of a carrier on one mark. `CheckoutClient` passes it unless the
+  store passes a map of its own, so a store gets branded rows with no files
+  to find and a new carrier arrives already dressed.
+
+### `<PickupPointSelector />` — `checkout/pickup-point-selector`
+
+- **Purpose** — THE pickup picker, every carrier, mounted by
+  `CheckoutClient` for any option whose fulfillment option ends `-office` or
+  `-locker`. Nearest three by haversine distance to the typed address, each
+  with its distance, and a door to search the whole catalogue. The shape
+  Alenika's checkout has carried since it was built.
+- **SDK calls** — `integrations.listPickupPoints(client, provider, {mode,
+  q, limit})`, one door for all of them. Where the SEARCH happens is the
+  platform's business: carriers that search are asked (Speedy by office
+  name and by town, Pigeon compensated with town and postcode), carriers
+  that publish whole catalogues are held per store and ranked there (Econt,
+  BoxNow). The component types into one query parameter either way.
+- **Props contract** — `{client, provider, mode, userCity, userAddress,
+  selectedPoint, onSelect}`. `onSelect` receives the point AND the carrier's
+  own key names, which arrive with the answer from the platform's
+  destination registry, so the checkout writes the point under the names
+  this carrier's booking reads without carrying a copy of that map. The
+  choice is remembered on the cart under the checkout's own `_checkout_*`
+  keys so a reload restores it; the carrier's REAL keys are still written
+  exactly once, at prepare.
+- **Why it replaced three components (2026-09-18)** — the kit asked "is
+  this a pickup option?" once per carrier, so a fourth carrier was invisible
+  to the checkout however well the platform served its catalogue: a store
+  could offer delivery to a Speedy office and give the shopper no way to
+  name one. `pickupOptionOf` (`checkout/pickup-option`) reads the carrier
+  and the mode off the option's own id, so a carrier connected tomorrow
+  opens its picker with no line added anywhere.
+- **Settings** — the carrier integrations (connected; the market's options).
+
+### `<EcontOfficeSelector />` / `<BoxNowLockerSelector />` / `<PigeonOfficeSelector />` — `checkout/econt-office-selector`, `checkout/boxnow-locker-selector`, `checkout/pigeon-office-selector`
+
+- **Superseded by `<PickupPointSelector />`** (2026-09-18) and no longer
+  mounted by `CheckoutClient`. Exported still, for a store that mounts its
+  own; the `econt`/`boxnow`/`pigeon` props of
+  `<CheckoutShippingMethodList />` keep working and win for their own
+  carrier when a store passes them.
 - **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.
+  page-level cache). BoxNow: `integrations.listBoxNowLockers(client)`.
+  Pigeon: `integrations.listPigeonOffices(client, {type:"office"})` — the
+  carrier catalogue is credentialed, so the platform serves it and the
+  browser never asks Pigeon; its id arrives as a NUMBER and is stringified
+  when it is written. All three: 503/502/network render one "temporarily
+  unavailable" state, and a town with no point of that carrier says so
+  instead of showing an empty box ([integrations.md](integrations.md)).
 - **Props contract** — `{userCity, userAddress, selectedOffice|Locker,
-  onSelect}` (+ `client` for BoxNow). The CHOSEN office/locker is client
+  onSelect}` (+ `client` for BoxNow and Pigeon). 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`).
@@ -498,41 +625,124 @@ code-first through the error-copy maps, never raw API strings.
 - **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),
+  `gatePaymentUntilDelivery?` (DEFAULT false since 2026-09-18: everything
+  is on screen from arrival and the Buy button carries the gate, naming the
+  missing step; pass true for the older dimmed-until-delivery flow),
   `beforePaymentButton?` slot, `total` (pass `optimisticTotal`),
-  `logError?`.
+  `nothingToPay?` (pass the hook's), `logError?`.
+- **An order that asks for no money** (2026-09-18) — with `nothingToPay` the
+  rail is replaced by one line saying the order is covered and the button
+  becomes **Complete order**, carrying no amount and waiting on no card
+  form. The platform already behaved this way (prepare mints no session at
+  a zero charge); the screen did not, so a fully discounted cart demanded
+  card details for a charge that would never happen.
 - **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`).
 
+### `<CheckoutErrorScreen error reset client? cartId? />` — `checkout/checkout-error-screen`
+
+- **Purpose** — the checkout route's error boundary. Next renders a route's
+  `error.tsx` in place of the page when anything in it throws, a server
+  component included; without one the shopper meets the framework's error
+  page at the moment of paying and nobody is told. Mount it as the default
+  export of `app/checkout/error.tsx` (the reference storefront, and so the
+  seed and every scaffolded store, ships exactly that).
+- **SDK calls** — `checkout.reportCheckoutError` as
+  `error_boundary_checkout` when a `client` is passed; without one the
+  screen still renders and the failure reaches nobody.
+- **Props contract** — Next's `{error, reset}` plus `client?`, `cartId?` and
+  `title?` / `body?` / `retryLabel?`. The copy comes from the label pack
+  when a `CheckoutProvider` stands ABOVE the boundary (one in the route's
+  layout does; one inside the page does not, because the page is what Next
+  replaced) — pass the three strings otherwise. The technical message is
+  never shown to the shopper, only logged.
+
 ### `<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.
+- **Purpose** — items (flat rows, READ-ONLY), promo + gift-card widgets,
+  totals breakdown (subtotal / shipping / COD fee / discount / total +
+  gift-card tender rows UNDER the unchanged total), secure badge.
+  `LineItemCard` is the standalone card variant.
+- **A CHECKOUT IS A CHECKOUT** (2026-09-18) — the rows carry no quantity
+  control and call no cart endpoint. The order is stated here and changed in
+  the cart; the typed form survives the walk back and forth. The quantity is
+  still shown, as a count on the picture and a "Qty n" line on the card.
+- **A free line says so** (2026-09-18) — a line whose total is zero prints
+  `labels.lineFree`, never €0.00, which reads as a pricing fault where a
+  shopper is deciding to pay. It is a SEPARATE label from `shippingFree`:
+  Bulgarian agrees the adjective with its noun, so the rows differ
+  ("Безплатно" on a line, "Безплатна" on shipping).
+- **The VAT row is for a company** (2026-09-18) — `isCompanyOrder(cart)`
+  decides it, on the platform's own precedence (`invoice_to`, then
+  `company_id`, plus the Company invoice fields the kit writes into
+  metadata), and it prints only when the figure is known. A consumer sees
+  the price they pay: the VAT is inside it and a row for it is noise. It
+  used to print a flat 0.00 before an address, beside prices containing 20%.
 - **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.
+  onOptimisticShippingClear?, optimisticMethodFee?,
+  onOptimisticMethodFeeClear?, methodFeeLabel?, showGiftCards?,
+  onCartChange?}`. Optimistic values clear automatically once the server
+  cart catches up.
+- **The numbers** — every figure comes from `checkoutTotals`
+  (`checkout/summary-math`), the pure function the two mobile bars call
+  too, so the total in the column and the total on a phone are the same
+  number by construction. It takes `{cart, optimisticShippingCost,
+  optimisticMethodFee?}` and answers the product rows (newest first, fee
+  lines filtered), the unit count, the subtotal, the shipping figure and
+  whether it is known, the method fee, the grand total and the gift-card
+  tender pair.
+- **Settings** — the payment method's own fee (fee row), gift cards,
+  promotions.
+
+### The phone's order overview — `checkout/mobile-checkout-top-bar`, `checkout/mobile-checkout-bottom-bar`, `checkout/mobile-order-summary-body`
+
+- **Purpose** — the summary column is a desktop shape; on a phone the same
+  content is two bars, each closed on arrival and one tap from everything.
+  `<MobileCheckoutTopBar />` is the strip above the contact form: the words
+  "Order summary", a chevron and the total. `<MobileCheckoutBottomBar />`
+  is the card directly above Place order: the newest item's picture with
+  the unit count on it, the word Total, the count, the figure, a chevron,
+  and it opens upwards so the row and the button stay under the thumb; with
+  no product line it renders nothing. Both reveal
+  `<MobileOrderSummaryBody />`: the items with their quantity pills, the
+  code and gift-card doors, then subtotal, shipping, the method fee,
+  discount, VAT and the gift-card tender pair. The grand total is not
+  repeated inside, because the bar's own row carries it open or closed.
+- **Mount rules** — `CheckoutClient` mounts both (the bottom one through
+  `beforePaymentButton`, with `hideDiscount`, beside an always-open
+  `DiscountSection`, because a code field two taps deep inside a closed bar
+  is a code field nobody finds). Every piece is `sm:hidden`, so a viewport
+  never shows a bar and the column at once. A store with its own layout
+  imports them and composes the same way.
+- **Props contract** — `{client, cart, optimisticShippingCost,
+  optimisticMethodFee?, methodFeeLabel?, showGiftCards?, onCartChange?}`,
+  plus `hideDiscount?` on the bottom bar and the body.
+- **The fee is Cartbase's own** — cart-level decoration
+  (`payment_method_fee_total` / `payment_method_fee_label`, already inside
+  `cart.total`), never a flagged line item, so no surface subtracts a fee
+  row out of the item list. Any method may carry a fee, and the row wears
+  the merchant's name for it.
 
 ### `<DiscountSection />` — `checkout/discount-section`
 
-- **Purpose** — collapsible promo-code input + applied-promotion list
-  (percentage or fixed amount display).
+- **Purpose** — promo-code input + applied-promotion list (percentage or
+  fixed amount display). Collapsed behind its own door by default;
+  `alwaysOpen` renders the field itself, which is what the checkout passes
+  on a phone.
 - **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).
+- **Props contract** — `{client, cart, alwaysOpen?, onCartChange?}`. Enter
+  applies the code. 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`
@@ -1214,6 +1424,42 @@ reaches, so the page passes `STORE_LOCALE.order`.
 ## Family: common (`@cartbase/storefront/common/*`)
 Shared storefront chrome, production-proven.
 
+### `<SocialLinks links label />` + `<SocialIcon network />` — `common/social-links`
+
+- **Purpose**: the store's social profiles as round links with each
+  network's mark in the text colour, for a footer or a header. Networks:
+  Facebook, Instagram, TikTok, YouTube, X, LinkedIn, Pinterest, Threads,
+  Snapchat, WhatsApp, Viber, Telegram (`SOCIAL_NETWORKS`).
+- **Data**: `links` is `store.brand.social` from `getStore` (Settings,
+  Brand, Social links); a network with no address is left out, none
+  renders nothing. `label` names the list for screen readers
+  (`STORE_LOCALE.store.socialProfiles`).
+- **Style**: `linkClassName` styles the round hit area (colour, hover),
+  `iconClassName` sizes the mark. Server-safe.
+
+### `<PaymentIcons methods label />` + `<PaymentIcon method />` — `common/payment-icons`
+
+- **Purpose**: the payment marks in their brands' colours on a 38 by 24
+  card: Visa, Mastercard, Maestro, American Express, UnionPay, Discover,
+  Diners Club, JCB, Apple Pay, Google Pay, PayPal, Revolut, Klarna,
+  Bancontact, iDEAL (`PAYMENT_METHODS`). No Shop Pay.
+- **Data**: `methods` is `payment_marks` from `getPaymentMarks(client)`
+  (`api/store`), what the store's Stripe allows, in order; empty renders
+  nothing. `label` is `STORE_LOCALE.store.paymentMethods`.
+- **Style**: `iconClassName` sizes a mark by height (24px default).
+  `CartPaymentBadges` draws the same marks. Server-safe.
+
+### `<PoweredByCartbase label />` — `common/powered-by-cartbase`
+
+- **Purpose**: "Powered by" and the Cartbase wordmark, a link to
+  cartbase.ai, for the footer's last line. Drawn in the text colour.
+- **Data**: `label` is `STORE_LOCALE.store.poweredBy`. `markClassName`
+  sizes the wordmark by height (14px default). Server-safe.
+
+The marks are generated: SVG files in `assets/icons`, built by
+`scripts/build-icons.mjs` (sources and licences in
+`assets/icons/README.md`).
+
 ### `<LocalizedLink href … />` — `common/localized-link`
 
 - `next/link` that persists the URL locale/country segment when the route

package/template/app/docs/consent.md

@@ -1,91 +1,91 @@
-# Consent
-
-The store's CMP configuration for the built-in Consent Mode v2 banner
-(consent-management card). Defaults are **always applied server-side**, so
-the payload is complete and renderable even for an unconfigured store
-(compliant built-in modal, BG + EN copy shipped).
-
-## Storefront wiring (the trap that matters)
-
-- Mount `<ConsentInit required={consent.enabled}>` as the **first child of
-  `<body>`** — it sets the synchronous Consent Mode v2 DEFAULT and must
-  **never wait on this fetch in the browser** (async default = first-hit
-  consent race). Resolve this config server-side (RSC) and inline the
-  setting into the document; the prop is required, a layout without it
-  does not compile.
-- **The switch decides the default; a stored choice wins.** `enabled: true`
-  is a store that collects consent: every visitor starts DENIED until they
-  choose on the banner. `enabled: false` is a store with no consent gate:
-  every visitor starts GRANTED, and every configured pixel fires. Either
-  way a choice already in the `_1c_consent` cookie is what counts, so a
-  visitor who declined keeps that decision if the banner is switched off.
-- Render the built-in banner only when `enabled && mode === "builtin"`.
-- `mode: "external"` = the merchant's CMP owns the UI and must write the
-  same `_1c_consent` cookie (or call `setConsent()`) — all Cartbase-side tag
-  gating works off that one seam.
-- Choices persist 12 months in the cookie. Rybbit (platform analytics)
-  stays outside consent by design.
-- Pair with [integrations.md](integrations.md): `tracking.consent_required`
-  mirrors `enabled` here, and `<StorefrontTags>` hands it to every pixel
-  that gates its own SDK (Meta, TikTok, ChatGPT). Google reads the
-  `<ConsentInit>` default.
-
-## GET /api/store/consent — the CMP config
-
-- **Purpose**: everything the banner needs to render, per locale.
-- **Auth**: anon (`x-client-id`).
-- **Request**: no params.
-- **Response** — the EXACT allowlist (nothing else will ever appear here):
-
-```jsonc
-{
-  "consent": {
-    "enabled": true,
-    "mode": "builtin",              // "builtin" | "external"
-    "layout": "modal",              // "modal" (blocking) | "banner-bottom" (non-blocking)
-    "privacy_href": "/cookies",
-    "reject_on_first_layer": false,
-    "copy": {
-      "bg": {
-        "title": "Преди да продължиш",
-        "body": "…",
-        "privacy_link_label": "…",
-        "accept_label": "…", "settings_label": "…", "reject_label": "…",
-        "settings_title": "…",
-        "accept_all_label": "…", "save_label": "…", "reject_all_label": "…",
-        "necessary_label": "…", "necessary_description": "…",
-        "analytics_label": "…", "analytics_description": "…",
-        "ads_label": "…", "ads_description": "…"
-      },
-      "en": { /* same 16 keys — every field always present per locale */ }
-    }
-  }
-}
-```
-
-- **Errors**: `400 missing_client_id` only — the payload itself always
-  succeeds (a corrupt/missing stored config degrades to defaults, never to
-  a broken banner).
-- **SDK**: `consent.getConsent(client)`
-- **Components**: `<ConsentInit required={consent.enabled}>` +
-  `<ConsentBanner copy={copy[locale]} layout privacyHref
-  rejectOnFirstLayer>` (consent family; reference impl
-  `src/components/storefront/consent/`).
-- **Settings**: admin → Settings → Consent (enabled/mode/layout/
-  privacy_href/copy per locale).
-
-```bash
-# Complete, renderable config — even on an unconfigured store the defaults
-# make every documented key present.
-BODY=$(curl -sf "$BASE/api/store/consent" -H "x-client-id: $CLIENT_ID")
-echo "$BODY" | grep -q '"consent"'
-echo "$BODY" | grep -q '"mode"'
-echo "$BODY" | grep -q '"layout"'
-echo "$BODY" | grep -q '"privacy_href"'
-echo "$BODY" | grep -q '"reject_on_first_layer"'
-echo "$BODY" | grep -q '"analytics_label"'
-echo "$BODY" | grep -q '"ads_description"'
-# Missing tenant header → the standard 400.
-STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/store/consent")
-test "$STATUS" = 400
-```
+# Consent
+
+The store's CMP configuration for the built-in Consent Mode v2 banner
+(consent-management card). Defaults are **always applied server-side**, so
+the payload is complete and renderable even for an unconfigured store
+(compliant built-in modal, BG + EN copy shipped).
+
+## Storefront wiring (the trap that matters)
+
+- Mount `<ConsentInit required={consent.enabled}>` as the **first child of
+  `<body>`** — it sets the synchronous Consent Mode v2 DEFAULT and must
+  **never wait on this fetch in the browser** (async default = first-hit
+  consent race). Resolve this config server-side (RSC) and inline the
+  setting into the document; the prop is required, a layout without it
+  does not compile.
+- **The switch decides the default; a stored choice wins.** `enabled: true`
+  is a store that collects consent: every visitor starts DENIED until they
+  choose on the banner. `enabled: false` is a store with no consent gate:
+  every visitor starts GRANTED, and every configured pixel fires. Either
+  way a choice already in the `_1c_consent` cookie is what counts, so a
+  visitor who declined keeps that decision if the banner is switched off.
+- Render the built-in banner only when `enabled && mode === "builtin"`.
+- `mode: "external"` = the merchant's CMP owns the UI and must write the
+  same `_1c_consent` cookie (or call `setConsent()`) — all Cartbase-side tag
+  gating works off that one seam.
+- Choices persist 12 months in the cookie. Rybbit (platform analytics)
+  stays outside consent by design.
+- Pair with [integrations.md](integrations.md): `tracking.consent_required`
+  mirrors `enabled` here, and `<StorefrontTags>` hands it to every pixel
+  that gates its own SDK (Meta, TikTok, ChatGPT). Google reads the
+  `<ConsentInit>` default.
+
+## GET /api/store/consent — the CMP config
+
+- **Purpose**: everything the banner needs to render, per locale.
+- **Auth**: anon (`x-client-id`).
+- **Request**: no params.
+- **Response** — the EXACT allowlist (nothing else will ever appear here):
+
+```jsonc
+{
+  "consent": {
+    "enabled": true,
+    "mode": "builtin",              // "builtin" | "external"
+    "layout": "modal",              // "modal" (blocking) | "banner-bottom" (non-blocking)
+    "privacy_href": "/cookies",
+    "reject_on_first_layer": false,
+    "copy": {
+      "bg": {
+        "title": "Преди да продължиш",
+        "body": "…",
+        "privacy_link_label": "…",
+        "accept_label": "…", "settings_label": "…", "reject_label": "…",
+        "settings_title": "…",
+        "accept_all_label": "…", "save_label": "…", "reject_all_label": "…",
+        "necessary_label": "…", "necessary_description": "…",
+        "analytics_label": "…", "analytics_description": "…",
+        "ads_label": "…", "ads_description": "…"
+      },
+      "en": { /* same 16 keys — every field always present per locale */ }
+    }
+  }
+}
+```
+
+- **Errors**: `400 missing_client_id` only — the payload itself always
+  succeeds (a corrupt/missing stored config degrades to defaults, never to
+  a broken banner).
+- **SDK**: `consent.getConsent(client)`
+- **Components**: `<ConsentInit required={consent.enabled}>` +
+  `<ConsentBanner copy={copy[locale]} layout privacyHref
+  rejectOnFirstLayer>` (consent family; reference impl
+  `src/components/storefront/consent/`).
+- **Settings**: admin → Settings → Consent (enabled/mode/layout/
+  privacy_href/copy per locale).
+
+```bash
+# Complete, renderable config — even on an unconfigured store the defaults
+# make every documented key present.
+BODY=$(curl -sf "$BASE/api/store/consent" -H "x-client-id: $CLIENT_ID")
+echo "$BODY" | grep -q '"consent"'
+echo "$BODY" | grep -q '"mode"'
+echo "$BODY" | grep -q '"layout"'
+echo "$BODY" | grep -q '"privacy_href"'
+echo "$BODY" | grep -q '"reject_on_first_layer"'
+echo "$BODY" | grep -q '"analytics_label"'
+echo "$BODY" | grep -q '"ads_description"'
+# Missing tenant header → the standard 400.
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/store/consent")
+test "$STATUS" = 400
+```