create-brainerce-store 1.52.1 → 1.52.4

package/README.md

@@ -14,7 +14,7 @@ Run it with no flags for a fully interactive setup. The CLI fetches your store's
 
 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).
+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). The shipped texts are **example content** (a boutique voice, like any template's sample copy) — your catalog replaces the imagery automatically, and the copy lives in `messages/` ready to be rewritten by you or an AI session. On a brand-new store with no products yet, the homepage hero shows a designed placeholder that swaps for your first published products.
 
 ## Blank-canvas mode
 

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "create-brainerce-store",
-      version: "1.52.1",
+      version: "1.52.4",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       bin: {
         "create-brainerce-store": "dist/index.js"
@@ -393,6 +393,9 @@ async function scaffold(options) {
   const templateVars = {
     projectName: options.projectName,
     connectionId: options.connectionId,
+    /** Raw store name for prose contexts (markdown docs) — JS/env contexts
+     *  must keep using the escaped storeNameJs / storeNameEnv variants. */
+    storeName: cleanStoreName,
     storeNameJs: toJsStringLiteral(cleanStoreName),
     titleTemplateJs: toJsStringLiteral(`%s | ${cleanStoreName}`),
     storeNameEnv: toEnvLiteral(cleanStoreName),
@@ -963,7 +966,15 @@ Your store will be running at http://localhost:3000
 Your store will be running at http://localhost:3000`);
       logger.info(
         `
-Want a unique design? Open this folder in Claude Code and run:
+The storefront ships with example boutique copy as a starting point \u2014
+your real products replace the imagery automatically, and the texts
+live in messages/ (or let an AI session rewrite them).`
+      );
+      logger.info(
+        `
+Want a unique design? Open THE STORE FOLDER ITSELF in Claude Code
+(not a parent folder \u2014 that's how CLAUDE.md auto-loads and the AI
+knows this is a live, connected Brainerce storefront), then run:
   /design <your art-direction brief>
 (commerce stays intact \u2014 see AI-GUIDE.md)`
       );

package/package.json

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

package/templates/nextjs/base/AGENTS.md.ejs

@@ -0,0 +1,65 @@
+# AGENTS.md — this is a LIVE Brainerce storefront
+
+**Store: "<%- storeName %>" · sales channel `<%- connectionId %>` — already
+connected.** Products, cart, checkout, coupons, discounts, orders and content
+flow in real time from the Brainerce dashboard. There is nothing to hook up.
+
+- **NEVER suggest connecting this store to Shopify, WooCommerce, or "a real
+  system"** — Brainerce IS the commerce backend, and this store is wired to
+  it end-to-end.
+- **NEVER build standalone HTML mockups or demo pages** — design THIS Next.js
+  app. Run `pnpm dev` and you are working against live data.
+- **NEVER hardcode products, prices, or currency** — the catalog is live.
+- **No server side is needed** — the backend is Brainerce's cloud. This repo
+  is a frontend (plus thin, already-included API proxy routes under
+  `src/app/api/`). Do not scaffold databases, auth servers, or admin panels —
+  the merchant manages everything in the Brainerce dashboard.
+
+Platform docs (endpoints, SDK, integration recipes): https://brainerce.com/docs
+— AI-readable index: https://brainerce.com/llms.txt
+
+**Before building any feature the merchant asks for** (loyalty points,
+shipping zones, subscriptions, gift cards, multi-currency, reviews,
+abandoned-cart recovery, etc.) — check the docs first. Brainerce likely
+already has it as a platform capability (dashboard toggle + hook/SDK
+method) that only needs a UI in `src/ui/`, not a feature built from scratch.
+
+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.
+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, motion language, and hard-won RTL/i18n gotchas that will save you
+real debugging time.
+
+## Redesigning?
+
+Follow the process documented in AI-GUIDE.md: commit to one art direction,
+rewrite tokens first, then surfaces in order (header, home, card, product
+page, cart), then verify.
+
+## 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/`. The shipped copy is example boutique content — a
+starting point meant to be rewritten in the store's real voice. Hebrew: no
+uppercase transforms, no wide letter-spacing on headings, logical CSS
+properties only (`ms-/me-`, `ps-/pe-`, `start-/end-`).

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

@@ -103,6 +103,37 @@ Beautiful is the top priority — the first render must wow. Hard rules:
     it ("would a Lovable user accept this?"), fix, and only then move on.
 
 
+## Motion language (CSS-first)
+
+The store should feel alive, premium and intentional — every animation guides
+attention, confirms an action, or rewards exploration. Rules:
+
+- **Timing tokens** (use these, never ad-hoc numbers): 80ms instant feedback ·
+  180ms hover · 300ms UI state change · 500-600ms section entrance · 900ms
+  hero only. Stagger siblings 40-80ms.
+- **Easing**: entrances `cubic-bezier(0.16, 1, 0.3, 1)` (out-expo); springy
+  pops `cubic-bezier(0.34, 1.56, 0.64, 1)` (out-back); loops and hovers
+  ease-in-out. Exits faster than entrances.
+- **Reveals**: below-the-fold sections animate on viewport entry
+  (IntersectionObserver — see `src/ui/shared/reveal.tsx`), never tied to
+  scroll distance. One orchestrated reveal per section beats scattered
+  effects; `viewport once` — do not re-animate on every scroll.
+- **Micro-interactions**: CSS/WAAPI first (see `src/ui/shared/fly-to-cart.ts`
+  for the pattern) — ripple, bump, image zoom, quick-add slide-up are all
+  achievable without a library.
+- **Pointer effects** (magnetic buttons, tilt cards, custom cursor, mouse
+  parallax): desktop only — gate on `(pointer: fine)` and no-op under
+  `prefers-reduced-motion`. `will-change: transform` ONLY on elements animated
+  per-frame; never sprinkle it broadly.
+- **Never `transition-all`** — always name the property
+  (`transition-transform`, `transition-opacity`). Animate only compositor
+  properties (`transform`, `opacity`) — never layout properties
+  (width/height/top/margin). 60fps is non-negotiable.
+- **Ambient effects** (gradient blobs, particles): maximum one per page, hero
+  only — never on inner pages.
+- **framer-motion / GSAP are not installed.** They are allowed, but they are
+  new runtime dependencies — flag it to the user before adding.
+
 ## Hard-won gotchas (each one cost a real debugging session)
 
 - **RTL + cloned images**: `next/image` renders its `<img>` with `inset: 0`.

package/templates/nextjs/base/CLAUDE.md.ejs

@@ -0,0 +1,76 @@
+# CLAUDE.md — this is a LIVE Brainerce storefront
+
+**Store: "<%- storeName %>" · sales channel `<%- connectionId %>` — already
+connected.** Products, cart, checkout, coupons, discounts, orders and content
+flow in real time from the Brainerce dashboard. There is nothing to hook up.
+
+- **NEVER suggest connecting this store to Shopify, WooCommerce, or "a real
+  system"** — Brainerce IS the commerce backend, and this store is wired to
+  it end-to-end.
+- **NEVER build standalone HTML mockups or demo pages** — design THIS Next.js
+  app. Run `pnpm dev` and you are working against live data.
+- **NEVER hardcode products, prices, or currency** — the catalog is live.
+- **No server side is needed** — the backend is Brainerce's cloud. This repo
+  is a frontend (plus thin, already-included API proxy routes under
+  `src/app/api/`). Do not scaffold databases, auth servers, or admin panels —
+  the merchant manages everything in the Brainerce dashboard.
+
+Platform docs (endpoints, SDK, integration recipes): https://brainerce.com/docs
+— AI-readable index: https://brainerce.com/llms.txt
+
+**Before building any feature the merchant asks for** (loyalty points,
+shipping zones, subscriptions, gift cards, multi-currency, reviews,
+abandoned-cart recovery, etc.) — check the docs first. Brainerce likely
+already has it as a platform capability (dashboard toggle + hook/SDK
+method) that only needs a UI in `src/ui/`, not a feature built from scratch.
+
+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, motion language, 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:
+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/`. The shipped copy is example boutique content — a
+starting point meant to be rewritten in the store's real voice. Hebrew: no
+uppercase transforms, no wide letter-spacing on headings, logical CSS
+properties only (`ms-/me-`, `ps-/pe-`, `start-/end-`).

package/templates/nextjs/designs/atelier/messages-patch/en.json

@@ -55,7 +55,8 @@
     "newsletterPlaceholder": "Your email address",
     "newsletterCta": "Subscribe",
     "newsletterSuccess": "You are in! We promise to send only beautiful things.",
-    "newsletterPrivacy": "No spam. Unsubscribe anytime."
+    "newsletterPrivacy": "No spam. Unsubscribe anytime.",
+    "heroEmptyHint": "Your first published products will appear here"
   },
   "products": {
     "listingSubtitle": "Our full collection — handmade, genuine materials and love for detail.",

package/templates/nextjs/designs/atelier/messages-patch/he.json

@@ -55,7 +55,8 @@
     "newsletterPlaceholder": "כתובת האימייל שלך",
     "newsletterCta": "הרשמה",
     "newsletterSuccess": "נרשמת בהצלחה! מבטיחים לשלוח רק דברים יפים.",
-    "newsletterPrivacy": "בלי ספאם. אפשר להסיר את ההרשמה בכל רגע."
+    "newsletterPrivacy": "בלי ספאם. אפשר להסיר את ההרשמה בכל רגע.",
+    "heroEmptyHint": "המוצרים הראשונים שתפרסמו לחנות יופיעו כאן"
   },
   "products": {
     "listingSubtitle": "הקולקציה המלאה שלנו — עבודת יד, חומרים אמיתיים ואהבה לפרטים.",

package/templates/nextjs/designs/atelier/ui/home/hero-section.tsx

@@ -130,6 +130,32 @@ export function HeroSection({
             </span>
           </div>
         )}
+
+        {/* Empty catalog — the same floating composition as designed washes,
+            so a brand-new store still opens rich instead of half-blank. The
+            first two published products replace these automatically. */}
+        {!heroImage && (
+          <div
+            aria-hidden="true"
+            className="reveal reveal-delay-1 relative mx-auto h-[26rem] w-full max-w-md sm:h-[30rem] lg:col-span-6 lg:h-[34rem] lg:max-w-none"
+          >
+            <div
+              className="float-slow wash-forest absolute inset-y-0 start-[4%] flex w-[72%] -rotate-2 items-center justify-center overflow-hidden rounded-3xl border-4 border-background shadow-[0_36px_80px_-30px_hsl(var(--primary)/0.45)]"
+              style={{ '--float-rotate': '-2deg' } as React.CSSProperties}
+            >
+              <IconSparkle size={56} className="text-primary/25" />
+              <span className="glass absolute bottom-5 end-5 start-5 px-4 py-3 text-center text-sm font-medium text-muted-foreground">
+                {t('heroEmptyHint')}
+              </span>
+            </div>
+            <div
+              className="float-slower wash-sand absolute -end-2 top-[54%] flex aspect-[3/4] w-[38%] rotate-3 items-center justify-center rounded-3xl border-4 border-background shadow-[0_28px_60px_-24px_hsl(var(--primary)/0.4)] sm:end-0"
+              style={{ '--float-rotate': '3deg' } as React.CSSProperties}
+            >
+              <IconStar size={32} filled className="text-primary/20" />
+            </div>
+          </div>
+        )}
       </div>
     </section>
   );

package/templates/nextjs/base/AGENTS.md

@@ -1,41 +0,0 @@
-# AGENTS.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.
-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?
-
-Follow the process documented in AI-GUIDE.md: commit to one art direction,
-rewrite tokens first, then surfaces in order (header, home, card, product
-page, cart), then verify.
-
-## 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/CLAUDE.md

@@ -1,52 +0,0 @@
-# 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.
-
-## 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:
-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-`).