create-magic-storefront 0.3.1 → 0.5.0

package/template/.claude/skills/theme-section/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: theme-section
+description: >-
+  Create or change a theme section — a part of a page the merchant edits in the admin's theme
+  editor (a hero, a size guide, a lookbook, a FAQ). Use whenever a page gets a new block of content,
+  when asked for a "section", or when a section's settings change. Covers the five steps, the setting
+  types a section may use, and a worked example.
+---
+
+# Creating a new section
+
+A section is a file in `theme/sections/`: its schema (`defineSection`) and its React component. The
+backend has no code per section: `theme push` sends the schema, and the admin's editor, the API's
+validation and the merchant's AI tools work for that section at once. **So invent any section the
+design needs** (`size-guide`, `lookbook`, `faq`) — no one touches the backend.
+
+What the backend does not know is a new **setting type**. Compose sections from the types below;
+never invent one. A field no type covers is a contract change in magicbot, made there first.
+
+`GET /home` is optional: the theme builds the home page. Data sections fetch through the catalog
+operations (`productsIndex`, `collectionsProducts`, …), never through `/home`.
+
+## The five steps
+
+1. Create `theme/sections/<type>.tsx` with `defineSection` and the component (`SectionProps<typeof
+section>` types its `settings` and `blocks`).
+2. Register it in `theme/index.ts`: in `sections` of `defineTheme`, and its component in `components`.
+3. Put it in a template (`theme/templates/index.json` or `page.json`) or give it `presets`, so the
+   merchant can add it in the editor.
+4. Every word the buyer sees comes from a setting with a default in `en`, `ru` and `uz` (or from
+   `lib/i18n.ts` through `message()`), so the merchant can change it. Editor labels use `label(en,
+ru, uz)` from `theme/text.ts`. No copy written into the component.
+5. Run `npm run theme:check` (it must pass), then `npm run theme:push`, and bump `version` in
+   `theme/index.ts`. While developing, `npm run dev` with `MAGICSTORE_THEME_TOKEN` set pushes on
+   every change (`theme dev`).
+
+`theme check` fails on a file in `theme/sections/` that is not registered (`SECTION_NOT_REGISTERED`),
+a template that uses an unknown type, and a text setting without a default in every locale; it warns
+on copy in a component (`HARDCODED_COPY`; `// theme-copy-ok` on the line opts out).
+
+## Setting types
+
+The component receives the served value. Ids are camelCase (`^[a-z][a-zA-Z0-9]{0,63}$`); `SELECT`
+values are `UPPER_SNAKE_CASE`; every setting takes `label`, optional `info` and `default`.
+
+| Type              | Extra members                           | The component receives                                    |
+| ----------------- | --------------------------------------- | --------------------------------------------------------- |
+| `TEXT`            | `maxLength` (≤ 500)                     | `string`                                                  |
+| `TEXTAREA`        | `maxLength` (≤ 5 000)                   | `string`                                                  |
+| `RICHTEXT`        | —                                       | sanitised HTML `string` (the only HTML a section renders) |
+| `URL`             | —                                       | `string \| null`                                          |
+| `COLOR`           | —                                       | `#rrggbb` or `null`                                       |
+| `CHECKBOX`        | —                                       | `boolean`                                                 |
+| `NUMBER`          | `min`, `max` (optional)                 | `number \| null`                                          |
+| `RANGE`           | `min`, `max`, `step`, `unit` (optional) | `number`                                                  |
+| `SELECT`          | `options: [{ value, label }]` (≤ 100)   | one option `value`                                        |
+| `IMAGE`           | —                                       | `{ url, altText: null, width, height }` or `null`         |
+| `COLLECTION`      | —                                       | `{ id, handle, title }` or `null`                         |
+| `PRODUCT`         | —                                       | `{ id, handle, title }` or `null`                         |
+| `COLLECTION_LIST` | `limit` (1–50)                          | `{ id, handle, title }[]`                                 |
+| `PRODUCT_LIST`    | `limit` (1–50)                          | `{ id, handle, title }[]`                                 |
+| `HEADER`          | `content` (no `id`)                     | — (a heading in the editor form)                          |
+| `PARAGRAPH`       | `content` (no `id`)                     | — (a note in the editor form)                             |
+
+Text settings are stored per locale and served in the request's; the component only sees a string.
+`IMAGE`, `COLLECTION`, `PRODUCT` and the lists reference shop data, so their default is empty; a
+reference is not a full product — fetch what you show by `handle` through the catalog operations.
+`IMAGE` has no alt text: declare a `TEXT` setting for it. Blocks (`defineBlock`) are repeatable
+children with their own settings: slides, quotes, table rows (`maxBlocks` caps them).
+
+## Example: `size-guide`
+
+A heading and a table of `row` blocks, in `theme/sections/size-guide.tsx`:
+
+```tsx
+import { defineBlock, defineSection, type SectionProps } from '@magicstoreai/hydrogen/theme';
+
+import { label } from '../text';
+
+const row = defineBlock({
+  type: 'row',
+  name: label('Size', 'Размер', "O'lcham"),
+  settings: [
+    { id: 'size', type: 'TEXT', label: label('Size', 'Размер', "O'lcham"), default: '' },
+    { id: 'chest', type: 'TEXT', label: label('Chest', 'Грудь', "Ko'krak"), default: '' },
+    { id: 'waist', type: 'TEXT', label: label('Waist', 'Талия', 'Bel'), default: '' },
+  ],
+});
+
+export const sizeGuide = defineSection({
+  type: 'size-guide',
+  name: label('Size guide', 'Таблица размеров', "O'lchamlar jadvali"),
+  maxBlocks: 30,
+  settings: [
+    {
+      id: 'heading',
+      type: 'TEXT',
+      label: label('Heading', 'Заголовок', 'Sarlavha'),
+      default: { en: 'Size guide', ru: 'Таблица размеров', uz: "O'lchamlar jadvali" },
+    },
+    {
+      id: 'columns',
+      type: 'TEXT',
+      label: label('Column names', 'Названия колонок', 'Ustun nomlari'),
+      info: label('Separated by commas.', 'Через запятую.', 'Vergul bilan.'),
+      default: {
+        en: 'Size, Chest cm, Waist cm',
+        ru: 'Размер, Грудь см, Талия см',
+        uz: "O'lcham, Ko'krak sm, Bel sm",
+      },
+    },
+  ],
+  blocks: [row],
+  presets: [
+    {
+      name: label('Size guide', 'Таблица размеров', "O'lchamlar jadvali"),
+      blocks: [{ type: 'row' }, { type: 'row' }, { type: 'row' }],
+    },
+  ],
+});
+
+/** A size table the merchant fills row by row; nothing shows until a row has a size. */
+export function SizeGuide({ settings, blocks }: SectionProps<typeof sizeGuide>) {
+  const rows = blocks.filter((block) => block.settings.size !== '');
+  if (rows.length === 0) {
+    return null;
+  }
+  return (
+    <section className="stack">
+      <h2>{settings.heading}</h2>
+      <table>
+        <thead>
+          <tr>
+            {settings.columns.split(',').map((name) => (
+              <th key={name}>{name.trim()}</th>
+            ))}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map(({ id, settings: cells }) => (
+            <tr key={id}>
+              <td>{cells.size}</td>
+              <td>{cells.chest}</td>
+              <td>{cells.waist}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </section>
+  );
+}
+```
+
+Then in `theme/index.ts`: `import { SizeGuide, sizeGuide } from './sections/size-guide';`, add
+`sizeGuide` to `sections` and `'size-guide': SizeGuide` to `components`. The preset lets the merchant
+add it from the editor; to show it by default, add `"size": { "type": "size-guide" }` to a template's
+`sections` and `"size"` to its `order`. Run `npm run theme:check` and `npm run theme:push`.

