create-cartbase 0.1.13 → 0.1.14

package/README.md

@@ -19,3 +19,7 @@ app at a local or staging platform; without it the app talks to the
 platform. Deploy with the
 [`cartbase`](https://www.npmjs.com/package/cartbase) CLI: `cartbase login`,
 then `cartbase deploy`.
+
+Run it in a folder of its own. Inside an existing project, Next.js takes
+that project's folder as the workspace root; the scaffold notices and
+prints the one line to add to `next.config.ts` if that is what you meant.

package/dist/enclosing-project.js

@@ -0,0 +1,82 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+/**
+ * WHERE THE SCAFFOLD LANDS MATTERS TO NEXT.JS, so the scaffold says so.
+ *
+ * Next infers the workspace root from the lockfiles it finds walking up from
+ * the app (`next/dist/lib/find-root.js`, Next 16.2.4): the highest lockfile
+ * wins, the walk stops at the Git repository that contains the app, and a
+ * lockfile at or above the home directory never counts. A store scaffolded
+ * INSIDE another project therefore gets that project's folder as its root,
+ * and once the store has its own lockfile Next warns on every start that it
+ * "inferred your workspace root". The scaffold cannot know whether the
+ * merchant meant a workspace member or a stray folder, so it names the
+ * situation and both ways out at the moment they can still choose
+ * (store-package card, finding 4).
+ */
+/** The lockfiles Next.js treats as workspace-root markers, its own list. */
+export const ROOT_MARKERS = [
+    "pnpm-lock.yaml",
+    "package-lock.json",
+    "yarn.lock",
+    "bun.lock",
+    "bun.lockb",
+];
+/** Is `dir` `of` itself, or one of its ancestors? */
+function isAncestorOrSelf(dir, of) {
+    const rel = path.relative(dir, of);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+/** The nearest folder, from `start` upward, that is a Git repository or worktree. */
+function gitBoundary(start) {
+    let current = start;
+    for (;;) {
+        if (fs.existsSync(path.join(current, ".git")))
+            return current;
+        const parent = path.dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+/**
+ * The project the target folder would sit inside, by Next's own rule, or
+ * null when Next would take the app's own folder as the root. The target
+ * itself need not exist yet: the scaffold asks before it creates it.
+ */
+export function findEnclosingProject(target, options = {}) {
+    const home = options.homeDir === undefined ? os.homedir() : options.homeDir;
+    const parent = path.dirname(path.resolve(target));
+    const boundary = gitBoundary(parent);
+    let current = parent;
+    for (;;) {
+        // Never the home directory or above: Next ignores a marker there.
+        if (home && isAncestorOrSelf(current, home))
+            return null;
+        // Never above the repository that contains the app.
+        if (boundary && current !== boundary && isAncestorOrSelf(current, boundary))
+            return null;
+        for (const marker of ROOT_MARKERS) {
+            if (fs.existsSync(path.join(current, marker)))
+                return { dir: current, marker };
+        }
+        const next = path.dirname(current);
+        if (next === current)
+            return null;
+        current = next;
+    }
+}
+/** What the scaffold prints when the folder sits inside another project. */
+export function enclosingProjectNote(target, found) {
+    const app = path.basename(path.resolve(target));
+    return [
+        `Note: ${app}/ sits inside another project (${found.marker} in ${found.dir}).`,
+        `Next.js takes that folder as the workspace root and, once ${app}/ has its own`,
+        `lockfile, warns on every start that it inferred the root. Either it is a`,
+        `member of that workspace, so name the root in next.config.ts:`,
+        `  turbopack: { root: ${JSON.stringify(found.dir)} }`,
+        `or it is a project of its own, so create it outside that folder, or run`,
+        `git init inside it, which is where Next stops looking.`,
+    ].join("\n");
+}

package/dist/index.js

@@ -2,6 +2,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { enclosingProjectNote, findEnclosingProject } from "./enclosing-project.js";
 function parseArgs(argv) {
     const flags = new Map();
     let dir;
@@ -82,6 +83,9 @@ Given as a flag it is written into .env.local; otherwise a placeholder is.
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n");
     const key = flag(flags, "key");
     fs.writeFileSync(path.join(target, ".env.local"), envFile({ key, url: flag(flags, "url"), clientId: flag(flags, "client-id") }));
+    // A store scaffolded inside another project inherits that project's
+    // workspace root in Next's eyes; said once, here, while it is cheap to move.
+    const enclosing = findEnclosingProject(target);
     console.log(`
 Created ${path.basename(target)}/
 
@@ -97,6 +101,6 @@ Next steps:
 The complete storefront reference is in docs/ — hand CLAUDE.md (or
 AGENTS.md) to your coding agent and it has everything. Deploy with the
 Cartbase CLI: cartbase login, then cartbase deploy.
-`);
+${enclosing ? `\n${enclosingProjectNote(target, enclosing)}\n` : ""}`);
 }
 main();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-cartbase",
-  "version": "0.1.13",
+  "version": "0.1.14",
   "description": "Scaffold a Cartbase storefront: npm create cartbase my-store",
   "license": "MIT",
   "type": "module",

package/template/app/docs/BUILD-A-STOREFRONT.md

@@ -118,10 +118,14 @@ Fetch once at layout level, cache per the docs' cache headers:
 Order inside `<body>` matters (contracts in [components.md](components.md)
 and [consent.md](consent.md)):
 
-1. `<ConsentInit>` FIRST child of body — static and synchronous, never
-   awaits a fetch (first-hit consent race otherwise).
-2. Tracking mounts (`<MetaPixel>`, `<GA4>`, GTM) — gated on the consent
-   state and fed by the integrations tracking block, never by env vars.
+1. `<ConsentInit required={consent.enabled}>` FIRST child of body —
+   synchronous, never awaits a fetch in the browser (first-hit consent race
+   otherwise); the layout resolves the consent config on the server and
+   passes the switch. A store that collects consent starts visitors denied
+   until they choose; a store with the banner off starts them granted.
+2. `<StorefrontTags client={client}>` — every tag the store configured,
+   fed by the integrations tracking block, never by env vars, each gated by
+   the same switch (`tracking.consent_required`).
 3. Navigation from [menus.md](menus.md) — `main-menu` / `footer` handles;
    an unknown handle 404s and must render as "no nav", never crash.
 

package/template/app/docs/components.md

@@ -43,17 +43,26 @@ Shipping: `locales/en`, `locales/es`, `locales/bg`. Each is typed
 pack at compile time instead of falling back to English mid-checkout.
 
 The provider mounts the three pure label contexts (products, checkout,
-order). It deliberately does NOT mount the cart drawer, whose provider
-carries cart state, and two families read labels from a prop. Hand those
-their pack:
+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
-const locale = useStorefrontLocale()
-<CartDrawerProvider cart={cart} labels={locale.cartDrawer}>
-<StoreTemplate labels={locale.store} />
-<ReviewWidget labels={locale.reviews} />
+<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`).
@@ -72,17 +81,23 @@ GA4 Measurement Protocol sending is Cartbase-backend-owned** (the
 unconditionally — every component renders nothing when its id prop is absent,
 every helper no-ops outside the browser.
 
-### `<ConsentInit />` — `tracking/consent-init`
-
-- **Purpose** — the synchronous Consent Mode v2 "default" snippet: reads the
-  `_1c_consent` cookie and sets gtag's consent default (denied when no stored
-  choice) before any Google tag loads.
-- **SDK calls** — none. It must NEVER wait on a fetch: the per-store config
-  drives the banner, not this default (async default = first-hit consent
-  race).
+### `<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).
-- **Settings** — none (static; the shared cookie name is baked in).
+  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`
 
@@ -103,17 +118,22 @@ every helper no-ops outside the browser.
 - Also ships `<ConsentSettingsLink>` (footer link that re-opens the settings
   layer — "withdraw as easily as given") and the pure `<ConsentBannerCard>`.
 
-### `<MetaPixel pixelId />` — `tracking/meta-pixel`
+### `<MetaPixel pixelId consentRequired />` — `tracking/meta-pixel`
 
-- **Purpose** — injects fbevents.js, pushes the consent state from
-  `_1c_consent` BEFORE `fbq('init')` (pre-init revoke = Pixel queues events
-  until grant), fires the initial PageView.
+- **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`).
-- **Mount rules** — root layout, after `<ConsentInit>`. Renders nothing when
-  `pixelId` is falsy. When `tracking.consent_required` is true the consent
-  gate above is mandatory (it is wired in by construction — the snippet
-  always reads the cookie).
+  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 /
@@ -590,7 +610,8 @@ Domain doc for every call: [carts.md](carts.md); gift-card tender:
   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>`,
+  `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),
@@ -601,9 +622,10 @@ Domain doc for every call: [carts.md](carts.md); gift-card tender:
   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 via
-  `labels` (`cart-drawer/labels` holds the English defaults; pass
-  `locale.cartDrawer` from a pack in `locales/*` for another language).
+- **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`
 
@@ -831,12 +853,15 @@ with a legacy flat-row fallback. Unit-tested
 - **SDK calls** — none; expects a `StoreProduct` fetched with pricing
   context for the price line. Server-safe.
 
-### `<RelatedProducts client product pricingContext? limit? labels? renderProduct? />` — `products/related-products`
+### `<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>`.
 
@@ -850,7 +875,7 @@ with a legacy flat-row fallback. Unit-tested
 - **Mount rules** — async server component inside `<Suspense>` (fallback:
   disabled `<ProductActions>`).
 
-### `<ProductTemplate client product pricingContext? addToCart onAddToCart? openCart? />` — `products/product-template`
+### `<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
@@ -858,8 +883,10 @@ with a legacy flat-row fallback. Unit-tested
 - **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; wrap the page in
-  `ProductLabelsProvider` for i18n; `addToCart`/`openCart` seams as on
+- **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/*`)
@@ -871,8 +898,9 @@ 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?: Partial<StoreLabels>` props
-(no context in this family, matching the production original).
+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`
 
@@ -909,14 +937,14 @@ from a pack. Templates take `labels?: Partial<StoreLabels>` props
 
 - **Purpose** — pulse skeleton for any product grid. Server-safe, no calls.
 
-### `<StoreTemplate client sortBy? page? pricingContext? labels? renderProduct? />` — `store/store-template`
+### `<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 sortBy? page? pricingContext? labels? renderProduct? />` — `store/collection-template`
+### `<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).
@@ -930,7 +958,7 @@ from a pack. Templates take `labels?: Partial<StoreLabels>` props
   conditions, channel links (scoped-away collection 404s), price lists.
 - **Mount rules** — server component; grid suspends internally.
 
-### `<CategoryTemplate client category sortBy? page? pricingContext? labels? renderProduct? />` — `store/category-template`
+### `<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`.
@@ -940,7 +968,7 @@ from a pack. Templates take `labels?: Partial<StoreLabels>` props
   children sections don't render.
 - **Settings** — category tree (active/internal flags are server-filtered).
 
-### `<SearchTemplate client searchParams basePath? pricingContext? limit? labels? renderProduct? />` — `store/search-template`
+### `<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
@@ -981,9 +1009,11 @@ 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.
+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 items? shippingMethod? paymentProviderId? cardLast4? … />` — `order/order-completed-template`
+### `<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,
@@ -1109,14 +1139,17 @@ Shared storefront chrome, production-proven.
   `api/carts.deleteLineItem(client, cartId, id)` (idempotent) and hands
   the refreshed `{cart}` to `onDeleted`; spinner resets on failure.
 
-### `<CountrySelect regions value? onChange />` — `common/country-select`
-
-- **Purpose** — the market picker for a header or footer. It lists REGIONS
-  (`api/regions.listRegions`), valued by region id; persistence is app-owned
-  via `onChange` (usually `carts.updateCart(client, cartId, {region_id})` +
-  a cookie). The name is a leftover from the ported source and is wrong for
-  what it does: it selects a market, not a country. Use
-  `listCountries` + `CountryFlag` when you want a country.
+### `<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`
@@ -1154,10 +1187,12 @@ Shared storefront chrome, production-proven.
 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: `defaultReviewsUiLabels` +
-`locale.reviews` from a pack in `locales/*` (English by default,
-parameterized with `{n}`/`{pct}`/`{name}`/`{mb}`/`{s}`/`{email}` slots —
-resolve via `formatLabel`).
+[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
 

package/template/app/docs/consent.md

@@ -7,10 +7,18 @@ the payload is complete and renderable even for an unconfigured store
 
 ## Storefront wiring (the trap that matters)
 
-- Mount `<ConsentInit>` as the **first child of `<body>`** — it sets the
-  synchronous Consent Mode v2 DEFAULT and must **never wait on this fetch**
-  (async default = first-hit consent race). Resolve this config server-side
-  (RSC) and inline it into the document.
+- 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
@@ -18,8 +26,9 @@ the payload is complete and renderable even for an unconfigured store
 - 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 — tags mount only through the consent gate when
-  true.
+  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
 
@@ -58,8 +67,9 @@ the payload is complete and renderable even for an unconfigured store
   succeeds (a corrupt/missing stored config degrades to defaults, never to
   a broken banner).
 - **SDK**: `consent.getConsent(client)`
-- **Components**: `<ConsentInit>` + `<ConsentBanner copy={copy[locale]}
-  layout privacyHref rejectOnFirstLayer>` (consent family; reference impl
+- **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).

package/template/app/docs/customers.md

@@ -71,7 +71,6 @@ test "$STATUS" = 401
 {
   "customer": {
     "id": "uuid",
-    "client_id": "uuid",
     "email": "maria@example.com",
     "first_name": "Maria",
     "last_name": "Petrova",
@@ -83,15 +82,17 @@ test "$STATUS" = 401
     "account_status": "approved",   // "pending" | "approved" — B2B gating
     "tags": [],                      // admin-only labels; read-only here
     "metadata": null,
-    "created_by": null,
     "created_at": "ISO-8601",
     "updated_at": "ISO-8601",
-    "deleted_at": null,
     "addresses": [ /* CustomerAddress[], created_at asc — shape below */ ]
   }
 }
 ```
 
+Named columns only (2026-09-14): the tenant id, the staff member who
+created the row, the payment provider's customer id and the soft-delete
+stamp are not part of this payload.
+
 - **Errors**: `401 unauthenticated` · `400 missing_client_id`.
 - **SDK**: `customers.getMe(client)`
 - **Components**: account dashboard / header account state.
@@ -145,7 +146,6 @@ curl -s "$BASE/api/store/customers/me" -H "x-client-id: $CLIENT_ID" \
   "addresses": [
     {
       "id": "uuid",
-      "client_id": "uuid",
       "customer_id": "uuid",
       "address_name": "Home",
       "first_name": "Maria",
@@ -162,8 +162,7 @@ curl -s "$BASE/api/store/customers/me" -H "x-client-id: $CLIENT_ID" \
       "is_default_shipping": true,
       "metadata": null,
       "created_at": "ISO-8601",
-      "updated_at": "ISO-8601",
-      "deleted_at": null
+      "updated_at": "ISO-8601"
     }
   ],
   "count": 1,

package/template/app/docs/integrations.md

@@ -76,8 +76,10 @@ key-by-key.
   config); consent settings drive `tracking.consent_required`; Rybbit is
   deliberately ABSENT (platform analytics, not a tenant integration).
 
-Tracking wiring contract: mount tags only through the consent gate when
-`consent_required` (see [consent.md](consent.md)); Purchase events MUST use
+Tracking wiring contract: `consent_required` is the store's consent switch
+and decides every tag's default (see [consent.md](consent.md)): true starts
+a visitor denied until they choose, false starts them granted, and a stored
+choice wins either way. `<StorefrontTags>` applies it; Purchase events MUST use
 `eventID = "purchase_" + order.display_id` so Meta dedupes browser Pixel vs
 server CAPI, and `event_id = "tt_purchase_" + order.display_id` for TikTok;
 write TrackingAttribution keys into `cart.metadata` (consent-gated) so

package/template/app/docs/products.md

@@ -69,6 +69,7 @@ foreign key → 400 `invalid_publishable_key`.
   "collection_id": "pcol_01tst00000000000000000001",
   "type_id": null,
   "external_id": null,
+  "vendor": null,                     // the brand, plain text
   "weight": null, "length": null, "height": null, "width": null,
   "hs_code": null, "origin_country": null, "mid_code": null, "material": null,
   "seo_title": null,                  // null = fall back to title

package/template/app/package.json

@@ -9,7 +9,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@cartbase/storefront": "^0.14.0",
+    "@cartbase/storefront": "^0.15.0",
     "next": "16.2.4",
     "react": "19.2.4",
     "react-dom": "19.2.4"

package/template/app/src/app/layout.tsx

@@ -9,7 +9,7 @@ import { StorefrontTags } from "@cartbase/storefront/tracking/storefront-tags"
 import { TrackInit } from "@cartbase/storefront/tracking/track-init"
 import { CartButtonClient } from "@cartbase/storefront/common/cart-button-client"
 import { createStorefrontMetadata, PlatformInit } from "@cartbase/storefront/platform"
-import { BARTER_CLIENT_ID, readCartCookie } from "@/lib/config"
+import { BARTER_CLIENT_ID, readCartCookie, STORE_LOCALE } from "@/lib/config"
 import { getServerClient } from "@/lib/server-client"
 import { Providers } from "./providers"
 import "./globals.css"
@@ -126,14 +126,18 @@ export default async function RootLayout({
   ])
 
   return (
-    <html lang="en">
+    <html lang={STORE_LOCALE.code}>
       <body>
-        <ConsentInit />
+        {/* The store's own consent switch decides the default: a store
+            that collects consent starts every visitor denied until they
+            choose, a store with the banner off starts them granted. The
+            prop is required, so a layout cannot leave it out. */}
+        <ConsentInit required={consentRes.consent.enabled} />
         {/* Every marketing tag the store configured in the admin, mounted
-            from its own config: Meta, TikTok, Google (GA4 + Ads on one
-            tag), GTM. Nothing to wire per vendor — saving the ids in
-            Settings → Integrations is the whole merchant-side act. Order
-            matters: ConsentInit sets the Consent Mode defaults
+            from its own config: Meta, TikTok, ChatGPT, Google (GA4 + Ads
+            on one tag), GTM. Nothing to wire per vendor — saving the ids
+            in Settings → Integrations is the whole merchant-side act.
+            Order matters: ConsentInit sets the Consent Mode defaults
             synchronously ABOVE this, so every tag below inherits the
             gate. */}
         <StorefrontTags client={client} />

package/template/app/src/app/order/[id]/confirmed/page.tsx

@@ -15,6 +15,7 @@ import {
 import { TrackOrderPurchase } from "@cartbase/storefront/tracking/track-order-purchase"
 import { useTrackingConfig } from "@cartbase/storefront/tracking/use-tracking-config"
 import { browserClient } from "@/lib/browser-client"
+import { STORE_LOCALE } from "@/lib/config"
 import { LAST_ORDER_STORAGE_KEY } from "../../../checkout/checkout-page-client"
 
 /**
@@ -86,6 +87,9 @@ export default function OrderConfirmedPage() {
       // the order.
       paymentMethodName={"Cash on delivery"}
       storeHref="/"
+      // The order pack, as a prop: this template reads its copy from props,
+      // not from the locale provider, and the prop is required.
+      labels={STORE_LOCALE.order}
       />
     </>
   )

package/template/app/src/app/page.tsx

@@ -1,6 +1,6 @@
 import { StoreTemplate } from "@cartbase/storefront/store/store-template"
 import type { SortOptions } from "@cartbase/storefront/lib/sort-products"
-import { PRICING_CONTEXT } from "@/lib/config"
+import { PRICING_CONTEXT, STORE_LOCALE } from "@/lib/config"
 import { getServerClient } from "@/lib/server-client"
 
 /**
@@ -20,6 +20,9 @@ export default async function HomePage({
       sortBy={sortBy as SortOptions | undefined}
       page={page}
       pricingContext={PRICING_CONTEXT}
+      // Server-rendered: the locale provider cannot reach it, so the pack
+      // comes as a prop, and the prop is required.
+      labels={STORE_LOCALE.store}
     />
   )
 }

package/template/app/src/app/products/[handle]/page.tsx

@@ -3,7 +3,7 @@ import { retrieveProduct } from "@cartbase/storefront/api/products"
 import { StoreApiError } from "@cartbase/storefront/api/types"
 import { ProductTemplate } from "@cartbase/storefront/products/product-template"
 import { addToCartAction } from "@/lib/cart-actions"
-import { PRICING_CONTEXT } from "@/lib/config"
+import { PRICING_CONTEXT, STORE_LOCALE } from "@/lib/config"
 import { getServerClient } from "@/lib/server-client"
 
 /**
@@ -50,6 +50,11 @@ export default async function ProductPage({
       // default for a store that has not decided yet. The physical-facts
       // section appears on its own for products that HAVE facts, and is
       // skipped for those that do not.
+      //
+      // The pack has to be handed over here, not just mounted at the root:
+      // the related-products strip is a server component and cannot read
+      // the locale provider, so its heading would stay English. Required.
+      labels={STORE_LOCALE.products}
     />
   )
 }

package/template/app/src/app/providers.tsx

@@ -9,14 +9,20 @@ import {
   shouldRenderBanner,
   type ConsentSettings,
 } from "@cartbase/storefront/tracking/consent"
-import { CART_COOKIE, CART_COOKIE_MAX_AGE } from "@/lib/config"
+import { StorefrontLocaleProvider } from "@cartbase/storefront/locales"
+import { CART_COOKIE, CART_COOKIE_MAX_AGE, STORE_LOCALE } from "@/lib/config"
 import { browserClient } from "@/lib/browser-client"
 
 /**
- * Client-side shell: ONE CartDrawerProvider per app (cart-drawer family
- * mount rule) + the consent banner (consent.md: render the builtin banner
- * only when `enabled && mode === "builtin"`; ConsentInit stays in the
- * server layout as the first child of <body>).
+ * Client-side shell: the store's language, ONE CartDrawerProvider per app
+ * (cart-drawer family mount rule) + the consent banner (consent.md: render
+ * the builtin banner only when `enabled && mode === "builtin"`; ConsentInit
+ * stays in the server layout as the first child of <body>).
+ *
+ * The language is mounted once, here. Every client component inside reads
+ * it, the cart drawer included, so nothing is handed over below. The
+ * server-rendered templates cannot read it, so each page hands them their
+ * area (`labels={STORE_LOCALE.store}`), and those props are required.
  */
 export function Providers({
   cart,
@@ -27,28 +33,32 @@ export function Providers({
   consent: ConsentSettings
   children: React.ReactNode
 }) {
-  const copy = pickConsentCopy(consent.copy, "en")
+  // The store's own consent copy, in the store's language where it has it;
+  // pickConsentCopy falls back to English and then to whatever exists.
+  const copy = pickConsentCopy(consent.copy, STORE_LOCALE.code)
   return (
-    <CartDrawerProvider
-      cart={cart}
-      client={browserClient}
-      onCartChange={(next) => {
-        // Persist the cart id (carts.md: the app owns the cart cookie).
-        document.cookie = `${CART_COOKIE}=${encodeURIComponent(
-          next.id
-        )};path=/;max-age=${CART_COOKIE_MAX_AGE};samesite=lax`
-      }}
-    >
-      {children}
-      <CartDrawerTemplate />
-      {shouldRenderBanner(consent) && copy && (
-        <ConsentBanner
-          copy={copy}
-          layout={consent.layout}
-          privacyHref={consent.privacy_href}
-          rejectOnFirstLayer={consent.reject_on_first_layer}
-        />
-      )}
-    </CartDrawerProvider>
+    <StorefrontLocaleProvider locale={STORE_LOCALE}>
+      <CartDrawerProvider
+        cart={cart}
+        client={browserClient}
+        onCartChange={(next) => {
+          // Persist the cart id (carts.md: the app owns the cart cookie).
+          document.cookie = `${CART_COOKIE}=${encodeURIComponent(
+            next.id
+          )};path=/;max-age=${CART_COOKIE_MAX_AGE};samesite=lax`
+        }}
+      >
+        {children}
+        <CartDrawerTemplate />
+        {shouldRenderBanner(consent) && copy && (
+          <ConsentBanner
+            copy={copy}
+            layout={consent.layout}
+            privacyHref={consent.privacy_href}
+            rejectOnFirstLayer={consent.reject_on_first_layer}
+          />
+        )}
+      </CartDrawerProvider>
+    </StorefrontLocaleProvider>
   )
 }

package/template/app/src/app/search/page.tsx

@@ -1,5 +1,5 @@
 import { SearchTemplate } from "@cartbase/storefront/store/search-template"
-import { PRICING_CONTEXT } from "@/lib/config"
+import { PRICING_CONTEXT, STORE_LOCALE } from "@/lib/config"
 import { getServerClient } from "@/lib/server-client"
 
 /** Search page (runbook step 5) — fully URL-state driven search-template. */
@@ -15,6 +15,9 @@ export default async function SearchPage({
       client={client}
       searchParams={params}
       pricingContext={PRICING_CONTEXT}
+      // Server-rendered: the locale provider cannot reach it, so the pack
+      // comes as a prop, and the prop is required.
+      labels={STORE_LOCALE.store}
     />
   )
 }

package/template/app/src/lib/config.ts

@@ -26,5 +26,16 @@ export const CART_COOKIE_MAX_AGE = 60 * 60 * 24 * 30 // 30 days
 /** Locale cookie read by the clients' `getLocale`. */
 export const LOCALE_COOKIE = "_barter_locale"
 
+/**
+ * THE STORE'S LANGUAGE, declared once. The library speaks international
+ * English and knows no other language; a language is a typed pack the store
+ * imports. Swap `en` for `bg` or `es` here (`@cartbase/storefront/locales/bg`)
+ * and every screen follows: providers.tsx mounts it for the client
+ * components, and each page hands the server-rendered templates their area
+ * from it (`labels={STORE_LOCALE.store}`), because a server component cannot
+ * read a client context. Those props are required, so a page cannot forget.
+ */
+export { en as STORE_LOCALE } from "@cartbase/storefront/locales/en"
+
 /** Pricing context for every catalog surface (runbook step 5). EUR only. */
 export const PRICING_CONTEXT = { currency_code: "eur" } as const