create-brainerce-store 1.50.5 → 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.50.5",
+      version: "1.52.0",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       bin: {
         "create-brainerce-store": "dist/index.js"
@@ -178,7 +178,9 @@ var BRAINERCE_RUNTIME_DEPS = Object.freeze({
   // (Product.displayPrice / displayCurrency / displaySalePrice attached
   // additively when getProducts is called with a regionId). Scaffolded stores
   // must pin >=1.30 to get the auto-region + tax-estimate methods.
-  brainerce: "^1.32.0",
+  // 1.44 adds the order-level `notes` field to SetShippingAddressDto /
+  // SetCheckoutCustomerDto — the scaffolded checkout form types depend on it.
+  brainerce: "^1.44.0",
   "isomorphic-dompurify": "^3.8.0"
 });
 
@@ -286,66 +288,30 @@ 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
-    },
-    {
-      type: "select",
-      name: "theme",
-      message: "Theme:",
-      choices: [
-        {
-          title: "Minimal",
-          description: "Clean, neutral design with Inter font",
-          value: "minimal"
-        },
-        {
-          title: "Luxury",
-          description: "Dark, sophisticated design with Cormorant Garamond serif font",
-          value: "luxury"
-        },
-        {
-          title: "Playful",
-          description: "Warm, vibrant design with Nunito rounded font",
-          value: "playful"
-        }
-      ],
-      initial: 0
-    },
-    {
-      type: "select",
-      name: "pkgManager",
-      message: "Package manager:",
-      choices: [
-        {
-          title: `pnpm${detectInvokingPackageManager() === "pnpm" ? " (detected)" : ""}`,
-          value: "pnpm"
-        },
-        {
-          title: `npm${detectInvokingPackageManager() === "npm" ? " (detected)" : ""}`,
-          value: "npm"
-        },
-        {
-          title: `yarn${detectInvokingPackageManager() === "yarn" ? " (detected)" : ""}`,
-          value: "yarn"
-        },
-        {
-          title: `bun${detectInvokingPackageManager() === "bun" ? " (detected)" : ""}`,
-          value: "bun"
-        }
-      ],
-      initial: ["pnpm", "npm", "yarn", "bun"].indexOf(detectInvokingPackageManager())
-    }
-  );
+  questions.push({
+    type: "select",
+    name: "pkgManager",
+    message: "Package manager:",
+    choices: [
+      {
+        title: `pnpm${detectInvokingPackageManager() === "pnpm" ? " (detected)" : ""}`,
+        value: "pnpm"
+      },
+      {
+        title: `npm${detectInvokingPackageManager() === "npm" ? " (detected)" : ""}`,
+        value: "npm"
+      },
+      {
+        title: `yarn${detectInvokingPackageManager() === "yarn" ? " (detected)" : ""}`,
+        value: "yarn"
+      },
+      {
+        title: `bun${detectInvokingPackageManager() === "bun" ? " (detected)" : ""}`,
+        value: "bun"
+      }
+    ],
+    initial: ["pnpm", "npm", "yarn", "bun"].indexOf(detectInvokingPackageManager())
+  });
   const response = await (0, import_prompts.default)(questions, {
     onCancel: () => {
       throw new Error("PROMPT_CANCELLED");
@@ -355,8 +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 || "atelier",
     pkgManager: response.pkgManager || defaults.pkgManager || detectInvokingPackageManager()
   };
 }
@@ -383,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';",
@@ -411,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);
@@ -421,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);
@@ -459,6 +411,37 @@ async function scaffold(options) {
     isomorphicDompurifyVersion: BRAINERCE_RUNTIME_DEPS["isomorphic-dompurify"]
   };
   await copyWithEjs(baseDir, targetDir, templateVars);