package/template/.env.example

@@ -10,8 +10,19 @@ MAGICSTORE_API_URL=
 # browser calls go through this app's /storefront-api proxy (app/storefront-api/[...path]).
 NEXT_PUBLIC_MAGICSTORE_STOREFRONT_TOKEN=
 
+# Optional. Who holds the buyer's sign-in tokens and cart id: "server" (default) keeps them in httpOnly
+# cookies behind app/storefront-api, out of reach of page JavaScript; "browser" keeps them in
+# localStorage. A public storefront token (below) always means "browser".
+MAGICSTORE_CREDENTIALS=
+
+# Optional. The storefront access token (msf_…) the server sends with its reads: the API then serves
+# this storefront's own theme, and theme previews work (they need it). Server-only; when empty, the
+# public token below is used, else the shop is found by its domain.
+MAGICSTORE_STOREFRONT_TOKEN=
+
 # Optional. The signing secret of the token's webhook (whsec_…): /api/magicstore/webhook
-# revalidates cached pages when the merchant changes the catalog, pages or home.
+# revalidates cached pages when the merchant changes the catalog, pages or home, and
+# /api/magicstore/preview verifies the theme editor's preview links with it.
 MAGICSTORE_WEBHOOK_SECRET=
 
 # The language pages render in (a locale the shop enables).

