create-cartbase 0.1.18 → 0.1.19

package/package.json

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

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

@@ -73,8 +73,15 @@ Construct ONE `StorefrontClient` per scope and pass it to every SDK call
 (all SDK functions take the client as first argument — see any domain doc's
 SDK line):
 
-- **Server** (RSC, server actions): construct per request; `getAuthToken`
-  reads the customer session cookie; `getLocale` reads the locale cookie.
+- **Server, catalogue** (`src/lib/store-client.ts`): ONE client with the
+  store's key and nothing about the visitor. It reads no cookie, so every
+  catalogue read made with it can be cached and every page built from
+  those reads is prerendered (Step 3). A store with customer prices or
+  several languages keys its cached reads by the customer group or the
+  locale, passed in as arguments; it never reads a cookie inside one.
+- **Server, visitor** (`src/lib/server-client.ts`, checkout, account):
+  construct per request; `getAuthToken` reads the customer session cookie;
+  `getLocale` reads the locale cookie. Only behind a `<Suspense>` boundary.
 - **Browser**: construct once; token from your session store.
 
 Auth model (recap — full detail in [auth.md](auth.md)):
@@ -102,9 +109,35 @@ async rewrites() {
 }
 ```
 
-## Step 3 — Store configuration bootstrap
-
-Fetch once at layout level, cache per the docs' cache headers:
+## Step 3 — Store configuration bootstrap, and the prerendered store
+
+**Every page is a prerendered file on the CDN.** The scaffold runs Next.js
+Cache Components (`cacheComponents: true` and the `catalog` life in
+`next.config.ts`), which is what makes a storefront fast: Alenika, the
+store the package came from, serves every page this way.
+
+- Every catalogue read (the store, consent, tags, menus, products,
+  collections, content, reviews) is a function in `src/lib/catalog.ts`
+  marked `"use cache: remote"` with `cacheLife("catalog")`, made with the
+  catalogue client. The platform is asked once per two minutes per read,
+  whichever server renders; a change in the admin reaches the store within
+  that window. A failed read throws inside the cache, so an error is never
+  stored as an empty answer; the public function decides what it reads as.
+- What belongs to one visitor renders behind `<Suspense>`: the query
+  (`searchParams`: sort, page, search, the product page's `?variant=`),
+  the checkout's cart, a customer's account. A page passes `searchParams`
+  down unread and the component inside the boundary reads it.
+- Dynamic routes list their pages with `generateStaticParams` (every
+  product handle, every collection handle), so the build prerenders them;
+  a page added later renders on its first visit and is kept.
+- The build refuses a request read outside a boundary ("Uncached data was
+  accessed outside of `<Suspense>`"). That error is the speed law doing its
+  job: wrap the read, never switch the setting off.
+- A component never reads the query while it renders
+  (`useSearchParams`): read `window.location.search` when you need it, at
+  the click or in an effect. The package holds itself to this with a test.
+
+Fetch once at layout level, through `src/lib/catalog.ts`:
 
 1. [regions.md](regions.md) — regions (→ region_id for pricing + payment
    providers), currencies, supported locales.
@@ -123,19 +156,34 @@ and [consent.md](consent.md)):
    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`).
+2. `<StorefrontTags config={tracking}>` — every tag the store configured,
+   fed by the integrations tracking block (a cached read in
+   `src/lib/catalog.ts`), 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.
 
+The layout reads nothing from the request: no `cookies()`, no cart. The
+cart drawer reads the stored cart id in the browser
+(`readBrowserCartId()` handed to `CartDrawerProvider` as `cartId`) and the
+cart after it, and `<CartButtonClient />` with no `cart` counts the
+drawer's cart. A layout that reads the cart cookie makes every page of the
+store render per visit.
+
 ## Step 5 — Catalog
 
 - [products.md](products.md) — listing + PDP. Always pass a pricing context
   (`currency_code` or `region_id`) or prices come back undecorated; render
   `variant.calculated_price`, fall back to base `prices[]`. **Never cache a
   `calculated_price` response shared when a customer JWT was present** —
-  prices vary by customer group.
+  prices vary by customer group. The product page reads the product from
+  the cache for the page and hands `ProductTemplate` the query as a promise
+  (`initialVariantId={searchParams.then((q) => q.variant)}`): the buy box
+  re-reads the product live behind its boundary, so price and stock are
+  this minute's while the rest of the page is prerendered.
+- A sliding row in a browser component takes cards drawn on the server,
+  never the products: a product is tens of kilobytes, and every prop of a
+  browser component is written into the page.
 - [collections.md](collections.md) — collection pages use the membership
   endpoint (`/collections/:id/products`) which honors the admin's sort.
 - [categories.md](categories.md) — category tree, tags, types.
@@ -160,7 +208,9 @@ and [consent.md](consent.md)):
 ## Step 7 — Cart
 
 [carts.md](carts.md): create the cart lazily on first add-to-cart with the
