create-cartbase 0.1.5 → 0.1.7

package/template/app/docs/deploy.md

@@ -5,7 +5,10 @@ Cartbase builds and hosts your storefront. You send the app's source files
 running site: first on a **permanent preview URL**, then, when you press
 **Publish** (or call the publish endpoint), on the store's live domain.
 You never touch build servers, DNS, or hosting configuration; the platform
-provisions all of it on your first deploy.
+provisions all of it the moment the store is created, and makes the first
+deploy itself: the store's starting point, a complete storefront on your
+own (still empty) catalog, already running on the preview link. Pull it
+with the CLI, change anything, deploy it back.
 
 Two URLs exist per store, both created automatically:
 
@@ -56,24 +59,25 @@ Error codes you can hit: `empty_bundle`, `bundle_too_large`,
 
 ## Environment — provided, not configured
 
-Hosted storefronts receive the three runbook inputs automatically at
-build time; do **not** put them in the bundle (`.env*` files are blocked
+Hosted storefronts receive their store's values automatically at build
+time; do **not** put them in the bundle (`.env*` files are blocked
 anyway):
 
 | Variable | Value |
 |---|---|
-| `NEXT_PUBLIC_CARTBASE_URL` | The store's API origin |
-| `NEXT_PUBLIC_CARTBASE_CLIENT_ID` | The store's client id |
-| `NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY` | The store's publishable key, when one exists |
+| `NEXT_PUBLIC_CARTBASE_PUBLISHABLE_KEY` | The store's publishable key, the one input a storefront needs |
+| `NEXT_PUBLIC_CARTBASE_URL` | The platform origin (a constant; injected so a hosted build never guesses) |
+| `NEXT_PUBLIC_CARTBASE_CLIENT_ID` | The store's id, the platform's own door; a storefront never needs to copy it |
 
 Only these public values ever reach a storefront build — secret keys are
 never injected, so code that expects one is a design error.
 
 ## Deploy to preview
 
-`POST /api/admin/storefront/deploys` — the one ingestion door. The first
-call on a store also provisions its hosting (takes a few extra seconds);
-every later call is just a deploy.
+`POST /api/admin/storefront/deploys` — the one ingestion door. Hosting is
+provisioned when the store is born, so every call is just a deploy; on a
+store whose hosting setup failed, the first call resumes it (a few extra
+seconds).
 
 ```bash
 # doc-noexec — admin-session auth; run from an authenticated context.
@@ -153,7 +157,8 @@ curl -s "$BASE/api/admin/storefront"
 }
 ```
 
-`storefront` is `null` until the store's first deploy. `status:
+`storefront` is present from the store's birth (`null` only on a store
+created before hosting-at-birth that has never deployed). `status:
 "provisioning"` / `"failed"` (with `last_error`) describe hosting setup,
 not builds; a failed provisioning resumes automatically on the next
 deploy attempt.

package/template/app/docs/integrations.md

@@ -56,6 +56,10 @@ key-by-key.
     "ga4": { "measurementId": "G-…" },
     "klaviyo": { "publicKey": "…" },
     "googleAds": { "conversionId": "AW-…", "conversionLabel": "…" },
+    // Pixel id only. The TikTok Events API token stays on the platform
+    // and is used by the order.placed forwarder, exactly like Meta's
+    // CAPI token, which has never appeared on this endpoint.
+    "tiktok": { "pixelId": "C…" },
     "consent_required": true     // always present — mirrors the consent CMP's enabled
   }
 }
@@ -64,7 +68,10 @@ key-by-key.
 - **Errors**: `400 missing_client_id` · `400 invalid_publishable_key`.
 - **SDK**: `integrations.getIntegrationsConfig(client)`
 - **Components**: carrier/locker pickers, COD fee row in checkout, tracking
-  mounts (`<MetaPixel>/<GA4>/<Gtm>` behind the consent gate).
+  mounts (`<MetaPixel>/<GoogleTag>/<TikTokPixel>/<Gtm>` behind the consent
+  gate). `<GoogleTag measurementId adsConversionId>` takes BOTH Google
+  destinations: one loader, two `config` calls, which is Google's own
+  instruction and is what lets Consent Mode gate the Ads tag for free.
 - **Settings**: admin → Settings → Integrations (per-provider enable +
   config); consent settings drive `tracking.consent_required`; Rybbit is
   deliberately ABSENT (platform analytics, not a tenant integration).