package/template/AGENTS.md

@@ -19,13 +19,16 @@ each error code means — then `PAGES.md` for how each page type is built, and
 ## Rules
 
 - Import the SDK only from `@magicstoreai/storefront-client`, `@magicstoreai/hydrogen`,
-  `@magicstoreai/hydrogen/core`, `/server` and `/seo`. Call the API through client methods, never
-  by `/api/v2/storefront/…` URL. A server component takes only components from
+  `@magicstoreai/hydrogen/core`, `/server`, `/seo` and `/theme`. Call the API through client
+  methods, never by `/api/v2/storefront/…` URL. A server component takes only components from
   `@magicstoreai/hydrogen` (a client module); functions and classes come from `/core`, `/server`,
-  `/seo` or `@magicstoreai/storefront-client`. `npx create-magic-storefront check` must pass.
+  `/seo`, `/theme` or `@magicstoreai/storefront-client`. `npx create-magic-storefront check` must pass.
 - Never compute money: render `Money` values with `<Money>` / `formatMoney`, totals from the cart
   and the checkout.
-- Cart id, checkout id, tokens, OTP codes, phone numbers: never logged, never in a URL.
+- Cart id, checkout id, tokens, OTP codes, phone numbers: never logged, never in a URL. By default
+  the browser never holds them at all: `app/storefront-api` keeps them in httpOnly cookies and
+  pages see `"current"` (`MAGICSTORE_CREDENTIALS`, `lib/upstream.ts`). Never read or parse a cart
+  or checkout id — pass back what the API returned.
 - Public reads render on the server through `lib/api.ts` (cached by tag, revalidated by the
   webhook). Anything personal — cart, customer, wishlist — lives in client components under
   `MagicStoreProvider` (`app/providers.tsx`).
@@ -55,20 +58,55 @@ screenshot every page type at 390 and 1280px, fix what you see. Interactive UI f
 
 ## Where things go
 