-region + (optionally) sales channel; persist `cart.id` in a cookie; all cart
+region + (optionally) sales channel; persist `cart.id` in a cookie
+(`writeCartCookie` in the drawer's `onCartChange`, `readBrowserCartId()`
+for its `cartId`, `clearCartCookie` for its `onCartEnd`); all cart
 mutations return the decorated cart — totals are SERVER truth, render them
 verbatim, never compute client-side. Line items, quantity updates, deletes,
 and the customer-attach call after login are all in that doc.

package/template/app/docs/components.md

@@ -832,10 +832,14 @@ Six rules every buy panel is held to, the package's own and a store's:
    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.
+2. **The first paint is right.** The page hands `searchParams.variant` down
+   (`initialVariantId` on `ProductTemplate`, `ProductActions` or the hook),
+   so the server renders that variant's price, code and stock and nothing
+   flashes. On Cache Components the page passes it to `ProductTemplate` as a
+   promise (`searchParams.then((q) => q.variant)`) and the live buy box
+   reads it behind its boundary, so the rest of the page stays prerendered.
+   The hook itself never reads the query while rendering: it reads
+   `window.location.search` when it rewrites the address.
 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
@@ -969,7 +973,9 @@ with a legacy flat-row fallback. Unit-tested
 - **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);
+  address's variant (`searchParams.variant`, rule 2 of the contract), a
+  string or a promise of one; a promise is read inside the live buy box's
+  boundary, and the fallback box renders the merchant's default;
   `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
@@ -1214,12 +1220,15 @@ Shared storefront chrome, production-proven.
   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`
+### `<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 =
+- **SDK calls** — `<CartButtonClient />` with no `cart` counts the drawer's
+  own cart (the one the provider read in the browser): the default, and
+  the only shape that keeps a store's pages prerendered. The server wrapper
+  `CartButton` reads `api/carts.retrieveCart(client, cartId)` from the
+  cookie, so it renders per visit and belongs behind a `<Suspense>`; fetch
+  failure degrades to an empty button. Badge count =
   `productItemCount(cart.items)` (fee-line-aware, consistent with the
   drawer).
 - **Mount rules** — `CartButtonClient` must sit inside the cart-drawer
@@ -1303,12 +1312,37 @@ parameterized with `{n}`/`{pct}`/`{name}`/`{mb}`/`{s}`/`{email}` slots
 - **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`.
+- Pieces exported for custom layouts: `<StarRow>` (`size="lg"` is the
+  lightbox's row), `<StarBadge>`, `<RatingDistribution>` (`star-badge`),
+  `<ReviewList>` (the presentational cards; a click on a card opens it in
+  `<ReviewLightbox>`), `reviewDisplayName` (first name and surname
+  initial, shared with any app JSON-LD so UI and structured data cannot
+  drift, a production fix), `formatReviewDate`.
+- **Theme**: the stars fill in the `rating` colour (`--rating` in
+  tokens.css, the warning yellow unless the store sets its own).
+
+### `<ReviewLightbox reviews position onPositionChange labels? />`: one review, whole
+
+- **Purpose**: the review opened from ANY widget that shows reviews: the
+  photo or video on the left, and on the right the reviewer, the verified
+  badge with a button that says what it means, the stars, the date, the
+  text and the store's reply. On a phone the photo sits on top and the
+  review scrolls under it. The arrows and the arrow keys walk the open
+  review's photos, then on to the next review; the dots jump between one
+  review's photos; Escape, the close button and a click outside close it.
+- **Mount rules**: client component, built on the Dialog primitive. The
+  opening widget owns the state and hands over its own list, so the
+  lightbox walks the reviews in the widget's order:
+
+  ```tsx
+  const [open, setOpen] = useState<LightboxPosition | null>(null)
+  // on a card: onClick={() => setOpen({ review: index, media: 0 })}
+  <ReviewLightbox reviews={reviews} position={open} onPositionChange={setOpen} />
+  ```
+
+  `media` indexes `lightboxMedia(review)`, the same filtered list a card
+  counts its photos from. `stepLightbox` is the walk itself, for a widget
+  that steps on its own.
 
 ### `<ReviewWizard client token validation rewardPct? supportEmail? … />` — the token page
 

package/template/app/docs/store.md

@@ -38,10 +38,18 @@ SDK module: `@cartbase/storefront/api/store` (from 0.8.0; on 0.7.0 call
 - **Errors** — `404 store_not_found` when the key names no live store.
 
 ```ts
+import { cacheLife } from "next/cache"
 import { getStore } from "@cartbase/storefront/api/store"
 
