create-brainerce-store 1.51.0 → 1.52.0

package/README.md

@@ -0,0 +1,72 @@
+# create-brainerce-store
+
+Scaffold a production-ready e-commerce storefront connected to [Brainerce](https://brainerce.com) — cart, checkout, variants, coupons, auth, SEO, and i18n wired out of the box.
+
+```bash
+npm create brainerce-store@latest my-store -- --connection-id vc_xxxxxxxx
+# or
+pnpm create brainerce-store my-store --connection-id vc_xxxxxxxx
+```
+
+Run it with no flags for a fully interactive setup. The CLI fetches your store's name, currency, language, and locales from the connection ID (`vc_*`, from your Brainerce dashboard), so the generated store matches the real channel from the first `dev` run.
+
+## The design
+
+Every scaffold ships **Atelier** — a complete, AI-built storefront look (not just a color theme): warm editorial gallery with soft washes + glass surfaces, a floating hero collage, near-full-bleed product grid, styled popover dropdowns, a mini-cart drawer that opens on add-to-cart, and an RTL-safe fly-to-cart micro-interaction. Fully de-branded — driven by your store's name, catalog and dashboard content.
+
+It's a starting point, not a lock-in: the entire look lives in `src/ui/` + `globals.css` and is designed to be rewritten (see below).
+
+## Blank-canvas mode
+
+```bash
+npm create brainerce-store@latest my-store -- --connection-id vc_xxx --canvas
+```
+
+`--canvas` ships `src/ui/` as bare, semantic, essentially-unstyled skeletons (`DESIGN ME` markers included) with zero aesthetic opinion — commerce stays fully wired. It's the starting point for designing a storefront from scratch with an AI session, and the authoring substrate for new gallery designs. Canvas mode skips design packs and theme overlays entirely.
+
+## AI-first by default
+
+Every scaffolded store is ready to be redesigned by an AI coding session:
+
+- **`CLAUDE.md`** — auto-loaded by Claude Code; teaches the session the one rule (`core/` is the platform's, `ui/` is yours) before it touches anything.
+- **`AGENTS.md`** — the same context for other agentic tools.
+- **`/design <your art-direction brief>`** — a ready-made slash command that walks the full redesign: concept → implementation in `ui/` → verification (tsc, real browser, screenshots, RTL checks).
+- **`AI-GUIDE.md`** — the design contract: file map, per-page hook contracts, verification loop, and hard-won RTL/i18n gotchas from real agency builds.
+
+## Architecture (core/ui)
+
+- `src/core/` — platform-owned commerce: client, auth, providers, and data/behavior hooks that return state + handlers, never JSX. Don't modify.
+- `src/ui/` — 100% replaceable presentation. Delete-and-rebuild is encouraged; the store keeps working.
+- `src/app/` — thin routes composing the two (~10 lines each).
+- An ESLint boundary rule enforces the split in both directions.
+
+Full details: [TEMPLATE-ARCHITECTURE.md](./TEMPLATE-ARCHITECTURE.md).
+
+## Flags
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--connection-id <id>` | Brainerce vibe-coded connection ID (`vc_*`) | prompted |
+| `--canvas` | Bare unstyled `src/ui/` skeletons for AI-driven design | off |
+| `--language <lang>` | Store language (`en`, `he`) | fetched from store |
+| `--pkg-manager <pm>` | `npm`, `pnpm`, `yarn`, `bun` | auto-detected |
+| `--framework <fw>` | `nextjs` (Vite/Remix coming) | `nextjs` |
+| `--theme <name>` | Token theme (`minimal`, `luxury`, `playful`) — kept for backward compat | `minimal` |
+| `--api-url <url>` | Brainerce API base URL (or `BRAINERCE_API_URL` env) | auto-discovered |
+| `--no-git` | Skip git initialization | git on |
+| `--no-install` | Skip dependency installation | install on |
+
+Pass `.` as the project name to scaffold into the current directory.
+
+## Requirements
+
+Node `^20.19.0 || ^22.13.0 || >=24.0.0`.
+
+## After scaffolding
+
+```bash
+cd my-store
+pnpm dev          # store at http://localhost:3000
+```
+
+Want a unique look? Open the folder in Claude Code and run `/design <your art-direction brief>`.

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "create-brainerce-store",
-      version: "1.51.0",
+      version: "1.52.0",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       bin: {
         "create-brainerce-store": "dist/index.js"
@@ -288,37 +288,6 @@ async function runInteractive(defaults) {
       initial: 0
     });
   }
-  questions.push({
-    type: "select",
-    name: "framework",
-    message: "Framework:",
-    choices: [
-      { title: "Next.js 15 (recommended)", value: "nextjs" },
-      { title: "Vite + React (coming soon)", value: "vite", disabled: true },
-      { title: "Remix (coming soon)", value: "remix", disabled: true }
-    ],
-    initial: 0
-  });
-  if (!defaults.canvas && !defaults.design) {
-    questions.push({
-      type: "select",
-      name: "design",
-      message: "Design:",
-      choices: [
-        {
-          title: "Passe-Partout \u2014 warm gallery minimal (recommended)",
-          description: "Framed product cards, placard PDP, print-serif titles",
-          value: "passepartout"
-        },
-        {
-          title: "Minimal \u2014 bare clean base",
-          description: "Neutral tokens, unopinionated layout",
-          value: "minimal"
-        }
-      ],
-      initial: 0
-    });
-  }
   questions.push({
     type: "select",
     name: "pkgManager",
@@ -352,9 +321,9 @@ async function runInteractive(defaults) {
     projectName: defaults.projectName || response.projectName,
     connectionId: defaults.connectionId || response.connectionId,
     language: response.language || defaults.language || "en",
-    framework: response.framework || defaults.framework || "nextjs",
+    framework: defaults.framework || "nextjs",
     theme: response.theme || defaults.theme || "minimal",
-    design: response.design || defaults.design || "minimal",
+    design: response.design || defaults.design || "atelier",
     pkgManager: response.pkgManager || defaults.pkgManager || detectInvokingPackageManager()
   };
 }
@@ -381,22 +350,8 @@ function toEnvLiteral(value) {
 function isValidLocale(locale) {
   return typeof locale === "string" && /^[a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})?$/.test(locale);
 }
-function getFontConfig(language, theme) {
+function getFontConfig(language) {
   const isHebrew = language === "he";
-  if (theme === "luxury") {
-    const subsets = isHebrew ? "['latin']" : "['latin']";
-    return {
-      fontImport: "import { Cormorant_Garamond } from 'next/font/google';",
-      fontVariable: `const font = Cormorant_Garamond({ weight: ['400', '500', '600', '700'], subsets: ${subsets} });`
-    };
-  }
-  if (theme === "playful") {
-    const subsets = isHebrew ? "['latin']" : "['latin']";
-    return {
-      fontImport: "import { Nunito } from 'next/font/google';",
-      fontVariable: `const font = Nunito({ subsets: ${subsets} });`
-    };
-  }
   if (isHebrew) {
     return {
       fontImport: "import { Rubik } from 'next/font/google';",
@@ -409,7 +364,7 @@ function getFontConfig(language, theme) {
   };
 }
 async function scaffold(options) {
-  const { projectName, framework, theme, scaffoldInPlace } = options;
+  const { projectName, framework, scaffoldInPlace } = options;
   const targetDir = scaffoldInPlace ? process.cwd() : import_path.default.resolve(process.cwd(), projectName);
   if (!scaffoldInPlace && await import_fs_extra.default.pathExists(targetDir)) {
     const contents = await import_fs_extra.default.readdir(targetDir);
@@ -419,12 +374,11 @@ async function scaffold(options) {
   }
   const templatesRoot = findTemplatesDir(__dirname);
   const baseDir = import_path.default.join(templatesRoot, framework, "base");
-  const themeDir = import_path.default.join(templatesRoot, framework, "themes", theme);
   if (!await import_fs_extra.default.pathExists(baseDir)) {
     throw new Error(`Template "${framework}" not found at ${baseDir}`);
   }
   const direction = getDirection(options.language);
-  const fontConfig = getFontConfig(options.language, theme);
+  const fontConfig = getFontConfig(options.language);
   const ogLocale = options.language === "he" ? "he_IL" : "en_US";
   const rawSupportedLocales = options.i18n?.supportedLocales || [options.language];
   const supportedLocales = rawSupportedLocales.filter(isValidLocale);
@@ -537,16 +491,6 @@ async function scaffold(options) {
       await import_fs_extra.default.move(import_path.default.join(appDir, entry.name), import_path.default.join(localeDir, entry.name));
     }
   }
-  if (!options.canvas && !designName && await import_fs_extra.default.pathExists(themeDir)) {
-    const themeCss = import_path.default.join(themeDir, "globals.css");
-    if (await import_fs_extra.default.pathExists(themeCss)) {
-      await import_fs_extra.default.copy(themeCss, import_path.default.join(targetDir, "src", "app", "globals.css"));
-    }
-    const themeJson = import_path.default.join(themeDir, "theme.json");
-    if (await import_fs_extra.default.pathExists(themeJson)) {
-      await import_fs_extra.default.copy(themeJson, import_path.default.join(targetDir, "theme.json"));
-    }
-  }
 }
 function deepMerge(base, patch) {
   const out = { ...base };
@@ -777,10 +721,7 @@ var program = new import_commander.Command();
 program.name("create-brainerce-store").description("Scaffold a production-ready e-commerce storefront connected to Brainerce").version(pkg.version).argument("[project-name]", "Name for the project directory").option("--connection-id <id>", "Brainerce vibe-coded connection ID (vc_*)").option(
   "--api-url <url>",
   "Brainerce API base URL (overrides BRAINERCE_API_URL env, defaults to https://api.brainerce.com)"
-).option("--language <lang>", "Store language (en, he)").option("--framework <framework>", "Framework to use", "nextjs").option("--theme <theme>", "Token theme to apply (kept for backward compat)", "minimal").option(
-  "--design <design>",
-  "Storefront design pack: passepartout (warm gallery minimal) or minimal (bare base)"
-).option("--pkg-manager <manager>", "Package manager (npm, pnpm, yarn, bun)").option(
+).option("--language <lang>", "Store language (en, he)").addOption(new import_commander.Option("--framework <framework>", "Framework to use").default("nextjs").hideHelp()).option("--theme <theme>", "Token theme to apply (kept for backward compat)", "minimal").addOption(new import_commander.Option("--design <design>", "Storefront design pack").hideHelp()).option("--pkg-manager <manager>", "Package manager (npm, pnpm, yarn, bun)").option(
   "--canvas",
   "Scaffold src/ui as bare unstyled skeletons \u2014 a blank canvas for AI-driven design (commerce stays fully wired)"
 ).option("--no-git", "Skip git initialization").option("--no-install", "Skip dependency installation").action(async (projectNameArg, options) => {
@@ -815,7 +756,7 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
     const VALID_PKG_MANAGERS = ["npm", "pnpm", "yarn", "bun"];
     const VALID_FRAMEWORKS = ["nextjs"];
     const VALID_THEMES = ["minimal", "luxury", "playful"];
-    const VALID_DESIGNS = ["minimal", "passepartout"];
+    const VALID_DESIGNS = ["minimal", "atelier"];
     let language = options.language;
     if (language && !VALID_LANGUAGES.includes(language)) {
       logger.error(
@@ -952,7 +893,7 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
       i18n: storeInfo.i18n,
       scaffoldInPlace,
       canvas,
-      design: canvas ? void 0 : design || "minimal"
+      design: canvas ? void 0 : design || "atelier"
     });
     scaffoldSpinner.succeed(
       scaffoldInPlace ? "Scaffolded into current directory" : `Scaffolded into ./${projectName}`

package/messages/en.json

@@ -100,6 +100,38 @@
     "addingAll": "Adding...",
     "by": "By"
   },
+  "reviews": {
+    "title": "Reviews",
+    "noReviews": "No reviews yet — be the first to share your experience.",
+    "verifiedPurchase": "Verified purchase",
+    "loading": "Loading…",
+    "signIn": "Sign in",
+    "signInSuffix": "to leave a review for this product.",
+    "onlyPurchasers": "Only customers who purchased this product can leave a review.",
+    "reviewsDisabled": "Reviews are not enabled for this store.",
+    "cannotReview": "You cannot review this product right now.",
+    "confirmDelete": "Delete your review for this product?",
+    "deleteFailed": "Could not delete your review. Please try again.",
+    "startOver": "Want to start over? You can delete your review.",
+    "deleting": "Deleting…",
+    "deleteReview": "Delete review",
+    "alreadySubmitted": "You've already submitted a review for this product.",
+    "tooMany": "Too many submissions. Please try again in a few minutes.",
+    "updateFailed": "Could not update your review. Please try again.",
+    "submitFailed": "Could not submit your review. Please try again.",
+    "thanksUpdated": "Thanks! Your review has been updated.",
+    "thanksSubmitted": "Thanks! Your review has been submitted.",
+    "editYourReview": "Edit your review",
+    "writeReview": "Write a review",
+    "yourRating": "Your rating",
+    "starRating": "Star rating",
+    "yourReview": "Your review",
+    "optionalField": "optional",
+    "saving": "Saving…",
+    "submittingBtn": "Submitting…",
+    "saveChanges": "Save changes",
+    "submitReview": "Submit review"
+  },
   "customization": {
     "title": "Personalize this product",
     "selectPlaceholder": "Choose an option",

package/messages/he.json

@@ -100,6 +100,38 @@
     "addingAll": "מוסיף...",
     "by": "מאת"
   },
+  "reviews": {
+    "title": "ביקורות",
+    "noReviews": "אין עדיין ביקורות — היו הראשונים לשתף.",
+    "verifiedPurchase": "רכישה מאומתת",
+    "loading": "טוען…",
+    "signIn": "התחברו",
+    "signInSuffix": "כדי לכתוב ביקורת על המוצר.",
+    "onlyPurchasers": "רק לקוחות שרכשו את המוצר יכולים לכתוב ביקורת.",
+    "reviewsDisabled": "ביקורות אינן פעילות בחנות זו.",
+    "cannotReview": "לא ניתן לכתוב ביקורת על המוצר כרגע.",
+    "confirmDelete": "למחוק את הביקורת שלך על המוצר?",
+    "deleteFailed": "לא ניתן היה למחוק את הביקורת. נסו שוב.",
+    "startOver": "רוצים להתחיל מחדש? אפשר למחוק את הביקורת.",
+    "deleting": "מוחק…",
+    "deleteReview": "מחיקת ביקורת",
+    "alreadySubmitted": "כבר שלחתם ביקורת על המוצר הזה.",
+    "tooMany": "יותר מדי נסיונות. נסו שוב בעוד כמה דקות.",
+    "updateFailed": "לא ניתן היה לעדכן את הביקורת. נסו שוב.",
+    "submitFailed": "לא ניתן היה לשלוח את הביקורת. נסו שוב.",
+    "thanksUpdated": "תודה! הביקורת עודכנה.",
+    "thanksSubmitted": "תודה! הביקורת נשלחה.",
+    "editYourReview": "עריכת הביקורת",
+    "writeReview": "כתיבת ביקורת",
+    "yourRating": "הדירוג שלכם",
+    "starRating": "דירוג כוכבים",
+    "yourReview": "הביקורת שלכם",
+    "optionalField": "לא חובה",
+    "saving": "שומר…",
+    "submittingBtn": "שולח…",
+    "saveChanges": "שמירת שינויים",
+    "submitReview": "שליחת ביקורת"
+  },
   "customization": {
     "title": "התאמה אישית של המוצר",
     "selectPlaceholder": "בחר אפשרות",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-brainerce-store",
-  "version": "1.51.0",
+  "version": "1.52.0",
   "description": "Scaffold a production-ready e-commerce storefront connected to Brainerce",
   "bin": {
     "create-brainerce-store": "dist/index.js"

package/templates/nextjs/base/.claude/commands/design.md

@@ -32,6 +32,15 @@ which surface.
 
 ## The process
 
+## The quality bar (non-negotiable — from the AI-GUIDE)
+
+Exactly 3-5 colors (no purple unless asked, no gradients by default), max 2
+font families, tokens-only colors, Tailwind spacing scale, real imagery
+(never abstract filler), content-rich sections, mobile-first. After EACH
+major surface: screenshot → self-critique ("would a Lovable user accept
+this?") → fix → continue. See AI-GUIDE.md "The quality bar".
+
+
 1. **Commit to ONE art direction** — write it down in 4 lines (typography
    pairing incl. a script-compatible webfont, 6-10 color tokens, layout
    concept, motion language) at the top of `DESIGN.md` in the project root.

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

@@ -26,10 +26,31 @@ core change, stop and say so instead.
 | `src/ui/cart/` | you | cart page pieces |
 | `src/ui/shared/` | you | loader, image wrapper |
 | `src/app/globals.css` | you | tokens + global styles |
+| `src/components/ui/` | shared | shadcn/ui primitives — compose them, extend via variants |
 | `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 dialect (shadcn/ui + lucide + cn)
+
+This store speaks the same component dialect as Lovable / v0 / Bolt output:
+
+- **`src/components/ui/` holds official shadcn/ui primitives** (button, card,
+  badge, input, label, textarea, select, checkbox, radio-group, separator,
+  accordion, dialog, sheet, skeleton, tabs, tooltip). Compose them in `src/ui/`
+  instead of hand-rolling controls. Need a new look? **Extend via CVA
+  variants** (add a variant to `buttonVariants`/`badgeVariants`), never by
+  inline-overriding the same styles in twenty call sites.
+- **Icons: lucide-react only.** No inline `<svg>` paths, no emoji-as-icons,
+  no second icon set. Consistent 16/20/24px sizes.
+- **Class merging: `cn()`** from `@/core/lib/utils` (clsx + tailwind-merge) —
+  it's the same helper shadcn expects, already wired into every primitive.
+- **Tokens drive everything**: primitives read `--primary`, `--card`,
+  `--input`, `--ring`, `--radius`, etc. from `globals.css`. Restyle the store
+  by changing tokens (and variants), not by scattering literal colors.
+- `rounded`, `rounded-md`, `rounded-lg` all derive from `--radius`
+  (shadcn convention), so corner radius follows the theme automatically.
+
 ## The hook contract (your data supply)
 
 UI components get *everything* from `@/core/hooks/*` and
@@ -54,6 +75,34 @@ images, stock) comes from them — **never hardcode products**.
 4. If the store is RTL: check nothing is left-anchored that should be
    right-anchored, and directional arrows point with the reading direction.
 
+## The quality bar (distilled from Lovable / v0 / Bolt system prompts)
+
+Beautiful is the top priority — the first render must wow. Hard rules:
+
+1. **Design system first**: define all HSL semantic tokens in globals.css
+   BEFORE styling any component. Never direct colors (`text-white`,
+   `bg-black`) in classNames — tokens only.
+2. **Color budget: exactly 3-5 colors.** 1 brand color, 2-3 neutrals, 1-2
+   accents. Never purple/violet unless the merchant asked. No gradients by
+   default — solid colors; gradients only as subtle accents if requested.
+3. **Max 2 font families** (1 display + 1 body, both with the store's
+   script). Body line-height 1.4-1.6. Nothing below 14px.
+4. **Mobile-first**; flexbox by default, grid for true 2D; no absolute
+   positioning unless necessary.
+5. **Tailwind discipline**: spacing scale only (`p-4`, never `p-[16px]`),
+   `gap-*` over margins between siblings, `text-balance` on headlines.
+6. **Real imagery everywhere** — product photos from the catalog do the
+   heavy lifting; free stock hotlinks (Pexels/Unsplash) for editorial
+   sections. NEVER abstract filler shapes (gradient circles, blobs).
+   NEVER emojis as icons — one icon set, consistent 16/20/24px sizes.
+7. **Content-rich**: no section may render empty or thin. Empty states are
+   designed states with copy and structure, not blank space.
+8. Component variants in the design system, not inline overrides.
+9. Semantic HTML + ARIA + alt text + `sr-only` labels — always.
+10. **Verify with your eyes**: screenshot after each major surface, critique
+    it ("would a Lovable user accept this?"), fix, and only then move on.
+
+
 ## Hard-won gotchas (each one cost a real debugging session)
 
 - **RTL + cloned images**: `next/image` renders its `<img>` with `inset: 0`.
@@ -62,9 +111,9 @@ images, stock) comes from them — **never hardcode products**.
   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.