-| Path                            | What                                                                                                              |
-| ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `app/`                          | Pages (server components) and route handlers                                                                      |
-| `app/error.tsx`                 | Error boundary: the API's `detail`, a retry                                                                       |
-| `app/blog/`                     | Blog: index, category, author, tag and article pages (`PAGES.md`, Blog)                                           |
-| `app/sitemap.ts`                | Sitemap from `GET /sitemap`                                                                                       |
-| `app/page.tsx`                  | Home: renders `GET /home` sections in the merchant's order. Optional: a custom home composes its own (`PAGES.md`) |
-| `components/sections/`          | One renderer per home section type; an unknown type renders nothing                                               |
-| `components/`                   | Shared UI; client components start with `'use client'`                                                            |
-| `components/telegram-shell.tsx` | Telegram Mini App: theme marks, back arrow, the one automatic Telegram sign-in (`PAGES.md`)                       |
-| `lib/api.ts`                    | The server-side client (`nextCacheFetch`), `orNotFound`                                                           |
-| `app/providers.tsx`             | `MagicStoreProvider`: customer, cart, wishlist, analytics in the browser                                          |
-| `app/storefront-api/[...path]`  | Same-origin proxy for browser calls without a public storefront token                                             |
-| `app/api/magicstore/webhook`    | Signed webhook → `revalidateTag`                                                                                  |
+| Path                            | What                                                                                                           |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------- |
+| `app/`                          | Pages (server components) and route handlers                                                                   |
+| `app/error.tsx`                 | Error boundary: the API's `detail`, a retry                                                                    |
+| `app/blog/`                     | Blog: index, category, author, tag and article pages (`PAGES.md`, Blog)                                        |
+| `app/sitemap.ts`                | Sitemap from `GET /sitemap`                                                                                    |
+| `app/page.tsx`                  | Home: the theme's `index` template (`loadTemplate` + `ThemeSections`, `PAGES.md`)                              |
+| `theme/`                        | The theme: `sections/` (schema + component), `templates/*.json`, `settings.ts`, registered in `index.ts`       |
+| `components/sections/`          | One renderer per `GET /home` section type (the `platform-home` theme section); an unknown type renders nothing |
+| `components/`                   | Shared UI; client components start with `'use client'`                                                         |
+| `components/telegram-shell.tsx` | Telegram Mini App: theme marks, back arrow, the one automatic Telegram sign-in (`PAGES.md`)                    |
+| `lib/api.ts`                    | The server-side client (`nextCacheFetch`), `orNotFound`                                                        |
+| `app/providers.tsx`             | `MagicStoreProvider`: customer, cart, wishlist, analytics in the browser                                       |
+| `app/storefront-api/[...path]`  | Same-origin proxy (`createStorefrontProxy`); holds tokens and cart / checkout ids in httpOnly cookies          |
+| `app/api/magicstore/webhook`    | Signed webhook → `revalidateTag`                                                                               |
+| `app/api/magicstore/preview`    | Theme editor preview: signed token → draft mode; pages pass `themePreview()` (`lib/preview.ts`) as `preview`   |
+
+## Creating a new section
+
+A page part the merchant edits in the admin is a theme section. Invent any section the design needs
+(`size-guide`, `lookbook`): the backend has no code per section, so a type it has never seen is fine.
+A **setting type** it has never seen is not — compose the types below, never invent one; a missing
+type is a contract change in magicbot. `GET /home` is optional. Full recipe and a worked example
+(`size-guide`): `.claude/skills/theme-section/SKILL.md`.
+
+1. `theme/sections/<type>.tsx`: `defineSection` + the component (`SectionProps<typeof section>`).
+2. Register it in `theme/index.ts` (`sections` and `components`).
+3. Put it in `theme/templates/*.json` or give it `presets`.
+4. Every buyer-facing word comes from a setting with an `en`/`ru`/`uz` default. No copy in the component.
+5. `npm run theme:check`, then `npm run theme:push` (bump `version`); `theme dev` pushes while developing.
+
+| Type              | Extra members                           | The component receives                                    |
+| ----------------- | --------------------------------------- | --------------------------------------------------------- |
+| `TEXT`            | `maxLength` (≤ 500)                     | `string`                                                  |
+| `TEXTAREA`        | `maxLength` (≤ 5 000)                   | `string`                                                  |
+| `RICHTEXT`        | —                                       | sanitised HTML `string` (the only HTML a section renders) |
+| `URL`             | —                                       | `string \| null`                                          |
+| `COLOR`           | —                                       | `#rrggbb` or `null`                                       |
+| `CHECKBOX`        | —                                       | `boolean`                                                 |
+| `NUMBER`          | `min`, `max` (optional)                 | `number \| null`                                          |
+| `RANGE`           | `min`, `max`, `step`, `unit` (optional) | `number`                                                  |
+| `SELECT`          | `options: [{ value, label }]` (≤ 100)   | one option `value`                                        |
+| `IMAGE`           | —                                       | `{ url, altText: null, width, height }` or `null`         |
+| `COLLECTION`      | —                                       | `{ id, handle, title }` or `null`                         |
+| `PRODUCT`         | —                                       | `{ id, handle, title }` or `null`                         |
+| `COLLECTION_LIST` | `limit` (1–50)                          | `{ id, handle, title }[]`                                 |
+| `PRODUCT_LIST`    | `limit` (1–50)                          | `{ id, handle, title }[]`                                 |
+| `HEADER`          | `content` (no `id`)                     | — (a heading in the editor form)                          |
+| `PARAGRAPH`       | `content` (no `id`)                     | — (a note in the editor form)                             |
 
 ## Commands
 
@@ -77,4 +115,6 @@ npm run dev          # needs MAGICSTORE_SHOP_DOMAIN (or MAGICSTORE_API_URL) in .
 npm run build
 npm run typecheck
 npx create-magic-storefront check   # SDK used only through its public API
