create-brainerce-store 1.84.0 → 1.86.0

package/templates/nextjs/base/src/components/auth/oauth-buttons.tsx

@@ -1,137 +1,174 @@
-'use client';
-
-import { useState, useEffect } from 'react';
-import type { CustomerOAuthProvider } from 'brainerce';
-import { getClient } from '@/core/lib/brainerce';
-import { useTranslations } from '@/core/lib/translations';
-import { cn } from '@/core/lib/utils';
-import { LoadingSpinner } from '@/ui/shared/loading-spinner';
-
-const PROVIDER_CONFIG: Record<CustomerOAuthProvider, { labelKey: string; icon: React.ReactNode }> =
-  {
-    GOOGLE: {
-      labelKey: 'google',
-      icon: (
-        <svg className="h-5 w-5" viewBox="0 0 24 24" fill="currentColor">
-          <path
-            d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92a5.06 5.06 0 01-2.2 3.32v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.1z"
-            fill="#4285F4"
-          />
-          <path
-            d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"
-            fill="#34A853"
-          />
-          <path
-            d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"
-            fill="#FBBC05"
-          />
-          <path
-            d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"
-            fill="#EA4335"
-          />
-        </svg>
-      ),
-    },
-    FACEBOOK: {
-      labelKey: 'facebook',
-      icon: (
-        <svg className="h-5 w-5" viewBox="0 0 24 24" fill="#1877F2">
-          <path d="M24 12.073c0-6.627-5.373-12-12-12s-12 5.373-12 12c0 5.99 4.388 10.954 10.125 11.854v-8.385H7.078v-3.47h3.047V9.43c0-3.007 1.792-4.669 4.533-4.669 1.312 0 2.686.235 2.686.235v2.953H15.83c-1.491 0-1.956.925-1.956 1.874v2.25h3.328l-.532 3.47h-2.796v8.385C19.612 23.027 24 18.062 24 12.073z" />
-        </svg>
-      ),
-    },
-    GITHUB: {
-      labelKey: 'github',
-      icon: (
-        <svg className="h-5 w-5" viewBox="0 0 24 24" fill="currentColor">
-          <path d="M12 0C5.374 0 0 5.373 0 12c0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23A11.509 11.509 0 0112 5.803c1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576C20.566 21.797 24 17.3 24 12c0-6.627-5.373-12-12-12z" />
-        </svg>
-      ),
-    },
-  };
-
-interface OAuthButtonsProps {
-  className?: string;
-}
-
-export function OAuthButtons({ className }: OAuthButtonsProps) {
-  const t = useTranslations('auth');
-  const [providers, setProviders] = useState<CustomerOAuthProvider[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [redirecting, setRedirecting] = useState<CustomerOAuthProvider | null>(null);
-
-  useEffect(() => {
-    async function fetchProviders() {
-      try {
-        const client = getClient();
-        const result = await client.getAvailableOAuthProviders();
-        setProviders(result.providers);
-      } catch {
-        // OAuth not available - silently hide buttons
-        setProviders([]);
-      } finally {
-        setLoading(false);
-      }
-    }
-
-    fetchProviders();
-  }, []);
-
-  async function handleOAuthClick(provider: CustomerOAuthProvider) {
-    if (redirecting) return;
-
-    try {
-      setRedirecting(provider);
-      const client = getClient();
-      const redirectUrl = window.location.origin + '/api/auth/oauth-callback';
-      const result = await client.getOAuthAuthorizeUrl(provider, { redirectUrl });
-      window.location.href = result.authorizationUrl;
-    } catch (err) {
-      console.error('OAuth redirect failed:', err);
-      setRedirecting(null);
-    }
-  }
-
-  if (loading) {
-    return null;
-  }
-
-  if (providers.length === 0) {
-    return null;
-  }
-
-  return (
-    <div className={cn('space-y-3', className)}>
-      <div className="relative">
-        <div className="absolute inset-0 flex items-center">
-          <div className="border-border w-full border-t" />
-        </div>
-        <div className="relative flex justify-center text-xs uppercase">
-          <span className="bg-background text-muted-foreground px-2">{t('orContinueWith')}</span>
-        </div>
-      </div>
-
-      <div className="grid gap-2">
-        {providers.map((provider) => {
-          const config = PROVIDER_CONFIG[provider];
-          if (!config) return null;
-
-          const isRedirecting = redirecting === provider;
-
-          return (
-            <button
-              key={provider}
-              type="button"
-              onClick={() => handleOAuthClick(provider)}
-              disabled={!!redirecting}
-              className="border-border text-foreground bg-background hover:bg-muted flex h-10 w-full items-center justify-center gap-2 rounded border text-sm font-medium transition-colors disabled:cursor-not-allowed disabled:opacity-50"
-            >
-              {isRedirecting ? <LoadingSpinner size="sm" /> : config.icon}
-              {t(config.labelKey as 'google' | 'facebook' | 'github')}
-            </button>
-          );
-        })}
-      </div>
-    </div>
-  );
-}
+'use client';
+
+import { useState, useEffect } from 'react';
+import type { CustomerOAuthProvider } from 'brainerce';
+import { getClient } from '@/core/lib/brainerce';
+import { useTranslations } from '@/core/lib/translations';
+import { cn } from '@/core/lib/utils';
+import { LoadingSpinner } from '@/ui/shared/loading-spinner';
+
+const PROVIDER_CONFIG: Record<CustomerOAuthProvider, { labelKey: string; icon: React.ReactNode }> =
+  {
+    GOOGLE: {
+      labelKey: 'google',
+      icon: (
+        <svg className="h-5 w-5" viewBox="0 0 24 24" fill="currentColor">
+          <path
+            d="M22.56 12.25c0-.78-.07-1.53-.2-2.25H12v4.26h5.92a5.06 5.06 0 01-2.2 3.32v2.77h3.57c2.08-1.92 3.28-4.74 3.28-8.1z"
+            fill="#4285F4"
+          />
+          <path
+            d="M12 23c2.97 0 5.46-.98 7.28-2.66l-3.57-2.77c-.98.66-2.23 1.06-3.71 1.06-2.86 0-5.29-1.93-6.16-4.53H2.18v2.84C3.99 20.53 7.7 23 12 23z"
+            fill="#34A853"
+          />
+          <path
+            d="M5.84 14.09c-.22-.66-.35-1.36-.35-2.09s.13-1.43.35-2.09V7.07H2.18C1.43 8.55 1 10.22 1 12s.43 3.45 1.18 4.93l2.85-2.22.81-.62z"
+            fill="#FBBC05"
+          />
+          <path
+            d="M12 5.38c1.62 0 3.06.56 4.21 1.64l3.15-3.15C17.45 2.09 14.97 1 12 1 7.7 1 3.99 3.47 2.18 7.07l3.66 2.84c.87-2.6 3.3-4.53 6.16-4.53z"
+            fill="#EA4335"
+          />
+        </svg>
+      ),
+    },
+    FACEBOOK: {
+      labelKey: 'facebook',
+      icon: (
+        <svg className="h-5 w-5" viewBox="0 0 24 24" fill="#1877F2">
+          <path d="M24 12.073c0-6.627-5.373-12-12-12s-12 5.373-12 12c0 5.99 4.388 10.954 10.125 11.854v-8.385H7.078v-3.47h3.047V9.43c0-3.007 1.792-4.669 4.533-4.669 1.312 0 2.686.235 2.686.235v2.953H15.83c-1.491 0-1.956.925-1.956 1.874v2.25h3.328l-.532 3.47h-2.796v8.385C19.612 23.027 24 18.062 24 12.073z" />
+        </svg>
+      ),
+    },
+    GITHUB: {
+      labelKey: 'github',
+      icon: (
+        <svg className="h-5 w-5" viewBox="0 0 24 24" fill="currentColor">
+          <path d="M12 0C5.374 0 0 5.373 0 12c0 5.302 3.438 9.8 8.207 11.387.599.111.793-.261.793-.577v-2.234c-3.338.726-4.033-1.416-4.033-1.416-.546-1.387-1.333-1.756-1.333-1.756-1.089-.745.083-.729.083-.729 1.205.084 1.839 1.237 1.839 1.237 1.07 1.834 2.807 1.304 3.492.997.107-.775.418-1.305.762-1.604-2.665-.305-5.467-1.334-5.467-5.931 0-1.311.469-2.381 1.236-3.221-.124-.303-.535-1.524.117-3.176 0 0 1.008-.322 3.301 1.23A11.509 11.509 0 0112 5.803c1.02.005 2.047.138 3.006.404 2.291-1.552 3.297-1.23 3.297-1.23.653 1.653.242 2.874.118 3.176.77.84 1.235 1.911 1.235 3.221 0 4.609-2.807 5.624-5.479 5.921.43.372.823 1.102.823 2.222v3.293c0 .319.192.694.801.576C20.566 21.797 24 17.3 24 12c0-6.627-5.373-12-12-12z" />
+        </svg>
+      ),
+    },
+  };
+
+interface OAuthButtonsProps {
+  className?: string;
+}
+
+export function OAuthButtons({ className }: OAuthButtonsProps) {
+  const t = useTranslations('auth');
+  const [providers, setProviders] = useState<CustomerOAuthProvider[]>([]);
+  const [loading, setLoading] = useState(true);
+  const [redirecting, setRedirecting] = useState<CustomerOAuthProvider | null>(null);
+  const [failedProvider, setFailedProvider] = useState<CustomerOAuthProvider | null>(null);
+
+  useEffect(() => {
+    async function fetchProviders() {
+      try {
+        const client = getClient();
+        const result = await client.getAvailableOAuthProviders();
+        // `redirectReady` is per storefront address: a provider can be enabled
+        // while the sales channel has nowhere to send the session back to
+        // (TEST channel, no domain, this preview URL not registered). The
+        // authorize call would 400 on click, so render nothing — and tell the
+        // builder why, in dev only, since only the merchant can fix it.
+        // Read through a local shape rather than the SDK type: the scaffold pins
+        // an SDK that may predate the field, and `=== false` keeps an older
+        // backend (which omits it) behaving exactly as before.
+        const readiness = result as { redirectReady?: boolean; redirectBlockedReason?: string };
+        if (readiness.redirectReady === false) {
+          if (process.env.NODE_ENV !== 'production') {
+            console.warn(
+              `[brainerce] Social login hidden: this storefront's address (${window.location.origin}) ` +
+                `is not registered on the sales channel (reason: ${readiness.redirectBlockedReason}). ` +
+                'Add it under Dashboard → Sales Channels → Domains.'
+            );
+          }
+          setProviders([]);
+          return;
+        }
+        setProviders(result.providers);
+      } catch {
+        // OAuth not available - silently hide buttons
+        setProviders([]);
+      } finally {
+        setLoading(false);
+      }
+    }
+
+    fetchProviders();
+  }, []);
+
+  async function handleOAuthClick(provider: CustomerOAuthProvider) {
+    if (redirecting) return;
+
+    try {
+      setRedirecting(provider);
+      setFailedProvider(null);
+      const client = getClient();
+      const redirectUrl = window.location.origin + '/api/auth/oauth-callback';
+      const result = await client.getOAuthAuthorizeUrl(provider, { redirectUrl });
+      window.location.href = result.authorizationUrl;
+    } catch (err) {
+      // The 400 body is a rule for the merchant (`redirect_not_allowed` and
+      // which channel setting to fix) — the shopper gets store-language copy,
+      // never the English policy text.
+      console.error('OAuth redirect failed:', err);
+      setFailedProvider(provider);
+      setRedirecting(null);
+    }
+  }
+
+  if (loading) {
+    return null;
+  }
+
+  if (providers.length === 0) {
+    return null;
+  }
+
+  return (
+    <div className={cn('space-y-3', className)}>
+      <div className="relative">
+        <div className="absolute inset-0 flex items-center">
+          <div className="border-border w-full border-t" />
+        </div>
+        <div className="relative flex justify-center text-xs uppercase">
+          <span className="bg-background text-muted-foreground px-2">{t('orContinueWith')}</span>
+        </div>
+      </div>
+
+      {failedProvider && (
+        <div
+          role="alert"
+          className="bg-destructive/10 border-destructive/20 text-destructive rounded-lg border px-4 py-3 text-sm"
+        >
+          {t('socialLoginUnavailable', {
+            provider: t(PROVIDER_CONFIG[failedProvider].labelKey as 'google' | 'facebook' | 'github'),
+          })}
+        </div>
+      )}
+
+      <div className="grid gap-2">
+        {providers.map((provider) => {
+          const config = PROVIDER_CONFIG[provider];
+          if (!config) return null;
+
+          const isRedirecting = redirecting === provider;
+
+          return (
+            <button
+              key={provider}
+              type="button"
+              onClick={() => handleOAuthClick(provider)}
+              disabled={!!redirecting}
+              className="border-border text-foreground bg-background hover:bg-muted flex h-10 w-full items-center justify-center gap-2 rounded border text-sm font-medium transition-colors disabled:cursor-not-allowed disabled:opacity-50"
+            >
+              {isRedirecting ? <LoadingSpinner size="sm" /> : config.icon}
+              {t(config.labelKey as 'google' | 'facebook' | 'github')}
+            </button>
+          );
+        })}
+      </div>
+    </div>
+  );
+}

package/templates/nextjs/base/src/components/checkout/payment-step.tsx

@@ -73,6 +73,18 @@ function resolveClientSdk(
   return { renderType: 'redirect' };
 }
 
+/**
+ * Brainerce-hosted embed (Cardcom OpenFields) vs a provider-hosted page.
+ * Path-based so it holds across localhost/staging/prod without a domain list.
+ */
+function isBrainerceEmbedUrl(url: string): boolean {
+  try {
+    return new URL(url).pathname.includes('/embed/');
+  } catch {
+    return false;
+  }
+}
+
 function extractMessage(response: unknown): string {
   if (typeof response === 'string') return response;
   return (response as { message?: string })?.message || '';
@@ -88,7 +100,14 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
   // is only a fallback for providers that duplicate it there. Reading
   // clientSecret alone breaks providers that return a real identifier (MAX,
   // Takbull) — the iframe/link silently points at an id instead of a page.
+  //
+  // Every allowlist check and embed-detection below must read THIS value, not
+  // `paymentIntent.clientSecret` directly — that was the bug: two checks kept
+  // reading clientSecret straight off the intent after this fallback was
+  // introduced, so a MAX/Takbull-style provider failed `new URL()` on a bare
+  // id and the payment step silently rendered nothing.
   const paymentIntentUrl = paymentIntent?.clientSdk?.renderArg || paymentIntent?.clientSecret || '';
+  const isBrainerceEmbed = isBrainerceEmbedUrl(paymentIntentUrl);
   const [preloadedSdk, setPreloadedSdk] = useState<PaymentClientSdk | null>(null);
   const [loading, setLoading] = useState(true);
   const [error, setError] = useState<string | null>(null);
@@ -98,9 +117,60 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
   // from a provider's hosted page — used to narrow the modal + auto-size the
   // iframe instead of reserving the tall LowProfile footprint.
   const [embeddedIframeHeight, setEmbeddedIframeHeight] = useState<number | null>(null);
+  // Set when the inline embed never posts its first `brainerce:resize` within
+  // the timeout below — e.g. the parent's CSP blocks the iframe from framing
+  // at all. Without this the shopper stares at a permanently blank/broken box
+  // with no error and no way forward.
+  const [iframeLoadFailed, setIframeLoadFailed] = useState(false);
+  // Provider-hosted iframe modal, closed by the shopper. Without this the
+  // modal had no closed state at all: the X did a full navigation to
+  // `?canceled=true`, the page resumed on the payment step, a fresh intent
+  // re-opened the modal over the "payment canceled" banner, and browser Back
+  // did the same — the shopper could never get back to the checkout. Starts
+  // closed when the URL already says the previous attempt was canceled.
+  const [modalDismissed, setModalDismissed] = useState<boolean>(
+    () =>
+      typeof window !== 'undefined' &&
+      new URLSearchParams(window.location.search).get('canceled') === 'true'
+  );
   const walletOpenRef = useRef(false);
   const initialized = useRef(false);
 
+  // Whether the provider-hosted modal is on screen right now. Derived, not
+  // stored, so every branch below agrees on it.
+  const providerModalOpen =
+    !modalDismissed &&
+    !!paymentIntent &&
+    resolveClientSdk(paymentIntent, preloadedSdk).renderType === 'iframe' &&
+    !isBrainerceEmbed;
+
+  // Back closes the modal instead of leaving the shopper inside it. Opening
+  // pushes one history entry tagged as ours; popping it (Back, or the X below
+  // calling history.back()) dismisses. A provider page that navigates inside
+  // the iframe adds entries of its own on top, so Back may need a press per
+  // in-frame navigation first — that is the browser's rule, not ours, and it
+  // still ends on the checkout rather than looping through the payment page.
+  useEffect(() => {
+    if (!providerModalOpen) return;
+    const marker = { brainercePaymentModal: true };
+    window.history.pushState(marker, '');
+    const onPop = () => setModalDismissed(true);
+    window.addEventListener('popstate', onPop);
+    return () => window.removeEventListener('popstate', onPop);
+  }, [providerModalOpen]);
+
+  const closeProviderModal = useCallback(() => {
+    if (
+      (window.history.state as { brainercePaymentModal?: boolean } | null)?.brainercePaymentModal
+    ) {
+      // Our entry is on top: popping it fires popstate, which dismisses and
+      // leaves the history as it was before the modal opened.
+      window.history.back();
+    } else {
+      setModalDismissed(true);
+    }
+  }, []);
+
   // Stable refs for SDK event callbacks (avoids stale closures in onload)
   const cbRef = useRef({
     onSuccess: (_r: unknown) => {},
@@ -519,6 +589,26 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
     return () => cleanups.forEach((fn) => fn());
   }, [checkoutId]);
 
+  // Brainerce-hosted embed pages announce themselves immediately via the
+  // `brainerce:resize` postMessage handled above (it sets
+  // `embeddedIframeHeight`). If that never arrives — most commonly the
+  // parent origin isn't in the embed page's `frame-ancestors` allowlist and
+  // the browser refuses to frame it at all — there is otherwise no signal:
+  // cross-origin framing failures are invisible to the parent window, so the
+  // shopper is left staring at a blank box forever with no error and no way
+  // forward.
+  useEffect(() => {
+    if (!isBrainerceEmbed || !paymentIntentUrl) return;
+    setIframeLoadFailed(false);
+    const timer = setTimeout(() => {
+      setEmbeddedIframeHeight((h) => {
+        if (h === null) setIframeLoadFailed(true);
+        return h;
+      });
+    }, 10000);
+    return () => clearTimeout(timer);
+  }, [isBrainerceEmbed, paymentIntentUrl]);
+
   // --- UI ---
 
   // Invalid checkout id — render the error box instead of ever spinning.
@@ -636,23 +726,31 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
   }
 
   if (sdk.renderType === 'iframe') {
-    if (!isAllowedPaymentUrl(paymentIntent.clientSecret)) return null;
+    if (!isAllowedPaymentUrl(paymentIntentUrl)) return null;
 
     // Detect Brainerce-hosted embed (path-based — works across localhost/
     // staging/prod without a domain list) vs. a provider-hosted page. The
     // embed page is already brand-styled and compact → render inline in the
     // checkout flow. Provider-hosted pages carry their own branding/chrome →
     // keep the modal overlay so they don't fight the checkout layout.
-    const iframeUrlObj = (() => {
-      try {
-        return new URL(paymentIntent.clientSecret);
-      } catch {
-        return null;
+    if (isBrainerceEmbed) {
+      if (iframeLoadFailed) {
+        return (
+          <div className={cn('border-border rounded-lg border px-4 py-6 text-center', className)}>
+            <p className="text-foreground text-sm font-medium">{t('paymentError')}</p>
+            <p className="text-muted-foreground mt-1 text-sm">{t('paymentLoadFailed')}</p>
+            <a
+              href={paymentIntentUrl}
+              target="_blank"
+              rel="noopener noreferrer"
+              className="bg-primary text-primary-foreground mt-4 inline-flex items-center rounded px-6 py-3 text-sm font-medium transition-opacity hover:opacity-90"
+            >
+              {t('openPaymentModal')}
+            </a>
+          </div>
+        );
       }
-    })();
-    const isBrainerceEmbed = iframeUrlObj?.pathname.includes('/embed/') ?? false;
 
-    if (isBrainerceEmbed) {
       // Inline: default to a reasonable height until the embed posts its real
       // height via `brainerce:resize`. Transition smooths the resize into the
       // final measurement.
@@ -674,6 +772,27 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
       );
     }
 
+    // Closed by the shopper (X, browser Back, or arriving with
+    // `?canceled=true`): hold the payment step with a way back in. The intent
+    // is kept; re-opening reuses it (the core hands back the same intent for
+    // an unchanged charge).
+    if (modalDismissed) {
+      return (
+        <div
+          className={cn('flex flex-col items-center justify-center py-12 text-center', className)}
+        >
+          <p className="text-muted-foreground mb-4 text-sm">{t('paymentModalClosed')}</p>
+          <button
+            type="button"
+            onClick={() => setModalDismissed(false)}
+            className="bg-primary text-primary-foreground hover:bg-primary/90 rounded-md px-6 py-2.5 text-sm font-medium transition-colors"
+          >
+            {t('openPaymentModal')}
+          </button>
+        </div>
+      );
+    }
+
     // Provider-hosted page (e.g. Cardcom LowProfile with full merchant
     // branding) — modal overlay keeps it visually contained.
     const formattedAmount = formatPrice((Number(paymentIntent.amount) || 0) / 100, {
@@ -702,9 +821,8 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
                 </span>
               </div>
               <button
-                onClick={() => {
-                  window.location.href = `/checkout?checkout_id=${checkoutId}&canceled=true`;
-                }}
+                type="button"
+                onClick={closeProviderModal}
                 className="text-muted-foreground hover:bg-secondary hover:text-foreground flex h-8 w-8 shrink-0 items-center justify-center rounded-full transition-colors"
                 aria-label="Close"
               >

package/templates/nextjs/base/src/core/lib/store-name.ts.ejs

@@ -0,0 +1,56 @@
+/**
+ * Single source of truth for "what is this store called?" — the twin of
+ * `resolve-currency.ts` / `use-currency.ts`, and the ONLY file that carries
+ * the name the scaffolder knew at generation time.
+ *
+ * The chain, strongest first:
+ *   1. `storeInfo.name` — live, from `/api/vc/<id>/info`. Server components
+ *      and `generateMetadata` get it from `fetchStoreInfo()`; client
+ *      components from `useStoreInfo()`. Always right, and free wherever the
+ *      layout already fetched it.
+ *   2. `process.env.NEXT_PUBLIC_STORE_NAME` — written to `.env.local` by
+ *      `npm run setup` (which `npm run connect` runs for you) and inlined at
+ *      BUILD time. It is what the client bundle carries before the live data
+ *      arrives, and what a page renders when the API is unreachable. Refresh
+ *      it with `npm run setup`, then rebuild.
+ *   3. `SCAFFOLD_STORE_NAME` — the literal below, baked when the project was
+ *      generated. Under `--defer-connection` the scaffolder knew no store, so
+ *      this is just the project directory name: a placeholder, never a brand.
+ *      It must never be the only source anywhere (it once was, and a Hebrew
+ *      sports store went live titled "storefront").
+ *
+ * ⛔ No imports here, on purpose: this file is used by server components,
+ * `generateMetadata`, route handlers, the OG image and `'use client'` hooks
+ * alike, so it must never pull in `next/headers` or React.
+ */
+
+/** The name the scaffolder knew — see (3) above. Rendered by the scaffolder
+ *  as a complete JS string literal (`storeNameJs`), so quotes, backticks and
+ *  `</script>` inside a real store name are already escaped here; every
+ *  consumer still escapes for ITS context (React text, JSON-LD, `<title>`). */
+export const SCAFFOLD_STORE_NAME: string = <%- storeNameJs %>;
+
+/**
+ * Resolve the display name for this store.
+ *
+ * @param storeInfo result of `fetchStoreInfo()` / `useStoreInfo()` — may be
+ *                  null when the fetch failed or has not resolved yet
+ * @param override  pass when the caller already has a more specific name
+ *                  (a sales-channel label, an order's captured store name)
+ */
+export function resolveStoreName(
+  storeInfo: { name?: string | null } | null | undefined,
+  override?: string | null
+): string {
+  return (
+    override?.trim() ||
+    storeInfo?.name?.trim() ||
+    process.env.NEXT_PUBLIC_STORE_NAME?.trim() ||
+    SCAFFOLD_STORE_NAME
+  );
+}
+
+/** `<title>` template for pages that set their own title: "Page | Store". */
+export function buildTitleTemplate(storeName: string): string {
+  return `%s | ${storeName}`;
+}

package/templates/nextjs/base/src/core/lib/tracking.ts

@@ -1,5 +1,5 @@
 import type { Cart, Order, Product, ProductVariant, TrackingEventItem } from 'brainerce';
-import { getCartTotals } from 'brainerce';
+import { getCartTotals, buildGa4CommercePayload } from 'brainerce';
 
 import { getClient } from './brainerce';
 
@@ -16,12 +16,14 @@ import { getClient } from './brainerce';
  *
  * ## Item ids
  *
- * `itemId` is always the **SKU**. That is the id Brainerce publishes to the
- * Google Merchant Center and Meta catalog feeds, so it is the only id the ad
- * platforms can match a pixel event against. Sending a product or variant id
- * instead breaks attribution and dynamic remarketing silently — the events
- * arrive, the platform reports an id its catalog has never seen, and the
- * remarketing audience never builds.
+ * `itemId` is the SKU-preferring id Meta/TikTok pixels match against (Meta
+ * deliberately uses the bare internal id instead, since SKU is nullable
+ * there — see `apps/meta-connector/src/lib/mappers.ts`). For GA4/GTM, the SDK
+ * builds a SEPARATE id from `productId`/`variantId` (`prod_<id>`/`var_<id>`)
+ * matching the Google Merchant Center feed's `offerId` — neither SKU nor a
+ * bare unprefixed id matches that feed, which silently breaks Shopping ads /
+ * dynamic remarketing item matching. Always pass `productId`/`variantId`
+ * alongside `itemId` so both platforms attribute correctly.
  */
 
 /** Parse a Brainerce decimal string (`"29.99"`) into a number. */
@@ -54,6 +56,8 @@ export function trackProductView(
     items: [
       {
         itemId: resolveItemId(product, variant),
+        productId: product.id,
+        variantId: variant?.id,
         itemName: product.name,
         price,
         quantity: 1,
@@ -77,6 +81,8 @@ export function trackAddToCart(
     items: [
       {
         itemId: resolveItemId(product, variant),
+        productId: product.id,
+        variantId: variant?.id,
         itemName: product.name,
         price,
         quantity,
@@ -92,6 +98,8 @@ function cartItems(cart: Cart): TrackingEventItem[] {
     // The cart line carries product + variant snapshots; prefer the variant's
     // SKU for the same catalog-parity reason as `resolveItemId`.
     itemId: item.variant?.sku || item.product?.sku || item.variantId || item.productId,
+    productId: item.productId,
+    variantId: item.variantId ?? undefined,
     itemName: item.product?.name,
     price: toNumber(item.currentUnitPrice ?? item.unitPrice),
     quantity: item.quantity,
@@ -151,18 +159,21 @@ export function trackPurchase(order: Order): void {
     // vendor-side transaction id de-dupe rather than skipping the conversion.
   }
 
+  // GA4 spec: `value` is net item revenue only — `tax`/`shipping` are
+  // reported alongside it, never folded in. See `buildGa4CommercePayload`.
+  const commerce = buildGa4CommercePayload(order);
+
   getClient().trackMarketingEvent('purchase', {
     transactionId: order.id,
-    currency: order.currency,
-    value: toNumber(order.total ?? order.totalAmount),
-    shipping: toNumber(order.shippingAmount),
-    // In inclusive (VAT) pricing `taxAmount` is "0" and the real VAT lives in
-    // the frozen breakdown — reporting the 0 would understate tax on every
-    // order for every VAT-region merchant.
-    tax: toNumber(order.taxBreakdown?.totalTax) ?? toNumber(order.taxAmount),
+    currency: commerce.currency,
+    value: commerce.value,
+    shipping: commerce.shipping,
+    tax: commerce.tax,
     coupon: order.couponCode ?? undefined,
     items: (order.items ?? []).map((item) => ({
       itemId: item.sku || item.variantId || item.productId,
+      productId: item.productId,
+      variantId: item.variantId,
       itemName: item.name,
       price: toNumber(item.price),
       quantity: item.quantity,