+  if (options.canvas) {
+    const canvasDir = import_path.default.join(templatesRoot, framework, "ui-canvas");
+    if (!await import_fs_extra.default.pathExists(canvasDir)) {
+      throw new Error(`Canvas template not found at ${canvasDir}`);
+    }
+    const uiTarget = import_path.default.join(targetDir, "src", "ui");
+    await import_fs_extra.default.remove(uiTarget);
+    await copyWithEjs(canvasDir, uiTarget, templateVars);
+  }
+  const designName = options.design && options.design !== "minimal" ? options.design : null;
+  if (designName && !/^[a-z0-9-]+$/.test(designName)) {
+    throw new Error(`Invalid design name "${designName}"`);
+  }
+  const designDir = designName ? import_path.default.join(templatesRoot, framework, "designs", designName) : null;
+  if (designName && !options.canvas) {
+    if (!designDir || !await import_fs_extra.default.pathExists(designDir)) {
+      throw new Error(`Design "${designName}" not found at ${designDir}`);
+    }
+    const designUi = import_path.default.join(designDir, "ui");
+    if (await import_fs_extra.default.pathExists(designUi)) {
+      await copyWithEjs(designUi, import_path.default.join(targetDir, "src", "ui"), templateVars);
+    }
+    const designCss = import_path.default.join(designDir, "globals.css");
+    if (await import_fs_extra.default.pathExists(designCss)) {
+      await import_fs_extra.default.copy(designCss, import_path.default.join(targetDir, "src", "app", "globals.css"));
+    }
+    const designApp = import_path.default.join(designDir, "app-overlay");
+    if (await import_fs_extra.default.pathExists(designApp)) {
+      await copyWithEjs(designApp, import_path.default.join(targetDir, "src", "app"), templateVars);
+    }
+  }
   const messagesRoot = findMessagesDir(__dirname);
   const targetMessages = import_path.default.join(targetDir, "messages");
   await import_fs_extra.default.ensureDir(targetMessages);
@@ -479,6 +462,24 @@ async function scaffold(options) {
       import_path.default.join(targetMessages, `${options.language}.json`)
     );
   }
