create-cartbase 0.0.1 → 0.1.1

package/template/app/docs/search.md

@@ -0,0 +1,218 @@
+# Search & related products
+
+Configurable storefront search (search-discovery card) plus the PDP's
+related-products rail. Results are the SAME canonical product objects the
+products listing serves (see products.md) — reuse your product-card renderer
+as-is. Money is EUR decimal major units.
+
+SDK module: `@cartbase/storefront/api/search`.
+
+**Matching** — title/subtitle/description full-text (Cyrillic-correct
+'simple' config, prefix match) ∪ typo tolerance via trigram similarity on
+the title ("linnen" finds "Linen Shirt") ∪ SKU prefix ∪ exact tag value.
+Draft products, other tenants, and products outside the publishable key's
+channels NEVER appear.
+
+**Synonyms (admin-authored)** — expansion is BIDIRECTIONAL and SINGLE-LEVEL
+(bounded — expansions never re-expand; capped at 24 terms): a query word
+matching a row's term adds its synonyms; a query word matching one of a
+row's synonyms adds the term + its sibling synonyms. So with the admin row
+`term: "зехтин", synonyms: ["olive oil"]`, EITHER direction finds the
+product. Terms are normalized lowercase.
+
+**Pins & boosts (admin-authored)** — ordering is: (1) pins for this EXACT
+normalized query, in position order — pins are INJECTED even without a text
+match, but only if they pass filters + channel scope + published (the leak
+rule applies to pins too); then (2) globally-boosted products WITHIN the
+match set, in position order; then (3) relevance rank with a deterministic
+tie-break. Global boosts reorder, never inject.
+
+**Cache rule** — responses carry `calculated_price` when a pricing context
+is given; they vary by customer group — never cache shared when a JWT was
+present.
+
+---
+
+## GET /api/store/products/search
+
+- **Purpose** — the search results page + autocomplete backend.
+- **Auth** — anon: `x-client-id` required; `x-publishable-api-key` optional
+  (channel scope, products-listing semantics); Bearer JWT optional (group
+  pricing).
+- **Request**
+
+```jsonc
+// query — q is REQUIRED (min 1 char), everything else optional
+{
+  "q": "linen",
+  "collection_id": "pcol_a,pcol_b", // CSV
+  "category_id": "pcat_a",          // CSV
+  "tag_id": "ptag_a",               // CSV
+  "type_id": "ptyp_a",              // CSV
+  "price_min": 10,                  // major units, on the product's cheapest base price
+  "price_max": 50,
+  "availability": "in_stock",       // in_stock | out_of_stock
+  // Option filters — dynamic keys, repeatable; OR within an option, AND
+  // across options. URL-encode titles ("Length (cm)" → option.Length%20(cm)):
+  "option.Size": "S,M",
+  "currency_code": "eur",           // pricing context (default price facet currency: eur)
+  "region_id": "reg_…",
+  "limit": 20,                      // 1–100, default 20
+  "offset": 0
+}
+```
+
+- **Response**
+
+```jsonc
+{
+  "results": [ /* canonical product objects — see products.md */ ],
+  "facets": [
+    {
+      "key": "price",              // "price" | "availability" | "type" |
+                                   // "tags" | "collection" | "options.<Title>"
+      "label": "Price",
+      "type": "range",             // "range" for price, "value" otherwise
+      "buckets": [
+        { "value": "20-40", "label": "€20 – €40", "count": 3,
+          "min": 20, "max": 40 }   // min/max on range buckets only; max null = open top
+      ]
+    },
+    {
+      "key": "availability", "label": "Availability", "type": "value",
+      "buckets": [ { "value": "in_stock", "label": "In stock", "count": 5 } ]
+    }
+  ],
+  "total": 5,
+  "offset": 0,
+  "limit": 20
+}
+```
+
+  **Facets** follow the tenant's Settings → Search & discovery → Filters
+  config (order + enabled; defaults: price, availability, type, tags,
+  collection). **The faceting count rule:** each facet's bucket counts are
+  computed on the result set filtered by every OTHER active filter — the
+  facet's own dimension is excluded, so selecting "Size: M" never zeroes the
+  other sizes. Empty buckets are omitted; a facet with no buckets is
+  omitted (the dev tenant has no tags/types, so those facets simply don't
+  appear). Price buckets: `auto` (deterministic nice-number split of
+  observed prices, ≤10 buckets) or `fixed` admin ranges; apply one by
+  passing its `min`/`max` back as `price_min`/`price_max`. Value-facet
+  buckets carry ids as `value` (type/tags/collection) or the option value
+  string (`options.<Title>`).
+
+- **Working curl** — seeded catalog: Linen Shirt (45), Wool Beanie (23),
+  Leather Belt (60), all in the `essentials` collection:
+
+```bash
+SEARCH=$(curl -sf "$BASE/api/store/products/search?q=linen&currency_code=eur" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$SEARCH" | grep -q '"results"'
+echo "$SEARCH" | grep -q '"facets"'
+echo "$SEARCH" | grep -q '"total"'
+echo "$SEARCH" | grep -q '"handle":"linen-shirt"'
+echo "$SEARCH" | grep -q '"calculated_price"'
+# Default facet config puts price + availability on a priced, stocked catalog:
+echo "$SEARCH" | grep -q '"key":"price"'
+echo "$SEARCH" | grep -q '"key":"availability"'
+```
+
+```bash
+# Typo tolerance (title trigram): "linnen" still finds the Linen Shirt.
+curl -sf "$BASE/api/store/products/search?q=linnen" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"handle":"linen-shirt"'
+# SKU prefix match:
+curl -sf "$BASE/api/store/products/search?q=LIN-SHIRT" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"handle":"linen-shirt"'
+```
+
+```bash
+# Option filter: only the Linen Shirt has Size S; the beanie (Color) and the
+# belt (Length (cm)) don't match option.Size at all.
+OPT=$(curl -sf "$BASE/api/store/products/search?q=linen&option.Size=S" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$OPT" | grep -q '"handle":"linen-shirt"'
+# A value no variant carries → empty result set (envelope intact):
+curl -sf "$BASE/api/store/products/search?q=linen&option.Size=XXL" \
+  -H "x-client-id: $CLIENT_ID" | grep -q '"results":\[\]'
+```
+
+```bash
+# Channel scope: the dev PUBLISHABLE_KEY is bound to the B2B channel
+# (shirt + beanie). "leather" matches anon but returns nothing under the key.
+curl -sf "$BASE/api/store/products/search?q=leather" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"handle":"leather-belt"'
+curl -sf "$BASE/api/store/products/search?q=leather" \
+  -H "x-client-id: $CLIENT_ID" -H "x-publishable-api-key: $PUBLISHABLE_KEY" \
+  | grep -q '"results":\[\]'
+```
+
+- **Errors** — 400 `validation_failed` (missing/empty `q`, bad
+  `availability`, limit > 100), 400 `missing_client_id`,
+  400 `invalid_publishable_key`, 400 `invalid_region`.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/products/search" -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 400
+curl -s "$BASE/api/store/products/search" -H "x-client-id: $CLIENT_ID" \
+  | grep -q '"code":"validation_failed"'
+```
+
+- **SDK** — `searchProducts(client, query)` — pass option filters as
+  `options: { Size: ["S","M"] }`; the SDK folds them into `option.<Title>`
+  params.
+- **Components** — search page, facet sidebar, autocomplete.
+- **Settings** — Search & discovery: synonyms, pins (per-query) + global
+  boosts, facet order/enabled, price bucket strategy (auto/fixed).
+
+---
+
+## GET /api/store/products/:idOrHandle/related
+
+- **Purpose** — the PDP's related-products rail. Manual admin picks first
+  (position order), then a DETERMINISTIC fallback fills to `limit`: same
+  primary collection (newest first), then most-shared-tags.
+  `auto_filled: true` when any fallback item is present.
+- **Auth** — anon: `x-client-id`; optional publishable key — the anchor
+  product must be visible to the key, and scoped-away products never appear
+  as related items; optional Bearer JWT (group pricing).
+- **Request** — query `{ limit? (1–24, default 12), currency_code?,
+  region_id? }`. Accepts a product id (`prod_…`) or handle.
+- **Response**
+
+```jsonc
+{
+  "products": [ /* canonical product objects, self-excluded */ ],
+  "count": 2,
+  "auto_filled": true   // at least one item came from the fallback chain
+}
+```
+
+- **Working curl** — the seeded products share the `essentials` collection,
+  so the shirt's rail fills from it:
+
+```bash
+RELATED=$(curl -sf "$BASE/api/store/products/linen-shirt/related?currency_code=eur" \
+  -H "x-client-id: $CLIENT_ID")
+echo "$RELATED" | grep -q '"products"'
+echo "$RELATED" | grep -q '"auto_filled"'
+echo "$RELATED" | grep -q '"count"'
+```
+
+- **Errors** — 404 `not_found` (unknown id/handle, draft, or anchor outside
+  the key's channels), 400 `validation_failed`, 400 `invalid_region`.
+
+```bash
+# Channel scope on the ANCHOR: the belt is outside the B2B key's channels.
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' \
+  "$BASE/api/store/products/leather-belt/related" \
+  -H "x-client-id: $CLIENT_ID" -H "x-publishable-api-key: $PUBLISHABLE_KEY")
+test "$STATUS" = 404
+```
+
+- **SDK** — `listRelatedProducts(client, idOrHandle, query?)`.
+- **Components** — PDP related rail.
+- **Settings** — manual picks: Admin → Product → Related (drag-ordered,
+  ≤24); the fallback chain needs no configuration.

package/template/app/docs/subscriptions.md

@@ -0,0 +1,148 @@
+# Subscriptions — the customer portal
+
+The "My subscriptions" surface (subscriptions-portal card): list, detail,
+schedule control, contract edits, cancel/reactivate and payment-method
+recovery. Every endpoint requires a **customer session**
+(`authorization: Bearer <supabase jwt>` — see [auth.md](auth.md)) **plus**
+`x-client-id`. Missing/invalid JWT → `401 {code: "unauthenticated"}`;
+a subscription that isn't the caller's own → **`404 not_found`** (never
+403 — existence is not confirmed across accounts).
+
+The API contract (all routes, shapes, error codes):
+`docs/contracts/store-api.md` § Subscriptions portal. This doc is the
+component-facing guide.
+
+> The executable blocks prove the **auth boundary** — the docs harness is
+> anonymous; happy paths are pinned by
+> `tests/store/subscriptions-portal.test.ts` and
+> `tests/store/subscription-payment-update.test.ts` with real sessions.
+
+## Render actions from `permissions` — never hardcode
+
+Every detail payload carries the merchant's live portal policy:
+
+```jsonc
+"permissions": {
+  "allow_skip": true,              // merchant toggles (Settings → Subscriptions)
+  "allow_reschedule": true,
+  "allow_pause": true,
+  "allow_frequency_change": true,
+  "allow_line_edits": true,
+  "allow_address_change": true,
+  "allow_cancel": true,            // constant — cancel is a customer right
+  "can_update_payment": false      // true only for card (Stripe) contracts
+}
+```
+
+Components MUST render conditionally from this object — a toggled-off
+action answers `403 {code: "portal_action_disabled"}`, so hiding the button
+is UX, the server is the enforcement. Cancel is ALWAYS shown (the cancel
+law: retention offers may render alongside, never instead). Payment update
+renders only when `can_update_payment` — COD/offline contracts have no card.
+
+## GET /api/store/subscriptions — my contracts
+
+`{ subscriptions: [...], count }` — newest first. `payment_method` is the
+merchant-facing display name from the payments registry (never `pp_*`).
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/store/subscriptions" \
+  -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 401
+```
+
+## GET /api/store/subscriptions/:id — the receipt view
+
+Sanitized detail: `plan`, `lines` (titles + contracted `unit_price`),
+`cycles` (index, status, date, linked order display id — no internal error
+strings), `upcoming` (next 3 PROJECTED charge dates; empty unless active)
+and `permissions`. Render the cycle list as order history; a `failed` cycle
+plus `can_update_payment` is the cue to surface the payment-update flow
+prominently (that pairing IS dunning recovery).
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' "$BASE/api/store/subscriptions/sub_doesnotexist" \
+  -H "x-client-id: $CLIENT_ID")
+test "$STATUS" = 401
+```
+
+## Actions
+
+All POST, all answer `{ subscription }` (the fresh detail — re-render from
+it, no refetch needed):
+
+| Route | Body | Gate |
+|---|---|---|
+| `/:id/skip` | — | `allow_skip` |
+| `/:id/charge-date` | `{ next_charge_at }` | `allow_reschedule` |
+| `/:id/pause` | `{ until? }` | `allow_pause` |
+| `/:id/resume` | — | right |
+| `/:id/cancel` | `{ reason? }` | right |
+| `/:id/reactivate` | `{ next_charge_at? }` | right |
+| `/:id/address` | `{ shipping_address }` | `allow_address_change` |
+| `/:id/lines/:lineId` | `{ quantity?, variant_id? }` | `allow_line_edits` |
+| `/:id/plan` | `{ selling_plan_id }` | `allow_frequency_change` |
+
+Component notes:
+
+- **Skip** — confirm-dialog copy should show the NEW next date (current
+  next date + one plan interval). A cycle mid-payment-retry cannot skip
+  (400) — hide skip while the latest cycle is `failed`.
+- **Pause** — offer preset durations (1/2/3 months → `until`); an `until`
+  pause auto-resumes server-side, no customer action needed. Indefinite
+  pause (no body) needs an explicit Resume.
+- **Reactivate** — render on canceled contracts; default schedule is
+  now + interval and it NEVER charges immediately — say so in the copy.
+- **Swap / frequency** — variant options come from the product's variants
+  (same product only); frequency options are the product's other selling
+  plans (`GET /api/store/products/:id/selling-plans`). Both re-price
+  server-side through the one price engine — display the returned
+  `unit_price`, never compute prices client-side.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' -X POST "$BASE/api/store/subscriptions/sub_doesnotexist/cancel" \
+  -H "x-client-id: $CLIENT_ID" -H "content-type: application/json" -d '{}')
+test "$STATUS" = 401
+```
+
+## Payment-method update (dunning recovery)
+
+Two steps, card contracts only:
+
+1. `POST /:id/payment-method/session` → `{ session: { setup_intent_id,
+   client_secret, publishable_key } }`.
+2. Confirm client-side with Stripe.js — card fields never touch Cartbase:
+
+```jsonc
+// stripe = Stripe(session.publishable_key)
+// elements = stripe.elements({ clientSecret: session.client_secret })
+// mount PaymentElement, then:
+// await stripe.confirmSetup({ elements, redirect: "if_required" })
+```
+
+3. `POST /:id/payment-method` with `{ setup_intent_id }` → verified +
+   stamped; the response is the fresh detail. The next renewal charge (the
+   automatic retry ladder or the merchant's "Retry now") uses the new card.
+
+Entry points to build: the payment-failed email links here; the detail view
+surfaces it on `failed` cycles; the account shell may badge past-due
+subscriptions.
+
+```bash
+STATUS=$(curl -s -o /dev/null -w '%{http_code}' -X POST "$BASE/api/store/subscriptions/sub_doesnotexist/payment-method/session" \
+  -H "x-client-id: $CLIENT_ID" -d '')
+test "$STATUS" = 401
+```
+
+## Checkout + confirmation touchpoints
+
+- **Consent line at checkout**: subscription carts save the card for future
+  charges (`setup_future_usage: off_session`) — the checkout MUST show the
+  mandate text next to the pay button. [checkout.md](checkout.md) documents
+  the duty; the component ships with the portal family.
+- **Order confirmation**: a completed subscription checkout returns
+  contracts (cycle 1 = that order) — show "subscription started, next
+  charge on <date>" from the order's subscription metadata.
+- **PDP purchase options**: `GET /api/store/products/:id/selling-plans`
+  (see [products.md](products.md)) — the plan chosen at PDP rides the cart
+  line as `selling_plan_id`.

package/template/app/next.config.ts

@@ -0,0 +1,34 @@
+import path from "node:path"
+import type { NextConfig } from "next"
+
+const nextConfig: NextConfig = {
+  // Monorepo: pin the workspace root (Next otherwise infers it from a
+  // stray lockfile OUTSIDE the repo and mis-roots the dev module graph).
+  outputFileTracingRoot: path.join(__dirname, "../.."),
+  // The smoke driver browses via 127.0.0.1; allow dev-resource access.
+  allowedDevOrigins: ["127.0.0.1"],
+  // @cartbase/storefront is source-shipped TypeScript (workspace package) —
+  // the app's Next build transpiles it.
+  transpilePackages: ["@cartbase/storefront"],
+  images: {
+    // Reference app: seeded product images live on arbitrary demo hosts.
+    // A real store should allowlist its media domain via remotePatterns.
+    unoptimized: true,
+  },
+  // The Cartbase store API ships NO CORS headers — browser-side SDK calls
+  // must be same-origin. Proxy them through the app origin (the browser
+  // client's baseUrl is window.location.origin); server-side SDK calls go
+  // straight to NEXT_PUBLIC_CARTBASE_URL and are unaffected.
+  async rewrites() {
+    const barterUrl = process.env.NEXT_PUBLIC_CARTBASE_URL
+    if (!barterUrl) return []
+    return [
+      {
+        source: "/api/store/:path*",
+        destination: `${barterUrl}/api/store/:path*`,
+      },
+    ]
+  },
+}
+
+export default nextConfig

package/template/app/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "cartbase-storefront",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Reference storefront built from docs/storefront/BUILD-A-STOREFRONT.md alone — the adoption proof for @cartbase/storefront.",
+  "scripts": {
+    "dev": "next dev --webpack -p 4778",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@cartbase/storefront": "^0.2.0",
+    "next": "16.2.4",
+    "react": "19.2.4",
+    "react-dom": "19.2.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "autoprefixer": "^10.4.20",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5"
+  }
+}