@@ -72,8 +79,13 @@ key-by-key.
 Tracking wiring contract: mount tags only through the consent gate when
 `consent_required` (see [consent.md](consent.md)); Purchase events MUST use
 `eventID = "purchase_" + order.display_id` so Meta dedupes browser Pixel vs
-server CAPI; write TrackingAttribution keys into `cart.metadata`
-(consent-gated) so server events inherit fbp/fbc/anon-id/ga signals.
+server CAPI, and `event_id = "tt_purchase_" + order.display_id` for TikTok;
+write TrackingAttribution keys into `cart.metadata` (consent-gated) so
+server events inherit fbp/fbc/anon-id/ga signals AND the ad-click ids
+(`tt_ttclid`, `tt_ttp`, `google_gclid`, `google_gbraid`, `google_wbraid`)
+that let TikTok and Google tie a conversion back to the click that caused
+it. Capture those with `captureClickIdsFromUrl()` beside
+`captureUtmsFromUrl()`.
 
 ```bash
 BODY=$(curl -sf "$BASE/api/store/integrations" -H "x-client-id: $CLIENT_ID")

package/template/app/docs/platform.md

@@ -88,7 +88,7 @@ window.Cartbase").
 ```tsx
 // app/layout.tsx, inside <body>, first children:
 <ConsentInit />
-<PlatformInit storeId={CARTBASE_CLIENT_ID} />
+<PlatformInit storeId={store.id} />   // from GET /api/store/store (store.md)
 ```
 
 Also build-time/render-only — no store-API curl to demonstrate; the exact

package/template/app/docs/store.md

@@ -0,0 +1,47 @@
+# Store
+
+The store's own identity: its name, its slug and its brand (what the
+merchant set under Settings → Brand). One anonymous read, usually at
+layout level, so a storefront titles, heads and foots itself with the
+merchant's name and never hardcodes one. Logo URLs are public. Colors are
+`#rrggbb`. Every field except `name` and `slug` may be null.
+
+SDK module: `@cartbase/storefront/api/store` (from 0.8.0; on 0.7.0 call
+`client.request("/api/store/store")` with the same shape).
+
+---
+
+## GET /api/store/store
+
+- **Purpose** — read the store's id, name, slug and brand.
+- **Auth** — anon: the store's publishable key (`x-publishable-api-key`).
+- **Request** — `GET /api/store/store`
+- **Response 200**
+
+```jsonc
+{
+  "store": {
+    "id": "1e7a4c02-9b31-4f7e-8d2a-5c6f90ab12cd",   // the store's public id (what PlatformInit mounts)
+    "name": "Demo Store",
+    "slug": "demo-store",
+    "brand": {
+      "logo_url": "https://…/brand/…/logo.png",   // or null
+      "logo_square_url": null,
+      "color_primary": "#111111",                  // or null
+      "color_secondary": null,
+      "slogan": null
+    }
+  }
+}
+```
+
+- **Errors** — `404 store_not_found` when the key names no live store.
+
+```ts
+import { getStore } from "@cartbase/storefront/api/store"
+
+export async function generateMetadata() {
+  const { store } = await getStore(await getServerClient())
+  return createStorefrontMetadata({ title: store.name, description: store.brand.slogan ?? undefined })
+}
+```

package/template/app/docs/variables.md

@@ -58,7 +58,7 @@ Every customer notification carries it. Money is formatted in the order's own cu
 | `{{ order.email }}` | The address the order was placed with. | email |  |
 | `{{ order.date }}` | When the order was placed. | date |  |
 | `{{ order.status }}` | Lifecycle state: pending, completed, canceled or archived. | text |  |
-| `{{ order.payment_status }}` | Paid, Awaiting payment, Refunded and so on, in the same words the admin uses. | text |  |
+| `{{ order.payment_status }}` | Paid, Unpaid, Partially paid, Refunded and so on, in the same words the admin uses. | text |  |
 | `{{ order.fulfillment_status }}` | Unfulfilled, Shipped, Delivered and so on, in the same words the admin uses. | text |  |
 | `{{ order.locale }}` | Language the customer shopped in, when the storefront sends one. | text |  |
 | `{{ order.cancelled_at }}` | When the order was cancelled, if it was. | datetime |  |
