create-brainerce-store 1.50.5 → 1.51.0

package/templates/nextjs/base/AI-GUIDE.md

@@ -0,0 +1,94 @@
+# AI-GUIDE — designing this store safely
+
+You (an AI coding assistant, or a human designer) have been asked to redesign
+this storefront. This guide is the contract that lets you go as bold as you
+want without breaking commerce. It was distilled from real agency builds.
+
+## The one rule
+
+**`src/core/` is the platform's. `src/ui/` is yours.**
+
+Everything under `src/ui/` may be rewritten from scratch — layouts, markup,
+classes, animations, entire visual languages. (Canvas-mode stores —
+scaffolded with `--canvas` — ship `src/ui/` as bare unstyled skeletons with
+`DESIGN ME` markers; same rules apply, you're just starting from zero.) Everything under `src/core/`
+(and `src/app/api/`) keeps the store working: cart, checkout, variants,
+inventory, auth, SEO, i18n. Never modify it. If a redesign seems to require a
+core change, stop and say so instead.
+
+## File map
+
+| Path | Owner | Notes |
+|------|-------|-------|
+| `src/ui/layout/` | you | header, footer, announcement bar |
+| `src/ui/home/` | you | homepage sections |
+| `src/ui/product/` | you | card, grid, listing, product page, price, badges, selectors |
+| `src/ui/cart/` | you | cart page pieces |
+| `src/ui/shared/` | you | loader, image wrapper |
+| `src/app/globals.css` | you | tokens + global styles |
+| `src/core/**` | platform | hooks, lib, providers — read, never edit |
+| `src/components/{checkout,auth,account,seo}` | platform | core-styled in v1; they inherit your tokens |
+| `src/app/**` | platform | thin routes; edit only to wire new ui components |
+
+## The hook contract (your data supply)
+
+UI components get *everything* from `@/core/hooks/*` and
+`@/core/providers/store-provider` — never from `@/core/lib` directly:
+
+- `useHomeData()` → `{ products, banners, loading }`
+- `useProductListing()` → products + filters/sort/facets/pagination + handlers
+- `useProductPage(product)` → variant/image selection, `priceInfo`, `inventory`,
+  `quantity`, `handleAddToCart`, `addingToCart`, `addedMessage`, customization
+  + modifier state and errors
+- `useCartPage()` / `useCart()` → `{ cart, itemCount, totals, refreshCart }`
+
+Hooks return data and handlers, never JSX. All catalog content (names, prices,
+images, stock) comes from them — **never hardcode products**.
+
+## Verification loop (before you declare anything done)
+
+1. `pnpm exec tsc --noEmit` → must be 0.
+2. `pnpm dev` → drive the real flow you changed: home → listing → product →
+   add to cart → cart → checkout page renders.
+3. Screenshot desktop (1440) AND mobile (390), in the store's language.
+4. If the store is RTL: check nothing is left-anchored that should be
+   right-anchored, and directional arrows point with the reading direction.
+
+## Hard-won gotchas (each one cost a real debugging session)
+
+- **RTL + cloned images**: `next/image` renders its `<img>` with `inset: 0`.
+  If you clone one for an animation and set `left`, the leftover `right: 0`
+  wins in RTL documents (over-constrained boxes resolve to the RIGHT).
+  Set `inset: 'auto'` before positioning.
+- **Never name a custom class `overline`** — it is a Tailwind utility
+  (`text-decoration-line: overline`) and will draw a line above your text.
+- **`rounded-md` / `rounded-lg` are fixed radii** — they ignore your
+  `--radius` token. For token-driven corners use `rounded` (DEFAULT) or set
+  radii explicitly.
+- **Hebrew has no uppercase** — remove `text-transform: uppercase` and wide
+  `letter-spacing` from heading styles; they are Latin idioms that distort
+  Hebrew (tracking is acceptable only at caption sizes).
+- **Logical properties only**: `ms-/me-`, `ps-/pe-`, `start-/end-`,
+  `text-start/end`. Never `ml-/mr-`, `left-/right-`, `text-left/right`,
+  `flex-row-reverse`.
+- **Motion**: wrap every animation in a `prefers-reduced-motion: reduce`
+  guard. One well-orchestrated reveal beats scattered effects.
+- **Fonts**: any face used for body or headlines must include the store's
+  script (e.g. Google Fonts `hebrew` subset). Latin-only display faces are
+  accent-only.
+
+## Never do
+
+- Modify `src/core/`, `src/app/api/`, or checkout/auth/account internals.
+- Remove accessibility attributes (`aria-*`, `role`, `alt`, focus styles).
+- Hardcode catalog content, prices, or currency symbols.
+- Swallow the add-to-cart / checkout error states — restyle them, keep them.
+- Introduce new runtime dependencies without flagging it.
+
+## Adding things
+
+- New homepage section → new component in `src/ui/home/`, composed in
+  `home-client.tsx`, data via existing hooks only.
+- New UI copy → add keys to **both** `messages/he.json` and
+  `messages/en.json` (or all supported locales), use `useTranslations()`.
+- New microinteraction → CSS-first; JS only for things CSS cannot do.

package/templates/nextjs/base/CLAUDE.md

@@ -0,0 +1,42 @@
+# CLAUDE.md — this is a Brainerce storefront
+
+This store's commerce engine (cart, checkout, variants, auth, i18n) is
+already wired and working. Your job here is almost always **design**.
+
+## The one rule
+
+**`src/core/` is the platform's. `src/ui/` is yours.**
+
+The shipped `src/ui/` is a working reference, not a design to preserve —
+full delete-and-rebuild of ui files is encouraged and expected. (Stores
+scaffolded with `--canvas` ship `src/ui/` as bare unstyled skeletons —
+there is no reference look at all; the design is entirely yours to create.)
+Rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
+like — the store keeps working. Never modify `src/core/`, `src/app/api/`, or
+the checkout/auth/account components. Data and behavior come exclusively from
+`@/core/hooks/*` and `@/core/providers/store-provider` — hooks return state
+and handlers, never JSX. Never hardcode catalog content.
+
+**Read `AI-GUIDE.md` before any redesign** — it has the full file map, hook
+contracts, and hard-won RTL/i18n gotchas that will save you real debugging
+time.
+
+## Redesigning? Use the ready-made flow
+
+Run `/design <your art-direction brief>` — it walks the whole process:
+concept → implementation in `ui/` → verification.
+
+## Verify before declaring done
+
+1. `pnpm exec tsc --noEmit` → 0 errors
+2. `pnpm dev` → drive the changed flow in a real browser (home → product →
+   add to cart → cart)
+3. Screenshot desktop (1440px) and mobile (390px)
+4. RTL stores: check anchoring and arrow directions
+
+## i18n
+
+Every user-facing string goes through `useTranslations()` with keys in **all**
+files under `messages/`. Hebrew: no uppercase transforms, no wide
+letter-spacing on headings, logical CSS properties only (`ms-/me-`, `ps-/pe-`,
+`start-/end-`).

package/templates/nextjs/base/TRANSLATIONS.md

@@ -37,7 +37,7 @@ You write **one** `fetch` and it works for every language.
 
 ```tsx
 // src/app/[locale]/products/[slug]/page.tsx
-import { getServerClient } from '@/lib/server-client';
+import { getServerClient } from '@/core/lib/server-client';
 import { headers } from 'next/headers';
 
 export default async function ProductPage({ params }: { params: Promise<{ slug: string }> }) {

package/templates/nextjs/base/next.config.ts

@@ -1,5 +1,5 @@
 import type { NextConfig } from 'next';
-import { OPTIMIZED_IMAGE_HOSTS } from './src/lib/image-hosts';
+import { OPTIMIZED_IMAGE_HOSTS } from './src/core/lib/image-hosts';
 
 // Build-time invariant — fail loud if NEXT_PUBLIC_STORE_CURRENCY is missing
 // for a production build. Next.js inlines NEXT_PUBLIC_* into the client
@@ -35,7 +35,7 @@ const nextConfig: NextConfig = {
     // its image-import job is pending or failed. Rather than allowlist every
     // possible merchant host (or hard-fail on them), only cdn.brainerce.com
     // goes through the server-side optimizer; components render product/blog
-    // images via `CdnImage` (src/components/shared/cdn-image.tsx), which
+    // images via `CdnImage` (src/ui/shared/cdn-image.tsx), which
     // detects any other host and renders it `unoptimized` — an unresized
     // direct-from-origin fetch, same as this template's prior behavior —
     // instead of next/image throwing on an unconfigured hostname. No

package/templates/nextjs/base/src/app/account/page.tsx

@@ -1,15 +1,15 @@
 'use client';
 
 import { useEffect, useState } from 'react';
-import { useRouter } from '@/lib/navigation';
+import { useRouter } from '@/core/lib/navigation';
 import type { CustomerProfile, Order } from 'brainerce';
-import { getClient } from '@/lib/brainerce';
-import { useAuth } from '@/providers/store-provider';
-import { LoadingSpinner } from '@/components/shared/loading-spinner';
+import { getClient } from '@/core/lib/brainerce';
+import { useAuth } from '@/core/providers/store-provider';
+import { LoadingSpinner } from '@/ui/shared/loading-spinner';
 import { ProfileSection } from '@/components/account/profile-section';
 import { AddressBook } from '@/components/account/address-book';
 import { OrderHistory } from '@/components/account/order-history';
-import { useTranslations } from '@/lib/translations';
+import { useTranslations } from '@/core/lib/translations';
 
 export default function AccountPage() {
   const router = useRouter();

package/templates/nextjs/base/src/app/api/auth/logout/route.ts

@@ -1,5 +1,5 @@
 import { NextRequest, NextResponse } from 'next/server';
-import { checkCsrf } from '@/lib/csrf';
+import { checkCsrf } from '@/core/lib/csrf';
 
 const TOKEN_COOKIE = 'brainerce_customer_token';
 const LOGGED_IN_COOKIE = 'brainerce_logged_in';

package/templates/nextjs/base/src/app/api/auth/reset-password/route.ts

@@ -1,7 +1,7 @@
 import { NextRequest, NextResponse } from 'next/server';
 import { cookies } from 'next/headers';
-import { validatePassword } from '@/lib/validation';
-import { checkCsrf } from '@/lib/csrf';
+import { validatePassword } from '@/core/lib/validation';
+import { checkCsrf } from '@/core/lib/csrf';
 
 const BACKEND_URL = (process.env.BRAINERCE_API_URL || 'https://api.brainerce.com').replace(
   /\/$/,

package/templates/nextjs/base/src/app/api/store/[...path]/route.ts

@@ -5,7 +5,7 @@
 // like customers/login and customers/register are the most important to cover.
 import { NextRequest, NextResponse } from 'next/server';
 import { cookies } from 'next/headers';
-import { checkCsrf } from '@/lib/csrf';
+import { checkCsrf } from '@/core/lib/csrf';
 
 const BACKEND_URL = (process.env.BRAINERCE_API_URL || 'https://api.brainerce.com').replace(
   /\/$/,

package/templates/nextjs/base/src/app/auth/callback/page.tsx

@@ -2,10 +2,10 @@
 
 import { Suspense, useEffect, useState, useRef } from 'react';
 import { useSearchParams } from 'next/navigation';
-import { useRouter } from '@/lib/navigation';
-import { useAuth } from '@/providers/store-provider';
-import { LoadingSpinner } from '@/components/shared/loading-spinner';
-import { useTranslations } from '@/lib/translations';
+import { useRouter } from '@/core/lib/navigation';
+import { useAuth } from '@/core/providers/store-provider';
+import { LoadingSpinner } from '@/ui/shared/loading-spinner';
+import { useTranslations } from '@/core/lib/translations';
 
 function OAuthCallbackContent() {
   const router = useRouter();

package/templates/nextjs/base/src/app/blog/[slug]/page.tsx.ejs

@@ -12,11 +12,11 @@ import * as React from 'react';
 import type { Metadata } from 'next';
 import { notFound } from 'next/navigation';
 import Link from 'next/link';
-import { CdnImage as Image } from '@/components/shared/cdn-image';
+import { CdnImage as Image } from '@/ui/shared/cdn-image';
 
-import { getServerClient } from '@/lib/brainerce';
-import { sanitizeHtml } from '@/lib/sanitize';
-import { decodeSlug } from '@/lib/utils';
+import { getServerClient } from '@/core/lib/brainerce';
+import { sanitizeHtml } from '@/core/lib/sanitize';
+import { decodeSlug } from '@/core/lib/utils';
 
 <% if (i18nEnabled) { %>
 type PageProps = {

package/templates/nextjs/base/src/app/blog/page.tsx.ejs

@@ -10,9 +10,9 @@
 import * as React from 'react';
 import type { Metadata } from 'next';
 import Link from 'next/link';
-import { CdnImage as Image } from '@/components/shared/cdn-image';
+import { CdnImage as Image } from '@/ui/shared/cdn-image';
 
-import { getServerClient } from '@/lib/brainerce';
+import { getServerClient } from '@/core/lib/brainerce';
 
 <% if (i18nEnabled) { %>
 type PageProps = {

package/templates/nextjs/base/src/app/cart/page.tsx

@@ -1,178 +1,7 @@
 'use client';
 
-import { useEffect, useState } from 'react';
-import { Link } from '@/lib/navigation';
-import type {
-  CartRecommendationsResponse,
-  CartUpgradesResponse,
-  CartBundlesResponse,
-} from 'brainerce';
-import { getClient } from '@/lib/brainerce';
-import { useCart } from '@/providers/store-provider';
-import { CartItem } from '@/components/cart/cart-item';
-import { CartUpgradeBanner } from '@/components/cart/cart-upgrade-banner';
-import { CartBundleOfferCard } from '@/components/cart/cart-bundle-offer';
-import { CartSummary } from '@/components/cart/cart-summary';
-import { CouponInput } from '@/components/cart/coupon-input';
-import { CartNudges } from '@/components/cart/cart-nudges';
-import { FreeShippingBar } from '@/components/cart/free-shipping-bar';
-import { ReservationCountdown } from '@/components/cart/reservation-countdown';
-import { CartRecommendationSection } from '@/components/products/recommendation-section';
-import { LoadingSpinner } from '@/components/shared/loading-spinner';
-import { useTranslations } from '@/lib/translations';
+import { CartView } from '@/ui/cart/cart-view';
 
 export default function CartPage() {
-  const { cart, cartLoading, refreshCart, itemCount } = useCart();
-  const t = useTranslations('cart');
-  const tc = useTranslations('common');
-  const [cartRecs, setCartRecs] = useState<CartRecommendationsResponse | null>(null);
-  const [upgrades, setUpgrades] = useState<CartUpgradesResponse | null>(null);
-  const [bundles, setBundles] = useState<CartBundlesResponse | null>(null);
-
-  // Load recommendations, upgrades, and bundles in a single request
-  useEffect(() => {
-    if (!cart?.id || cart.items.length === 0) {
-      setCartRecs(null);
-      setUpgrades(null);
-      setBundles(null);
-      return;
-    }
-    const client = getClient();
-    client
-      .getCart(cart.id, { include: ['recommendations', 'upgrades', 'bundles'] })
-      .then((enriched) => {
-        setCartRecs(enriched.recommendations ?? null);
-        setUpgrades(enriched.upgrades ?? null);
-        setBundles(enriched.bundles ?? null);
-      })
-      .catch(() => {});
-  }, [cart?.id, cart?.items.length]);
-
-  if (cartLoading) {
-    return (
-      <div className="flex min-h-[60vh] items-center justify-center">
-        <LoadingSpinner size="lg" />
-      </div>
-    );
-  }
-
-  // Empty cart state
-  if (!cart || cart.items.length === 0) {
-    return (
-      <div className="mx-auto max-w-7xl px-4 py-16 text-center sm:px-6 lg:px-8">
-        <svg
-          className="text-muted-foreground mx-auto mb-4 h-16 w-16"
-          fill="none"
-          viewBox="0 0 24 24"
-          stroke="currentColor"
-        >
-          <path
-            strokeLinecap="round"
-            strokeLinejoin="round"
-            strokeWidth={1.5}
-            d="M16 11V7a4 4 0 00-8 0v4M5 9h14l1 12H4L5 9z"
-          />
-        </svg>
-        <h1 className="text-foreground text-2xl font-bold">{t('emptyTitle')}</h1>
-        <p className="text-muted-foreground mt-2">{t('emptySubtitle')}</p>
-        <Link
-          href="/products"
-          className="bg-primary text-primary-foreground mt-6 inline-flex items-center rounded px-6 py-3 font-medium transition-opacity hover:opacity-90"
-        >
-          {tc('continueShopping')}
-        </Link>
-      </div>
-    );
-  }
-
-  return (
-    <div className="mx-auto max-w-7xl px-4 py-8 sm:px-6 lg:px-8">
-      <h1 className="text-foreground mb-6 text-2xl font-bold">
-        {t('title')} ({itemCount} {itemCount === 1 ? tc('item') : tc('items')})
-      </h1>
-
-      {/* Reservation countdown */}
-      {cart.reservation?.hasReservation && (
-        <ReservationCountdown reservation={cart.reservation} className="mb-6" />
-      )}
-
-      <div className="grid grid-cols-1 gap-8 lg:grid-cols-3">
-        {/* Cart Items */}
-        <div className="lg:col-span-2">
-          {/* Nudges */}
-          {cart.nudges && cart.nudges.length > 0 && (
-            <CartNudges nudges={cart.nudges} className="mb-4" />
-          )}
-
-          {/* Cart items */}
-          <div>
-            {cart.items.map((item) => (
-              <div key={item.id}>
-                <CartItem item={item} onUpdate={refreshCart} />
-                {upgrades?.upgrades?.[item.productId] && (
-                  <CartUpgradeBanner
-                    suggestion={upgrades.upgrades[item.productId]}
-                    cartItem={item}
-                    onUpgrade={refreshCart}
-                    className="mb-2 ms-24"
-                  />
-                )}
-              </div>
-            ))}
-          </div>
-
-          {/* Bundle offers */}
-          {bundles?.bundles && bundles.bundles.length > 0 && (
-            <div className="mt-6 space-y-3">
-              <h3 className="text-foreground text-sm font-semibold">{t('bundleOffers')}</h3>
-              {bundles.bundles.map((offer) => (
-                <CartBundleOfferCard
-                  key={offer.id}
-                  offer={offer}
-                  cartId={cart.id}
-                  onAdd={refreshCart}
-                />
-              ))}
-            </div>
-          )}
-
-          {/* Coupon input */}
-          <div className="border-border mt-6 border-t pt-4">
-            <CouponInput cart={cart} onUpdate={refreshCart} />
-          </div>
-        </div>
-
-        {/* Summary sidebar */}
-        <div className="lg:col-span-1">
-          <div className="bg-muted/50 border-border sticky top-24 rounded-lg border p-6">
-            <FreeShippingBar className="mb-4" />
-            <CartSummary />
-
-            <Link
-              href="/checkout"
-              className="bg-primary text-primary-foreground mt-6 inline-flex w-full items-center justify-center rounded px-6 py-3 text-sm font-medium transition-opacity hover:opacity-90"
-            >
-              {t('proceedToCheckout')}
-            </Link>
-
-            <Link
-              href="/products"
-              className="text-muted-foreground hover:text-foreground mt-3 inline-flex w-full items-center justify-center px-6 py-2 text-sm transition-colors"
-            >
-              {tc('continueShopping')}
-            </Link>
-          </div>
-        </div>
-      </div>
-
-      {/* Cross-sell recommendations */}
-      {cartRecs?.recommendations && cartRecs.recommendations.length > 0 && (
-        <CartRecommendationSection
-          title={t('youMightAlsoNeed')}
-          items={cartRecs.recommendations}
-          className="mt-10"
-        />
-      )}
-    </div>
-  );
+  return <CartView />;
 }

package/templates/nextjs/base/src/app/checkout/page.tsx

@@ -2,8 +2,8 @@
 
 import { Suspense, useEffect, useState, useCallback, useRef } from 'react';
 import { useSearchParams } from 'next/navigation';
-import { CdnImage as Image } from '@/components/shared/cdn-image';
-import { Link } from '@/lib/navigation';
+import { CdnImage as Image } from '@/ui/shared/cdn-image';
+import { Link } from '@/core/lib/navigation';
 import type {
   Checkout,
   ShippingRate,
@@ -14,9 +14,9 @@ import type {
   CheckoutCustomFieldDefinition,
 } from 'brainerce';
 import { formatPrice } from 'brainerce';
-import { getClient } from '@/lib/brainerce';
-import { useStoreInfo, useCart, useAuth } from '@/providers/store-provider';
-import { useCurrency } from '@/lib/use-currency';
+import { getClient } from '@/core/lib/brainerce';
+import { useStoreInfo, useCart, useAuth } from '@/core/providers/store-provider';
+import { useCurrency } from '@/core/lib/use-currency';
 import { CheckoutForm } from '@/components/checkout/checkout-form';
 import { ShippingStep } from '@/components/checkout/shipping-step';
 import { PaymentStep } from '@/components/checkout/payment-step';
@@ -25,12 +25,12 @@ import { PickupStep } from '@/components/checkout/pickup-step';
 import { CustomFieldsStep } from '@/components/checkout/custom-fields-step';
 import { TaxDisplay } from '@/components/checkout/tax-display';
 import { OrderBumpCard } from '@/components/checkout/order-bump-card';
-import { CouponInput } from '@/components/cart/coupon-input';
-import { ReservationCountdown } from '@/components/cart/reservation-countdown';
-import { LoadingSpinner } from '@/components/shared/loading-spinner';
-import { useTranslations } from '@/lib/translations';
-import { cn } from '@/lib/utils';
-import { isValidCheckoutId } from '@/lib/safe-redirect';
+import { CouponInput } from '@/ui/cart/coupon-input';
+import { ReservationCountdown } from '@/ui/cart/reservation-countdown';
+import { LoadingSpinner } from '@/ui/shared/loading-spinner';
+import { useTranslations } from '@/core/lib/translations';
+import { cn } from '@/core/lib/utils';
+import { isValidCheckoutId } from '@/core/lib/safe-redirect';
 
 type CheckoutStep = 'method' | 'address' | 'shipping' | 'pickup' | 'custom-fields' | 'payment';
 
@@ -261,6 +261,7 @@ function CheckoutContent() {
           lastName: address.lastName,
           phone: address.phone,
           acceptsMarketing: consent.acceptsMarketing,
+          notes: address.notes,
         });
         setCheckout(updated);
         setStep('payment');

package/templates/nextjs/base/src/app/contact/page.tsx

@@ -34,9 +34,9 @@
 
 import { useEffect, useMemo, useState } from 'react';
 import type { ContactFormPublic, ContactFormPublicField } from 'brainerce';
-import { getClient } from '@/lib/brainerce';
-import { LoadingSpinner } from '@/components/shared/loading-spinner';
-import { useTranslations } from '@/lib/translations';
+import { getClient } from '@/core/lib/brainerce';
+import { LoadingSpinner } from '@/ui/shared/loading-spinner';
+import { useTranslations } from '@/core/lib/translations';
 
 type FieldValue = string | string[] | boolean;
 

package/templates/nextjs/base/src/app/faq/page.tsx.ejs

@@ -11,8 +11,8 @@
 import * as React from 'react';
 import type { Metadata } from 'next';
 
-import { getServerClient } from '@/lib/brainerce';
-import { FaqSection } from '@/components/content/faq-section';
+import { getServerClient } from '@/core/lib/brainerce';
+import { FaqSection } from '@/ui/layout/faq-section';
 <% if (i18nEnabled) { %>
 type PageProps = {
   params: Promise<{ locale: string }>;

package/templates/nextjs/base/src/app/forgot-password/page.tsx

@@ -1,10 +1,10 @@
 'use client';
 
 import { useState } from 'react';
-import { Link } from '@/lib/navigation';
-import { getClient } from '@/lib/brainerce';
-import { LoadingSpinner } from '@/components/shared/loading-spinner';
-import { useTranslations } from '@/lib/translations';
+import { Link } from '@/core/lib/navigation';
+import { getClient } from '@/core/lib/brainerce';
+import { LoadingSpinner } from '@/ui/shared/loading-spinner';
+import { useTranslations } from '@/core/lib/translations';
 
 export default function ForgotPasswordPage() {
   const t = useTranslations('auth');

package/templates/nextjs/base/src/app/layout.tsx.ejs

@@ -1,14 +1,14 @@
 <% if (i18nEnabled) { %>
 import type { Metadata } from 'next';
 <%- fontImport %>
-import { StoreProvider } from '@/providers/store-provider';
-import { AnnouncementBar } from '@/components/content/announcement-bar';
-import { SiteHeader } from '@/components/content/site-header';
-import { SiteFooter } from '@/components/content/site-footer';
+import { StoreProvider } from '@/core/providers/store-provider';
+import { AnnouncementBar } from '@/ui/layout/announcement-bar';
+import { SiteHeader } from '@/ui/layout/site-header';
+import { SiteFooter } from '@/ui/layout/site-footer';
 import { BrainerceBotWidget } from '@/components/brainerce-bot';
-import { getServerClient, fetchStoreInfo } from '@/lib/brainerce';
+import { getServerClient, fetchStoreInfo } from '@/core/lib/brainerce';
 import { getDirection, supportedLocales } from '@/i18n';
-import { getNonce } from '@/lib/nonce';
+import { getNonce } from '@/core/lib/nonce';
 import '../globals.css';
 
 <%- fontVariable %>
@@ -116,13 +116,13 @@ export default async function RootLayout({
 <% } else { %>
 import type { Metadata } from 'next';
 <%- fontImport %>
-import { StoreProvider } from '@/providers/store-provider';
-import { AnnouncementBar } from '@/components/content/announcement-bar';
-import { SiteHeader } from '@/components/content/site-header';
-import { SiteFooter } from '@/components/content/site-footer';
+import { StoreProvider } from '@/core/providers/store-provider';
+import { AnnouncementBar } from '@/ui/layout/announcement-bar';
+import { SiteHeader } from '@/ui/layout/site-header';
+import { SiteFooter } from '@/ui/layout/site-footer';
 import { BrainerceBotWidget } from '@/components/brainerce-bot';
-import { getServerClient, fetchStoreInfo } from '@/lib/brainerce';
-import { getNonce } from '@/lib/nonce';
+import { getServerClient, fetchStoreInfo } from '@/core/lib/brainerce';
+import { getNonce } from '@/core/lib/nonce';
 import './globals.css';
 
 <%- fontVariable %>

package/templates/nextjs/base/src/app/login/page.tsx

@@ -1,12 +1,12 @@
 'use client';
 
 import { useState } from 'react';
-import { useRouter, Link } from '@/lib/navigation';
-import { useAuth } from '@/providers/store-provider';
-import { proxyLogin } from '@/lib/auth';
+import { useRouter, Link } from '@/core/lib/navigation';
+import { useAuth } from '@/core/providers/store-provider';
+import { proxyLogin } from '@/core/lib/auth';
 import { LoginForm } from '@/components/auth/login-form';
 import { OAuthButtons } from '@/components/auth/oauth-buttons';
-import { useTranslations } from '@/lib/translations';
+import { useTranslations } from '@/core/lib/translations';
 
 export default function LoginPage() {
   const router = useRouter();

package/templates/nextjs/base/src/app/order-confirmation/page.tsx

@@ -2,12 +2,12 @@
 
 import { Suspense, useEffect, useState } from 'react';
 import { useSearchParams } from 'next/navigation';
-import { Link } from '@/lib/navigation';
+import { Link } from '@/core/lib/navigation';
 import type { WaitForOrderResult, OrderDownloadLink } from 'brainerce';
-import { getClient } from '@/lib/brainerce';
-import { useCart } from '@/providers/store-provider';
-import { LoadingSpinner } from '@/components/shared/loading-spinner';
-import { useTranslations } from '@/lib/translations';
+import { getClient } from '@/core/lib/brainerce';
+import { useCart } from '@/core/providers/store-provider';
+import { LoadingSpinner } from '@/ui/shared/loading-spinner';
+import { useTranslations } from '@/core/lib/translations';
 
 function OrderConfirmationContent() {
   const searchParams = useSearchParams();
@@ -35,20 +35,27 @@ function OrderConfirmationContent() {
         client.handlePaymentSuccess(checkoutId!);
         await refreshCart();
 
-        // For redirect-based payment providers (e.g. CardCom), the customer
-        // returns with provider params in the URL (lowprofilecode, etc.).
-        // Send these to the backend for server-side verification via the
-        // provider's API (e.g. GetLpResult) — never trust URL params alone.
+        // For redirect-based payment providers, the customer returns with
+        // provider params in the URL — CardCom: lowprofilecode; PayPal:
+        // token + PayerID. Send these to the backend for server-side
+        // verification via the provider's API (e.g. GetLpResult / PayPal
+        // capture) — never trust URL params alone. For PayPal this call is
+        // what actually captures the approved payment.
         const lowProfileCode =
           searchParams.get('lowprofilecode') || searchParams.get('LowProfileCode');
-        if (lowProfileCode) {
+        const paypalOrderToken =
+          searchParams.get('token') && searchParams.get('PayerID')
+            ? searchParams.get('token')
+            : null;
+        const redirectReturnToken = lowProfileCode || paypalOrderToken;
+        if (redirectReturnToken) {
           try {
             await client.confirmSdkPayment(checkoutId!, {
-              paymentIntentId: lowProfileCode,
+              paymentIntentId: redirectReturnToken,
             });
           } catch (err) {
             console.warn('Redirect payment confirmation failed:', err);
-            // Don't block — webhook may still process the payment
+            // Don't block — payment-status polling re-verifies server-side
           }
         }