+npm run theme:check                 # theme sections and templates; npm run build runs it too
+npm run theme:push                  # send the theme to the shop (MAGICSTORE_THEME_TOKEN, mtt_…)
 ```

package/template/PAGES.md

@@ -17,17 +17,28 @@ errors).
 `nextCacheFetch` tags every public `GET` by its path (`tagForPath`), and
 `app/api/magicstore/webhook` revalidates the tags of each webhook topic:
 
-| Tag                  | Paths                                                                                           | Webhook topic     |
-| -------------------- | ----------------------------------------------------------------------------------------------- | ----------------- |
-| `magicstore:shop`    | `/shop`, `/contacts`, `/theme/section-schema`                                                   | `SHOP_UPDATED`    |
-| `magicstore:home`    | `/home`                                                                                         | `HOME_UPDATED`    |
-| `magicstore:pages`   | `/pages*`, `/blog/*`, `/menus/footer`, `/sitemap`                                               | `PAGES_UPDATED`   |
-| `magicstore:catalog` | `/products*`, `/collections*`, other `/menus/*`, `/reels`, `/sitemap` (both tags), `/locations` | `CATALOG_UPDATED` |
-| none (`no-store`)    | `/search*`, `/reviews/site`, cart, checkout, customer, orders                                   | —                 |
+| Tag                          | Paths                                                                                           | Webhook topic                    |
+| ---------------------------- | ----------------------------------------------------------------------------------------------- | -------------------------------- |
+| `magicstore:shop`            | `/shop`, `/contacts`, `/theme/section-schema`                                                   | `SHOP_UPDATED`                   |
+| `magicstore:home`            | `/home`                                                                                         | `HOME_UPDATED`                   |
+| `magicstore:pages`           | `/pages*`, `/blog/*`, `/menus/footer`, `/sitemap`                                               | `PAGES_UPDATED`                  |
+| `magicstore:catalog`         | `/products*`, `/collections*`, other `/menus/*`, `/reels`, `/sitemap` (both tags), `/locations` | `CATALOG_UPDATED`                |
+| `magicstore:theme`           | `/theme`, `/theme/settings`, `/templates/*` (both tags)                                         | `THEME_UPDATED`                  |
+| `magicstore:template:<name>` | `/templates/<name>`                                                                             | `TEMPLATE_UPDATED` (`data.name`) |
+| none (`no-store`)            | `/search*`, `/reviews/site`, cart, checkout, customer, orders, theme previews                   | —                                |
 
 Every page renders per request (`dynamic = 'force-dynamic'` in `app/layout.tsx`): the shop is the
 API's, not the build's. The fetch cache still spares the API.
 
+### Who holds the buyer's credentials
+
+By default (`MAGICSTORE_CREDENTIALS` unset or `server`, `lib/upstream.ts`) every browser call goes
+through `app/storefront-api`, which keeps the sign-in tokens and the cart and checkout ids in
+httpOnly cookies. Page JavaScript only ever sees `"current"` in their place — `cart.id`,
+`checkout.id`, the session's tokens — and passes it back as is. Choose `browser` only when a public
+storefront token sends the browser straight to the API; then the tokens and the cart id live in
+`localStorage`.
+
 ## Layout — `app/layout.tsx`
 
 - Reads `api.shop()` and the navigation (`api.collectionsIndex` or `api.menusShow({ path: { handle: 'main' } })`).
@@ -44,25 +55,31 @@ API's, not the build's. The fetch cache still spares the API.
   `TelegramShell` (`components/telegram-shell.tsx`) inside `Providers` (see "Running as a Telegram
   Mini App").
 
-## Home — `app/page.tsx`, `components/sections/`
+## Home — `app/page.tsx`, `theme/`
+
+The home page belongs to the storefront. This starter is a **theme** (Online Store 2.0 style):
 
-The home page belongs to the storefront. `GET /home` is one way to fill it, not a requirement.
-Pick one per project:
+- `theme/sections/<type>.tsx` holds one section: its schema (`defineSection`) next to its component.
+  `theme/index.ts` registers every section (`defineTheme`) and its component (`components`).
+- `theme/templates/index.json` is the home's default content; `theme/templates/page.json` lays out
+  content pages; `theme/settings.ts` holds global settings (the announcement above the header).
+- `create-magic-storefront theme push` sends the theme to the shop, and the merchant edits texts,
+  images, products and the order of sections in the admin's theme editor. `app/page.tsx` reads the
+  merchant's template with `loadTemplate(api, 'index', theme)` and renders it with `ThemeSections`;
+  until the theme is pushed, the bundled `templates/index.json` renders instead.
+- Every buyer-facing string in a section comes from a setting with a default (from `lib/i18n.ts`),
+  so the merchant can change it. `npm run theme:check` flags copy written into a component.
 
-- **Merchant-managed** (this starter's default): render `GET /home`, described below. The merchant
-  arranges the page in the admin and the storefront follows.
-- **Custom**: compose the page yourself from any API data — `productsIndex` with its sorts and
-  filters, `collectionsIndex`, `collectionsProducts`, `reviewsSite`, `pagesShow`, `shop.branding` —
-  in whatever layout the design calls for. Not calling `api.home()` at all is fine, and so is
-  taking only some sections from it (the merchant's `BANNER` slides, the `ANNOUNCEMENT_BAR` text)
-  and placing them where the design wants. `components/sections/` can then be deleted.
+`GET /home` is optional: the default template never calls it. The `platform-home` section renders
+the platform's home editor layout (below) when the merchant adds it in the theme editor. Theme reads
+are cached under `magicstore:theme` and `magicstore:template:<name>` (table above).
 
-A custom home is a trade-off: the merchant's home editor in the admin no longer controls the page.
-Tell whoever owns the store. Everything else still holds: data only from the API, nothing invented,
-and the page is revalidated by the tags of what it reads (`magicstore:catalog`, `magicstore:shop`),
-not by `HOME_UPDATED` unless it calls `api.home()`.
+A storefront may still drop the theme and compose a **custom** home from any API data —
+`productsIndex` with its sorts and filters, `collectionsIndex`, `collectionsProducts`,
+`reviewsSite`, `pagesShow`, `shop.branding`. The merchant's editor then no longer controls the page:
+tell whoever owns the store. Everything else still holds: data only from the API, nothing invented.
 
-### Rendering `GET /home`
+### Rendering `GET /home` — `components/sections/`, the `platform-home` section
 
 `api.home()` answers `{ sections: HomeSection[] }` in the merchant's order. Render each by `type`
 with one component per type; a type the storefront does not know renders **nothing** (the API can
@@ -95,6 +112,15 @@ render nothing then.
 personal; render it in a client component or not at all. A shop with no sections still needs a
 home: show new arrivals.
 
+## Creating a new section
+
+A section is one file in `theme/sections/`, registered in `theme/index.ts`, placed in a template or
+given `presets`, with every buyer-facing word in a setting, then `npm run theme:check` and
+`npm run theme:push`. The backend needs nothing for a new section type — only a new setting type is
+a contract change. The steps, the setting types and a worked example (`size-guide`) are in
+`AGENTS.md` and `.claude/skills/theme-section/SKILL.md`; `theme/sections/testimonials.tsx` is a
+section with blocks to copy from.
+
 ## Collection — `app/collections/[handle]/page.tsx`
 
 - `api.collectionsShow({ path: { handle } })` and `api.collectionsProducts({ path: { handle }, query: { page, perPage } })`,

package/template/README.md

@@ -20,6 +20,7 @@ npm run dev
 | `app/providers.tsx`            | `MagicStoreProvider`: customer, cart, wishlist and analytics in the browser.  |
 | `app/storefront-api/[...path]` | Same-origin proxy for browser calls when there is no public storefront token. |
 | `app/api/magicstore/webhook`   | Verifies the platform's webhook and revalidates the tags its topic covers.    |
+| `app/api/magicstore/preview`   | The admin's theme preview: verifies its token, turns on draft mode.           |
 
 **Browser calls.** With `NEXT_PUBLIC_MAGICSTORE_STOREFRONT_TOKEN` (a token that lists this site's
 origin) the browser calls the shop's API directly. Without it, calls go through the proxy route,
@@ -35,3 +36,8 @@ serves every page from the spec's example data.
 
 **Webhook.** In Shop settings → Storefront API, set the token's webhook to
 `https://<this site>/api/magicstore/webhook` and put its secret in `MAGICSTORE_WEBHOOK_SECRET`.
+The same secret signs the theme editor's preview links: the admin opens
+`https://<this site>/api/magicstore/preview?token=…&path=/`, which turns on draft mode for ten minutes
+and serves the draft theme to that browser only (`lib/preview.ts`); `?exit=1` ends it. Previews also need
+`MAGICSTORE_STOREFRONT_TOKEN`, the storefront token that webhook belongs to: the API previews only a
+read that names its token.

package/template/_gitignore

@@ -4,3 +4,5 @@ node_modules/
 next-env.d.ts
 *.tsbuildinfo
 .screenshots/
+.magicstore/
+.tmp/

package/template/app/api/magicstore/preview/route.ts

@@ -0,0 +1,56 @@
+import {
+  THEME_PREVIEW_COOKIE,
+  previewRedirectPath,
+  verifyThemePreview,
+} from '@magicstoreai/hydrogen/server';
+import { cookies, draftMode } from 'next/headers';
+import { redirect } from 'next/navigation';
+
+import { storefrontToken } from '@/lib/api';
+
+/**
+ * The admin's theme editor opens `/api/magicstore/preview?token=…&path=/` (in a frame or a tab) to
+ * show an unpublished theme or unsaved changes. A valid token turns on draft mode and is kept in an
+ * httpOnly cookie for its ten minutes; pages then send it as `X-Theme-Preview`, uncached.
+ * `?exit=1` ends the preview. The token is signed with the webhook secret and never logged.
+ */
+export async function GET(request: Request): Promise<Response> {
+  const secret = process.env.MAGICSTORE_WEBHOOK_SECRET;
+  if (!secret) {
+    return new Response('MAGICSTORE_WEBHOOK_SECRET is not set', { status: 501 });
+  }
+  if (!storefrontToken()) {
+    // The API previews only a request that names its storefront token.
+    return new Response('MAGICSTORE_STOREFRONT_TOKEN is not set', { status: 501 });
+  }
+  const params = new URL(request.url).searchParams;
+  const path = previewRedirectPath(params.get('path'));
+  const jar = await cookies();
+
+  if (params.has('exit')) {
+    (await draftMode()).disable();
+    jar.delete(THEME_PREVIEW_COOKIE);
+    redirect(path);
+  }
+
+  const token = params.get('token');
+  const now = Math.floor(Date.now() / 1000);
+  const preview = await verifyThemePreview(secret, token, now);
+  if (preview === null || token === null) {
+    return new Response('The preview link is invalid or has expired.', {
+      status: 403,
+      headers: { 'Cache-Control': 'no-store' },
+    });
+  }
+
+  (await draftMode()).enable();
+  jar.set(THEME_PREVIEW_COOKIE, token, {
+    httpOnly: true,
+    secure: true,
+    // The editor shows the storefront in a frame on the admin's origin.
+    sameSite: 'none',
+    path: '/',
+    maxAge: Math.max(1, preview.expiresAt - now),
+  });
+  redirect(path);
+}