@@ -70,7 +70,7 @@ Every customer notification carries it. Money is formatted in the order's own cu
 | `{{ order.shipping }}` | What delivery cost the customer. | money |  |
 | `{{ order.discount }}` | Total discount applied to the order. | money |  |
 | `{{ order.payment_method_fee }}` | The fee of the payment method the customer chose (a COD courier fee, a handling fee on a manual method). | money |  |
-| `{{ order.paid }}` | How much has actually been captured so far. | money |  |
+| `{{ order.paid }}` | How much has actually been received so far. | money |  |
 | `{{ order.refunded }}` | How much has been refunded. | money |  |
 | `{{ order.balance_due }}` | What is still outstanding on the order. | money |  |
 
@@ -271,7 +271,7 @@ Staff operational alerts only.
 | Order Shipped | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
 | Order Delivered | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
 | Order Refunded | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
-| Order Cancelled | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
+| Order Canceled | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
 | Admin: New Order | Order, Customer, Shipping address, Billing address, Delivery, Store, Brand |
 | Welcome Email | Customer, Store, Brand |
 | Password Reset | Customer, Store, Brand |

package/template/app/next.config.ts

@@ -1,31 +1,27 @@
-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.
+  // @cartbase/storefront is source-shipped TypeScript — 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.
+    // Product images come from the Cartbase media CDN and, until you
+    // allowlist your own hosts under remotePatterns, from anywhere the
+    // catalog points. Tighten this when the media domain is known.
     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.
+  // straight to the platform origin and are unaffected. The origin is the
+  // platform's constant; NEXT_PUBLIC_CARTBASE_URL only overrides it for a
+  // local or staging platform.
   async rewrites() {
-    const barterUrl = process.env.NEXT_PUBLIC_CARTBASE_URL
-    if (!barterUrl) return []
+    const cartbaseUrl = process.env.NEXT_PUBLIC_CARTBASE_URL || "https://admin.cartbase.ai"
     return [
       {
         source: "/api/store/:path*",
-        destination: `${barterUrl}/api/store/:path*`,
+        destination: `${cartbaseUrl}/api/store/:path*`,
       },
     ]
   },

package/template/app/package.json

@@ -2,13 +2,14 @@
   "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",
+    "build": "next build",
+    "start": "next start",
+    "dev": "next dev",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@cartbase/storefront": "^0.6.0",
+    "@cartbase/storefront": "^0.8.0",
     "next": "16.2.4",
     "react": "19.2.4",
     "react-dom": "19.2.4"

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

@@ -7,7 +7,6 @@ import type { StorePaymentEntry } from "@cartbase/storefront/api/checkout"
 import { CheckoutProvider } from "@cartbase/storefront/checkout/context"
 import { CheckoutClient } from "@cartbase/storefront/checkout/checkout-client"
 import { browserClient } from "@/lib/browser-client"
-import { MyposDemoTab } from "./mypos-demo-tab"
 
 /** sessionStorage key the confirmation page reads (guests have no order
  * read endpoint — the completeCart() response is the only order handle,
@@ -42,25 +41,6 @@ export function CheckoutPageClient({
         paymentMethodFilter={(methods) =>
           methods?.filter((m) => "payment_method_id" in m) ?? null
         }
-        // Provider-research demo (2026-08-04): the myPOS sandbox as a third
-        // radio card, so the embedded-provider seam can be judged inside
-        // the real checkout. Off unless NEXT_PUBLIC_MYPOS_DEMO=1.
-        extraPaymentTabs={
-          process.env.NEXT_PUBLIC_MYPOS_DEMO === "1"
-            ? [
-                {
-                  id: "mypos-demo",
-                  label: "Card via myPOS (demo)",
-                  content: (
-                    <MyposDemoTab
-                      amount={Number(cart.total) || 23.45}
-                      currency={cart.currency_code}
-                    />
-                  ),
-                },
-              ]
-            : undefined
-        }
         onOrderPlaced={(order) => {
           // Guest order handle = the completeCart() response (orders.md).
           // Stash it (+ the decorated cart lines for the items list) for

package/template/app/src/app/globals.css

@@ -17,7 +17,7 @@
  * to scan it to know which classes exist. Without this the components render
  * with no styles at all — the classes are in the markup but never generated.
  */