+// A cached read with the catalogue client (BUILD-A-STOREFRONT.md step 3).
+async function readStore() {
+  "use cache: remote"
+  cacheLife("catalog")
+  return (await getStore(storeClient)).store
+}
+
 export async function generateMetadata() {
-  const { store } = await getStore(await getServerClient())
+  const store = await readStore()
   return createStorefrontMetadata({ title: store.name, description: store.brand.slogan ?? undefined })
 }
 ```

package/template/app/next.config.ts

@@ -4,6 +4,17 @@ const nextConfig: NextConfig = {
   // @cartbase/storefront is source-shipped TypeScript — the app's Next
   // build transpiles it.
   transpilePackages: ["@cartbase/storefront"],
+  // Cache Components: every page is a prerendered shell served from the
+  // CDN. The catalogue reads are cached (src/lib/catalog.ts) and send no
+  // cookies; what belongs to one visitor (the cart, the query, the live buy
+  // box, the checkout) streams in behind <Suspense>. A request read left
+  // outside a boundary fails the build, so a slow page cannot ship.
+  cacheComponents: true,
+  cacheLife: {
+    // The catalogue: products, menus, the store, consent, tags. A change in
+    // the admin reaches the store within two minutes.
+    catalog: { stale: 60, revalidate: 120, expire: 3600 },
+  },
   images: {
     // Product pictures live on the Cartbase media CDN and Next resizes them
     // on this project, per device, in the modern formats. A picture from

package/template/app/package.json

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

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

@@ -1,3 +1,4 @@
+import { Suspense } from "react"
 import { cookies } from "next/headers"
 import { redirect } from "next/navigation"
 import { retrieveCart } from "@cartbase/storefront/api/carts"
@@ -16,7 +17,17 @@ import { CheckoutPageClient } from "./checkout-page-client"
  * client layout. Redirect completed/missing carts server-side
  * (checkout-client mount rule).
  */
-export default async function CheckoutPage() {
+export default function CheckoutPage() {
+  // The cart is this visitor's: the checkout renders at request time,
+  // behind its boundary (Cache Components).
+  return (
+    <Suspense fallback={null}>
+      <Checkout />
+    </Suspense>
+  )
+}
+
+async function Checkout() {
   const jar = await cookies()
   // Back-compat: prefer `_cartbase_cart`, fall back to the legacy
   // `_barter_cart_id` name (platform-fingerprints card).

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

@@ -1,184 +1,126 @@
-import type { Metadata } from "next"
-import Link from "next/link"
-import { cookies } from "next/headers"
-import { retrieveCart, type Cart } from "@cartbase/storefront/api/carts"
-import { getConsent } from "@cartbase/storefront/api/consent"
-import { getMenu, type Menu } from "@cartbase/storefront/api/menus"
-import { ConsentInit } from "@cartbase/storefront/tracking/consent-init"
-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, STORE_LOCALE } from "@/lib/config"
-import { getServerClient } from "@/lib/server-client"
-import { Providers } from "./providers"
-import "./globals.css"
-
-// createStorefrontMetadata (platform-fingerprints card) stamps
-// `<meta name="generator" content="Cartbase" />` on every page — never
-// hand-write `generator` here.
-export async function generateMetadata(): Promise<Metadata> {
-  const store = await fetchStore()
-  return createStorefrontMetadata({
-    title: store.name,
-    description: store.brand.slogan ?? undefined,
-  })
-}
-
-/**
- * The store's own identity (store.md): name, slug, brand. Read once per
- * request; a storefront never hardcodes its name. Until @cartbase/storefront
- * 0.8.0 ships `api/store`, the call goes through the client's low-level
- * request with the documented shape.
- */
-type StoreIdentity = {
-  /** The store's public id: what PlatformInit mounts (one key: never an env input). */
-  id: string
-  name: string
-  slug: string
-  brand: {
-    logo_url: string | null
-    logo_square_url: string | null
-    color_primary: string | null
-    color_secondary: string | null
-    slogan: string | null
-  }
-}
-
-async function fetchStore(): Promise<StoreIdentity> {
-  const client = await getServerClient()
-  try {
-    const { store } = await client.request<{ store: StoreIdentity }>("/api/store/store")
-    return store
-  } catch {
-    // Never crash the layout on a transient API error; the name is
-    // decoration, the store still renders.
-    return {
-      id: BARTER_CLIENT_ID ?? "",
-      name: "Store",
-      slug: "",
-      brand: {
-        logo_url: null,
-        logo_square_url: null,
-        color_primary: null,
-        color_secondary: null,
-        slogan: null,
-      },
-    }
-  }
-}
-
-/**
- * Runbook steps 3–4: bootstrap store config at layout level, then mount
- * order inside <body>: ConsentInit FIRST (static, synchronous), then the
- * consent-gated UI, then navigation. A store with no menus 404s every
- * handle — render no nav, never crash (menus.md).
- */
-async function fetchMenu(handle: string): Promise<Menu | null> {
-  const client = await getServerClient()
-  try {
-    const { menu } = await getMenu(client, handle)
-    return menu
-  } catch {
-    return null // unknown/deleted handle (404) → graceful "no nav"
-  }
-}
-
-function MenuNav({ menu }: { menu: Menu | null }) {
-  if (!menu || menu.items.length === 0) return null
-  return (
-    <nav className="flex items-center gap-4">
-      {menu.items.map((item) => (
-        <Link
-          key={`${item.title}-${item.url}`}
-          href={item.url}
-          className="text-sm text-muted-foreground hover:text-foreground"
-        >
-          {item.title}
-        </Link>
-      ))}
-    </nav>
-  )
-}
-
-export default async function RootLayout({
-  children,
-}: {
-  children: React.ReactNode
-}) {
-  const client = await getServerClient()
-  const jar = await cookies()
-  // Back-compat: prefer the new `_cartbase_cart` cookie, fall back to the
-  // legacy `_barter_cart_id` name so an existing visitor's cart survives
-  // the rename (platform-fingerprints card).
-  const cartId = readCartCookie((name) => jar.get(name)?.value) ?? null
-
-  const [store, consentRes, mainMenu, footerMenu, cart] = await Promise.all([
-    fetchStore(),
-    getConsent(client),
-    fetchMenu("main-menu"),
-    fetchMenu("footer"),
-    cartId
-      ? retrieveCart(client, cartId)
-          .then((res): Cart | null => res.cart)
-          .catch(() => null) // stale cookie → empty cart state
-      : Promise.resolve(null),
-  ])
-
-  return (
-    <html lang={STORE_LOCALE.code}>
-      <body>
-        {/* 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, 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} />
-        {/* Captures UTMs and the ad-click ids (ttclid / gclid / gbraid /
-            wbraid) that exist ONLY on an ad's landing URL — miss them
-            here and no platform can attribute the order to the click. */}
-        <TrackInit />
-        <PlatformInit storeId={store.id} />
-        <Providers cart={cart} consent={consentRes.consent}>
-          <header className="border-b border-border">
-            <div className="max-w-7xl mx-auto px-4 h-16 flex items-center justify-between gap-6">
-              <Link href="/" className="font-semibold text-lg">
-                {store.name}
-              </Link>
-              <div className="flex items-center gap-6">
-                <MenuNav menu={mainMenu} />
-                <Link
-                  href="/search"
-                  className="text-sm text-muted-foreground hover:text-foreground"
-                >
-                  Search
-                </Link>
-                {/*
-                  The component workbench lives at /gallery in THIS app only
-                  (the seed excludes it, src/lib/storefront/seed.ts), so the
-                  shop's own nav never links to it: a merchant's store must
-                  not carry a dead link.
-                */}
-                <CartButtonClient cart={cart} />
-              </div>
-            </div>
-          </header>
-          <main>{children}</main>
-          <footer className="border-t border-border mt-12">
-            <div className="max-w-7xl mx-auto px-4 py-8 text-sm text-muted-foreground flex items-center justify-between">
-              <span>{store.name}</span>
-              <MenuNav menu={footerMenu} />
-            </div>
-          </footer>
-        </Providers>
-      </body>
-    </html>
-  )
-}
+import type { Metadata } from "next"
+import Link from "next/link"
+import type { Menu } from "@cartbase/storefront/api/menus"
+import { ConsentInit } from "@cartbase/storefront/tracking/consent-init"
+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 { STORE_LOCALE } from "@/lib/config"
+import { getConsentSettings, getMenuSafe, getStoreIdentity, getTracking } from "@/lib/catalog"
+import { Providers } from "./providers"
+import "./globals.css"
+
+// createStorefrontMetadata (platform-fingerprints card) stamps
+// `<meta name="generator" content="Cartbase" />` on every page — never
+// hand-write `generator` here.
+export async function generateMetadata(): Promise<Metadata> {
+  const store = await getStoreIdentity()
+  return createStorefrontMetadata({
+    title: store.name,
+    description: store.brand.slogan ?? undefined,
+  })
+}
+
+function MenuNav({ menu }: { menu: Menu | null }) {
+  if (!menu || menu.items.length === 0) return null
+  return (
+    <nav className="flex items-center gap-4">
+      {menu.items.map((item) => (
+        <Link
+          key={`${item.title}-${item.url}`}
+          href={item.url}
+          className="text-sm text-muted-foreground hover:text-foreground"
+        >
+          {item.title}
+        </Link>
+      ))}
+    </nav>
+  )
+}
+
+/**
+ * Runbook steps 3–4: bootstrap store config at layout level, then mount
+ * order inside <body>: ConsentInit FIRST (static, synchronous), then the
+ * consent-gated UI, then navigation. A store with no menus 404s every
+ * handle — render no nav, never crash (menus.md).
+ *
+ * Nothing here reads the request. The store, the consent settings, the tags
+ * and the menus are cached reads (lib/catalog.ts), so the shell is
+ * prerendered and every page is served from the CDN (Cache Components). The
+ * cart is the visitor's: the drawer reads its id from the cookie in the
+ * browser and the cart after it (providers.tsx), and the cart button counts
+ * the drawer's cart, so no page waits for the cart.
+ */
+export default async function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  const [store, consent, tracking, mainMenu, footerMenu] = await Promise.all([
+    getStoreIdentity(),
+    getConsentSettings(),
+    getTracking(),
+    getMenuSafe("main-menu"),
+    getMenuSafe("footer"),
+  ])
+
+  return (
+    <html lang={STORE_LOCALE.code}>
+      <body>
+        {/* 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={consent.enabled} />
+        {/* Every marketing tag the store configured in the admin, mounted
+            from its own config: Meta, TikTok, ChatGPT, Google (GA4 + Ads
+            on one tag), GTM. Nothing to wire per vendor: saving the ids
+            under 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. The config is a cached read handed over, so the tags
+            cost the page nothing at request time. */}
+        {tracking ? <StorefrontTags config={tracking} /> : null}
+        {/* Captures UTMs and the ad-click ids (ttclid / gclid / gbraid /
+            wbraid) that exist ONLY on an ad's landing URL — miss them
+            here and no platform can attribute the order to the click. */}
+        <TrackInit />
+        <PlatformInit storeId={store.id} />
+        <Providers consent={consent}>
+          <header className="border-b border-border">
+            <div className="max-w-7xl mx-auto px-4 h-16 flex items-center justify-between gap-6">
+              <Link href="/" className="font-semibold text-lg">
+                {store.name}
+              </Link>
+              <div className="flex items-center gap-6">
+                <MenuNav menu={mainMenu} />
+                <Link
+                  href="/search"
+                  className="text-sm text-muted-foreground hover:text-foreground"
+                >
+                  Search
+                </Link>
+                {/*
+                  The component workbench lives at /gallery in THIS app only
+                  (the seed excludes it, src/lib/storefront/seed.ts), so the
+                  shop's own nav never links to it: a merchant's store must
+                  not carry a dead link.
+                */}
+                {/* No `cart` prop: the badge counts the drawer's own cart. */}
+                <CartButtonClient />
+              </div>
+            </div>
+          </header>
+          <main>{children}</main>
+          <footer className="border-t border-border mt-12">
+            <div className="max-w-7xl mx-auto px-4 py-8 text-sm text-muted-foreground flex items-center justify-between">
+              <span>{store.name}</span>
+              <MenuNav menu={footerMenu} />
+            </div>
+          </footer>
+        </Providers>
+      </body>
+    </html>
+  )
+}

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

@@ -1,28 +1,37 @@
-import { StoreTemplate } from "@cartbase/storefront/store/store-template"
-import type { SortOptions } from "@cartbase/storefront/lib/sort-products"
-import { PRICING_CONTEXT, STORE_LOCALE } from "@/lib/config"
-import { getServerClient } from "@/lib/server-client"
-
-/**
- * Home = the all-products listing (runbook step 5: always pass a pricing
- * context or prices come back undecorated).
- */
-export default async function HomePage({
-  searchParams,
-}: {
-  searchParams: Promise<{ sortBy?: string; page?: string }>
-}) {
-  const { sortBy, page } = await searchParams
-  const client = await getServerClient()
-  return (
-    <StoreTemplate
-      client={client}
-      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}
-    />
-  )
-}
+import { Suspense } from "react"
+import { StoreTemplate } from "@cartbase/storefront/store/store-template"
+import { SkeletonProductGrid } from "@cartbase/storefront/store/skeleton-product-grid"
+import type { SortOptions } from "@cartbase/storefront/lib/sort-products"
+import { PRICING_CONTEXT, STORE_LOCALE } from "@/lib/config"
+import { storeClient } from "@/lib/store-client"
+
+type ListingQuery = { sortBy?: string; page?: string }
+
+/**
+ * Home = the all-products listing (runbook step 5: always pass a pricing
+ * context or prices come back undecorated). The sort and the page number
+ * are request data, so the listing renders behind a boundary and the shell
+ * around it stays prerendered.
+ */
+export default function HomePage({ searchParams }: { searchParams: Promise<ListingQuery> }) {
+  return (
+    <Suspense fallback={<SkeletonProductGrid />}>
+      <Listing searchParams={searchParams} />
+    </Suspense>
+  )
+}
+
+async function Listing({ searchParams }: { searchParams: Promise<ListingQuery> }) {
+  const { sortBy, page } = await searchParams
+  return (
+    <StoreTemplate
+      client={storeClient}
+      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

@@ -1,87 +1,89 @@
-import { notFound } from "next/navigation"
-import { retrieveProduct } from "@cartbase/storefront/api/products"
-import { StoreApiError } from "@cartbase/storefront/api/types"
-import { ProductTemplate } from "@cartbase/storefront/products/product-template"
-import { PRICING_CONTEXT, STORE_LOCALE } from "@/lib/config"
-import { getServerClient } from "@/lib/server-client"
-
-/**
- * PDP (runbook step 5): fetch by handle WITH the pricing context, render
- * the full product template. No `addToCart` is passed: the add goes
- * through the cart drawer mounted in `providers.tsx`, so the drawer opens
- * at the click with the product in it and no page render runs (the product
- * page contract, rule 6). The drawer's `onCartChange` owns the cart cookie.
- */
-export default async function ProductPage({
-  params,
-  searchParams,
-}: {
-  params: Promise<{ handle: string }>
-  searchParams: Promise<{ variant?: string }>
-}) {
-  const [{ handle }, { variant }] = await Promise.all([params, searchParams])
-  const client = await getServerClient()
-
-  let product
-  try {
-    const res = await retrieveProduct(client, handle, PRICING_CONTEXT)
-    product = res.product
-  } catch (e) {
-    if (e instanceof StoreApiError && e.status === 404) notFound()
-    throw e
-  }
-
-  return (
-    <ProductTemplate
-      client={client}
-      product={product}
-      pricingContext={PRICING_CONTEXT}
-      // The product page contract: the address names the variant
-      // (`?variant=<digits>`, Shopify's parameter), and the page hands it to
-      // the template so the FIRST paint is that variant's price, code and
-      // stock. Switching a variant rewrites the address in the browser
-      // without asking the server.
-      initialVariantId={variant}
-      // NO `promises` here, deliberately. Until 0.13.0 the library carried
-      // delivery, exchange and return promises as label DEFAULTS, so every
-      // store scaffolded from this file told shoppers "your package will
-      // arrive in 3-5 business days" and "we'll refund your money" without
-      // anyone having decided that. Those are YOUR commitments, so you write
-      // them:
-      //
-      //   promises={[
-      //     { icon: "delivery", title: "Fast delivery",
-      //       body: "Your order arrives in 2 working days." },
-      //   ]}
-      //
-      // Pass nothing and the section does not exist, which is the right
-      // 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}
-    />
-  )
-}
-
-export async function generateMetadata({
-  params,
-}: {
-  params: Promise<{ handle: string }>
-}) {
-  const { handle } = await params
-  const client = await getServerClient()
-  try {
-    const { product } = await retrieveProduct(client, handle)
-    // SEO fields with title/description fallbacks (runbook step 5).
-    return {
-      title: product.seo_title ?? product.title,
-      description: product.seo_description ?? product.description ?? undefined,
-    }
-  } catch {
-    return {}
-  }
-}
+import { notFound } from "next/navigation"
+import { ProductTemplate } from "@cartbase/storefront/products/product-template"
+import { getProduct, listProductHandles } from "@/lib/catalog"
+import { PRICING_CONTEXT, STORE_LOCALE } from "@/lib/config"
+import { storeClient } from "@/lib/store-client"
+
+/**
+ * Every product's page is prerendered at build, so it is a file on the CDN.
+ * A product added after the last deploy renders on its first visit and is
+ * kept from then on. Without this list the handle would be request data and
+ * every product page would render per visit (Cache Components).
+ */
+export async function generateStaticParams() {
+  const handles = await listProductHandles()
+  // Cache Components refuses an empty list; a store with no products yet
+  // still builds, and the placeholder answers 404.
+  return handles.length ? handles.map((handle) => ({ handle })) : [{ handle: "__none__" }]
+}
+
+/**
+ * PDP (runbook step 5): the product is a cached read by handle WITH the
+ * pricing context (lib/catalog.ts), and the template renders it. The buy
+ * box re-reads the product live behind its own boundary, so price and stock
+ * are this minute's while the rest of the page is prerendered.
+ *
+ * No `addToCart` is passed: the add goes through the cart drawer mounted in
+ * `providers.tsx`, so the drawer opens at the click with the product in it
+ * and no page render runs (the product page contract, rule 6). The drawer's
+ * `onCartChange` owns the cart cookie.
+ */
+export default async function ProductPage({
+  params,
+  searchParams,
+}: {
+  params: Promise<{ handle: string }>
+  searchParams: Promise<{ variant?: string }>
+}) {
+  const { handle } = await params
+  const product = await getProduct(handle)
+  if (!product) notFound()
+
+  return (
+    <ProductTemplate
+      client={storeClient}
+      product={product}
+      pricingContext={PRICING_CONTEXT}
+      // The product page contract: the address names the variant
+      // (`?variant=<digits>`, Shopify's parameter), and the FIRST paint of
+      // the buy box is that variant's price, code and stock. The query is
+      // request data, so it goes in as a promise and the live buy box reads
+      // it behind its boundary. Switching a variant rewrites the address in
+      // the browser without asking the server.
+      initialVariantId={searchParams.then((query) => query.variant)}
+      // NO `promises` here, deliberately. Until 0.13.0 the library carried
+      // delivery, exchange and return promises as label DEFAULTS, so every
+      // store scaffolded from this file told shoppers "your package will
+      // arrive in 3-5 business days" and "we'll refund your money" without
+      // anyone having decided that. Those are YOUR commitments, so you write
+      // them:
+      //
+      //   promises={[
+      //     { icon: "delivery", title: "Fast delivery",
+      //       body: "Your order arrives in 2 working days." },
+      //   ]}
+      //
+      // Pass nothing and the section does not exist, which is the right
+      // 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}
+    />
+  )
+}
+
+export async function generateMetadata({ params }: { params: Promise<{ handle: string }> }) {
+  const { handle } = await params
+  // The page's own read: one cache entry answers both.
+  const product = await getProduct(handle).catch(() => null)
+  if (!product) return {}
+  // SEO fields with title/description fallbacks (runbook step 5).
+  return {
+    title: product.seo_title ?? product.title,
+    description: product.seo_description ?? product.description ?? undefined,
+  }
+}

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

@@ -1,6 +1,6 @@
 "use client"
 
-import type { Cart } from "@cartbase/storefront/api/carts"
+import { useState } from "react"
 import { CartDrawerProvider } from "@cartbase/storefront/cart-drawer/context"
 import { CartDrawerTemplate } from "@cartbase/storefront/cart-drawer/template"
 import { ConsentBanner } from "@cartbase/storefront/tracking/consent-banner"
@@ -10,8 +10,12 @@ import {
   type ConsentSettings,
 } from "@cartbase/storefront/tracking/consent"
 import { StorefrontLocaleProvider } from "@cartbase/storefront/locales"
-import { clearCartCookie } from "@cartbase/storefront/lib/cookie-names"
-import { CART_COOKIE, CART_COOKIE_MAX_AGE, STORE_LOCALE } from "@/lib/config"
+import {
+  clearCartCookie,
+  readBrowserCartId,
+  writeCartCookie,
+} from "@cartbase/storefront/lib/cookie-names"
+import { STORE_LOCALE } from "@/lib/config"
 import { browserClient } from "@/lib/browser-client"
 
 /**
@@ -26,28 +30,27 @@ import { browserClient } from "@/lib/browser-client"
  * area (`labels={STORE_LOCALE.store}`), and those props are required.
  */
 export function Providers({
-  cart,
   consent,
   children,
 }: {
-  cart: Cart | null
   consent: ConsentSettings
   children: React.ReactNode
 }) {
+  // The stored cart id, read once in the browser: the prerendered shell
+  // knows no visitor, so the server renders without one, and the drawer
+  // reads the cart as soon as it has the id.
+  const [cartId] = useState(readBrowserCartId)
   // 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 (
     <StorefrontLocaleProvider locale={STORE_LOCALE}>
       <CartDrawerProvider
-        cart={cart}
+        cartId={cartId}
         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`
