create-brainerce-store 1.50.5 → 1.52.0

package/templates/nextjs/base/.eslintrc.json

@@ -1,3 +1,57 @@
-{
-  "extends": ["next/core-web-vitals"]
-}
+{
+  "extends": [
+    "next/core-web-vitals"
+  ],
+  "overrides": [
+    {
+      "files": [
+        "src/ui/**/*.{ts,tsx}"
+      ],
+      "rules": {
+        "no-restricted-imports": [
+          "error",
+          {
+            "patterns": [
+              {
+                "group": [
+                  "@/core/lib/*",
+                  "!@/core/lib/auth",
+                  "!@/core/lib/brainerce",
+                  "!@/core/lib/image-hosts",
+                  "!@/core/lib/navigation",
+                  "!@/core/lib/product-options",
+                  "!@/core/lib/sanitize",
+                  "!@/core/lib/sanitize-html",
+                  "!@/core/lib/translations",
+                  "!@/core/lib/use-currency",
+                  "!@/core/lib/utils"
+                ],
+                "message": "UI consumes data via @/core/hooks/* and @/core/providers/* — not core internals. (Approved presentation helpers are exempt.)"
+              }
+            ]
+          }
+        ]
+      }
+    },
+    {
+      "files": [
+        "src/core/**/*.{ts,tsx}"
+      ],
+      "rules": {
+        "no-restricted-imports": [
+          "error",
+          {
+            "patterns": [
+              {
+                "group": [
+                  "@/ui/*"
+                ],
+                "message": "core/ must never depend on presentation (ui/)."
+              }
+            ]
+          }
+        ]
+      }
+    }
+  ]
+}

package/templates/nextjs/base/AGENTS.md

@@ -0,0 +1,41 @@
+# 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/AI-GUIDE.md

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

package/templates/nextjs/base/CLAUDE.md

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

package/templates/nextjs/base/TRANSLATIONS.md

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

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

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

package/templates/nextjs/base/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/account/page.tsx

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

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

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

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

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

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

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

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

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

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

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

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

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