-@source "../../../../packages/storefront/src";
+@source "../../node_modules/@cartbase/storefront/src";
 
 /*
  * Dark mode is class-based: put `.dark` on <html> and every token swaps.

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

@@ -5,6 +5,8 @@ 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 } from "@/lib/config"
@@ -15,10 +17,56 @@ import "./globals.css"
 // createStorefrontMetadata (platform-fingerprints card) stamps
 // `<meta name="generator" content="Cartbase" />` on every page — never
 // hand-write `generator` here.
-export const metadata: Metadata = createStorefrontMetadata({
-  title: "Barter Example Store",
-  description: "Reference storefront built on @cartbase/storefront",
-})
+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
@@ -65,7 +113,8 @@ export default async function RootLayout({
   // the rename (platform-fingerprints card).
   const cartId = readCartCookie((name) => jar.get(name)?.value) ?? null
 
-  const [consentRes, mainMenu, footerMenu, cart] = await Promise.all([
+  const [store, consentRes, mainMenu, footerMenu, cart] = await Promise.all([
+    fetchStore(),
     getConsent(client),
     fetchMenu("main-menu"),
     fetchMenu("footer"),
@@ -80,12 +129,24 @@ export default async function RootLayout({
     <html lang="en">
       <body>
         <ConsentInit />
-        <PlatformInit storeId={BARTER_CLIENT_ID} />
+        {/* 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
+            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">
-                Barter Example Store
+                {store.name}
               </Link>
               <div className="flex items-center gap-6">
                 <MenuNav menu={mainMenu} />
@@ -96,17 +157,11 @@ export default async function RootLayout({
                   Search
                 </Link>
                 {/*
-                  The workbench, reachable from the shop rather than by
-                  knowing the URL. This app is the reference store AND the
-                  place the library gets designed; the link is what makes the
-                  second half discoverable.
+                  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.
                 */}
-                <Link
-                  href="/gallery"
-                  className="text-sm text-muted-foreground hover:text-foreground"
-                >
-                  Library
-                </Link>
                 <CartButtonClient cart={cart} />
               </div>
             </div>