+- **`rounded` / `rounded-md` / `rounded-lg` all follow `--radius`** (shadcn
+  convention, wired in tailwind.config.ts) — change the token, not the
+  classes, when you want sharper or softer corners.
 - **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).

package/templates/nextjs/base/CLAUDE.md

@@ -21,6 +21,16 @@ and handlers, never JSX. Never hardcode catalog content.
 contracts, and hard-won RTL/i18n gotchas that will save you real debugging
 time.
 
+## The dialect
+
+- `src/components/ui/` = official **shadcn/ui primitives** (Button, Card,
+  Badge, Input, Select, Accordion, Dialog, Sheet, Skeleton, …). Compose them;
+  extend looks via CVA **variants**, never repeated inline overrides.
+- Icons: **lucide-react only** — no inline `<svg>`, no emoji-as-icons.
+- Class merging: **`cn()`** from `@/core/lib/utils`.
+- Colors/radius come from the semantic HSL tokens in `globals.css`
+  (`--primary`, `--card`, `--ring`, `--radius`, …) — restyle via tokens.
+
 ## Redesigning? Use the ready-made flow
 
 Run `/design <your art-direction brief>` — it walks the whole process:

package/templates/nextjs/base/package.json.ejs

@@ -1,39 +1,52 @@
-{
-  "name": "<%= projectName %>",
-  "version": "0.1.0",
-  "private": true,
-  "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start",
-    "lint": "next lint",
-    "setup": "node scripts/fetch-store-info.mjs"
-  },
-  "dependencies": {
-    "brainerce": "<%= brainerceVersion %>",
-    "next": "^15.3.4",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0",
-    "clsx": "^2.1.0",
-    "tailwind-merge": "^2.2.0",
-    "isomorphic-dompurify": "<%= isomorphicDompurifyVersion %>",
-    "sharp": "^0.35.3"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "@types/react": "^19.0.0",
-    "@types/react-dom": "^19.0.0",
-    "autoprefixer": "^10.4.0",
-    "eslint": "^9.0.0",
-    "eslint-config-next": "^15.3.4",
-    "postcss": "^8.4.49",
-    "tailwindcss": "^3.4.0",
-    "typescript": "^5.4.0"
-  },
-  "engines": {
-    "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": ["sharp"]
-  }
-}
+{
+  "name": "<%= projectName %>",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "setup": "node scripts/fetch-store-info.mjs"
+  },
+  "dependencies": {
+    "brainerce": "<%= brainerceVersion %>",
+    "next": "^15.3.4",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "@radix-ui/react-accordion": "^1.2.0",
+    "@radix-ui/react-checkbox": "^1.1.1",
+    "@radix-ui/react-dialog": "^1.1.2",
+    "@radix-ui/react-label": "^2.1.0",
+    "@radix-ui/react-radio-group": "^1.2.0",
+    "@radix-ui/react-select": "^2.1.1",
+    "@radix-ui/react-separator": "^1.1.0",
+    "@radix-ui/react-slot": "^1.1.0",
+    "@radix-ui/react-tabs": "^1.1.0",
+    "@radix-ui/react-tooltip": "^1.1.4",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.462.0",
+    "tailwind-merge": "^2.5.2",
+    "tailwindcss-animate": "^1.0.7",
+    "isomorphic-dompurify": "<%= isomorphicDompurifyVersion %>",
+    "sharp": "^0.35.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "autoprefixer": "^10.4.0",
+    "eslint": "^9.0.0",
+    "eslint-config-next": "^15.3.4",
+    "postcss": "^8.4.49",
+    "tailwindcss": "^3.4.0",
+    "typescript": "^5.4.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || ^22.13.0 || >=24.0.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": ["sharp"]
+  }
+}