-        }}
+        // Persist the cart id (carts.md: the app decides when the cart
+        // cookie is written; the package owns its name and shape).
+        onCartChange={(next) => writeCartCookie(next.id)}
         // The cart is over (ordered, or gone): forget the stored id, so the
         // next add starts a new cart.
         onCartEnd={clearCartCookie}

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

@@ -1,23 +1,33 @@
-import { SearchTemplate } from "@cartbase/storefront/store/search-template"
-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. */
-export default async function SearchPage({
-  searchParams,
-}: {
-  searchParams: Promise<Record<string, string | string[] | undefined>>
-}) {
-  const params = await searchParams
-  const client = await getServerClient()
-  return (
-    <SearchTemplate
-      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}
-    />
-  )
-}
+import { Suspense } from "react"
+import { SearchTemplate } from "@cartbase/storefront/store/search-template"
+import { SkeletonProductGrid } from "@cartbase/storefront/store/skeleton-product-grid"
+import { PRICING_CONTEXT, STORE_LOCALE } from "@/lib/config"
+import { storeClient } from "@/lib/store-client"
+
+type Query = Record<string, string | string[] | undefined>
+
+/**
+ * Search page (runbook step 5) — fully URL-state driven search-template. The
+ * query is request data, so the results render behind a boundary.
+ */
+export default function SearchPage({ searchParams }: { searchParams: Promise<Query> }) {
+  return (
+    <Suspense fallback={<SkeletonProductGrid />}>
+      <Results searchParams={searchParams} />
+    </Suspense>
+  )
+}
+
+async function Results({ searchParams }: { searchParams: Promise<Query> }) {
+  const params = await searchParams
+  return (
+    <SearchTemplate
+      client={storeClient}
+      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/catalog.ts

@@ -0,0 +1,120 @@
+import { cacheLife, cacheTag } from "next/cache"
+import { getConsent, type ConsentConfig } from "@cartbase/storefront/api/consent"
+import { getMenu, type Menu } from "@cartbase/storefront/api/menus"
+import { listProducts, retrieveProduct, type StoreProduct } from "@cartbase/storefront/api/products"
+import { getStore, type StoreIdentity } from "@cartbase/storefront/api/store"
+import { getTrackingConfig } from "@cartbase/storefront/tracking/get-tracking-config"
+import type { TrackingConfig } from "@cartbase/storefront/tracking/types"
+import { BARTER_CLIENT_ID, PRICING_CONTEXT } from "./config"
+import { storeClient } from "./store-client"
+
+/**
+ * The store's cached reads (runbook step 3, Cache Components). Each is a
+ * `use cache: remote` function on the `catalog` life (next.config.ts): the
+ * platform is asked once per window, whichever instance renders, and every
+ * page built from these reads is a prerendered file on the CDN.
+ *
+ * Failure contract: inside the cache a failed read THROWS, so a platform
+ * blip is never stored as an empty answer for the whole window; the public
+ * function decides what an error reads as. An unknown handle (404) is an
+ * answer, null, and is kept.
+ */
+
+function isNotFound(error: unknown): boolean {
+  return (error as { status?: number } | null)?.status === 404
+}
+
+const FALLBACK_STORE: StoreIdentity = {
+  id: BARTER_CLIENT_ID ?? "",
+  name: "Store",
+  slug: "",
+  brand: {
+    logo_url: null,
+    logo_square_url: null,
+    color_primary: null,
+    color_secondary: null,
+    slogan: null,
+  },
+}
+
+async function readStore(): Promise<StoreIdentity> {
+  "use cache: remote"
+  cacheLife("catalog")
+  cacheTag("catalog")
+  const { store } = await getStore(storeClient)
+  return store
+}
+
+/**
+ * The store's own identity (store.md): name, slug, brand. A storefront never
+ * hardcodes its name, and a transient API error never takes the layout down.
+ */
+export async function getStoreIdentity(): Promise<StoreIdentity> {
+  return readStore().catch(() => FALLBACK_STORE)
+}
+
+/** The store's consent configuration; the platform always answers a complete one. */
+export async function getConsentSettings(): Promise<ConsentConfig> {
+  "use cache: remote"
+  cacheLife("catalog")
+  cacheTag("catalog")
+  const { consent } = await getConsent(storeClient)
+  return consent
+}
+
+async function readTracking(): Promise<TrackingConfig> {
+  "use cache: remote"
+  cacheLife("catalog")
+  cacheTag("catalog")
+  return getTrackingConfig(storeClient)
+}
+
+/** The store's marketing tags; null when the platform does not answer, so no tag mounts. */
+export async function getTracking(): Promise<TrackingConfig | null> {
+  return readTracking().catch(() => null)
+}
+
+async function readMenu(handle: string): Promise<Menu | null> {
+  "use cache: remote"
+  cacheLife("catalog")
+  cacheTag("catalog")
+  try {
+    const { menu } = await getMenu(storeClient, handle)
+    return menu
+  } catch (error) {
+    if (isNotFound(error)) return null
+    throw error
+  }
+}
+
+/** One menu by handle, or null: a store with no menus 404s every handle (menus.md). */
+export async function getMenuSafe(handle: string): Promise<Menu | null> {
+  return readMenu(handle).catch(() => null)
+}
+
+/** One product by handle, priced; null for a handle the store does not have. */
+export async function getProduct(handle: string): Promise<StoreProduct | null> {
+  "use cache: remote"
+  cacheLife("catalog")
+  cacheTag("catalog")
+  try {
+    const { product } = await retrieveProduct(storeClient, handle, PRICING_CONTEXT)
+    return product
+  } catch (error) {
+    if (isNotFound(error)) return null
+    throw error
+  }
+}
+
+/** The platform's largest page of products. */
+const PAGE = 200
+
+/** Every product handle, for the product pages the build prerenders. */
+export async function listProductHandles(): Promise<string[]> {
+  const handles: string[] = []
+  for (let offset = 0; ; offset += PAGE) {
+    const { products, count } = await listProducts(storeClient, { limit: PAGE, offset })
+    handles.push(...products.map((product) => product.handle).filter(Boolean))
+    if (!products.length || offset + PAGE >= count) return handles
+  }
+}

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

@@ -15,13 +15,13 @@ export const BARTER_URL = cartbaseApiOrigin(process.env.NEXT_PUBLIC_CARTBASE_URL
 export const BARTER_CLIENT_ID = process.env.NEXT_PUBLIC_CARTBASE_CLIENT_ID || undefined
 
 /**
- * Cart-id cookie — owned by the app (the SDK never persists the cart);
- * the NAME is owned by the library so every consumer emits the same wire
- * fingerprint (platform-fingerprints card). `readCartCookie` is the
- * backward-compat reader for the legacy `_barter_cart_id` name.
+ * Cart-id cookie: the app decides when it is written (providers.tsx hands
+ * `writeCartCookie` to the drawer); the NAME and shape are the library's so
+ * every consumer emits the same wire fingerprint (platform-fingerprints
+ * card). `readCartCookie` is the backward-compat reader for the legacy
+ * `_barter_cart_id` name, which the checkout uses on the server.
  */
 export { CART_COOKIE, readCartCookie } from "@cartbase/storefront/lib/cookie-names"
-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"

package/template/app/src/lib/store-client.ts

@@ -0,0 +1,16 @@
+import { StorefrontClient } from "@cartbase/storefront/api/http"
+import { BARTER_CLIENT_ID, BARTER_PUBLISHABLE_KEY, BARTER_URL } from "./config"
+
+/**
+ * The catalogue's client on the server (runbook step 2): the store's key and
+ * nothing about the visitor. It reads no cookie, so every read made with it
+ * can be cached (`lib/catalog.ts`) and every page built from those reads is
+ * prerendered. A store with one language and no customer prices has nothing
+ * in its catalogue that depends on who asks. Reads that belong to one
+ * visitor (the checkout's cart) use `getServerClient` instead.
+ */
+export const storeClient = new StorefrontClient({
+  baseUrl: BARTER_URL,
+  clientId: BARTER_CLIENT_ID,
+  publishableKey: BARTER_PUBLISHABLE_KEY,
+})