package/template/app/postcss.config.cjs

@@ -0,0 +1,6 @@
+module.exports = {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+}

package/template/app/smoke.mjs

@@ -0,0 +1,158 @@
+/**
+ * Adoption-proof smoke: drives the REAL example-storefront UI from home to
+ * a completed pp_manual checkout against the barter backend.
+ *
+ * Prereqs: backend on :4777, example app on :4778 (see examples/storefront
+ * package.json). Run: `node examples/storefront/smoke.mjs` from the repo
+ * root (Playwright is a root devDependency). Exits 0 only when the
+ * confirmation page shows an order number and totals.
+ */
+import { chromium } from "@playwright/test"
+
+const BASE = process.env.SMOKE_BASE_URL ?? "http://127.0.0.1:4778"
+const trail = []
+const step = (msg) => {
+  trail.push(msg)
+  console.log(`[smoke] ${msg}`)
+}
+
+const browser = await chromium.launch()
+const page = await browser.newPage()
+page.setDefaultTimeout(30_000)
+
+try {
+  // ── Home ────────────────────────────────────────────────────────────
+  await page.goto(`${BASE}/`, { waitUntil: "domcontentloaded" })
+  step("home loaded")
+
+  // Consent banner (builtin modal is the server default) — accept.
+  const acceptButton = page.getByRole("button", { name: "Accept", exact: true })
+  try {
+    await acceptButton.waitFor({ state: "visible", timeout: 10_000 })
+    await acceptButton.click()
+    step("consent banner accepted")
+  } catch {
+    step("no consent banner rendered (disabled or external mode)")
+  }
+
+  await page.locator('a[href^="/products/"]').first().waitFor()
+  step("home renders product cards")
+
+  // ── PDP (seeded handle) ─────────────────────────────────────────────
+  await page.goto(`${BASE}/products/linen-shirt`, {
+    waitUntil: "domcontentloaded",
+  })
+  await page.getByTestId("product-container").waitFor()
+  step("PDP linen-shirt rendered")
+
+  // Pick the REAL Size option's "M" (the shared dev tenant accretes junk
+  // options; variant match needs exactly the Size choice). Dev-mode
+  // hydration can lag the SSR paint — retry until the selection sticks.
+  const sizeRow = page
+    .locator('div.flex.flex-col:has(> span:text-is("Select Size"))')
+    .first()
+  const mButton = sizeRow.getByRole("button", { name: "M", exact: true })
+  let selected = false
+  for (let i = 0; i < 30 && !selected; i++) {
+    await mButton.click()
+    await page.waitForTimeout(700)
+    selected = ((await mButton.getAttribute("class")) ?? "").includes(
+      "border-primary"
+    )
+  }
+  if (!selected) throw new Error("Size M never became selected")
+  step("selected Size M")
+
+  const addButton = page.getByTestId("add-product-button").first()
+  await addButton.click()
+  step("clicked Add to cart")
+
+  // ── Cart drawer → checkout ──────────────────────────────────────────
+  // The drawer auto-opens only on a rise from a nonzero base (first add
+  // never auto-opens — components.md); open it via the header cart
+  // button once the badge confirms the server-side add landed.
+  await page
+    .getByTestId("nav-cart-link")
+    .locator("span")
+    .filter({ hasText: /^\d+$/ })
+    .waitFor({ timeout: 20_000 })
+  step("header cart badge shows the added item")
+  await page.getByTestId("nav-cart-link").click()
+  const checkoutLink = page.getByRole("link", { name: "Checkout" })
+  await checkoutLink.click()
+  step("cart drawer opened via header cart button")
+  await page.waitForURL("**/checkout")
+  step("navigated to /checkout")
+
+  // ── Address form ────────────────────────────────────────────────────
+  const fill = async (name, value) => {
+    await page.locator(`[name="${name}"]`).fill(value)
+  }
+  await fill("email", "smoke-adoption@example.test")
+  await fill("shipping_address.first_name", "Ivan")
+  await fill("shipping_address.last_name", "Petrov")
+  await fill("shipping_address.address_1", "ul. Vitosha 15")
+  await fill("shipping_address.postal_code", "1000")
+  await fill("shipping_address.city", "Sofia")
+  await fill("shipping_address.phone", "+359888123456")
+  await page.locator('[name="shipping_address.phone"]').blur()
+  step("address form filled (BG address, EUR cart)")
+
+  // ── Shipping method ─────────────────────────────────────────────────
+  await page.getByText("Flat Rate (Bulgaria)", { exact: false }).first().click()
+  step('selected shipping "Flat Rate (Bulgaria)"')
+
+  // ── Payment: manual/offline tab (no Stripe env) ─────────────────────
+  const codTab = page.getByRole("button", { name: "Cash on delivery" })
+  await codTab.waitFor({ state: "visible" })
+  await codTab.click()
+  step("selected manual payment (pp_manual offline tab)")
+
+  // ── Place order ─────────────────────────────────────────────────────
+  const submit = page.getByTestId("submit-order-button")
+  await submit.waitFor({ state: "visible" })
+  // The Buy button enables once the debounced address autosave lands.
+  await page.waitForFunction(
+    () =>
+      !document.querySelector('[data-testid="submit-order-button"]')?.disabled,
+    undefined,
+    { timeout: 20_000 }
+  )
+  await submit.click()
+  step("clicked Place order")
+
+  // ── Confirmation ────────────────────────────────────────────────────
+  await page.waitForURL("**/order/**/confirmed", { timeout: 60_000 })
+  step(`confirmation URL: ${new URL(page.url()).pathname}`)
+
+  const orderNumberText = await page
+    .getByText(/#\d+/)
+    .first()
+    .innerText({ timeout: 30_000 })
+  const displayNumber = orderNumberText.match(/#(\d+)/)?.[1]
+  if (!displayNumber) throw new Error("no order display number rendered")
+  step(`order number rendered: #${displayNumber}`)
+
+  // Totals: the order family renders a Total row with a EUR amount.
+  const totalRow = page
+    .locator("div,li")
+    .filter({ hasText: /^Total/ })
+    .filter({ hasText: "€" })
+    .first()
+  const totalText = (await totalRow.innerText()).replace(/\s+/g, " ").trim()
+  if (!/€\s?\d/.test(totalText)) throw new Error("no EUR total rendered")
+  step(`totals rendered: ${totalText}`)
+
+  console.log("\n[smoke] PASS — completed checkout, order #" + displayNumber)
+  await browser.close()
+  process.exit(0)
+} catch (err) {
+  console.error("\n[smoke] FAIL after steps:\n - " + trail.join("\n - "))
+  console.error(err)
+  try {
+    await page.screenshot({ path: "examples/storefront/smoke-failure.png" })
+    console.error("[smoke] screenshot: examples/storefront/smoke-failure.png")
+  } catch {}
+  await browser.close()
+  process.exit(1)
+}

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

@@ -0,0 +1,66 @@
+"use client"
+
+import { useRouter } from "next/navigation"
+import type { Cart } from "@cartbase/storefront/api/carts"
+import type { StoreShippingOption } from "@cartbase/storefront/api/checkout"
+import type { StorePaymentProvider } from "@cartbase/storefront/api/checkout"
+import type { PublicCodConfig } from "@cartbase/storefront/api/integrations"
+import { CheckoutProvider } from "@cartbase/storefront/checkout/context"
+import { CheckoutClient } from "@cartbase/storefront/checkout/checkout-client"
+import { browserClient } from "@/lib/browser-client"
+
+/** sessionStorage key the confirmation page reads (guests have no order
+ * read endpoint — the completeCart() response is the only order handle,
+ * orders.md). */
+export const LAST_ORDER_STORAGE_KEY = "barter:last-order"
+
+export function CheckoutPageClient({
+  cart,
+  shippingOptions,
+  paymentProviders,
+  codConfig,
+}: {
+  cart: Cart
+  shippingOptions: StoreShippingOption[]
+  paymentProviders: StorePaymentProvider[]
+  codConfig: PublicCodConfig | null
+}) {
+  const router = useRouter()
+
+  return (
+    <CheckoutProvider orderConfirmedPath="/order/{id}/confirmed">
+      <CheckoutClient
+        client={browserClient}
+        cart={cart}
+        customer={null}
+        availableShippingMethods={shippingOptions}
+        availablePaymentMethods={paymentProviders}
+        countryCode="bg"
+        countries={[{ iso_2: "bg", display_name: "Bulgaria" }]}
+        // Per-store rule (the documented paymentMethodFilter seam): this
+        // reference store checks out offline via pp_manual only — without
+        // the filter the hook prefers a tenant-enabled pp_cod for the
+        // offline tab.
+        paymentMethodFilter={(methods) =>
+          methods?.filter((m) => m.id === "pp_manual") ?? null
+        }
+        codConfig={codConfig}
+        onOrderPlaced={(order) => {
+          // Guest order handle = the completeCart() response (orders.md).
+          // Stash it (+ the decorated cart lines for the items list) for
+          // the confirmation page, then navigate.
+          try {
+            sessionStorage.setItem(
+              LAST_ORDER_STORAGE_KEY,
+              JSON.stringify({ order, cartItems: cart.items ?? [] })
+            )
+          } catch {
+            // best-effort — the confirmation page has a fallback state
+          }
+          router.push(`/order/${order.id}/confirmed`)
+        }}
+        onCartChange={() => router.refresh()}
+      />
+    </CheckoutProvider>
+  )
+}