create-brainerce-store 1.74.0 → 1.76.0

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

@@ -1,172 +1,200 @@
-# 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
-
-## MCP servers
-
-- **`brainerce-docs`** (already connected via `.mcp.json`, no auth needed).
-  Treat it as the build spec, not a lookup desk. `get-required-features` is
-  the functional checklist this store is measured against, and it is longer
-  than what any art-direction brief would make you think to build.
-  `get-critical-rules` and `get-business-flows` carry the sequences that cause
-  incidents when reordered. `get-sdk-docs`, `get-type-definitions` and
-  `get-code-example` give current method shapes instead of training-data
-  guesses, and `get-store-capabilities` reports what is actually toggled on
-  for `<%- connectionId %>` right now. Read the checklist before you start,
-  and again before you call the work done.
-- **Brainerce Admin MCP** — opt-in, not wired up by default. Lets an agent
-  directly manage this store's *live* data (products, orders, discounts,
-  shipping, …) instead of just reading docs. Only add it if the merchant
-  wants that: connect `https://api.brainerce.com/api/mcp` as a remote HTTP
-  MCP server (e.g. `claude mcp add --transport http brainerce-admin
-  https://api.brainerce.com/api/mcp`) — it opens a browser to log into the
-  Brainerce dashboard, pick this store, and grant scoped OAuth permissions.
-  Treat it like handing the agent write access to production commerce data.
-
-**Before building any feature the merchant asks for** (loyalty points,
-shipping zones, subscriptions, gift cards, donations, 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**. It is never *only* design: the
-coverage checklist in `get-required-features` applies to a redesign exactly as
-it applies to a build from scratch.
-
-## 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: a full
-delete-and-rebuild of the *look* is encouraged and expected, and you can
-rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
-like. The store keeps working. (Stores scaffolded with `--canvas` ship
-`src/ui/` as bare unstyled skeletons, so there is no reference look at all and
-the design is entirely yours to create.) 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.
-
-### Rebuilding the look is free. Dropping a feature is not.
-
-Some files under `src/ui/` are the ONLY place a mandatory checklist entry
-exists in this project. Delete one and the capability leaves the store with
-nothing to notice it by: no type error, no console warning, and no visual hole
-either, because these components auto-hide while the merchant has the feature
-switched off, so a deleted one and an idle one look identical on the page.
-These are the usual casualties of a redesign, because no art-direction brief
-asks for them by name:
-
-```
-product/  back-in-stock-form · customization-fields · modifier-group-selector
-          review-form · reviews-section · frequently-bought-together
-          discount-badge · stock-badge
-cart/     reservation-countdown · coupon-input · cart-upgrade-banner
-          cart-bundle-offer · tax-estimate-line
-home/     discount-banner-strip
-layout/   newsletter-signup · announcement-bar · region-switcher<% if (i18nEnabled) { %>
-          language-switcher<% } %> · faq-section · rich-text-block
-```
-
-Restyle them, re-lay them out, rename them, fold them into other components,
-split them in half: all fine. What has to survive a rebuild is the SDK call
-each one makes and the states it handles (loading, empty, failed, and the
-merchant-has-it-off state that renders nothing).
-
-The list is short on purpose and it is NOT the specification. It names the
-files people lose, not every mandatory entry. `get-required-features` is the
-specification, and step 1 of "Verify before declaring done" is what actually
-catches a loss. `git show HEAD:src/ui/<path>` brings back anything you already
-deleted: the scaffolder committed the tree before you touched it.
-
-**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.
-
-## The store's web address
-
-This project has no web address written into it, and that is deliberate — the
-scaffolder cannot know where you will deploy. `src/core/lib/site-url.ts`
-resolves it per request (hosting-platform variables, then the forwarded host),
-so canonical tags, `sitemap.xml`, `robots.txt` and JSON-LD are correct in local
-development and on any host with nothing configured.
-
-- **Never invent an address.** Do not write `NEXT_PUBLIC_SITE_URL`,
-  `SITE_URL`, `localhost`, or a placeholder domain into `.env.local`. A wrong
-  absolute URL is indistinguishable from a right one to a search crawler, so a
-  guess is worse than an empty value.
-- **Never hand-roll an origin** from `host` / `x-forwarded-proto` in a route
-  handler. Call `getCanonicalSiteUrl()` (for canonical/SEO URLs) or
-  `getRequestOrigin()` (for the `Origin` header sent to Brainerce). Hand-rolled
-  versions have shipped `http://` on HTTPS hosts and internal container
-  hostnames.
-- **Some hosts hide the real hostname from the app.** Platforms whose proxy
-  forwards requests as `Host: localhost:<port>` with no `x-forwarded-host`
-  (OpenAI Sites / `*.chatgpt.site` does this) leave the resolver blind — the
-  request looks like it arrived on localhost. On such platforms `SITE_URL` is
-  not optional: set it, and the resolver prefers it over any internal host it
-  sees. Without it, server-side API calls send `Origin: http://localhost:3000`
-  and a channel with a configured Domain rejects them with 403.
-- **When the merchant gives you a real domain**, set `SITE_URL` in the hosting
-  provider's environment variables — not in `.env.local`, which is gitignored
-  and never travels with a deploy.
-- **Tell the merchant the other half.** A sales channel in **Live** mode only
-  accepts requests whose Origin matches the Domain configured on the channel in
-  the Brainerce dashboard. That check is server-side; nothing in this project
-  can satisfy it. If they skip it, every storefront API call returns 403 and the
-  store loads empty — no matter what `SITE_URL` says.
-
-## Verify before declaring done
-
-1. **Feature coverage, first and always.** Call `get-required-features` on the
-   `brainerce-docs` MCP server (already wired, nothing to set up) and confirm
-   every mandatory entry is still reachable in the running store. Do this
-   before the steps below, because if you rebuilt `src/ui/` a feature that
-   lived only in the shipped reference is now gone, and no other check can see
-   it: `tsc` cannot see a missing feature, and the component that used to
-   carry it auto-hid when the merchant had not switched it on, so the page
-   looks right either way.
-2. `pnpm exec tsc --noEmit` → 0 errors
-3. `pnpm dev` → drive the changed flow in a real browser (home → product →
-   add to cart → cart)
-4. Screenshot desktop (1440px) and mobile (390px)
-5. 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-`).
+# 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
+
+## MCP servers
+
+- **`brainerce-docs`** (already connected via `.mcp.json`, no auth needed).
+  Treat it as the build spec, not a lookup desk. `get-required-features` is
+  the functional checklist this store is measured against, and it is longer
+  than what any art-direction brief would make you think to build.
+  `get-critical-rules` and `get-business-flows` carry the sequences that cause
+  incidents when reordered. `get-sdk-docs`, `get-type-definitions` and
+  `get-code-example` give current method shapes instead of training-data
+  guesses, and `get-store-capabilities` reports what is actually toggled on
+  for `<%- connectionId %>` right now. Read the checklist before you start,
+  and again before you call the work done.
+- **Brainerce Admin MCP** — opt-in, not wired up by default. Lets an agent
+  directly manage this store's *live* data (products, orders, discounts,
+  shipping, …) instead of just reading docs. Only add it if the merchant
+  wants that: connect `https://api.brainerce.com/api/mcp` as a remote HTTP
+  MCP server (e.g. `claude mcp add --transport http brainerce-admin
+  https://api.brainerce.com/api/mcp`) — it opens a browser to log into the
+  Brainerce dashboard, pick this store, and grant scoped OAuth permissions.
+  Treat it like handing the agent write access to production commerce data.
+
+**Before building any feature the merchant asks for** (loyalty points,
+shipping zones, subscriptions, gift cards, donations, 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.
+
+### ⛔ This storefront never holds an admin API key
+
+Everything here runs on the sales channel's PUBLIC credentials, and that is the
+whole security model. `.env.local` ships no secret on purpose. Anything you put
+in a browser-reachable app is readable by anyone who opens devtools, so an
+admin API key (`brainerce_*`) in this project hands the merchant's entire live
+store to the first person who looks. Never add one to `.env.local`, to a
+hosting environment variable this app reads, or to any file under `src/`.
+
+**Gift cards are where this goes wrong**, because one feature name covers two
+very different powers:
+
+- **Redemption is yours to build.** `applyGiftCard()`, `removeGiftCard()` and
+  `checkGiftCardBalance()` are public storefront calls needing no key beyond
+  the sales channel. `src/ui/cart/gift-card-input.tsx` already wires the first
+  two into checkout. Restyle it freely.
+- **⛔ Issuing is not.** The `gift_cards:issue` scope mints stored value, which
+  is real money the merchant is liable for. It belongs to the dashboard, or to
+  server-side code on infrastructure the merchant controls. Never request that
+  scope for this storefront, never hold a key that carries it, and never add an
+  "issue a gift card" control to these pages. A merchant who wants to SELL gift
+  cards sells them as an ordinary product through normal checkout, and the
+  platform issues the card once payment clears.
+
+The same split governs every admin capability you may be tempted to reach for
+(creating discounts, editing inventory, refunding an order): this storefront
+reads and transacts as a shopper, the dashboard administers.
+
+Your job here is almost always **design**. It is never *only* design: the
+coverage checklist in `get-required-features` applies to a redesign exactly as
+it applies to a build from scratch.
+
+## 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: a full
+delete-and-rebuild of the *look* is encouraged and expected, and you can
+rewrite anything under `src/ui/` and `src/app/globals.css` as boldly as you
+like. The store keeps working. (Stores scaffolded with `--canvas` ship
+`src/ui/` as bare unstyled skeletons, so there is no reference look at all and
+the design is entirely yours to create.) 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.
+
+### Rebuilding the look is free. Dropping a feature is not.
+
+Some files under `src/ui/` are the ONLY place a mandatory checklist entry
+exists in this project. Delete one and the capability leaves the store with
+nothing to notice it by: no type error, no console warning, and no visual hole
+either, because these components auto-hide while the merchant has the feature
+switched off, so a deleted one and an idle one look identical on the page.
+These are the usual casualties of a redesign, because no art-direction brief
+asks for them by name:
+
+```
+product/  back-in-stock-form · customization-fields · modifier-group-selector
+          review-form · reviews-section · frequently-bought-together
+          discount-badge · stock-badge
+cart/     reservation-countdown · coupon-input · cart-upgrade-banner
+          cart-bundle-offer · tax-estimate-line
+home/     discount-banner-strip
+layout/   newsletter-signup · announcement-bar · region-switcher<% if (i18nEnabled) { %>
+          language-switcher<% } %> · faq-section · rich-text-block
+```
+
+Restyle them, re-lay them out, rename them, fold them into other components,
+split them in half: all fine. What has to survive a rebuild is the SDK call
+each one makes and the states it handles (loading, empty, failed, and the
+merchant-has-it-off state that renders nothing).
+
+The list is short on purpose and it is NOT the specification. It names the
+files people lose, not every mandatory entry. `get-required-features` is the
+specification, and step 1 of "Verify before declaring done" is what actually
+catches a loss. `git show HEAD:src/ui/<path>` brings back anything you already
+deleted: the scaffolder committed the tree before you touched it.
+
+**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.
+
+## The store's web address
+
+This project has no web address written into it, and that is deliberate — the
+scaffolder cannot know where you will deploy. `src/core/lib/site-url.ts`
+resolves it per request (hosting-platform variables, then the forwarded host),
+so canonical tags, `sitemap.xml`, `robots.txt` and JSON-LD are correct in local
+development and on any host with nothing configured.
+
+- **Never invent an address.** Do not write `NEXT_PUBLIC_SITE_URL`,
+  `SITE_URL`, `localhost`, or a placeholder domain into `.env.local`. A wrong
+  absolute URL is indistinguishable from a right one to a search crawler, so a
+  guess is worse than an empty value.
+- **Never hand-roll an origin** from `host` / `x-forwarded-proto` in a route
+  handler. Call `getCanonicalSiteUrl()` (for canonical/SEO URLs) or
+  `getRequestOrigin()` (for the `Origin` header sent to Brainerce). Hand-rolled
+  versions have shipped `http://` on HTTPS hosts and internal container
+  hostnames.
+- **Some hosts hide the real hostname from the app.** Platforms whose proxy
+  forwards requests as `Host: localhost:<port>` with no `x-forwarded-host`
+  (OpenAI Sites / `*.chatgpt.site` does this) leave the resolver blind — the
+  request looks like it arrived on localhost. On such platforms `SITE_URL` is
+  not optional: set it, and the resolver prefers it over any internal host it
+  sees. Without it, server-side API calls send `Origin: http://localhost:3000`
+  and a channel with a configured Domain rejects them with 403.
+- **When the merchant gives you a real domain**, set `SITE_URL` in the hosting
+  provider's environment variables — not in `.env.local`, which is gitignored
+  and never travels with a deploy.
+- **Tell the merchant the other half.** A sales channel in **Live** mode only
+  accepts requests whose Origin matches the Domain configured on the channel in
+  the Brainerce dashboard. That check is server-side; nothing in this project
+  can satisfy it. If they skip it, every storefront API call returns 403 and the
+  store loads empty — no matter what `SITE_URL` says.
+
+## Verify before declaring done
+
+1. **Feature coverage, first and always.** Call `get-required-features` on the
+   `brainerce-docs` MCP server (already wired, nothing to set up) and confirm
+   every mandatory entry is still reachable in the running store. Do this
+   before the steps below, because if you rebuilt `src/ui/` a feature that
+   lived only in the shipped reference is now gone, and no other check can see
+   it: `tsc` cannot see a missing feature, and the component that used to
+   carry it auto-hid when the merchant had not switched it on, so the page
+   looks right either way.
+2. `pnpm exec tsc --noEmit` → 0 errors
+3. `pnpm dev` → drive the changed flow in a real browser (home → product →
+   add to cart → cart)
+4. Screenshot desktop (1440px) and mobile (390px)
+5. 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/src/app/order-confirmation/page.tsx

@@ -333,6 +333,43 @@ function ConfirmationLineItems({ order }: { order: Order | null }) {
           {formatPrice(parseFloat(totalAmount), { currency }) as string}
         </span>
       </div>
+
+      {/* What actually paid.
+          This is the first screen a customer sees after handing over money, and
+          a total with no gift-card line tells them they paid an amount they did
+          not. The total above is what the order was WORTH and stays unreduced —
+          tax was calculated on it — so the cards sit below it, followed by what
+          the card or wallet was really charged. */}
+      {order.tenders && order.tenders.length > 0 && (
+        <>
+          {order.tenders.map((tender) => (
+            <div key={tender.id} className="mt-2 flex items-center justify-between text-sm">
+              <span className="text-muted-foreground">
+                {tender.giftCard?.codeLast4
+                  ? `${tc('giftCard')} ····${tender.giftCard.codeLast4}`
+                  : tc('giftCard')}
+              </span>
+              <span className="text-primary">
+                -{formatPrice(parseFloat(tender.amountBase), { currency }) as string}
+              </span>
+            </div>
+          ))}
+          <div className="border-border mt-2 flex items-center justify-between border-t pt-2">
+            <span className="text-foreground text-sm font-medium">{tc('amountCharged')}</span>
+            <span className="text-foreground text-sm font-semibold">
+              {
+                formatPrice(
+                  order.tenders.reduce(
+                    (due, tn) => due - parseFloat(tn.amountBase),
+                    parseFloat(totalAmount)
+                  ),
+                  { currency }
+                ) as string
+              }
+            </span>
+          </div>
+        </>
+      )}
     </div>
   );
 }

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

@@ -1,65 +1,75 @@
-import type { Metadata } from 'next';
-import { getServerClient } from '@/core/lib/brainerce.server';
-import { buildMetaDescription } from '@/core/lib/seo';
-import { OrganizationJsonLd } from '@/components/seo/organization-json-ld';
-import { getCanonicalSiteUrl } from '@/core/lib/site-url';
-import { RichTextBlock } from '@/ui/layout/rich-text-block';
-import { HomeClient } from '@/ui/home/home-client';
-
-// Build homepage metadata server-side so Google, Facebook, WhatsApp etc.
-// see a real <meta name="description"> on first request. Falls back to the
-// store name when the merchant hasn't authored a meta description yet.
-export async function generateMetadata(): Promise<Metadata> {
-  try {
-    const storeInfo = await (await getServerClient()).getStoreInfo();
-    const description = buildMetaDescription(storeInfo.metaDescription) || undefined;
-    return {
-      title: storeInfo.name,
-      description,
-      openGraph: {
-        title: storeInfo.name,
-        description,
-        type: 'website',
-      },
-      twitter: {
-        card: 'summary_large_image',
-        title: storeInfo.name,
-        description,
-      },
-    };
-  } catch {
-    return {};
-  }
-}
-
-export default async function HomePage() {
-  // Fetch store info server-side so the JSON-LD is in the initial HTML —
-  // crawlers and AI Overviews see it without needing to execute JavaScript.
-  // Failure here is non-fatal: the client component re-fetches via the
-  // StoreProvider so the page still renders.
-  //
-  // Also fetch the merchant's homepage intro (RICH_TEXT key='main'). When
-  // present, it renders as a sanitized HTML block above the product grid —
-  // typical use is brand introduction, value-prop copy, or a seasonal
-  // announcement that needs more formatting than the AnnouncementBar.
-  // When absent, RichTextBlock returns null cleanly so the layout collapses
-  // to just the product grid.
-  const client = await getServerClient();
-  const [storeInfo, intro] = await Promise.all([
-    client.getStoreInfo().catch(() => null),
-    client.content.richText.get('main').catch(() => null),
-  ]);
-
-  const baseUrl = await getCanonicalSiteUrl();
-
-  return (
-    <>
-      {storeInfo && baseUrl ? <OrganizationJsonLd storeInfo={storeInfo} baseUrl={baseUrl} /> : null}
-      <RichTextBlock
-        block={intro}
-        className="prose prose-sm dark:prose-invert mx-auto max-w-3xl px-4 py-8 sm:px-6 lg:px-8"
-      />
-      <HomeClient />
-    </>
-  );
-}
+import type { Metadata } from 'next';
+import { Suspense } from 'react';
+import { getServerClient } from '@/core/lib/brainerce.server';
+import { buildMetaDescription } from '@/core/lib/seo';
+import { OrganizationJsonLd } from '@/components/seo/organization-json-ld';
+import { getCanonicalSiteUrl } from '@/core/lib/site-url';
+import { RichTextBlock } from '@/ui/layout/rich-text-block';
+import { HomeClient } from '@/ui/home/home-client';
+import { ReferralGreeting } from '@/components/referral/referral-greeting';
+
+// Build homepage metadata server-side so Google, Facebook, WhatsApp etc.
+// see a real <meta name="description"> on first request. Falls back to the
+// store name when the merchant hasn't authored a meta description yet.
+export async function generateMetadata(): Promise<Metadata> {
+  try {
+    const storeInfo = await (await getServerClient()).getStoreInfo();
+    const description = buildMetaDescription(storeInfo.metaDescription) || undefined;
+    return {
+      title: storeInfo.name,
+      description,
+      openGraph: {
+        title: storeInfo.name,
+        description,
+        type: 'website',
+      },
+      twitter: {
+        card: 'summary_large_image',
+        title: storeInfo.name,
+        description,
+      },
+    };
+  } catch {
+    return {};
+  }
+}
+
+export default async function HomePage() {
+  // Fetch store info server-side so the JSON-LD is in the initial HTML —
+  // crawlers and AI Overviews see it without needing to execute JavaScript.
+  // Failure here is non-fatal: the client component re-fetches via the
+  // StoreProvider so the page still renders.
+  //
+  // Also fetch the merchant's homepage intro (RICH_TEXT key='main'). When
+  // present, it renders as a sanitized HTML block above the product grid —
+  // typical use is brand introduction, value-prop copy, or a seasonal
+  // announcement that needs more formatting than the AnnouncementBar.
+  // When absent, RichTextBlock returns null cleanly so the layout collapses
+  // to just the product grid.
+  const client = await getServerClient();
+  const [storeInfo, intro] = await Promise.all([
+    client.getStoreInfo().catch(() => null),
+    client.content.richText.get('main').catch(() => null),
+  ]);
+
+  const baseUrl = await getCanonicalSiteUrl();
+
+  return (
+    <>
+      {storeInfo && baseUrl ? <OrganizationJsonLd storeInfo={storeInfo} baseUrl={baseUrl} /> : null}
+      {/* Referral landing. A referral link is `/?ref=<code>`, so it lands here.
+          Renders nothing without a valid `?ref=`, and nothing at all on a store
+          with referrals switched off. The Suspense boundary is required: the
+          component reads `useSearchParams()`, which would otherwise opt this
+          whole page out of static rendering. */}
+      <Suspense fallback={null}>
+        <ReferralGreeting className="mt-6" />
+      </Suspense>
+      <RichTextBlock
+        block={intro}
+        className="prose prose-sm dark:prose-invert mx-auto max-w-3xl px-4 py-8 sm:px-6 lg:px-8"
+      />
+      <HomeClient />
+    </>
+  );
+}