package/templates/nextjs/base/src/app/globals.css

@@ -1,30 +1,36 @@
-@tailwind base;
-@tailwind components;
-@tailwind utilities;
-
-@layer base {
-  :root {
-    --background: 0 0% 100%;
-    --foreground: 0 0% 9%;
-    --primary: 0 0% 9%;
-    --primary-foreground: 0 0% 98%;
-    --secondary: 0 0% 96%;
-    --secondary-foreground: 0 0% 9%;
-    --muted: 0 0% 96%;
-    --muted-foreground: 0 0% 45%;
-    --accent: 0 0% 96%;
-    --accent-foreground: 0 0% 9%;
-    --destructive: 0 84% 60%;
-    --destructive-foreground: 0 0% 98%;
-    --border: 0 0% 90%;
-    --radius: 0.5rem;
-  }
-
-  * {
-    @apply border-border;
-  }
-
-  body {
-    @apply bg-background text-foreground antialiased;
-  }
-}
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 0 0% 9%;
+    --primary: 0 0% 9%;
+    --primary-foreground: 0 0% 98%;
+    --secondary: 0 0% 96%;
+    --secondary-foreground: 0 0% 9%;
+    --muted: 0 0% 96%;
+    --muted-foreground: 0 0% 45%;
+    --accent: 0 0% 96%;
+    --accent-foreground: 0 0% 9%;
+    --destructive: 0 84% 60%;
+    --destructive-foreground: 0 0% 98%;
+    --border: 0 0% 90%;
+    --input: 0 0% 90%;
+    --ring: 0 0% 9%;
+    --card: 0 0% 100%;
+    --card-foreground: 0 0% 9%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 0 0% 9%;
+    --radius: 0.5rem;
+  }
+
+  * {
+    @apply border-border;
+  }
+
+  body {
+    @apply bg-background text-foreground antialiased;
+  }
+}

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