@@ -114,7 +169,7 @@ export default async function RootLayout({
           <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>Barter Example Store</span>
+              <span>{store.name}</span>
               <MenuNav menu={footerMenu} />
             </div>
           </footer>

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

@@ -1,78 +1,92 @@
-"use client"
-
-import { useEffect, useState } from "react"
-import Link from "next/link"
-import type { CompletedOrder, CartLineItem } from "@cartbase/storefront/api/carts"
-import {
-  OrderCompletedTemplate,
-} from "@cartbase/storefront/order/order-completed-template"
-import {
-  displayItemFromCartLine,
-} from "@cartbase/storefront/order/order-item"
-import {
-  orderTotalsFromSummary,
-} from "@cartbase/storefront/order/order-totals"
-import { LAST_ORDER_STORAGE_KEY } from "../../../checkout/checkout-page-client"
-
-/**
- * Order confirmation (runbook step 8.6 + orders.md): guests have NO
- * anonymous order read — the `completeCart()` response is the only order
- * handle, so the checkout page stashes it in sessionStorage and this page
- * renders it through the order family. Totals come from the order's
- * summary snapshot (`orderTotalsFromSummary`); items keep the decorated
- * cart lines' server-computed totals (`displayItemFromCartLine`).
- */
-type Stash = { order: CompletedOrder; cartItems: CartLineItem[] }
-
-export default function OrderConfirmedPage() {
-  const [stash, setStash] = useState<Stash | null | "missing">(null)
-
-  useEffect(() => {
-    try {
-      const raw = sessionStorage.getItem(LAST_ORDER_STORAGE_KEY)
-      setStash(raw ? (JSON.parse(raw) as Stash) : "missing")
-    } catch {
-      setStash("missing")
-    }
-  }, [])
-
-  if (stash === null) return null // first paint before sessionStorage read
-
-  if (stash === "missing") {
-    return (
-      <div className="max-w-xl mx-auto px-4 py-16 text-center">
-        <h1 className="text-xl font-semibold mb-2">Order placed</h1>
-        <p className="text-muted-foreground mb-6">
-          Your order was placed successfully. A confirmation email is on its
-          way.
-        </p>
-        <Link href="/" className="underline">
-          Continue shopping
-        </Link>
-      </div>
-    )
-  }
-
-  const { order, cartItems } = stash
-  const totals = orderTotalsFromSummary(order.summary) ?? {
-    total: null,
-  }
-  // The completeCart() order carries FLATTENED items (checkout.md), not the
-  // order-detail pivot shape the template's default converter expects —
-  // pass the normalized cart-line items instead and drop `order.items`.
-  const orderForTemplate = { ...order, items: undefined }
-
-  return (
-    <OrderCompletedTemplate
-      order={orderForTemplate}
-      totals={totals}
-      items={cartItems.map(displayItemFromCartLine)}
-      // This reference store checks out via one merchant method (pp_* kill:
-      // methods are merchant-named, provider-less); a multi-tender store
-      // should stash the chosen tender from its checkout state alongside
-      // the order.
-      paymentMethodName={"Cash on delivery"}
-      storeHref="/"
-    />
-  )
-}
+"use client"
+
+import { useEffect, useState } from "react"
+import Link from "next/link"
+import type { CompletedOrder, CartLineItem } from "@cartbase/storefront/api/carts"
+import {
+  OrderCompletedTemplate,
+} from "@cartbase/storefront/order/order-completed-template"
+import {
+  displayItemFromCartLine,
+} from "@cartbase/storefront/order/order-item"
+import {
+  orderTotalsFromSummary,
+} from "@cartbase/storefront/order/order-totals"
+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 { LAST_ORDER_STORAGE_KEY } from "../../../checkout/checkout-page-client"
+
+/**
+ * Order confirmation (runbook step 8.6 + orders.md): guests have NO
+ * anonymous order read — the `completeCart()` response is the only order
+ * handle, so the checkout page stashes it in sessionStorage and this page
+ * renders it through the order family. Totals come from the order's
+ * summary snapshot (`orderTotalsFromSummary`); items keep the decorated
+ * cart lines' server-computed totals (`displayItemFromCartLine`).
+ */
+type Stash = { order: CompletedOrder; cartItems: CartLineItem[] }
+
+export default function OrderConfirmedPage() {
+  const [stash, setStash] = useState<Stash | null | "missing">(null)
+  // The store's public tag config — Google Ads needs the account id
+  // and the purchase label from it, and null means the conversion is
+  // skipped rather than fired malformed.
+  const tracking = useTrackingConfig(browserClient)
+
+  useEffect(() => {
+    try {
+      const raw = sessionStorage.getItem(LAST_ORDER_STORAGE_KEY)
+      setStash(raw ? (JSON.parse(raw) as Stash) : "missing")
+    } catch {
+      setStash("missing")
+    }
+  }, [])
+
+  if (stash === null) return null // first paint before sessionStorage read
+
+  if (stash === "missing") {
+    return (
+      <div className="max-w-xl mx-auto px-4 py-16 text-center">
+        <h1 className="text-xl font-semibold mb-2">Order placed</h1>
+        <p className="text-muted-foreground mb-6">
+          Your order was placed successfully. A confirmation email is on its
+          way.
+        </p>
+        <Link href="/" className="underline">
+          Continue shopping
+        </Link>
+      </div>
+    )
+  }
+
+  const { order, cartItems } = stash
+  const totals = orderTotalsFromSummary(order.summary) ?? {
+    total: null,
+  }
+  // The completeCart() order carries FLATTENED items (checkout.md), not the
+  // order-detail pivot shape the template's default converter expects —
+  // pass the normalized cart-line items instead and drop `order.items`.
+  const orderForTemplate = { ...order, items: undefined }
+
+  return (
+    <>
+      {/* The purchase event, every configured vendor at once, fired once
+          per order per browser. Dedup keys match the platform's
+          server-side Purchase exactly, so the browser event and the
+          server event collapse into ONE conversion. */}
+      <TrackOrderPurchase order={order} items={cartItems} config={tracking} />
+      <OrderCompletedTemplate
+      order={orderForTemplate}
+      totals={totals}
+      items={cartItems.map(displayItemFromCartLine)}
+      // This reference store checks out via one merchant method (pp_* kill:
+      // methods are merchant-named, provider-less); a multi-tender store
+      // should stash the chosen tender from its checkout state alongside
+      // the order.
+      paymentMethodName={"Cash on delivery"}
+      storeHref="/"
+      />
+    </>
+  )
+}