+  if (designName && designDir && !options.canvas) {
+    const patchDir = import_path.default.join(designDir, "messages-patch");
+    if (await import_fs_extra.default.pathExists(patchDir)) {
+      const localeFiles = (await import_fs_extra.default.readdir(targetMessages)).filter((f) => f.endsWith(".json"));
+      for (const file of localeFiles) {
+        const locale = file.replace(/\.json$/, "");
+        let patchFile = import_path.default.join(patchDir, `${locale}.json`);
+        if (!await import_fs_extra.default.pathExists(patchFile)) {
+          patchFile = import_path.default.join(patchDir, "en.json");
+        }
+        if (!await import_fs_extra.default.pathExists(patchFile)) continue;
+        const targetFile = import_path.default.join(targetMessages, file);
+        const base = await import_fs_extra.default.readJson(targetFile);
+        const patch = await import_fs_extra.default.readJson(patchFile);
+        await import_fs_extra.default.writeJson(targetFile, deepMerge(base, patch), { spaces: 2 });
+      }
+    }
+  }
   if (isMultiLocale) {
     const appDir = import_path.default.join(targetDir, "src", "app");
     const localeDir = import_path.default.join(appDir, "[locale]");
@@ -490,16 +491,18 @@ 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 (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 };
+  for (const [key, value] of Object.entries(patch)) {
+    const existing = out[key];
+    if (value && typeof value === "object" && !Array.isArray(value) && existing && typeof existing === "object" && !Array.isArray(existing)) {
+      out[key] = deepMerge(existing, value);
+    } else {
+      out[key] = value;
     }
   }
+  return out;
 }
 function findTemplatesDir(fromDir) {
   let dir = fromDir;
@@ -693,7 +696,11 @@ async function checkForUpdate(name, current) {
           res.on("end", () => {
             try {
               const latest = JSON.parse(data).version;
-              resolve(latest && latest !== current ? latest : null);
+              const newer = latest && latest.split(".").map(Number).reduce((acc, seg, i) => {
+                if (acc !== 0) return acc;
+                return seg - (Number(current.split(".")[i]) || 0);
+              }, 0) > 0;
+              resolve(newer ? latest : null);
             } catch {
               resolve(null);
             }
@@ -714,7 +721,10 @@ 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>", "Theme to apply", "minimal").option("--pkg-manager <manager>", "Package manager (npm, pnpm, yarn, bun)").option("--no-git", "Skip git initialization").option("--no-install", "Skip dependency installation").action(async (projectNameArg, options) => {
+).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) => {
   try {
     logger.banner(pkg.version);
     const nodeError = validateNodeVersion(process.versions.node);
@@ -746,6 +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", "atelier"];
     let language = options.language;
     if (language && !VALID_LANGUAGES.includes(language)) {
       logger.error(
@@ -765,6 +776,11 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
       logger.error(`Invalid --theme "${theme}". Expected one of: ${VALID_THEMES.join(", ")}`);
       process.exit(1);
     }
+    let design = options.design;
+    if (design && !VALID_DESIGNS.includes(design)) {
+      logger.error(`Invalid --design "${design}". Expected one of: ${VALID_DESIGNS.join(", ")}`);
+      process.exit(1);
+    }
     let pkgManager = options.pkgManager;
     if (pkgManager && !VALID_PKG_MANAGERS.includes(pkgManager)) {
       logger.error(
@@ -774,6 +790,7 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
     }
     const skipGit = options.git === false;
     const skipInstall = options.install === false;
+    const canvas = options.canvas === true;
     let storeInfo = null;
     let resolvedApiUrl = candidateApiUrls[0];
     if (connectionId) {
@@ -813,13 +830,16 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
         language: languageDefault,
         framework,
         theme,
-        pkgManager
+        design,
+        pkgManager,
+        canvas
       });
       projectName = answers.projectName;
       connectionId = answers.connectionId;
       language = answers.language;
       framework = answers.framework;
       theme = answers.theme;
+      design = answers.design;
       pkgManager = answers.pkgManager;
     }
     const nameError = validateProjectName(projectName);
@@ -871,7 +891,9 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
       currency: storeInfo.currency,
       language: language || storeInfo.language,
       i18n: storeInfo.i18n,
-      scaffoldInPlace
+      scaffoldInPlace,
+      canvas,
+      design: canvas ? void 0 : design || "atelier"
     });
     scaffoldSpinner.succeed(
       scaffoldInPlace ? "Scaffolded into current directory" : `Scaffolded into ./${projectName}`
@@ -911,14 +933,38 @@ program.name("create-brainerce-store").description("Scaffold a production-ready
         );
       }
     }
-    logger.success("\nYour Brainerce store is ready!\n");
-    logger.info("Next steps:");
-    if (!scaffoldInPlace) {
-      logger.step(`cd ${projectName}`);
-    }
-    logger.step(`${pkgManager}${pkgManager === "npm" ? " run" : ""} dev`);
-    logger.info(`
+    if (canvas) {
+      logger.success("\nYour Brainerce store is ready \u2014 as a blank canvas!\n");
+      logger.info(
+        "Commerce is fully wired (cart, checkout, variants, coupons), but src/ui\nis bare, unstyled skeletons with zero aesthetic opinion. THE next step\nis to design it \u2014 open this folder in Claude Code and run:"
+      );
+      logger.step(`/design <your art-direction brief>`);
+      logger.info("\nThen:");
+      if (!scaffoldInPlace) {
+        logger.step(`cd ${projectName}`);
+      }
+      logger.step(`${pkgManager}${pkgManager === "npm" ? " run" : ""} dev`);
+      logger.info(
+        `
+Your store will be running at http://localhost:3000
+(hook contracts + rules: AI-GUIDE.md)`
+      );
+    } else {
+      logger.success("\nYour Brainerce store is ready!\n");
+      logger.info("Next steps:");
+      if (!scaffoldInPlace) {
+        logger.step(`cd ${projectName}`);
+      }
+      logger.step(`${pkgManager}${pkgManager === "npm" ? " run" : ""} dev`);
+      logger.info(`
 Your store will be running at http://localhost:3000`);
+      logger.info(
+        `
+Want a unique design? Open this folder in Claude Code and run:
+  /design <your art-direction brief>
+(commerce stays intact \u2014 see AI-GUIDE.md)`
+      );
+    }
     const latestVersion = await updateCheck;
     if (latestVersion) logger.updateAvailable(latestVersion, pkg.version);
   } catch (err) {

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",
@@ -247,7 +279,9 @@
     "privacyPolicyLink": "Privacy Policy",
     "privacyRequired": "You must accept the privacy policy to continue",
     "acceptsMarketing": "Send me news, promotions, and updates by email",
-    "saveDetailsForNextTime": "Save my details for faster checkout next time"
+    "saveDetailsForNextTime": "Save my details for faster checkout next time",
+    "orderNotes": "Order notes (optional)",
+    "orderNotesPlaceholder": "Anything we should know about your order? e.g. delivery instructions"
   },
   "auth": {
     "loginPageTitle": "Sign In",
@@ -331,6 +365,7 @@
     "orderHistory": "Order History",
     "noOrders": "No orders yet",
     "noOrdersDesc": "Your order history will appear here after your first purchase.",
+    "orderNotes": "Your order note",
     "verified": "Verified",
     "unverified": "Unverified",
     "memberSince": "Member since",

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": "בחר אפשרות",
@@ -247,7 +279,9 @@
     "privacyPolicyLink": "מדיניות הפרטיות",
     "privacyRequired": "יש לאשר את מדיניות הפרטיות כדי להמשיך",
     "acceptsMarketing": "שלחו לי חדשות, מבצעים ועדכונים במייל",
-    "saveDetailsForNextTime": "שמרו את הפרטים שלי לתשלום מהיר בפעם הבאה"
+    "saveDetailsForNextTime": "שמרו את הפרטים שלי לתשלום מהיר בפעם הבאה",
+    "orderNotes": "הערות להזמנה (אופציונלי)",
+    "orderNotesPlaceholder": "משהו שכדאי שנדע על ההזמנה? למשל הנחיות למשלוח"
   },
   "auth": {
     "loginPageTitle": "התחברות",
@@ -331,6 +365,7 @@
     "orderHistory": "היסטוריית הזמנות",
     "noOrders": "אין הזמנות עדיין",
     "noOrdersDesc": "היסטוריית ההזמנות שלך תופיע כאן לאחר הרכישה הראשונה.",
+    "orderNotes": "ההערה שלך להזמנה",
     "verified": "מאומת",
     "unverified": "לא מאומת",
     "memberSince": "חבר מאז",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-brainerce-store",
-  "version": "1.50.5",
+  "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

@@ -0,0 +1,60 @@
+---
+description: Redesign this storefront's presentation layer to a distinctive, production-grade look
+---
+
+You are the design lead for this Brainerce storefront. Design brief from the
+merchant: **$ARGUMENTS** (if empty, ask for a one-line direction first — e.g.
+"dark cinematic jewelry gallery", "brutalist streetwear", "warm Mediterranean
+boutique").
+
+## Rebuild, don't restyle
+
+The shipped `src/ui/` is a WORKING REFERENCE, not an aesthetic to preserve.
+(In a `--canvas` scaffold it's already a bare unstyled skeleton — each
+component carries a `DESIGN ME` marker telling you what the surface is and
+which hook feeds it; skip straight to designing.)
+You are expected to design from scratch: deleting entire files under
+`src/ui/` and rebuilding them around the same hooks is encouraged — that is
+what the folder exists for. Do not inherit the current look's layout,
+spacing, or component structure unless it genuinely serves your direction.
+Build the store YOU would build; the reference only shows which hooks feed
+which surface.
+
+## Ground rules (non-negotiable)
+
+1. Read `AI-GUIDE.md` and `src/ui/`'s current structure BEFORE writing code.
+2. You may rewrite anything in `src/ui/**` and `src/app/globals.css`, and
+   wire new ui components in the thin `src/app/**` routes. You may NOT touch
+   `src/core/**`, `src/app/api/**`, or checkout/auth/account components.
+3. All data via `@/core/hooks/*` and the store provider — no hardcoded
+   products, prices, or currency symbols.
+4. All copy via `useTranslations()`, keys added to every file in `messages/`.
+
+## 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.
+   Bold and specific beats safe and generic; do not hedge toward the middle.
+2. **Tokens first**: rewrite `globals.css` custom properties + font loading
+   in the locale layout.
+3. **Surfaces in order**: header/footer → homepage sections → product card +
+   grid → product page → cart. Keep each step compiling.
+4. **Micro-details**: hover states, loading states, one signature
+   interaction. Wrap all motion in `prefers-reduced-motion` guards.
+5. **Verify** (mandatory): `pnpm exec tsc --noEmit` = 0, then `pnpm dev` and
+   drive home → product → add-to-cart → cart in a real browser; screenshot
+   desktop (1440) AND mobile (390). For RTL locales check anchoring and
+   arrow directions. Fix what looks off before reporting.
+
+Report with: the direction chosen, what changed, screenshots, and anything
+that needs merchant input (e.g. brand name, logo, photography).

package/templates/nextjs/base/.env.local.ejs

@@ -17,3 +17,8 @@ NEXT_PUBLIC_BRAINERCE_API_URL=<%- apiBaseUrlEnv %>
 
 # Public site URL — used for sitemap, robots.txt, and SEO metadata
 NEXT_PUBLIC_SITE_URL=http://localhost:3000
+
+# Optional: floating WhatsApp contact button (used by some designs, e.g.
+# passepartout). Digits only, international format without "+"
+# (e.g. 14155550123). Leave unset to hide the button.
+# NEXT_PUBLIC_WHATSAPP_PHONE=