create-brainerce-store 1.87.0 → 1.88.1

package/dist/index.js

@@ -31,7 +31,7 @@ var require_package = __commonJS({
   "package.json"(exports2, module2) {
     module2.exports = {
       name: "create-brainerce-store",
-      version: "1.87.0",
+      version: "1.88.1",
       description: "Scaffold a production-ready e-commerce storefront connected to Brainerce",
       homepage: "https://brainerce.com",
       repository: {
@@ -359,7 +359,14 @@ var BRAINERCE_RUNTIME_DEPS = Object.freeze({
   // clear it could not. An exact pin ages once and then stays eligible.
   // Keep it exact when you raise it: a range here is not a convenience, it is
   // an open invitation for tomorrow's release to break yesterday's template.
-  brainerce: "2.7.0",
+  // 3.5.0 (published 2026-09-25, past the one-week cooldown): the floor the template
+  // actually needs. Files in `templates/` read `Order.invoiceUrl` /
+  // `invoiceNumber` and `TrackingEventItem.productId`, which 2.7.0 does not
+  // declare, so a CLEAN scaffold pinned to 2.7.0 failed `next build` with 7 type
+  // errors (2026-10-04 QA). The dead `product.downloads` read the 3.x types
+  // rejected was removed from the template in the same change. Raise this only
+  // after scaffolding a clean store and running `tsc` + `next build` against it.
+  brainerce: "3.5.0",
   "isomorphic-dompurify": "^3.8.0"
 });
 

package/messages/en.json

@@ -108,6 +108,8 @@
     "addedToCart": "Added to Cart!",
     "cartFull": "Your cart is full. Remove an item before adding this one.",
     "addToCartFailed": "We could not add this to your cart. Please try again.",
+    "addNotEnoughStock": "There is not enough stock left for that quantity.",
+    "addItemUnavailable": "This item is no longer available.",
     "outOfStock": "Out of Stock",
     "inStock": "In Stock",
     "unavailable": "Unavailable",
@@ -546,7 +548,14 @@
   },
   "coupon": {
     "placeholder": "Coupon code",
-    "invalidCode": "Invalid coupon code"
+    "invalidCode": "Invalid coupon code",
+    "notActive": "This coupon is not active yet.",
+    "expired": "This coupon has expired.",
+    "usageLimitReached": "This coupon is no longer available.",
+    "perCustomerLimitReached": "You have already used this coupon the maximum number of times.",
+    "minimumNotMet": "Your order does not reach the minimum amount for this coupon.",
+    "regionRestricted": "This coupon is not available in your region.",
+    "noEligibleItems": "This coupon does not apply to any items in your cart."
   },
   "contact": {
     "title": "Contact Us",

package/messages/he.json

@@ -108,6 +108,8 @@
     "addedToCart": "נוסף לעגלה!",
     "cartFull": "העגלה מלאה. הסירו מוצר אחד לפני הוספת המוצר הזה.",
     "addToCartFailed": "לא הצלחנו להוסיף את המוצר לעגלה. נסו שוב.",
+    "addNotEnoughStock": "אין מספיק מלאי לכמות הזו.",
+    "addItemUnavailable": "המוצר הזה אינו זמין עוד.",
     "outOfStock": "אזל מהמלאי",
     "inStock": "במלאי",
     "unavailable": "לא זמין",
@@ -546,7 +548,14 @@
   },
   "coupon": {
     "placeholder": "קוד קופון",
-    "invalidCode": "קוד קופון לא תקין"
+    "invalidCode": "קוד קופון לא תקין",
+    "notActive": "הקופון הזה עדיין לא פעיל.",
+    "expired": "תוקף הקופון הזה פג.",
+    "usageLimitReached": "הקופון הזה כבר לא זמין.",
+    "perCustomerLimitReached": "כבר השתמשת בקופון הזה את מספר הפעמים המרבי.",
+    "minimumNotMet": "סכום ההזמנה לא מגיע למינימום הנדרש לקופון הזה.",
+    "regionRestricted": "הקופון הזה לא זמין באזור שלך.",
+    "noEligibleItems": "הקופון הזה לא חל על אף מוצר בעגלה שלך."
   },
   "contact": {
     "title": "צור קשר",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-brainerce-store",
-  "version": "1.87.0",
+  "version": "1.88.1",
   "description": "Scaffold a production-ready e-commerce storefront connected to Brainerce",
   "homepage": "https://brainerce.com",
   "repository": {

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

@@ -19,6 +19,7 @@
                   "!@/core/lib/image-hosts",
                   "!@/core/lib/kit",
                   "!@/core/lib/add-to-cart-error",
+                  "!@/core/lib/coupon-error",
                   "!@/core/lib/navigation",
                   "!@/core/lib/product-options",
                   "!@/core/lib/sanitize",

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

@@ -1,221 +1,224 @@
-# 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`, `addToCartError`,
-  customization + modifier state and errors
-  - `addToCartError` is `'CART_FULL' | 'FAILED' | null`. **Render it, and render it
-    outside any `modifierGroups.length > 0` block** — a cart holds at most 50
-    distinct products and the 51st add is refused, so a design that drops this
-    leaves the shopper tapping a button that resets and adds nothing. Copy lives
-    in `productDetail.cartFull` / `productDetail.addToCartFailed`.
-  - Five more components hold the same message in their OWN local state, because
-    they add to the cart without this hook: `ui/product/product-card.tsx`,
-    `ui/product/frequently-bought-together.tsx`, `ui/cart/cart-bundle-offer.tsx`
-    (all three: `addError`), `app/checkout/page.tsx` (`bumpError`) and
-    `ui/cart/cart-upgrade-banner.tsx` (`upgradeError`). All five use
-    `toAddToCartError()` from `@/core/lib/add-to-cart-error`. **Nothing checks that
-    you kept them** — `check-template-parity.js` compares `@/ui/...` imports and SDK
-    calls only, so dropping one of these leaves a green build and a silent button.
-  - `ui/cart/cart-item.tsx` carries the same idea for the two writes it owns,
-    in its own `lineError` state: a failed quantity change or a failed Remove
-    used to log to the console and leave the row looking untouched. It uses
-    `getErrorCode()` from the same file (not `toAddToCartError()` — the 50-line
-    cap cannot refuse a quantity change, and "we could not add this" would be a
-    lie about a removal) and four `cart.*` strings, mapped in `LINE_ERROR_KEYS`:
-    `notEnoughStock`, `itemUnavailable`, `quantityUpdateFailed`, `removeFailed`.
-    The first two are for refusals a retry can never clear, so do not collapse
-    them into the generic one. Nothing checks that you kept any of this either.
-  - `ui/cart/cart-upgrade-banner.tsx` additionally swaps one cart line for
-    another, and the ORDER of its two SDK calls is a correctness property, not a
-    style choice: it **adds the upgrade first and removes the original second**,
-    so a failed add leaves the cart untouched instead of losing the shopper's
-    line. It also carries `upgradeAdded`, which stops a retry adding the upgrade
-    twice, and a third message, `cart.upgradeOriginalNotRemoved`, for the case
-    where the add landed and the removal did not. If you rebuild that component,
-    keep all three; the reasoning is in the JSDoc on `handleUpgrade`.
-- `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. **Feature coverage.** Call `get-required-features` on the `brainerce-docs`
-   MCP server (wired by the scaffolder in `.mcp.json`, no setup) and confirm
-   every mandatory entry is still reachable. First step, not last: you were
-   invited to rewrite `src/ui/` from scratch, and a feature that lived only in
-   the shipped reference is gone now with nothing to notice it by. `tsc`
-   cannot see a missing feature, and these components render nothing while the
-   merchant has the feature off, so a deleted one and an idle one look the
-   same. `CLAUDE.md` lists the files people usually lose; the MCP tool is the
-   actual specification.
-2. `pnpm exec tsc --noEmit` → must be 0.
-3. `pnpm dev` → drive the real flow you changed: home → listing → product →
-   add to cart → cart → checkout page renders.
-4. Screenshot desktop (1440) AND mobile (390), in the store's language.
-5. 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.
-
-
-## 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`.
-  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.
-- Hardcode the store name. `SiteHeader` / `SiteFooter` receive it as a prop
-  from the layout; anywhere else use `useStoreName()` (client) or
-  `resolveStoreName(storeInfo)` (server) from `src/core/lib/`. The name the
-  scaffold knew may be nothing more than the project directory.
-- Swallow the add-to-cart / checkout error states — restyle them, keep them.
-- Drop a `src/ui/` component that is the only place a mandatory feature
-  exists. Rebuilding the look is free; losing the SDK call inside it is not,
-  and it is silent. See "Rebuilding the look is free" in `CLAUDE.md` for the
-  files people usually lose, and `get-required-features` for the real list.
-- 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.
+# 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, except
+the approved presentation helpers listed (as `!@/core/lib/...`) in the `src/ui`
+`no-restricted-imports` rule in `.eslintrc.json`. `next build` runs that lint,
+so importing any other `@/core/lib` module from `src/ui` fails the build:
+
+- `useHomeData()` → `{ products, banners, loading }`
+- `useProductListing()` → products + filters/sort/facets/pagination + handlers
+- `useProductPage(product)` → variant/image selection, `priceInfo`, `inventory`,
+  `quantity`, `handleAddToCart`, `addingToCart`, `addedMessage`, `addToCartError`,
+  customization + modifier state and errors
+  - `addToCartError` is `'CART_FULL' | 'FAILED' | null`. **Render it, and render it
+    outside any `modifierGroups.length > 0` block** — a cart holds at most 50
+    distinct products and the 51st add is refused, so a design that drops this
+    leaves the shopper tapping a button that resets and adds nothing. Copy lives
+    in `productDetail.cartFull` / `productDetail.addToCartFailed`.
+  - Five more components hold the same message in their OWN local state, because
+    they add to the cart without this hook: `ui/product/product-card.tsx`,
+    `ui/product/frequently-bought-together.tsx`, `ui/cart/cart-bundle-offer.tsx`
+    (all three: `addError`), `app/checkout/page.tsx` (`bumpError`) and
+    `ui/cart/cart-upgrade-banner.tsx` (`upgradeError`). All five use
+    `toAddToCartError()` from `@/core/lib/add-to-cart-error`. **Nothing checks that
+    you kept them** — `check-template-parity.js` compares `@/ui/...` imports and SDK
+    calls only, so dropping one of these leaves a green build and a silent button.
+  - `ui/cart/cart-item.tsx` carries the same idea for the two writes it owns,
+    in its own `lineError` state: a failed quantity change or a failed Remove
+    used to log to the console and leave the row looking untouched. It uses
+    `getErrorCode()` from the same file (not `toAddToCartError()` — the 50-line
+    cap cannot refuse a quantity change, and "we could not add this" would be a
+    lie about a removal) and four `cart.*` strings, mapped in `LINE_ERROR_KEYS`:
+    `notEnoughStock`, `itemUnavailable`, `quantityUpdateFailed`, `removeFailed`.
+    The first two are for refusals a retry can never clear, so do not collapse
+    them into the generic one. Nothing checks that you kept any of this either.
+  - `ui/cart/cart-upgrade-banner.tsx` additionally swaps one cart line for
+    another, and the ORDER of its two SDK calls is a correctness property, not a
+    style choice: it **adds the upgrade first and removes the original second**,
+    so a failed add leaves the cart untouched instead of losing the shopper's
+    line. It also carries `upgradeAdded`, which stops a retry adding the upgrade
+    twice, and a third message, `cart.upgradeOriginalNotRemoved`, for the case
+    where the add landed and the removal did not. If you rebuild that component,
+    keep all three; the reasoning is in the JSDoc on `handleUpgrade`.
+- `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. **Feature coverage.** Call `get-required-features` on the `brainerce-docs`
+   MCP server (wired by the scaffolder in `.mcp.json`, no setup) and confirm
+   every mandatory entry is still reachable. First step, not last: you were
+   invited to rewrite `src/ui/` from scratch, and a feature that lived only in
+   the shipped reference is gone now with nothing to notice it by. `tsc`
+   cannot see a missing feature, and these components render nothing while the
+   merchant has the feature off, so a deleted one and an idle one look the
+   same. `CLAUDE.md` lists the files people usually lose; the MCP tool is the
+   actual specification.
+2. `pnpm exec tsc --noEmit` → must be 0.
+3. `pnpm dev` → drive the real flow you changed: home → listing → product →
+   add to cart → cart → checkout page renders.
+4. Screenshot desktop (1440) AND mobile (390), in the store's language.
+5. 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.
+
+
+## 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`.
+  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.
+- Hardcode the store name. `SiteHeader` / `SiteFooter` receive it as a prop
+  from the layout; anywhere else use `useStoreName()` (client) or
+  `resolveStoreName(storeInfo)` (server) from `src/core/lib/`. The name the
+  scaffold knew may be nothing more than the project directory.
+- Swallow the add-to-cart / checkout error states — restyle them, keep them.
+- Drop a `src/ui/` component that is the only place a mandatory feature
+  exists. Rebuilding the look is free; losing the SDK call inside it is not,
+  and it is silent. See "Rebuilding the look is free" in `CLAUDE.md` for the
+  files people usually lose, and `get-required-features` for the real list.
+- 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.