create-brainerce-store 1.52.2 → 1.52.5

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.2",
+      version: "1.52.5",
       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),
@@ -969,7 +972,9 @@ live in messages/ (or let an AI session rewrite them).`
       );
       logger.info(
         `
-Want a unique design? Open this folder in Claude Code and run:
+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.2",
+  "version": "1.52.5",
   "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/base/next.config.ts

@@ -26,7 +26,17 @@ const nextConfig: NextConfig = {
   // isomorphic-dompurify ships jsdom, which at runtime reads stylesheet files
   // from its own package directory. Webpack bundling breaks those relative
   // lookups — loading it externally from node_modules keeps the paths intact.
-  serverExternalPackages: ['isomorphic-dompurify'],
+  //
+  // brainerce (the SDK) is imported across both the server and client
+  // compilation boundaries in ~60 files, including the [locale]/layout.tsx
+  // route (see generateStaticParams below) whose static params are resolved
+  // by a separate jest-worker child process in `next dev` (webpack). That
+  // worker requires the compiled page against the vendor-chunks manifest
+  // while the main dev server may still be writing it, which can throw
+  // "Cannot find module './vendor-chunks/brainerce.js'". Excluding it from
+  // server bundling (loaded externally from node_modules instead) avoids the
+  // race.
+  serverExternalPackages: ['isomorphic-dompurify', 'brainerce'],
   images: {
     // The storefront is a consumer of the Brainerce API — it has to render
     // whatever image URLs the API returns. In practice those URLs are

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

@@ -7,7 +7,7 @@ import { SiteHeader } from '@/ui/layout/site-header';
 import { SiteFooter } from '@/ui/layout/site-footer';
 import { BrainerceBotWidget } from '@/components/brainerce-bot';
 import { getServerClient, fetchStoreInfo } from '@/core/lib/brainerce';
-import { getDirection, supportedLocales } from '@/i18n';
+import { getDirection, getMessages, supportedLocales } from '@/i18n';
 import { getNonce } from '@/core/lib/nonce';
 import '../globals.css';
 
@@ -62,7 +62,7 @@ export default async function RootLayout({
   // seeded a particular content type yet. New stores ship with default rows
   // seeded by the backend (StoresService.seedDefaultContent).
   const client = getServerClient(locale);
-  const [announcements, siteHeader, siteFooter, storeInfo] = await Promise.all([
+  const [announcements, siteHeader, siteFooter, storeInfo, messages] = await Promise.all([
     client.content.announcement.list(locale).catch(() => []),
     client.content.header.get('main', locale).catch(() => null),
     client.content.footer.get('main', locale).catch(() => null),
@@ -70,6 +70,10 @@ export default async function RootLayout({
     // render with the real currency, feature flags, and i18n config at frame 0
     // — without this, Googlebot sees USD/defaults baked into the HTML.
     fetchStoreInfo(locale),
+    // SSR-fetch UI message strings so translated text renders at frame 0 —
+    // without this, every page (and every locale switch) shows raw
+    // "namespace.key" strings until the client-only fetch resolves.
+    getMessages(locale),
   ]);
 
   return (
@@ -100,7 +104,7 @@ export default async function RootLayout({
         />
       </head>
       <body className={font.className}>
-        <StoreProvider locale={locale} initialStoreInfo={storeInfo}>
+        <StoreProvider locale={locale} initialStoreInfo={storeInfo} initialMessages={messages}>
           <div className="min-h-screen flex flex-col">
             <AnnouncementBar announcements={announcements} />
             <SiteHeader header={siteHeader} storeName={<%- storeNameJs %>} />

package/templates/nextjs/base/src/core/providers/store-provider.tsx.ejs

@@ -74,10 +74,12 @@ export function StoreProvider({
   children,
   locale,
   initialStoreInfo = null,
+  initialMessages,
 }: {
   children: React.ReactNode;
   locale?: string;
   initialStoreInfo?: PublicStoreInfo | null;
+  initialMessages?: Record<string, Record<string, string>>;
 }) {
 <% } else { %>
 export function StoreProvider({
@@ -99,7 +101,14 @@ export function StoreProvider({
   const [cart, setCart] = useState<Cart | null>(null);
   const [cartLoading, setCartLoading] = useState(true);
 <% if (i18nEnabled) { %>
-  const [messages, setMessages] = useState<Record<string, Record<string, string>>>({});
+  // Seed from server-rendered messages (see RootLayout) so translated text
+  // renders at frame 0 instead of a window of raw "namespace.key" strings
+  // before the client-only fetch in the effect below resolves — this also
+  // closes the same gap on every locale switch, since RootLayout re-runs
+  // server-side per locale and StoreProvider remounts with fresh initial data.
+  const [messages, setMessages] = useState<Record<string, Record<string, string>>>(
+    initialMessages ?? {}
+  );
 <% } %>
 
   // Check auth status via httpOnly cookie (server-side validation)

package/templates/nextjs/designs/atelier/app-overlay/layout.tsx.ejs

@@ -8,7 +8,7 @@ import { SiteFooter } from '@/ui/layout/site-footer';
 import { CartDrawer } from '@/ui/cart/cart-drawer';
 import { BrainerceBotWidget } from '@/components/brainerce-bot';
 import { getServerClient, fetchStoreInfo } from '@/core/lib/brainerce';
-import { getDirection, supportedLocales } from '@/i18n';
+import { getDirection, getMessages, supportedLocales } from '@/i18n';
 import { getNonce } from '@/core/lib/nonce';
 import '../globals.css';
 
@@ -75,7 +75,7 @@ export default async function RootLayout({
   // seeded a particular content type yet. New stores ship with default rows
   // seeded by the backend (StoresService.seedDefaultContent).
   const client = getServerClient(locale);
-  const [announcements, siteHeader, siteFooter, storeInfo] = await Promise.all([
+  const [announcements, siteHeader, siteFooter, storeInfo, messages] = await Promise.all([
     client.content.announcement.list(locale).catch(() => []),
     client.content.header.get('main', locale).catch(() => null),
     client.content.footer.get('main', locale).catch(() => null),
@@ -83,6 +83,10 @@ export default async function RootLayout({
     // render with the real currency, feature flags, and i18n config at frame 0
     // — without this, Googlebot sees USD/defaults baked into the HTML.
     fetchStoreInfo(locale),
+    // SSR-fetch UI message strings so translated text renders at frame 0 —
+    // without this, every page (and every locale switch) shows raw
+    // "namespace.key" strings until the client-only fetch resolves.
+    getMessages(locale),
   ]);
 
   return (
@@ -113,7 +117,7 @@ export default async function RootLayout({
         />
       </head>
       <body className={`${sans.variable} ${serif.variable} font-sans`}>
-        <StoreProvider locale={locale} initialStoreInfo={storeInfo}>
+        <StoreProvider locale={locale} initialStoreInfo={storeInfo} initialMessages={messages}>
           <div className="min-h-screen flex flex-col">
             <AnnouncementBar announcements={announcements} />
             <SiteHeader header={siteHeader} storeName={<%- storeNameJs %>} />

package/templates/nextjs/designs/atelier/ui/shared/icons.tsx

@@ -7,7 +7,7 @@
 import * as React from 'react';
 
 export type IconProps = {
-  size?: 16 | 18 | 20 | 24 | 28 | 32;
+  size?: 16 | 18 | 20 | 24 | 28 | 32 | 56;
   className?: string;
   /** stroke width — 1.75 default matches the light, jewelry-grade look */
   strokeWidth?: number;

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-`).