@@ -76,16 +76,6 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
   const t = useTranslations('checkout');
   const { storeInfo } = useStoreInfo();
 
-  // Defense in depth: the parent already validates checkoutId from URL params,
-  // but we re-check here so the component is safe to render in any context.
-  if (!isValidCheckoutId(checkoutId)) {
-    return (
-      <div className={cn('border-destructive/50 rounded-md border p-4', className)}>
-        <p className="text-destructive text-sm">{t('paymentError')}</p>
-      </div>
-    );
-  }
-
   const [paymentIntent, setPaymentIntent] = useState<PaymentIntent | null>(null);
   const [preloadedSdk, setPreloadedSdk] = useState<PaymentClientSdk | null>(null);
   const [loading, setLoading] = useState(true);
@@ -174,6 +164,10 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
   // "call createPaymentProcess right before you need to render the wallet"
   // =========================================================================
   useEffect(() => {
+    // Defense in depth: the parent already validates checkoutId from URL
+    // params, but we re-check here so the component is safe to render in any
+    // context. Invalid id → no SDK loading, no API calls (error UI below).
+    if (!isValidCheckoutId(checkoutId)) return;
     if (initialized.current) return;
     initialized.current = true;
 
@@ -488,6 +482,16 @@ export function PaymentStep({ checkoutId, className }: PaymentStepProps) {
 
   // --- UI ---
 
+  // Invalid checkout id — render the error box instead of ever spinning.
+  // (Checked after the hooks above so hook order is stable across renders.)
+  if (!isValidCheckoutId(checkoutId)) {
+    return (
+      <div className={cn('border-destructive/50 rounded-md border p-4', className)}>
+        <p className="text-destructive text-sm">{t('paymentError')}</p>
+      </div>
+    );
+  }
+
   if (loading) {
     return (
       <div className={cn('flex flex-col items-center justify-center py-12', className)}>