package/template/app/globals.css

@@ -410,3 +410,111 @@ footer.site nav {
 .author h1 {
   margin: 0;
 }
+/* Theme sections (theme/sections/): the merchant edits their content in the admin. */
+/* A section with nothing to show yet renders nothing, but ThemeSections still wraps it. */
+[data-section-id]:empty {
+  display: none;
+}
+.site-announcement {
+  margin: 0;
+  padding: 8px 16px;
+  background: var(--accent);
+  color: var(--on-accent);
+  text-align: center;
+}
+.hero {
+  display: grid;
+  border-radius: 12px;
+  overflow: hidden;
+  background: var(--placeholder);
+}
+.hero > img,
+.hero-text {
+  grid-area: 1 / 1;
+}
+.hero > img {
+  width: 100%;
+  height: auto;
+  aspect-ratio: 21 / 9;
+  object-fit: cover;
+}
+.hero-text {
+  align-self: center;
+  padding: 40px 24px;
+}
+.hero > img + .hero-text {
+  background: linear-gradient(to top, rgb(0 0 0 / 0.7), rgb(0 0 0 / 0.35) 55%, transparent);
+  color: #fff;
+  text-shadow: 0 1px 2px rgb(0 0 0 / 0.4);
+  align-self: stretch;
+  justify-content: flex-end;
+}
+.hero-center .hero-text {
+  align-items: center;
+  text-align: center;
+}
+.hero-text h1,
+.hero-text p {
+  margin: 0;
+  max-width: 40ch;
+}
+.hero-text .button,
+.image-with-text .button {
+  align-self: flex-start;
+  text-shadow: none;
+}
+.hero-center .hero-text .button {
+  align-self: center;
+}
+@media (max-width: 720px) {
+  .hero > img {
+    aspect-ratio: 4 / 5;
+  }
+}
+.rich-text-narrow {
+  max-width: 760px;
+}
+.image-with-text {
+  display: grid;
+  grid-template-columns: minmax(0, 1fr) minmax(0, 1fr);
+  gap: 32px;
+  align-items: center;
+}
+.image-with-text.image-right > img {
+  order: 2;
+}
+.image-with-text > img {
+  width: 100%;
+  height: auto;
+  aspect-ratio: 4 / 3;
+  object-fit: cover;
+  border-radius: 12px;
+}
+@media (max-width: 720px) {
+  .image-with-text {
+    grid-template-columns: 1fr;
+  }
+  .image-with-text.image-right > img {
+    order: 0;
+  }
+}
+.testimonials {
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(260px, 1fr));
+  gap: 20px;
+}
+.testimonials figure {
+  margin: 0;
+  padding: 16px;
+  border: 1px solid var(--line);
+  border-radius: 12px;
+}
+.testimonials blockquote {
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+.testimonials .rating {
+  color: var(--accent);
+  letter-spacing: 2px;
+}

package/template/app/layout.tsx

@@ -5,11 +5,15 @@ import type { ReactNode } from 'react';
 import { Image } from '@magicstoreai/hydrogen';
 // From /core, not the "use client" entry: a plain string a server component can read.
 import { TELEGRAM_WEB_APP_SCRIPT } from '@magicstoreai/hydrogen/core';
+import { loadThemeSettings } from '@magicstoreai/hydrogen/server';
 import { CartLink } from '@/components/cart-link';
 import { TelegramShell } from '@/components/telegram-shell';
 import { api, locale } from '@/lib/api';
+import { themePreview } from '@/lib/preview';
 import { brandStyle } from '@/lib/brand';
+import { credentialsMode } from '@/lib/upstream';
 import { messages } from '@/lib/i18n';
+import theme from '@/theme';
 import { Providers } from './providers';
 import './globals.css';
 
@@ -27,23 +31,30 @@ export async function generateMetadata(): Promise<Metadata> {
 }
 
 export default async function RootLayout({ children }: { children: ReactNode }) {
-  const [{ data: shop }, { data: collections }, { data: pages }] = await Promise.all([
-    api.shop(),
-    api.collectionsIndex({ query: { perPage: 6 } }),
-    api.pagesIndex(),
-  ]);
+  const [{ data: shop }, { data: collections }, { data: pages }, themeSettings] = await Promise.all(
+    [
+      api.shop(),
+      api.collectionsIndex({ query: { perPage: 6 } }),
+      api.pagesIndex(),
+      themePreview().then((preview) => loadThemeSettings(api, theme, { locale, preview })),
+    ],
+  );
+  const announcement = themeSettings.announcement as string;
   const t = messages(locale);
 
   return (
     // The merchant's colors, read per request: a change in the admin shows after SHOP_UPDATED.
-    <html lang={locale} style={brandStyle(shop.branding)}>
+    // Telegram's script (beforeInteractive) writes --tg-viewport-* into <html style> before React
+    // hydrates; suppressHydrationWarning covers this element's attributes only, not its children.
+    <html lang={locale} style={brandStyle(shop.branding)} suppressHydrationWarning>
       <body>
         {/* Telegram's Mini App script, only for a shop with a bot: nobody else can open it in Telegram. */}
         {shop.features.telegramBot && (
           <Script src={TELEGRAM_WEB_APP_SCRIPT} strategy="beforeInteractive" />
         )}
-        <Providers shop={shop}>
+        <Providers shop={shop} credentials={credentialsMode()}>
           <TelegramShell />
+          {announcement && <p className="site-announcement">{announcement}</p>}
           <header className="site">
             <nav>
               <Link href="/" className="brand">